AGENTS.md 是「给项目贴的说明」，那系统提示词就是「给模型立的人设」。这一节我们用 SYSTEM.md / APPEND_SYSTEM.md 给 Pi 定制一套专属行为——比如让它在处理 md-tools 时永远先输出「将做什么」。注意区别：一个是整体替换，一个是追加。默认系统提示词与两条定制通道
Pi 自带一个很精简的默认系统提示词（入门课讲过，不到 1000 tokens）。想定制它，官方给了两个文件、两种思路：
| 文件 | 行为 | 位置 |
|---|---|---|
.pi/SYSTEM.md |
替换默认系统提示词 | 项目级 |
~/.pi/agent/SYSTEM.md |
替换默认系统提示词 | 全局级 |
APPEND_SYSTEM.md |
追加到默认提示词，不替换 | 项目或全局对应位置 |
一句话记忆：SYSTEM.md 是「换掉」，APPEND_SYSTEM.md 是「加上」。
md-tools 我们更推荐用 APPEND_SYSTEM.md——它不动 Pi 原本的核心行为，只在后面追加「处理 markdown 时默认用 md-tools、先预览再执行」这类偏好。整体替换 SYSTEM.md 风险大，容易把 Pi 该有的能力弄丢，慎用。追加：写一份 APPEND_SYSTEM.md
在项目里新建 md-tools/APPEND_SYSTEM.md，追加你自己的行为偏好。比如：
你在本项目中的偏好：
- 处理 markdown 文件时，优先使用本项目的 md-tools 工具箱命令
- 任何会改动文件的操作，执行前先打印「将做什么」并等待确认
- 输出保持简洁，能用纯文本就不用多余格式
保存后重启 Pi，它的系统提示词末尾就会带上这几条。注意：全局放在 ~/.pi/agent/，项目放在项目根目录。
替换：什么时候才用 SYSTEM.md
SYSTEM.md 是整体替换，等于你亲手接管模型的行为设定。适合从头打造一套完全不同人格的场景——比如让 Pi 只做一个 markdown 格式化助手，把整套提示词都写死。
你是一个 markdown 处理助手。你的唯一职责是：
根据用户描述，调用 md-tools 的 stats / convert / rename 命令完成任务。
不要做任何任务之外的事情。
强烈提醒： 替换后，Pi 原本的内置工具说明、加载上下文、技能发现这些行为，默认的系统提示词就不在了。除非你确定要完全接管，否则先考虑追加。命令行也有等价开关：
pi --system-prompt "你的提示词" # 替换
pi --append-system-prompt "追加内容" # 追加
官方明确说：--system-prompt 替换默认提示词时，上下文文件和技能仍然会追加进去。所以即便你替换了，项目的约定和技能也还在——这一点可以放心。
命令行的追加/替换与文件的关系
两套方式可以混用：
- 文件
SYSTEM.md/APPEND_SYSTEM.md：持久化，每次启动都生效 - 命令行
--system-prompt/--append-system-prompt：一次性，本次运行生效
对反复使用的项目，写进文件更省心；临时调试，用命令行更轻。理解「替换 vs 追加」这套心智模型，比记住具体命令更重要。
落地练习：让 Pi 带着 md-tools 偏好跑
- 在
md-tools/建一份APPEND_SYSTEM.md，写入「优先用 md-tools」「先预览再执行」两条偏好 - 重启 pi，问它「你现在有哪些本项目的偏好」，确认它能复述出这两条
- 试着用
--system-prompt替换跑一次，对比「替换」和「追加」在行为上的差异
怎么判断做对了？——追加后 Pi 能说出你的偏好并在处理时遵守；替换后能明显感觉行为被你的提示词「接管」了。
卡住了怎么办？ 追加没生效 → 确认文件名、路径是否正确，重启 Pi。复述不出 → 说明追加内容可能太隐晦，写得更直接。替换后「变笨」了 → 记住这是整体替换的代价，改回用追加。
常见坑：分不清「替换」和「追加」把核心功能弄丢
最常见的翻车现场：想加几条偏好，结果用 SYSTEM.md 把默认系统提示词整个换掉，Pi 突然不会加载技能、不认上下文文件了。
记住口诀：默认的改动用「追加」，彻底重塑才用「替换」。 而且官方保证替换后上下文文件和技能仍在——但别的默认行为，你得自己补回来。没有十足把握，就用 APPEND_SYSTEM.md。
小结
SYSTEM.md整体替换默认系统提示词，APPEND_SYSTEM.md仅追加- 全局放
~/.pi/agent/，项目放项目根目录 - 命令行
--system-prompt/--append-system-prompt可一次性覆盖 - 替换后上下文文件和技能仍会追加，但其他默认行为要自己补
- 绝大多数场景，优先用「追加」而不是「替换」
下一节，聊聊「项目信任 Project Trust」——为什么 Pi 加载项目资源前会先问你一句。