配置

ZenCopy 开箱即用，什么都不用配置。本页是当你想让它更贴合自己时的指南。前半部分讲设置窗口，面向所有人；后半部分讲配置文件，面向进阶用户。

设置窗口

可以从托盘图标的菜单，或弹窗上的齿轮图标打开。它有三个标签页：通用、AI、提示词。

通用

弹窗位置 — 结果出现在屏幕的哪个角落。
主题 — 浅色 / 深色 / 跟随系统。
文字大小 — 小 / 标准 / 大。
界面语言 — 默认跟随操作系统。
登录时启动 — 只要电脑开着，ZenCopy 就随时待命。
发送图片和文件前确认 — 在把图片或文件发送给 AI 之前，是否先询问一次。

AI

在这里更改 AI 服务（提供商、模型、API 密钥）。点测试按钮，马上就能知道连接是否正常。

这个标签页还有一个关于你输入框。用平实的语言写几句你的角色和偏好即可，语言不限。

例如：“销售。写的大多是客户邮件——礼貌但不生硬，结论先行。”

填好之后，每个提示词的结果都会为你量身调整。解释会贴合你的知识水平，改出来的文稿会符合你偏好的语气。它不会影响无关的任务，写的内容本身也不会出现在结果里。

提示词

这是“复制两次之后做什么”的列表。

预装的提示词可以打开阅读 — 它们同时也是现成的写法示例。
新建提示词只需要一个名称和你想要的效果。例如：名称“3 行摘要”，指令“用 3 行总结这段内容”。
没把握写好指令？把想要的效果随手写下来，点用 AI 起草 — 你配置的 AI 会把它整理成一条规范的指令。
规则可以按内容类型（文本 / 图片 / 文件）分别指定不同的提示词。

你创建的提示词可以分享：导出会把它写成一个文件，接收方只需粘贴到导入里，或直接选择文件。

宁愿把所有工作都交给 AI 吗？任何 AI 对话助手都能为你写出一个随时可导入的提示词——粘贴以下内容并填空：

阅读 https://zencopy.app/llms-full.txt —— 完整的 ZenCopy 文档，包括提示词文件格式、模板变量以及规则的工作原理。然后编写一个实现以下功能的 ZenCopy 提示词：[你想要实现的功能]。在单个代码块中输出一个完整的提示词文件（带有 frontmatter 的 Markdown），以便直接粘贴到 ZenCopy 的 设置 → 提示词 → 导入 中。如果该提示词仅在特定应用或特定网站上才有意义，请添加一句话告诉我需要设置哪条规则。

回复中的代码块可以直接放入设置 → 提示词 → 导入。对于文档无法回答的问题（例如“ZenCopy 到底能不能做……”），只需一键即可打包相关源码——然后将结果交给同一个 AI。

配置文件（进阶用户）

从这里开始，讲的是直接编辑文本文件。所有基本功能都能在设置窗口里完成，所以到这里就停下也完全没问题。

文件从每个用户各自的应用配置目录读取。确切路径也会在启动时打印到日志里：

%APPDATA%\app.zencopy

~/Library/Application Support/app.zencopy

~/.config/app.zencopy

规则的默认值内嵌在应用里；rules.json 永远只起覆盖作用。提示词文件是只增不改的：它们定义新的提示词，内置提示词不可触碰（声明内置 id 的本地文件会被忽略）。编辑在下一次触发时生效 — 无需重启。

`ai-sdk-catalog.json`

提供商，加上 role → 模型的映射。这个文件格式的老家是 ai-sdk-catalog — 每个字段都在那里有文档（包括供编辑器校验和补全用的 $schema），examples/ 里有三种规模的配置。面向 ZenCopy 的起步配置（设置界面写出的形式、本地 Ollama、供提示词使用的 role）见配置示例。

有一条要求来自 ZenCopy 本身而非文件格式：roles 中必须始终包含 default。凡是 frontmatter 中未指定其他 role 的提示词都用它运行，设置界面的连接测试也是对它执行 ping。

API 密钥直接写进这个本地文件（设置界面写出的也是同样的格式）；它们绝不会离开你的电脑。不会读取环境变量 — GUI 应用由操作系统而不是你的 shell 启动，所以在 .zshrc 之类文件里 export 的变量根本到不了它那里。每次读取时都会按 schema 校验这个文件。改坏了会在弹窗和设置编辑器里显示明确的提示 — 不会有任何静默失败。

`rules.json`

