系统提示词
用 agent/prompts 中的文件扩展或替换 Cappy 的系统提示词，了解文件的适用范围与优先级、更新方式与数据库方言规则。
Cappy 内置系统提示词，用于指导 Agent 分析问题、使用工具和组织回答。
你可以在 agent/prompts/ 中添加文件，为不同平台扩展或替换这些指令。文件内容默认会替换整份系统提示词；保留 {{ cappy_prompt }} 占位符，则是在默认指令基础上追加要求。
提示词文件及适用范围
文件名决定自定义提示词影响哪些对话或任务。例如，telegram.md 只影响 Telegram 对话，slack.md 只影响 Slack 对话；system.md 用于 Web 对话，也作为没有专用文件时的通用配置。
cappy init 会创建 agent/prompts/，其中有说明文件 README.md 和示例 slack.md。下面的 my-project 表示你的项目文件夹；已有项目缺少这个目录时，可以直接创建，无需重新初始化：
my-project/
├── config.yaml
├── RULES.md
└── agent/
└── prompts/
├── README.md
└── slack.md根据要调整的对话平台或任务，在 agent/prompts/ 下创建或编辑相应文件：
| 文件 | 适用范围 |
|---|---|
system.md | Web 对话；没有专用文件的消息平台；当前版本的自动化运行 |
slack.md | Slack |
teams.md | Microsoft Teams |
telegram.md | Telegram |
whatsapp.md | |
mattermost.md | Mattermost |
feishu.md | 飞书 |
automation.md | 当前版本不生效；自动化运行使用 system.md |
除标注为不生效的 automation.md 外，使用表中的文件名进行配置。README.md 只是说明，不会作为系统提示词加载。消息平台需要先完成对应的集成配置，添加文件不会启用集成。
对于一个消息平台，Cappy 按以下优先级选择文件：
- 该平台的专用文件，例如
slack.md。 - 如果没有可用的专用文件，使用
system.md。 - 两者都没有时，使用该平台的内置提示词。
空文件或只有空白的文件会被跳过。Web 对话没有单独的 web.md，只检查 system.md。
专用文件与 system.md 不会自动合并。 例如，两者都存在时，Slack 只使用 slack.md。初始化生成的示例 slack.md 也会优先于 system.md：如果希望 Slack 使用通用文件，需要删除示例文件或将其清空。删除专用文件后，只有在 system.md 也不存在或为空时，才会恢复内置提示词。
当前版本尚不支持通过 automation.md 单独设置自动化的系统提示词，创建这个文件不会改变自动化行为。自动化运行读取 system.md；文件不存在或为空时，使用内置提示词。要约定某一个自动化任务的输出方式，可直接写进该任务的提示词；不要依赖 automation.md 单独定制自动化的系统提示词。
扩展或替换默认提示词
生效的提示词文件默认会完全替换对应的内置提示词。如果要保留默认行为并追加要求，在文件中加入 {{ cappy_prompt }}。Cappy 会把这个占位符替换为当前对话或任务的完整默认提示词。
{{ cappy_prompt }} 是当前版本识别的占位符。{{cappy_prompt}} 等空格变体也有效；同一文件出现多次时，每一处都会展开。
扩展默认提示词
下面以 Slack 为例，在保留默认分析和工具使用方式的基础上，要求回答先给结论，并附上已有报表链接。
编辑 Slack 提示词
打开项目中的 agent/prompts/slack.md，保留占位符，再添加要求：
{{ cappy_prompt }}
## Slack 回复要求
- 先用一句话概括分析结论，再给出关键数字和解释。
- 如果分析引用了已有报表，在回答中附上该报表的链接；没有链接时不要编造。这里的占位符展开为 Slack 的默认提示词，不会读取 system.md。同样，如果 Slack 使用的是通用文件 system.md，其中的占位符也会展开为 Slack 的默认提示词，而不是 Web 对话的默认提示词。
更新 Agent 使用的文件
在项目的本地工作副本中保存文件，提交并推送到项目仓库，再按更新上下文确认实例已取得最新提交。内建仓库推送后会请求同步；GitHub 项目按项目设置手动或自动拉取。
Cappy 在每次处理新消息时重新读取提示词文件，无需重启服务。修改本地文件后，需先通过 Git 发布并同步到实例，Agent 才能读取更新。
检查 Slack 中的回复
在已连接的 Slack 频道中向 Cappy 提问，例如“上个月销售额是多少？与前一个月相比有什么变化？”。检查回答是否先概括结论，再解释数字；引用已有报表时是否带有真实链接。同时确认原有的数据查询仍能完成。
如果回复没有变化，先确认修改的是该项目的 slack.md，且更新已发布到 Agent 使用的项目目录。只改 system.md 不会覆盖已有的 slack.md。
完全替换默认提示词
不写占位符时，整个文件就是系统提示词。例如，通过通用文件设置财务分析助手（已有专用文件的平台仍使用其专用文件）：
你是财务团队的 Cappy 分析助手。
回答中的金额和数量必须来自 prod_finance schema 中的实际查询结果。
先说明统计时间范围，再列出结果与计算口径。
数据不足时说明缺少什么，不推测未查询到的数字。这个例子会替换默认提示词，而不只是追加四条规则。内置的工具使用说明、查询与图表规则，以及默认提示词中加入的 RULES.md、个人记忆和数据库方言规则，都不会自动保留。通常应优先使用扩展方式；只有准备自行维护完整指令时，才完全替换。
示例中的 schema 限制是对 Agent 的指引，不会改变数据库账号或项目权限。真正的访问范围仍由权限配置决定。
上下文建议等使用独立系统提示词的任务，不受这些文件影响。
数据库方言规则
默认提示词会根据项目上下文中发现的数据库连接加入相应的 SQL 和工具使用规则，无需把这些通用要求再抄进 RULES.md。当前内置的专项规则包括：
| 数据库 | 提供给 Agent 的主要规则 |
|---|---|
| BigQuery | 标识符使用反引号；用 SAFE_DIVIDE 处理除法；聚合与窗口查询正确组织 GROUP BY；遵循字面量行与聚合函数的语法限制。 |
| Redshift | 用窗口函数去重；按需拆分 PERCENTILE_CONT 与 LISTAGG 的计算；使用适用的字符串拼接、日期和条件计数写法。 |
| SQL Server、Microsoft Fabric | 使用 TOP N，显式列出分组字段；使用 T-SQL 日期函数，并在两个参数的空值处理中优先使用 ISNULL()。 |
| MySQL、Doris、StarRocks | 表名和列名使用反引号；两个参数的空值处理优先使用 IFNULL()。 |
| ClickHouse | 存在 indexes.md 时，先查看表的排序键、主键与分区信息，帮助选择查询方式。 |
没有专项规则的数据库，例如 PostgreSQL、Snowflake、Databricks 和 DuckDB，使用默认提示词中的通用查询规则；这不表示它们不受支持。
这些规则属于默认提示词。完全替换时，它们也会被移除；保留 {{ cappy_prompt }} 才会继续包含它们。