1. 为什么“配置”才是把 Pi 变成主力的分水岭很多人第一次接触 Pi 这类编码代理工具注意力几乎全放在“它能不能写代码”“模型强不强”上结果装完、跑通一个 demo 就搁置了。我一开始也这样直到有段时间被一个重复性的重构任务折磨得不行才回头认真研究它的配置文件。结论很直接Pi 的上限不取决于你用的是哪个模型而取决于你把它“调教”到什么程度。同一套模型配置得好和配置得差产出质量能差出一个量级。这篇是实战系列的第一篇只聊配置。我会把settings.json、models.json、AGENTS.md、APPEND_SYSTEM.md这几个核心文件拆开讲清楚它们各自管什么、为什么这么设计、字段怎么填、哪些地方最容易踩坑。目标很明确——让你读完能把自己的 Pi 从“玩具”变成每天真正会打开的主力工具。不管你是刚装好还没动过配置的新手还是已经用了一阵但总觉得“差点意思”的老用户这篇都能给你可抄的作业。先说一个反直觉的点配置的核心不是“告诉 Pi 它能做什么”而是“约束它不要做什么”。大多数人配置失败是因为把配置文件当成了功能清单拼命往里塞能力而真正让 Pi 变好用的是边界、上下文和默认行为的设定。理解了这一点后面所有字段的取舍都会变得清晰。2. 四个配置文件的分工谁管行为、谁管模型、谁管记忆在动手改任何东西之前得先搞清楚这几个文件不是平级的它们处在不同的抽象层。很多人把它们混着改改到最后自己都忘了哪条规则生效这是配置混乱的根源。2.1 settings.json全局行为的总开关settings.json是 Pi 的主配置入口管的是运行时行为——比如默认用哪个模型、超时时间、日志级别、是否自动执行某些操作、工具调用的权限边界等。你可以把它理解成“操作系统的控制面板”它不定义能力本身而是定义能力怎么被调用。我建议这个文件保持精简。新手常犯的错是把所有能想到的开关都打开结果行为变得不可预测。一个务实的做法是只配置你当前工作流真正需要的项其余保持默认等遇到具体问题再回来加。2.2 models.json模型路由与参数的中枢models.json专门管模型。它定义有哪些模型可用、各自的接入参数、上下文窗口、默认温度、以及什么场景下路由到哪个模型。这是“配置篇”里技术含量最高的一块因为它直接决定成本和效果的平衡。一个常见的误区是只配一个“最强模型”然后所有任务都用它。实测下来这种做法既慢又贵而且对简单任务反而是负优化——强模型在琐碎任务上容易“想太多”。合理的做法是按任务类型分层后面第 4 节会详细展开。2.3 AGENTS.md项目级的“团队约定”AGENTS.md是放在项目根目录的约定文件描述这个项目的结构、技术栈、编码规范、目录约定、常用命令等。它的作用是让 Pi 在进入一个具体项目时快速获得这个项目的“背景知识”而不是每次都从零猜测。这个文件的价值在多人协作或长期项目里尤其明显。你写一次之后每次让 Pi 干活它都自动带着这些上下文省掉大量重复解释。它本质上是“项目记忆”的载体。2.4 APPEND_SYSTEM.md追加到系统提示的“私货”APPEND_SYSTEM.md的内容会被追加到系统提示词后面用来注入你个人的、跨项目的偏好。比如你希望 Pi 永远用某种代码风格、永远先给方案再动手、永远不要自作主张删文件——这些跨项目的通用约束放这里最合适。它和AGENTS.md的区别要记牢AGENTS.md是项目级的APPEND_SYSTEM.md是用户级的。前者跟着项目走后者跟着你走。搞混这两个就会出现“换个项目规则就失效”或者“个人偏好污染了团队项目”的问题。文件作用域管什么改动频率settings.json全局/用户级运行时行为、权限、默认项低models.json全局/用户级模型清单、路由、参数中AGENTS.md项目级项目结构、规范、命令随项目APPEND_SYSTEM.md用户级跨项目个人偏好低提示改配置前先备份。这几个文件一旦写错格式Pi 可能直接启动异常而报错信息往往不会直接指向出错的那一行。3. settings.json 实战从默认值到“顺手”的那几项settings.json的字段很多但真正影响日常体验的就那么几个。我把它们按“必调”和“按需调”分开说避免你被一堆选项淹没。3.1 必调项默认模型与超时默认模型决定了你敲下命令后第一反应由谁处理。如果你按第 4 节做了模型分层这里就填那个“通用主力”模型。超时时间则要根据你的网络和模型响应速度来定——设太短长任务被误杀设太长卡住时你干等。我的经验值是给复杂任务留足余量宁可长一点因为 Pi 卡住时通常会有其他信号提示而不是靠超时兜底。这里有个细节超时不要设成全局统一值。如果配置支持按任务类型区分就给轻量任务短超时、重任务长超时。统一值必然在某一端上不合适。3.2 权限边界自动执行到什么程度这是最需要谨慎的一项。Pi 能执行命令、改文件权限给太松它可能在你没注意时动了不该动的东西给太紧每步都要你确认效率又没了。我的建议是分阶段初期所有写操作和命令执行都要求确认先观察它的行为模式。熟悉后把只读操作、测试命令、格式化命令设为自动写文件和删除操作仍保留确认。稳定后对信任的项目可以放开更多但删除、覆盖、推送这类不可逆操作永远保留人工确认。这个渐进策略不是保守而是因为 Pi 的行为会随模型、上下文、提示词变化你无法保证它永远按你预期行事。保留关键确认点是给自己留后路。3.3 日志与可观测性很多人忽略日志配置出问题时两眼一抹黑。建议把日志级别调到能看清“它为什么这么做”的程度——至少能看到它调用了哪些工具、读了哪些文件、路由到了哪个模型。这些信息在排查“为什么它没按我说的做”时是决定性的。日志文件位置也要固定下来方便你事后翻。我习惯按天切分出问题时直接定位到当天。3.4 一个容易忽略的点工作目录与上下文范围Pi 默认会读取工作目录下的文件作为上下文。如果工作目录设得太宽比如整个用户目录它会读到大量无关文件既拖慢速度又干扰判断设得太窄又可能漏掉关键依赖。正确做法是把工作目录限定在当前项目根目录需要跨项目时再显式指定。这个设置看起来不起眼但它对输出质量的影响比很多人想象的大。上下文里塞满无关内容模型注意力会被稀释这是实测能明显感觉到的。4. models.json 的模型分层别用一个模型打天下模型配置是“配置篇”里最能体现功力的一块。我见过太多人只配一个模型然后抱怨“要么太慢要么太贵要么不够聪明”。问题不在模型在于你没做分层。4.1 按任务类型分三层我的做法是把任务粗分成三层每层对应不同的模型和参数轻量层格式化、重命名、简单查找替换、生成注释。这类任务要的是快和便宜用响应快的小模型温度调低保证稳定。通用层日常编码、重构、写测试、解释代码。这是主力层用综合能力均衡的模型温度适中。重载层架构设计、复杂调试、跨文件大改。这类任务用最强模型温度可以略高一点以激发推理但要接受它更慢更贵。分层之后你在settings.json里设的默认模型就是通用层遇到重活再显式切换。这样日常使用成本可控关键时刻又不掉链子。4.2 上下文窗口与截断策略每个模型都有上下文窗口上限。配置时要明确当上下文超限时是截断、摘要还是报错。默认截断最危险因为它可能悄悄丢掉关键信息导致 Pi 基于不完整上下文做出错误判断。我的建议是配置成“接近上限时提示并摘要”让 Pi 主动压缩历史而不是硬截断。这样虽然多一步但能保证它始终基于完整语义工作。4.3 温度与采样参数怎么定温度这个参数被讨论得很多但很多人设了就忘。经验值需要确定性输出的任务格式化、生成配置、写测试断言温度 0 到 0.2。日常编码和解释0.3 到 0.5。需要发散思考的任务方案设计、头脑风暴0.7 以上。关键是按模型分别设而不是全局一个值。不同模型对温度的敏感度不一样照搬数值往往效果打折。4.4 路由规则让 Pi 自己选模型如果配置支持条件路由强烈建议用起来。比如按文件类型、按任务关键词、按项目自动切换模型。这样你不需要每次手动指定Pi 会根据规则自己选。规则要写得具体避免模糊匹配导致误路由。一个实用的路由例子涉及测试文件的操作走轻量层涉及核心业务逻辑的走通用层涉及架构文件的走重载层。规则不用多覆盖高频场景即可。5. AGENTS.md 怎么写才算“有用”AGENTS.md是很多人写了但没写对的文件。常见问题是写成了一份 README 的复制粘贴堆了一堆对 Pi 干活没帮助的信息。它应该是一份给代理看的操作手册不是给人看的项目介绍。5.1 必须包含的四类信息一份有效的AGENTS.md至少覆盖项目结构与关键目录告诉 Pi 代码在哪、测试在哪、配置在哪、文档在哪。它不需要你列全但关键路径要有。技术栈与版本约束用什么语言、什么框架、什么版本。版本信息尤其重要因为不同版本的 API 差异会让 Pi 写出跑不通的代码。编码规范与约定命名风格、目录组织、提交信息格式、注释要求。这些是“团队约定”Pi 必须遵守。常用命令构建、测试、格式化、启动的命令。写清楚Pi 就不用猜。5.2 写法上的三个原则第一具体优于笼统。“使用一致的命名风格”是废话“组件文件用 PascalCase工具函数用 camelCase”才有用。第二给例子优于给规则。一条规则配一个正例一个反例Pi 理解得更准。第三保持更新。项目结构变了、命令改了AGENTS.md要同步否则它会基于过时信息干活比没有还糟。5.3 一个真实的反面案例我见过一个项目的AGENTS.md写了三百多行把每个文件的用途都列了一遍。结果 Pi 每次都要读这一大坨上下文被占满真正重要的规范反而被淹没。后来精简到四十行只留结构、规范、命令效果立刻好转。AGENTS.md不是越全越好是越准越好。注意AGENTS.md放在项目根目录才会被自动读取。放在子目录里除非配置了递归查找否则不生效。这个坑我踩过排查了半天才发现是位置问题。6. APPEND_SYSTEM.md把你的偏好变成默认行为如果说AGENTS.md是项目记忆APPEND_SYSTEM.md就是你的个人印记。它追加在系统提示之后优先级高影响所有项目。用好了Pi 会越来越像“你的”助手用不好会到处制造冲突。6.1 适合放什么跨项目通用的偏好最适合放这里交互风格比如“先给方案再动手”“不确定时先问而不是猜”。输出格式比如“代码块标注语言”“解释用中文代码注释用英文”。安全约束比如“不要自动删除文件”“不要执行网络请求”。工作习惯比如“改代码前先读相关测试”“提交前跑格式化”。这些内容不依赖具体项目放全局最省事。6.2 不适合放什么项目相关的规范不要放这里那是AGENTS.md的活。具体的技术栈约束也不要放否则换个项目就冲突。APPEND_SYSTEM.md越短越通用越好我自己的这份控制在二十行以内只保留最核心的几条。6.3 优先级冲突怎么处理当APPEND_SYSTEM.md和AGENTS.md冲突时通常系统提示优先级更高。这意味着如果你在APPEND_SYSTEM.md里写了“永远用某种风格”而项目AGENTS.md要求另一种项目规范可能被覆盖。所以写全局偏好时要克制只写那些真正跨项目成立的约束。一个实用技巧在APPEND_SYSTEM.md里加一条“项目级AGENTS.md的规范优先于本文件的通用偏好”这样能避免大部分冲突。7. 配置生效验证与常见故障排查配置写完不代表生效。我见过太多人改完文件就以为万事大吉结果跑起来还是老行为。这一节讲怎么验证以及出问题怎么查。7.1 验证配置是否被读取最直接的办法是让 Pi 复述它的当前配置或行为规则。比如问它“你现在默认用哪个模型”“你的编码规范是什么”。如果回答和你配置的一致说明生效了如果还是默认行为说明文件没被读到或格式有问题。另一个办法是看启动日志通常会打印加载了哪些配置文件。日志里没有的文件就是没生效的文件。7.2 格式错误的典型表现JSON 文件最常见的错误是多余逗号、引号不匹配、注释标准 JSON 不支持注释。这些错误往往导致整个文件被忽略而不是报错退出。表现就是“改了没反应”。所以改完 JSON 一定要用工具校验一遍别靠肉眼。Markdown 文件的问题通常是编码或换行符。如果文件是 Windows 换行符而系统期望 Unix可能读取异常。统一用 UTF-8 和 Unix 换行最稳。7.3 配置不生效的排查顺序按这个顺序查基本能定位文件位置对不对AGENTS.md在项目根目录吗。文件名拼写对不对大小写敏感。格式能不能通过校验。有没有被更高优先级的配置覆盖。需不需要重启或重新加载才生效。这五步走完九成问题都能解决。剩下的一成通常是多个配置互相冲突需要逐条注释掉来定位。7.4 一个隐蔽的坑缓存有些实现会缓存配置改完文件不重启不生效。如果你确认文件没问题但行为没变先试试重启。这个坑很隐蔽因为你会一直怀疑是自己写错了其实是缓存没刷新。8. 我踩过的几个配置坑和最终稳定下来的方案最后分享几个真实踩过的坑都是文档里不会写、但实际会遇到的。第一个坑是过度配置。刚开始我恨不得把每个字段都填满结果行为变得难以预测出问题也不知道是哪条配置导致的。后来砍到只剩必要的几项反而稳定了。配置的原则是“最小可用”需要时再加。第二个坑是模型分层没做全用最强模型。结果是简单任务慢得让人抓狂成本也高。分层之后日常体验提升非常明显而且成本降下来了。第三个坑是**AGENTS.md写太满**。前面提过三百行精简到四十行效果反而更好。上下文是稀缺资源别浪费在无关信息上。第四个坑是权限放太开。有一次让 Pi 自动执行它把一个我还没提交的改动覆盖了。从那以后不可逆操作我一律保留确认。这个习惯救过我很多次。最终我稳定下来的方案是settings.json只留默认模型、超时、权限边界和日志四项models.json做三层模型加简单路由AGENTS.md每个项目控制在五十行内只写结构、规范、命令APPEND_SYSTEM.md二十行以内只写跨项目偏好。这套配置用了大半年基本没再大改过。如果你刚开始配建议就从这套最小方案起步跑一段时间遇到具体问题再针对性调整。配置不是一次性的活是随着你使用习惯慢慢长出来的。下一篇我会聊实际使用中的工作流和提示词技巧那才是配置真正发挥价值的地方。 Pi 编码代理配置实战：用 settings.json 与 models.json 把工具变成主力
1. 为什么“配置”才是把 Pi 变成主力的分水岭很多人第一次接触 Pi 这类编码代理工具注意力几乎全放在“它能不能写代码”“模型强不强”上结果装完、跑通一个 demo 就搁置了。我一开始也这样直到有段时间被一个重复性的重构任务折磨得不行才回头认真研究它的配置文件。结论很直接Pi 的上限不取决于你用的是哪个模型而取决于你把它“调教”到什么程度。同一套模型配置得好和配置得差产出质量能差出一个量级。这篇是实战系列的第一篇只聊配置。我会把settings.json、models.json、AGENTS.md、APPEND_SYSTEM.md这几个核心文件拆开讲清楚它们各自管什么、为什么这么设计、字段怎么填、哪些地方最容易踩坑。目标很明确——让你读完能把自己的 Pi 从“玩具”变成每天真正会打开的主力工具。不管你是刚装好还没动过配置的新手还是已经用了一阵但总觉得“差点意思”的老用户这篇都能给你可抄的作业。先说一个反直觉的点配置的核心不是“告诉 Pi 它能做什么”而是“约束它不要做什么”。大多数人配置失败是因为把配置文件当成了功能清单拼命往里塞能力而真正让 Pi 变好用的是边界、上下文和默认行为的设定。理解了这一点后面所有字段的取舍都会变得清晰。2. 四个配置文件的分工谁管行为、谁管模型、谁管记忆在动手改任何东西之前得先搞清楚这几个文件不是平级的它们处在不同的抽象层。很多人把它们混着改改到最后自己都忘了哪条规则生效这是配置混乱的根源。2.1 settings.json全局行为的总开关settings.json是 Pi 的主配置入口管的是运行时行为——比如默认用哪个模型、超时时间、日志级别、是否自动执行某些操作、工具调用的权限边界等。你可以把它理解成“操作系统的控制面板”它不定义能力本身而是定义能力怎么被调用。我建议这个文件保持精简。新手常犯的错是把所有能想到的开关都打开结果行为变得不可预测。一个务实的做法是只配置你当前工作流真正需要的项其余保持默认等遇到具体问题再回来加。2.2 models.json模型路由与参数的中枢models.json专门管模型。它定义有哪些模型可用、各自的接入参数、上下文窗口、默认温度、以及什么场景下路由到哪个模型。这是“配置篇”里技术含量最高的一块因为它直接决定成本和效果的平衡。一个常见的误区是只配一个“最强模型”然后所有任务都用它。实测下来这种做法既慢又贵而且对简单任务反而是负优化——强模型在琐碎任务上容易“想太多”。合理的做法是按任务类型分层后面第 4 节会详细展开。2.3 AGENTS.md项目级的“团队约定”AGENTS.md是放在项目根目录的约定文件描述这个项目的结构、技术栈、编码规范、目录约定、常用命令等。它的作用是让 Pi 在进入一个具体项目时快速获得这个项目的“背景知识”而不是每次都从零猜测。这个文件的价值在多人协作或长期项目里尤其明显。你写一次之后每次让 Pi 干活它都自动带着这些上下文省掉大量重复解释。它本质上是“项目记忆”的载体。2.4 APPEND_SYSTEM.md追加到系统提示的“私货”APPEND_SYSTEM.md的内容会被追加到系统提示词后面用来注入你个人的、跨项目的偏好。比如你希望 Pi 永远用某种代码风格、永远先给方案再动手、永远不要自作主张删文件——这些跨项目的通用约束放这里最合适。它和AGENTS.md的区别要记牢AGENTS.md是项目级的APPEND_SYSTEM.md是用户级的。前者跟着项目走后者跟着你走。搞混这两个就会出现“换个项目规则就失效”或者“个人偏好污染了团队项目”的问题。文件作用域管什么改动频率settings.json全局/用户级运行时行为、权限、默认项低models.json全局/用户级模型清单、路由、参数中AGENTS.md项目级项目结构、规范、命令随项目APPEND_SYSTEM.md用户级跨项目个人偏好低提示改配置前先备份。这几个文件一旦写错格式Pi 可能直接启动异常而报错信息往往不会直接指向出错的那一行。3. settings.json 实战从默认值到“顺手”的那几项settings.json的字段很多但真正影响日常体验的就那么几个。我把它们按“必调”和“按需调”分开说避免你被一堆选项淹没。3.1 必调项默认模型与超时默认模型决定了你敲下命令后第一反应由谁处理。如果你按第 4 节做了模型分层这里就填那个“通用主力”模型。超时时间则要根据你的网络和模型响应速度来定——设太短长任务被误杀设太长卡住时你干等。我的经验值是给复杂任务留足余量宁可长一点因为 Pi 卡住时通常会有其他信号提示而不是靠超时兜底。这里有个细节超时不要设成全局统一值。如果配置支持按任务类型区分就给轻量任务短超时、重任务长超时。统一值必然在某一端上不合适。3.2 权限边界自动执行到什么程度这是最需要谨慎的一项。Pi 能执行命令、改文件权限给太松它可能在你没注意时动了不该动的东西给太紧每步都要你确认效率又没了。我的建议是分阶段初期所有写操作和命令执行都要求确认先观察它的行为模式。熟悉后把只读操作、测试命令、格式化命令设为自动写文件和删除操作仍保留确认。稳定后对信任的项目可以放开更多但删除、覆盖、推送这类不可逆操作永远保留人工确认。这个渐进策略不是保守而是因为 Pi 的行为会随模型、上下文、提示词变化你无法保证它永远按你预期行事。保留关键确认点是给自己留后路。3.3 日志与可观测性很多人忽略日志配置出问题时两眼一抹黑。建议把日志级别调到能看清“它为什么这么做”的程度——至少能看到它调用了哪些工具、读了哪些文件、路由到了哪个模型。这些信息在排查“为什么它没按我说的做”时是决定性的。日志文件位置也要固定下来方便你事后翻。我习惯按天切分出问题时直接定位到当天。3.4 一个容易忽略的点工作目录与上下文范围Pi 默认会读取工作目录下的文件作为上下文。如果工作目录设得太宽比如整个用户目录它会读到大量无关文件既拖慢速度又干扰判断设得太窄又可能漏掉关键依赖。正确做法是把工作目录限定在当前项目根目录需要跨项目时再显式指定。这个设置看起来不起眼但它对输出质量的影响比很多人想象的大。上下文里塞满无关内容模型注意力会被稀释这是实测能明显感觉到的。4. models.json 的模型分层别用一个模型打天下模型配置是“配置篇”里最能体现功力的一块。我见过太多人只配一个模型然后抱怨“要么太慢要么太贵要么不够聪明”。问题不在模型在于你没做分层。4.1 按任务类型分三层我的做法是把任务粗分成三层每层对应不同的模型和参数轻量层格式化、重命名、简单查找替换、生成注释。这类任务要的是快和便宜用响应快的小模型温度调低保证稳定。通用层日常编码、重构、写测试、解释代码。这是主力层用综合能力均衡的模型温度适中。重载层架构设计、复杂调试、跨文件大改。这类任务用最强模型温度可以略高一点以激发推理但要接受它更慢更贵。分层之后你在settings.json里设的默认模型就是通用层遇到重活再显式切换。这样日常使用成本可控关键时刻又不掉链子。4.2 上下文窗口与截断策略每个模型都有上下文窗口上限。配置时要明确当上下文超限时是截断、摘要还是报错。默认截断最危险因为它可能悄悄丢掉关键信息导致 Pi 基于不完整上下文做出错误判断。我的建议是配置成“接近上限时提示并摘要”让 Pi 主动压缩历史而不是硬截断。这样虽然多一步但能保证它始终基于完整语义工作。4.3 温度与采样参数怎么定温度这个参数被讨论得很多但很多人设了就忘。经验值需要确定性输出的任务格式化、生成配置、写测试断言温度 0 到 0.2。日常编码和解释0.3 到 0.5。需要发散思考的任务方案设计、头脑风暴0.7 以上。关键是按模型分别设而不是全局一个值。不同模型对温度的敏感度不一样照搬数值往往效果打折。4.4 路由规则让 Pi 自己选模型如果配置支持条件路由强烈建议用起来。比如按文件类型、按任务关键词、按项目自动切换模型。这样你不需要每次手动指定Pi 会根据规则自己选。规则要写得具体避免模糊匹配导致误路由。一个实用的路由例子涉及测试文件的操作走轻量层涉及核心业务逻辑的走通用层涉及架构文件的走重载层。规则不用多覆盖高频场景即可。5. AGENTS.md 怎么写才算“有用”AGENTS.md是很多人写了但没写对的文件。常见问题是写成了一份 README 的复制粘贴堆了一堆对 Pi 干活没帮助的信息。它应该是一份给代理看的操作手册不是给人看的项目介绍。5.1 必须包含的四类信息一份有效的AGENTS.md至少覆盖项目结构与关键目录告诉 Pi 代码在哪、测试在哪、配置在哪、文档在哪。它不需要你列全但关键路径要有。技术栈与版本约束用什么语言、什么框架、什么版本。版本信息尤其重要因为不同版本的 API 差异会让 Pi 写出跑不通的代码。编码规范与约定命名风格、目录组织、提交信息格式、注释要求。这些是“团队约定”Pi 必须遵守。常用命令构建、测试、格式化、启动的命令。写清楚Pi 就不用猜。5.2 写法上的三个原则第一具体优于笼统。“使用一致的命名风格”是废话“组件文件用 PascalCase工具函数用 camelCase”才有用。第二给例子优于给规则。一条规则配一个正例一个反例Pi 理解得更准。第三保持更新。项目结构变了、命令改了AGENTS.md要同步否则它会基于过时信息干活比没有还糟。5.3 一个真实的反面案例我见过一个项目的AGENTS.md写了三百多行把每个文件的用途都列了一遍。结果 Pi 每次都要读这一大坨上下文被占满真正重要的规范反而被淹没。后来精简到四十行只留结构、规范、命令效果立刻好转。AGENTS.md不是越全越好是越准越好。注意AGENTS.md放在项目根目录才会被自动读取。放在子目录里除非配置了递归查找否则不生效。这个坑我踩过排查了半天才发现是位置问题。6. APPEND_SYSTEM.md把你的偏好变成默认行为如果说AGENTS.md是项目记忆APPEND_SYSTEM.md就是你的个人印记。它追加在系统提示之后优先级高影响所有项目。用好了Pi 会越来越像“你的”助手用不好会到处制造冲突。6.1 适合放什么跨项目通用的偏好最适合放这里交互风格比如“先给方案再动手”“不确定时先问而不是猜”。输出格式比如“代码块标注语言”“解释用中文代码注释用英文”。安全约束比如“不要自动删除文件”“不要执行网络请求”。工作习惯比如“改代码前先读相关测试”“提交前跑格式化”。这些内容不依赖具体项目放全局最省事。6.2 不适合放什么项目相关的规范不要放这里那是AGENTS.md的活。具体的技术栈约束也不要放否则换个项目就冲突。APPEND_SYSTEM.md越短越通用越好我自己的这份控制在二十行以内只保留最核心的几条。6.3 优先级冲突怎么处理当APPEND_SYSTEM.md和AGENTS.md冲突时通常系统提示优先级更高。这意味着如果你在APPEND_SYSTEM.md里写了“永远用某种风格”而项目AGENTS.md要求另一种项目规范可能被覆盖。所以写全局偏好时要克制只写那些真正跨项目成立的约束。一个实用技巧在APPEND_SYSTEM.md里加一条“项目级AGENTS.md的规范优先于本文件的通用偏好”这样能避免大部分冲突。7. 配置生效验证与常见故障排查配置写完不代表生效。我见过太多人改完文件就以为万事大吉结果跑起来还是老行为。这一节讲怎么验证以及出问题怎么查。7.1 验证配置是否被读取最直接的办法是让 Pi 复述它的当前配置或行为规则。比如问它“你现在默认用哪个模型”“你的编码规范是什么”。如果回答和你配置的一致说明生效了如果还是默认行为说明文件没被读到或格式有问题。另一个办法是看启动日志通常会打印加载了哪些配置文件。日志里没有的文件就是没生效的文件。7.2 格式错误的典型表现JSON 文件最常见的错误是多余逗号、引号不匹配、注释标准 JSON 不支持注释。这些错误往往导致整个文件被忽略而不是报错退出。表现就是“改了没反应”。所以改完 JSON 一定要用工具校验一遍别靠肉眼。Markdown 文件的问题通常是编码或换行符。如果文件是 Windows 换行符而系统期望 Unix可能读取异常。统一用 UTF-8 和 Unix 换行最稳。7.3 配置不生效的排查顺序按这个顺序查基本能定位文件位置对不对AGENTS.md在项目根目录吗。文件名拼写对不对大小写敏感。格式能不能通过校验。有没有被更高优先级的配置覆盖。需不需要重启或重新加载才生效。这五步走完九成问题都能解决。剩下的一成通常是多个配置互相冲突需要逐条注释掉来定位。7.4 一个隐蔽的坑缓存有些实现会缓存配置改完文件不重启不生效。如果你确认文件没问题但行为没变先试试重启。这个坑很隐蔽因为你会一直怀疑是自己写错了其实是缓存没刷新。8. 我踩过的几个配置坑和最终稳定下来的方案最后分享几个真实踩过的坑都是文档里不会写、但实际会遇到的。第一个坑是过度配置。刚开始我恨不得把每个字段都填满结果行为变得难以预测出问题也不知道是哪条配置导致的。后来砍到只剩必要的几项反而稳定了。配置的原则是“最小可用”需要时再加。第二个坑是模型分层没做全用最强模型。结果是简单任务慢得让人抓狂成本也高。分层之后日常体验提升非常明显而且成本降下来了。第三个坑是**AGENTS.md写太满**。前面提过三百行精简到四十行效果反而更好。上下文是稀缺资源别浪费在无关信息上。第四个坑是权限放太开。有一次让 Pi 自动执行它把一个我还没提交的改动覆盖了。从那以后不可逆操作我一律保留确认。这个习惯救过我很多次。最终我稳定下来的方案是settings.json只留默认模型、超时、权限边界和日志四项models.json做三层模型加简单路由AGENTS.md每个项目控制在五十行内只写结构、规范、命令APPEND_SYSTEM.md二十行以内只写跨项目偏好。这套配置用了大半年基本没再大改过。如果你刚开始配建议就从这套最小方案起步跑一段时间遇到具体问题再针对性调整。配置不是一次性的活是随着你使用习惯慢慢长出来的。下一篇我会聊实际使用中的工作流和提示词技巧那才是配置真正发挥价值的地方。