哪种捕获由哪个提示词处理：一个扁平的 kind → prompt 映射，加上一个可选的、优先级更高的 overrides 列表（先匹配者胜出）。三种 kind 是 text、image 和 files（带格式的复制按 text 处理）；初始状态下，文本交给总结，图片和文件交给解释。扁平映射可以在应用内编辑（设置 → 提示词 → 规则），所以只有用 overrides 时才需要碰这个文件。

{
  "text": "zencopy-summarize",
  "image": "zencopy-explain",
  "files": "zencopy-explain",
  "overrides": [{ "when": { "app_name": "Slack", "min_chars": 200 }, "prompt": "summarize" }]
}

when 的条件：kind（三种 kind 之一，精确匹配）、app_name、exec_name、window_title、url（都支持 * 通配符），file_name（一个每个被复制文件的名称必须匹配的通配符，不区分大小写 — 例如 *.pdf），以及 min_chars / max_chars。

对于 image 和 files 类型的捕获，内容本身会发送给模型（每次捕获合计上限 10 MB）。文件类型按内容判断，而不是按文件名：图片、PDF 和音频原样附加，文本文件（Markdown、源代码、CSV 等）则成为这次捕获的文本（{{ text }}），表现得和你直接复制其内容完全一样。Office 文档（Word、Excel、PowerPoint）也会变为文本：其内容会被提取并发送，但布局和图像则不会。字符编码会自动检测，Shift_JIS、UTF-16 之类的旧格式也会被转换。其余类型会被拒绝，并给出明确的提示。完整路径会随内容一起发送，让模型能区分不同文件、知道它们的位置。由于二进制附件可能比文本花费更多，弹窗会在发送前先询问（文本文件无需确认直接运行）— 这个确认可以当场关闭，也可以在设置里关闭。

`prompts/*.md`

一个文件 = 一个提示词：YAML frontmatter + Liquid 正文。这同一个文件也就是分享格式 — 设置 → 提示词 → 导入既接受粘贴的文本，也接受选择的文件。

---
id: summarize
label: 摘要
role: default
instructions: 你是一位简洁的助手。
---

请用 {{ locale }} 把以下内容总结为 3 行：

{{ text }}

Frontmatter	含义
`id`	供 `rules.json` 引用的名称（默认为文件名）——前缀 `zencopy-` 专用于预装提示词
`label`	显示在弹窗中
`role`	运行时使用的 catalog role（默认为 `default`）
`instructions`	系统提示词（Liquid 模板）

模板变量，以及在浏览器中复制一个段落时的示例值：

变量	示例
`{{ text }}`	复制的文本（带格式的 HTML 复制会转换为 Markdown）
`{{ markup }}`	带格式复制的 HTML/RTF 源码
`{{ format }}`	`html`（或 `rtf`；纯文本复制时为空）
`{{ file_name }}`	`report.pdf`（第一个被复制文件的名称）
`{{ file_names }}`	每个被复制文件的名称，每行一个
`{{ file_paths }}`	每个被复制文件的完整路径，每行一个
`{{ app_name }}`	`Safari`
`{{ exec_name }}`	`Safari` / `chrome.exe`
`{{ exec_path }}`	`/Applications/Safari.app/Contents/MacOS/Safari`
`{{ window_title }}`	`定价 – Example`
`{{ url }}`	`https://example.com/pricing`（仅浏览器）
`{{ process_id }}`	`8123`
`{{ now }}`	`2026-07-08 20:15:00`
`{{ locale }}`	`zh-hans`

另外还有一个 ZenCopy 专有的 language_name 过滤器：{{ locale | language_name }} 会展开为“Simplified Chinese”而不是“zh-hans”，在提示词里读起来更自然。想看到实际的值，在设置里打开显示模板变量 — 每次捕获的变量会以 JSON 的形式出现在弹窗中。

简单的提示词（一个名称加一条指令）也可以在设置窗口里创建；它写出的正是这种文件格式。

进阶模板

instructions frontmatter 和正文都是完整的 LiquidJS 模板：条件、循环和过滤器全都可用。一个提示词可以根据复制来源自动切换行为：

---
id: context-aware
label: 随上下文切换
---

{% if url contains "github.com" %}
请审查这段代码，并指出其中最大的一个风险：
{% elsif app_name == "Slack" %}
请用 2 行总结这段聊天讨论：
{% else %}
请用 {{ locale }} 解释以下内容：
{% endif %}

{{ text | truncate: 8000 }}

日志

结构化日志（密钥和复制内容已脱敏）在开发版输出到终端，在正式版输出到自动轮转的文件：

%LOCALAPPDATA%\app.zencopy\logs

~/Library/Logs/app.zencopy/

~/.local/share/app.zencopy/logs