1. 为什么我要把 Pi 从玩具变成主力第一次接触 Pi 的人十有八九会经历同一个心理曲线装好、跑通、觉得挺新鲜然后……就没有然后了。它躺在终端里偶尔被想起来跑两句日常真正干活还是回到自己用惯的那套工具上。问题不在于 Pi 不够强而在于默认配置下的 Pi 只是一个能对话的壳子它不知道你的项目结构、不知道你的代码风格、不知道你踩过哪些坑每次都要从零开始解释背景用几次就累了。我自己的转折点是在一个多模块项目里。那段时间我每天要在三个仓库之间来回切每个仓库的构建命令、测试命令、目录约定都不一样。用默认 Pi 的时候我每次都得先花两分钟喂背景它才勉强给出能用的建议。后来我花了一个周末把settings.json、models.json、AGENTS.md、APPEND_SYSTEM.md这几个文件彻底捋了一遍情况完全变了——Pi 开始像一个熟悉我项目的老同事知道去哪找文件、知道用什么命令、知道哪些操作是禁区。这篇就是那次折腾的完整记录。我会把配置拆成四块讲清楚全局设置怎么定基调、模型清单怎么配才不浪费、AGENTS.md 怎么写才真正被读懂、APPEND_SYSTEM.md 怎么补上默认行为的短板。适合已经装好 Pi、但还没把它用顺手的人也适合那些配置改了一堆但感觉没生效的人——大概率是改错了地方或者优先级搞反了。先说一个反直觉的结论Pi 的配置不是越多越好而是越分层越好。全局配置管通用习惯项目配置管具体上下文两者职责不清就会出现在这个项目里好用、换个项目就抽风的情况。下面按这个思路一层层拆。2. 配置体系的整体设计与分层思路2.1 四个配置文件到底各管什么很多人第一次看到settings.json、models.json、AGENTS.md、APPEND_SYSTEM.md这四个文件是懵的名字都挺像功能边界模糊。我用一张表把它们的职责钉死文件作用域核心职责改动频率settings.json全局/项目行为开关、路径、超时、权限等运行时参数低配好基本不动models.json全局模型清单、别名、参数、上下文窗口中换模型时改AGENTS.md项目项目专属上下文、命令、约定、禁区高随项目演进APPEND_SYSTEM.md全局/项目追加到系统提示的补充规则中调教行为时改理解这张表的关键在于分清**机制和内容**。settings.json和models.json是机制层——它们决定 Pi 能做什么、用什么做AGENTS.md和APPEND_SYSTEM.md是内容层——它们决定 Pi 知道什么、怎么表现。机制层配错了内容层写得再好也白搭内容层偷懒机制层再精细也发挥不出来。我见过最常见的错误是把项目专属的命令写进APPEND_SYSTEM.md。这样做的后果是换个项目那些命令还在Pi 会一本正经地建议你运行一个根本不存在的脚本。项目相关的东西一律进AGENTS.md全局行为偏好才进APPEND_SYSTEM.md这条线必须划清。2.2 优先级与覆盖规则谁说了算分层配置绕不开优先级问题。Pi 的加载逻辑大致是项目级配置覆盖全局级配置后加载的覆盖先加载的。具体到四个文件settings.json项目目录下的会与全局的做合并同名键以项目级为准。models.json通常只在全局维护一份项目级很少单独覆盖除非你有特殊需求。AGENTS.md项目级是主力全局的那份作为兜底。APPEND_SYSTEM.md全局和项目级会叠加而不是覆盖这点要特别注意写重复了会啰嗦。提示调试配置是否生效时先确认你改的是项目级还是全局级。我踩过最蠢的坑就是在全局APPEND_SYSTEM.md里加了一条规则然后在项目里怎么测都没反应折腾半小时才发现项目级有一份同名文件把它盖住了。2.3 为什么选择文件驱动而不是命令行参数有人会问为什么不直接在启动命令后面跟一堆参数答案是可维护性和可复现性。命令行参数适合临时调试但日常使用中你需要的是打开终端就是配好的状态。文件驱动的好处是可版本控制AGENTS.md跟着项目走团队里谁拉下来都是同一套上下文。可复用全局配置一次写好所有项目受益。可审计出问题时能 diff能回滚命令行参数做不到。这也是我把配置当成项目资产而不是个人偏好的原因。下面进入具体操作。3. settings.json 与 models.json 的实操配置3.1 settings.json先把地基打稳settings.json是 Pi 的行为中枢。我建议第一次配置时只改真正影响体验的几项别一上来就抄一堆网上来的配置——很多参数你根本用不到改多了反而互相干扰。一个我实际在用的精简版本长这样字段名以你所用版本为准逻辑是通用的{ defaultModel: main, autoContext: true, maxContextFiles: 20, commandTimeout: 120000, confirmBeforeWrite: true, confirmBeforeExec: true, ignorePatterns: [ node_modules/**, dist/**, .git/**, *.log ] }逐项说下我的取舍逻辑defaultModel指向models.json里的别名而不是直接写模型全名。这样换模型时只改一处。autoContext打开后Pi 会自动把相关文件纳入上下文。这是变聪明的关键开关但配合maxContextFiles用否则大项目里它会一口气塞几十个文件既慢又贵。commandTimeout我设成 120 秒。默认值对跑测试、装依赖这类操作经常不够超时中断很烦。confirmBeforeWrite和confirmBeforeExec我强烈建议保持开启。让 Pi 自动改文件、自动跑命令听起来很爽直到它某次理解偏了把你的配置覆盖掉。确认一下的成本远低于恢复的成本。ignorePatterns是省钱的隐形功臣。把依赖目录、构建产物、日志排除掉Pi 就不会浪费上下文去读那些没意义的文件。注意ignorePatterns的写法跟.gitignore类似但不完全一样不同版本对通配符的支持有差异。写完最好用一个已知的大目录测一下确认真的被忽略了别想当然。3.2 models.json别把所有模型都塞进去models.json管理模型清单。新手容易犯的错是把能用的模型全列上结果选择困难还容易在关键时刻用错。我的做法是只保留三到四个有明确分工的别名{ models: { main: { provider: your-provider, model: your-main-model, contextWindow: 128000, temperature: 0.2 }, fast: { provider: your-provider, model: your-fast-model, contextWindow: 32000, temperature: 0.1 }, reason: { provider: your-provider, model: your-reasoning-model, contextWindow: 200000, temperature: 0.3 } } }分工逻辑是这样的main日常主力写代码、改 bug、解释逻辑都用它。温度调低0.2 左右保证输出稳定。fast干杂活比如格式化、重命名、写注释、生成提交信息。这类任务不需要强推理用快模型省钱省时间。reason遇到复杂架构问题、难缠的 bug 时才切过去。上下文窗口大能一次吃下更多文件。温度这个参数值得单独说。写代码场景下温度高于 0.5 输出会开始飘同样的输入两次结果差异明显不利于复现。我基本把主力模型的温度压在 0.1 到 0.3 之间。只有做头脑风暴、起名字这类创意任务时才会临时调高。contextWindow一定要填准。填大了Pi 以为能塞更多内容实际超出模型上限会报错或截断填小了白白浪费模型的容量。这个值查你所用模型的官方文档别猜。3.3 两个文件的联动别名是粘合剂settings.json里的defaultModel和models.json里的别名是一对。我强烈建议永远不要在 settings 里写模型全名全部走别名。原因很简单模型会更新换代全名会变别名不变。哪天你从 A 模型换到 B 模型只改models.json里main指向的那一行其他所有配置纹丝不动。这套别名机制还有个隐藏好处团队协作时统一认知。大家在讨论时说的是这个用 fast 跑就行而不是这个用某某某-3.5-turbo-0613 跑沟通成本低很多。4. AGENTS.md 与 APPEND_SYSTEM.md 的调教心法4.1 AGENTS.md让 Pi 秒懂你的项目如果说前两个文件是硬件配置AGENTS.md就是软件灵魂。它决定了 Pi 打开你的项目时第一眼看到什么、知道什么。我见过太多人把AGENTS.md写成一句这是一个 Node 项目然后抱怨 Pi 不好用——这相当于给新同事的入职文档只写了公司名字。一份真正好用的AGENTS.md我总结成五个模块第一项目一句话定位。别写这是一个 Web 应用这种废话要写清楚它解决什么问题、面向谁。比如这是一个面向中小团队的内部工单系统前端 React后端 Go数据库 PostgreSQL。Pi 拿到这句话后面所有建议都会围绕这个定位展开。第二目录结构速览。不用列全只列关键目录和它们的职责- cmd/ 各服务的入口 - internal/ 核心业务逻辑按领域分包 - web/ 前端代码 - scripts/ 构建与部署脚本 - docs/ 设计文档改架构前先看这里第三常用命令。这是AGENTS.md里价值最高的部分。把构建、测试、lint、启动开发环境的命令原样写进去- 安装依赖make deps - 跑测试make test单测/ make test-e2e端到端 - 本地启动make dev默认端口 8080 - 代码检查make lint提交前必须过写清楚之后Pi 就不会再瞎猜你试试 npm test而是直接给你项目里真实存在的命令。这一条能省掉大量来回确认的时间。第四代码约定。团队里那些只可意会的规矩全部显式写出来。比如错误处理用哪种模式、日志怎么打、命名用驼峰还是下划线、提交信息什么格式。这些约定不写Pi 就会按它的默认习惯来产出跟你项目风格不一致的代码你还得手动改。第五禁区与红线。明确告诉 Pi 哪些事不能做。比如不要直接改migrations/下的历史迁移文件、不要动vendor/目录、生产配置在config/prod/任何情况下不要读取或修改。这一块是安全网写得越具体越好。实操心得AGENTS.md不要一次写完就扔那。我习惯每次发现 Pi 犯了重复性错误就往里补一条规则。比如它老是忘记跑 lint我就在命令区加一句任何代码改动后必须执行make lint。这份文件是养出来的不是写出来的。4.2 APPEND_SYSTEM.md补上默认行为的短板APPEND_SYSTEM.md的内容会被追加到系统提示后面用来微调 Pi 的性格和习惯。它和AGENTS.md的区别在于AGENTS.md讲的是这个项目是什么APPEND_SYSTEM.md讲的是你作为助手应该怎么做。我在这份文件里放的东西主要是三类输出风格约束。比如回答代码问题时先给结论再给解释不要长篇铺垫、涉及多步骤操作时用有序列表不要写成大段文字。这些偏好写进去Pi 的输出会明显更贴合你的阅读习惯。工作流程约束。比如修改代码前先说明你打算改哪些文件、为什么、遇到不确定的地方先提问不要自行假设。这类规则能显著降低 Pi 自作主张的概率。安全与边界约束。比如执行任何删除操作前必须二次确认、不要在没有明确指令的情况下安装新依赖。这是最后一道防线。一个我实际在用的片段- 回答优先给可执行的结论解释放在后面。 - 改动超过三个文件时先列出改动清单再动手。 - 不确定的接口或配置先问不要猜。 - 任何破坏性操作删除、覆盖、重置必须明确确认。注意APPEND_SYSTEM.md是叠加的全局一份、项目一份会同时生效。所以别在两边写重复的规则否则 Pi 会收到两遍同样的指令虽然不至于出错但浪费上下文。我的做法是全局放通用风格项目放该项目特有的流程要求。4.3 两个文件的配合一个管知道一个管怎么做把AGENTS.md和APPEND_SYSTEM.md的关系理清楚配置就成功了一大半。打个比方AGENTS.md是给新员工的项目手册告诉他这个项目的历史、结构、规矩APPEND_SYSTEM.md是岗位行为规范告诉他作为助手应该怎么说话、怎么做事。两者配合得好效果是叠加的。举个例子AGENTS.md里写了提交前必须跑make lintAPPEND_SYSTEM.md里写了改动完成后主动提醒下一步操作。那么 Pi 在你改完代码后会主动说改动完成建议执行make lint验证。这就是配置带来的主动性而不是每次都要你提醒。5. 常见问题与排查技巧实录5.1 配置改了不生效按这个顺序查这是最高频的问题。我整理了一个排查顺序基本能覆盖九成情况现象可能原因排查动作改了没反应改错层级全局 vs 项目确认文件路径项目级优先部分生效部分不生效被更高优先级覆盖检查是否有同名文件规则重复出现全局和项目都写了去重只留一处模型切换无效别名拼写不一致核对 settings 与 models 的别名上下文塞太多ignorePatterns 没生效用大目录实测忽略规则排查的核心思路是从加载顺序倒推。Pi 先读全局再读项目后读的覆盖先读的。所以当你发现改了没用第一反应应该是是不是有个更高优先级的文件把它盖了。5.2 上下文爆炸Pi 变慢变贵的元凶用一段时间后很多人会发现 Pi 越来越慢、越来越贵。八成是上下文失控。常见诱因有三个ignorePatterns 没配好Pi 把node_modules里的文件也读进去了。maxContextFiles 设太大一次塞几十个文件。AGENTS.md 写太长本身占用了大量上下文。我的处理办法是给AGENTS.md设一个心理上限——控制在 200 行以内。超过这个长度说明你把太多细节塞进去了应该把详细文档放到docs/里AGENTS.md只留索引和关键约定。Pi 需要细节时会自己去读docs/不需要你一次性全喂给它。实操心得我习惯在AGENTS.md末尾加一句详细设计见docs/architecture.md需要时再读。这样既给了 Pi 线索又不占用默认上下文。实测下来响应速度和成本都有明显改善。5.3 模型选错的典型场景模型选错不会报错但会让你觉得Pi 今天怎么这么笨。几个典型场景用 fast 模型做架构设计快模型推理能力弱给出的方案往往浮于表面。复杂问题一定切reason。用 reason 模型做格式化杀鸡用牛刀又慢又贵。杂活交给fast。温度设太高写代码输出不稳定同样的需求两次结果不一样没法复现。我的习惯是默认用 main遇到卡壳手动切 reason杂活切 fast。切换动作要养成肌肉记忆别一个模型用到底。5.4 一份可以直接抄的配置检查清单最后给一份我每次新项目初始化时都会过一遍的清单[ ]settings.json里defaultModel指向别名而非全名[ ]confirmBeforeWrite和confirmBeforeExec已开启[ ]ignorePatterns覆盖了依赖、构建产物、日志目录[ ]models.json里每个别名都填了准确的contextWindow[ ] 主力模型温度在 0.1 到 0.3 之间[ ]AGENTS.md包含定位、目录、命令、约定、禁区五块[ ]AGENTS.md长度控制在 200 行以内[ ]APPEND_SYSTEM.md全局和项目无重复规则[ ] 用一个真实任务跑一遍确认命令和风格都符合预期这份清单看着琐碎但每一条背后都是我踩过的坑。尤其是最后一条——配置完一定要用真实任务验证别配完就以为万事大吉。我见过太多配置看起来很完美、实际一跑全是问题的情况。把这几块配好之后Pi 才算真正从玩具变成了主力。它不再需要你每次从头解释背景而是带着对你项目的理解直接进入工作状态。这个转变带来的效率提升远比换一个更强的模型明显。后续如果要做更细的调教比如针对特定语言或框架的专属规则思路是一样的先想清楚这条规则属于机制还是内容再决定它该进哪个文件。