1. 为什么配置才是把 Pi 变成主力的第一道分水岭很多人第一次接触 Pi 这类编码代理工具注意力全在它能不能写代码它能不能跑命令上结果装完用两天就丢到一边回头还吐槽也就那样。我踩过这个坑后来才想明白一件事决定一个代理工具能不能成为你日常主力的从来不是模型本身有多强而是配置层有没有把它调教成懂你的状态。Pi 这个工具的设计思路很有意思它把绝大部分可定制的东西都收敛到了几个纯文本文件里——settings.json、models.json、AGENTS.md、APPEND_SYSTEM.md。这四个文件基本构成了 Pi 的人格骨架和行为边界。你不动它们Pi 就是一个通用助手谁用都一样你认真调一遍它才会变成你的主力工具知道你的项目结构、你的代码风格、你踩过的那些约定俗成的坑。这篇是配置篇我打算把整个配置体系从头到尾拆一遍。适合两类人看一类是刚装上 Pi、还在纠结那几个 json 文件到底填什么的另一类是已经用了一阵子但总觉得它不够顺手、想系统性地把配置理顺的。我会讲清楚每个文件管什么、为什么这么设计、参数怎么算、哪些地方最容易翻车以及我自己实测下来比较稳的一套配置思路。全程按从业者交流的口吻来不整那些虚的。先说结论性的判断配置的核心不是填满而是分层。全局层放通用偏好项目层放具体约定系统提示层放行为约束模型层放能力路由。四层各司其职互不打架这才是把 Pi 调教成主力的正确姿势。下面逐层拆。2. 四个配置文件到底各管什么先建立整体心智模型在动手改任何一个文件之前你得先在脑子里建立一张地图。否则很容易出现我把这条规则写哪来着的混乱最后四个文件里塞了一堆重复又互相矛盾的内容Pi 的行为反而更飘。2.1 settings.json全局行为开关与默认值settings.json是 Pi 的总控台。它管的是那些跟具体项目无关、但影响整体行为的东西。典型内容包括默认使用哪个模型、界面的一些显示偏好、工具调用的超时时间、是否开启某些自动行为、日志级别等等。你可以把它理解成手机的设置App——里面全是开关和默认值改一次全局生效。它的特点是作用域最大、优先级相对较低。也就是说如果项目层有更具体的设定通常会覆盖全局层的同名项。这个就近覆盖的逻辑非常关键后面讲冲突排查时会反复用到。我个人的习惯是settings.json里只放我这个人一贯的偏好比如我习惯用哪个模型做日常编码、我讨厌自动执行危险命令、我希望输出简洁一点。凡是这个项目特有的东西一律不往这里塞。2.2 models.json模型清单与能力路由models.json管的是模型这一层。它定义了你手上有哪些模型可用、每个模型的接入参数比如接口地址、认证方式的环境变量名、上下文窗口大小、是否支持工具调用等以及一些路由规则。为什么模型要单独一个文件因为模型是会变的。今天你用 A 模型写代码明天可能换成 B 模型做重构后天又要用 C 模型处理长文档。如果把模型配置混在settings.json里每次换模型都要动总控台很容易误伤其他设置。单独拆出来换模型就是改一个文件的事干净利落。这里有个容易被忽略的点上下文窗口大小这个参数一定要填准。填大了Pi 会以为能塞下更多内容结果请求超限报错填小了明明能放下的历史被提前截断代理就失忆了。这个后面会专门讲怎么估算。2.3 AGENTS.md项目级的入职手册AGENTS.md是我认为四个文件里性价比最高的一个。它本质上是写给代理看的项目说明书。新来的同事入职你会给他讲项目结构、代码规范、怎么跑测试、哪些目录别碰AGENTS.md就是把这套话写给 Pi 看。它通常放在项目根目录Pi 启动时会读取它把里面的内容作为上下文的一部分。所以它管的是**这个项目里该怎么干活**目录结构说明、构建和测试命令、代码风格约定、提交信息格式、已知的坑等等。我见过太多人把AGENTS.md写成一句这是一个 React 项目就完事了然后抱怨 Pi 老是乱改文件。问题不在 Pi在于你没告诉它边界在哪。一份好的AGENTS.md能让 Pi 的输出质量肉眼可见地提升一个档次。2.4 APPEND_SYSTEM.md追加到系统提示的行为约束APPEND_SYSTEM.md是追加在系统提示词后面的内容。系统提示词是工具内置的、定义 Pi 基本身份和行为准则的那段文字你改不了它但可以通过这个文件追加你的要求。它和AGENTS.md的区别在于作用层级AGENTS.md偏项目知识APPEND_SYSTEM.md偏行为准则。比如回答前先确认理解了我的意图不要在没有明确指令时执行破坏性命令解释代码时用中文这类跨项目的、偏风格和纪律的要求放这里更合适。注意APPEND_SYSTEM.md的内容会进入每一次请求的系统提示所以它越长占用的上下文越多。别把它当成许愿池什么都往里塞。控制在合理长度只放真正影响行为的关键约束。把四个文件的分工理清楚之后你会发现配置这件事突然变得有章法了。接下来逐个深入。3. settings.json 实战把全局偏好一次调到位这一节我按我实际会改哪些项的顺序来讲而不是照着文档罗列。因为文档里几十个字段真正天天用的就那么几个。3.1 默认模型与降级策略settings.json里最该先定的就是默认模型。我的建议是默认模型选综合能力均衡、响应速度可接受的那个而不是能力最强但最慢最贵的那个。原因很实际——日常编码里 80% 的操作是读文件、改小函数、跑测试这些用均衡模型完全够用顶配模型纯属浪费还拖慢节奏。真正需要顶配模型的复杂重构临时切换就行。如果工具支持降级策略比如主模型不可用时自动切备用一定要配上。我遇到过好几次主模型接口临时抽风如果没有降级整个工作流就卡死了。降级链一般配两到三级就够配太多反而增加不确定性。3.2 工具调用的安全开关这是我最看重的一块。Pi 这类工具能执行命令、能改文件能力越大风险越大。settings.json里通常会有控制是否自动执行命令是否需要确认的开关。我的配置原则很简单读操作放开写操作和危险操作收紧。读文件、列目录、搜索这类无副作用的操作让它自动跑别每次都弹确认否则你一天要点几百次同意很快就烦了。但删除文件、执行带副作用的脚本、推送到远端这类操作必须保留确认环节。有些工具支持命令白名单/黑名单机制。白名单是只允许跑这些黑名单是这些不许跑。我倾向于白名单为主——把常用的安全命令比如ls、cat、grep、项目里的测试命令加进去其余一律走确认。这样既流畅又安全。3.3 超时与重试参数怎么定超时时间这个参数很多人直接抄默认值其实值得根据你的实际网络和任务类型调一调。普通请求超时一般 30 到 60 秒够用。太短了稍微大点的文件处理就超时太长了真卡住的时候你要干等。长任务超时如果 Pi 会跑构建、跑测试这类耗时操作这个要单独设长一点比如 5 到 10 分钟。重试次数建议 2 到 3 次。重试太多遇到持续性故障会一直卡着重试浪费时间不重试偶发的网络抖动就直接失败。这里有个经验重试要配指数退避。也就是第一次失败等 1 秒重试第二次等 2 秒第三次等 4 秒。如果工具支持这个配置一定开上。因为很多接口故障是瞬时的立刻重试往往还是失败等几秒反而就通了。3.4 输出与日志偏好日志级别建议日常用info排查问题时临时调到debug。一直开debug会让日志文件疯长而且刷屏严重反而看不清关键信息。输出风格上我偏好让 Pi 简洁一点别每次都长篇大论解释。这个偏好可以写在settings.json也可以写在APPEND_SYSTEM.md看工具支持哪种。我一般放后者因为它是行为约束性质的东西。实操心得改完settings.json后别急着大改项目先在一个小项目或测试目录里跑几个典型任务确认行为符合预期。配置文件的错误往往不会立刻报错而是以行为诡异的形式出现早发现早省事。4. models.json 深挖模型清单、上下文窗口与路由models.json是四个文件里最技术的一个也是最容易配错的。这一节把关键参数一个个拆开讲。4.1 模型条目的基本结构一个模型条目通常包含这些字段模型标识名、接口地址、认证信息一般是引用环境变量别硬编码密钥、上下文窗口大小、最大输出长度、是否支持工具调用、是否支持视觉输入等。这里重点说两个坑第一认证信息千万别硬编码。密钥写死在文件里一旦这个文件被提交到代码仓库就是安全事故。正确做法是引用环境变量比如apiKeyEnv: MY_MODEL_KEY然后密钥放在环境变量里。这样文件可以安全地分享和版本管理。第二模型标识名要和接口实际接受的名称完全一致。差一个字符都会报模型不存在。我见过有人把gpt-4o写成gpt4o排查了半天。4.2 上下文窗口大小怎么估算这是最需要算的一个参数。上下文窗口指的是模型一次能处理的最大 token 数包括输入和输出。估算方法中文大约 1 个汉字对应 1 到 2 个 token英文大约 1 个单词对应 1.3 个 token代码介于两者之间。一个 1000 行的代码文件大概在 8000 到 15000 token 之间。为什么必须填准因为 Pi 需要根据这个值来决定能塞多少历史对话、能读多大的文件。填大了请求超限接口直接报错填小了明明能放下的上下文被提前丢弃代理就记不住前面聊了什么。我的做法是填模型官方标称的窗口大小但实际使用时留 20% 余量。因为系统提示、工具定义这些也要占 token标称值不等于你能全用上。4.3 能力路由什么任务用什么模型如果工具支持按任务类型路由模型这是提升效率的利器。我的路由思路任务类型推荐模型档位理由读代码、搜索、简单问答轻量快速模型这类任务不需要强推理快最重要日常编码、改函数均衡模型能力够用速度可接受复杂重构、架构设计顶配模型需要强推理慢一点值得长文档处理大窗口模型窗口大小是硬约束路由配好了日常体验会顺很多——简单任务秒回复杂任务才动用重武器。4.4 多模型切换的实操建议我建议在models.json里至少配两个模型一个日常主力一个备用/顶配。切换方式看工具支持有的是改配置有的是命令行参数有的是对话里直接指定。注意切换模型后之前对话的上下文可能不兼容不同模型的 token 计算方式不同。如果发现切换后行为异常开个新会话往往比硬撑着继续更省事。5. AGENTS.md 怎么写才真正有用AGENTS.md是投入产出比最高的文件但也是最容易被写废的。我见过两种极端一种是只有一行这是一个项目另一种是复制了整个 wiki 进去。都不对。5.1 该写什么四类核心信息一份实用的AGENTS.md我建议包含这四块第一项目结构速览。用几行说清楚主要目录是干嘛的。比如src/是源码tests/是测试scripts/是构建脚本vendor/是第三方代码不要改。这一条能避免 Pi 在错误的地方乱翻。第二构建与测试命令。明确写出怎么装依赖、怎么跑测试、怎么构建。Pi 需要跑验证的时候直接照这个来不用猜。比如跑测试用npm test跑单个测试文件用npm test -- 文件名。第三代码风格约定。比如缩进用几个空格、命名用驼峰还是下划线、import 怎么排序、注释用中文还是英文。这些约定写清楚Pi 生成的代码才能和现有代码风格一致减少你手动调整的工作量。第四已知的坑和禁忌。比如不要动config/legacy/目录改数据库 schema 前必须先看迁移文件某个函数有副作用调用要小心。这些是项目里口口相传的经验写进去 Pi 就不会踩。5.2 怎么写给代理看的说明书不是给人看的文档关键心态转变AGENTS.md的读者是 Pi不是人。所以写法要指令化而不是叙述化。对比一下叙述化差本项目采用了模块化的架构设计各个模块之间通过接口进行通信……指令化好模块间通信统一走src/interfaces/下的接口定义不要直接跨模块 import 内部实现。后者直接告诉 Pi该怎么做不该怎么做前者只是描述Pi 读完不知道该干嘛。5.3 长度控制够用就好AGENTS.md会进入上下文所以不是越长越好。我的经验是控制在 500 到 1500 字之间。这个长度足够说清楚关键约定又不会占用太多上下文。如果项目特别复杂可以分层根目录放通用的子目录放该子目录特有的。Pi 读取时通常会合并就近的优先。实操心得AGENTS.md要跟着项目演进。每次你发现 Pi 犯了同一个错误就想想是不是该往AGENTS.md里加一条约定。用久了这个文件就成了项目的活文档新人来了也能直接看。6. APPEND_SYSTEM.md给 Pi 立规矩的地方如果说AGENTS.md是项目知识那APPEND_SYSTEM.md就是行为纪律。它追加在系统提示后面影响 Pi 的每一次响应。6.1 适合放什么内容我总结了几类适合放这里的东西交互风格比如回答简洁不要复述我的问题解释代码时用中文不确定的时候直接说不确定不要编。行为约束比如执行破坏性操作前必须确认不要在没有明确指令时修改多个文件改代码前先读相关文件。工作流程比如改完代码后主动跑相关测试提交前检查是否有调试代码残留。安全边界比如不要读取.env等敏感文件不要执行来源不明的脚本。6.2 不适合放什么项目特有的东西那些放AGENTS.md。模型参数那些放models.json。全局开关那些放settings.json。超长的规则清单规则太多Pi 反而记不住重点还占上下文。挑最重要的几条。6.3 措辞技巧正向指令优于负向禁止这是个很实用的技巧。心理学上有个说法人和模型对不要做 X的执行力往往不如要做 Y。因为不要做 X只说了禁止没说替代方案。对比负向差不要写太长的函数。正向好函数尽量控制在 50 行以内超过就拆分。后者给了明确的标准和动作Pi 更容易执行到位。注意APPEND_SYSTEM.md里的规则如果和AGENTS.md冲突通常系统提示层的优先级更高。所以别在两个文件里写互相矛盾的要求否则行为会很飘。7. 配置冲突与优先级出问题时怎么排查配置多了冲突是难免的。这一节讲清楚优先级逻辑和排查方法。7.1 优先级的一般规律大多数工具遵循就近覆盖原则从高到低大致是命令行参数临时指定优先级最高项目级配置AGENTS.md、项目内的 settings全局配置用户目录下的 settings工具内置默认值优先级最低APPEND_SYSTEM.md因为是追加到系统提示通常独立于这个链条但它的内容会和系统提示合并冲突时以更具体的指令为准。7.2 常见冲突场景速查现象可能原因排查方向改了配置没生效被更高优先级覆盖检查项目级是否有同名配置行为时好时坏两个文件规则矛盾对比AGENTS.md和APPEND_SYSTEM.md模型切换后异常上下文不兼容开新会话老是超时超时参数太小调大settings.json里的超时上下文被截断窗口大小填小了核对models.json的窗口值7.3 排查的基本方法我的排查套路是从大到小逐层排除先确认是不是全局配置的问题——临时用命令行参数覆盖看行为是否变化。再确认是不是项目配置的问题——换个干净目录跑同样的任务。最后看系统提示层——临时清空APPEND_SYSTEM.md试试。一层层排除很快就能定位到是哪个文件在捣乱。实操心得养成给配置文件写注释的习惯如果格式支持。比如在settings.json里用注释说明这个超时值是因为某次构建任务调的。过几个月回头看你会感谢当时的自己。8. 一套可直接抄的配置模板与落地步骤讲了这么多原理最后给一套我实际在用的配置思路你可以直接参考。8.1 落地步骤先配models.json把常用模型列进去认证走环境变量窗口大小填准。再配settings.json定默认模型、安全开关、超时重试。然后写AGENTS.md按项目结构、命令、风格、禁忌四块来。最后写APPEND_SYSTEM.md放交互风格和行为约束控制在合理长度。小范围验证在测试目录跑几个典型任务确认行为符合预期。迭代用一段时间发现哪里不顺手就回去改对应文件。8.2 关键参数速查参数建议值说明普通请求超时30-60 秒视网络情况调长任务超时5-10 分钟构建、测试用重试次数2-3 次配指数退避日志级别info排查时临时调 debug上下文余量留 20%系统提示也占 tokenAGENTS.md 长度500-1500 字够用就好8.3 我踩过的几个坑坑一把密钥写进models.json提交了。后来改成环境变量引用并且加了.gitignore。这个教训很深刻密钥泄露的后果不用多说。坑二AGENTS.md写成了项目介绍。结果 Pi 读完还是不知道该干嘛。改成指令化写法后效果立竿见影。坑三上下文窗口填了标称最大值。结果经常请求超限。后来留了 20% 余量稳定多了。坑四APPEND_SYSTEM.md塞了太多规则。Pi 反而抓不住重点。精简到几条核心约束后行为清晰多了。配置这件事说到底就是把你脑子里的隐性知识变成Pi 能读到的显性规则。你越舍得花时间把项目约定、行为偏好写清楚Pi 就越像你的主力。反过来指望它自己猜那永远只能是个通用助手。这套配置调完你会发现 Pi 从能用变成了好用这个转变是实实在在的。 Pi 编码代理配置实战：settings.json、models.json、AGENTS.md 与 APPEND_SYSTEM.md 分层调优指南
1. 为什么配置才是把 Pi 变成主力的第一道分水岭很多人第一次接触 Pi 这类编码代理工具注意力全在它能不能写代码它能不能跑命令上结果装完用两天就丢到一边回头还吐槽也就那样。我踩过这个坑后来才想明白一件事决定一个代理工具能不能成为你日常主力的从来不是模型本身有多强而是配置层有没有把它调教成懂你的状态。Pi 这个工具的设计思路很有意思它把绝大部分可定制的东西都收敛到了几个纯文本文件里——settings.json、models.json、AGENTS.md、APPEND_SYSTEM.md。这四个文件基本构成了 Pi 的人格骨架和行为边界。你不动它们Pi 就是一个通用助手谁用都一样你认真调一遍它才会变成你的主力工具知道你的项目结构、你的代码风格、你踩过的那些约定俗成的坑。这篇是配置篇我打算把整个配置体系从头到尾拆一遍。适合两类人看一类是刚装上 Pi、还在纠结那几个 json 文件到底填什么的另一类是已经用了一阵子但总觉得它不够顺手、想系统性地把配置理顺的。我会讲清楚每个文件管什么、为什么这么设计、参数怎么算、哪些地方最容易翻车以及我自己实测下来比较稳的一套配置思路。全程按从业者交流的口吻来不整那些虚的。先说结论性的判断配置的核心不是填满而是分层。全局层放通用偏好项目层放具体约定系统提示层放行为约束模型层放能力路由。四层各司其职互不打架这才是把 Pi 调教成主力的正确姿势。下面逐层拆。2. 四个配置文件到底各管什么先建立整体心智模型在动手改任何一个文件之前你得先在脑子里建立一张地图。否则很容易出现我把这条规则写哪来着的混乱最后四个文件里塞了一堆重复又互相矛盾的内容Pi 的行为反而更飘。2.1 settings.json全局行为开关与默认值settings.json是 Pi 的总控台。它管的是那些跟具体项目无关、但影响整体行为的东西。典型内容包括默认使用哪个模型、界面的一些显示偏好、工具调用的超时时间、是否开启某些自动行为、日志级别等等。你可以把它理解成手机的设置App——里面全是开关和默认值改一次全局生效。它的特点是作用域最大、优先级相对较低。也就是说如果项目层有更具体的设定通常会覆盖全局层的同名项。这个就近覆盖的逻辑非常关键后面讲冲突排查时会反复用到。我个人的习惯是settings.json里只放我这个人一贯的偏好比如我习惯用哪个模型做日常编码、我讨厌自动执行危险命令、我希望输出简洁一点。凡是这个项目特有的东西一律不往这里塞。2.2 models.json模型清单与能力路由models.json管的是模型这一层。它定义了你手上有哪些模型可用、每个模型的接入参数比如接口地址、认证方式的环境变量名、上下文窗口大小、是否支持工具调用等以及一些路由规则。为什么模型要单独一个文件因为模型是会变的。今天你用 A 模型写代码明天可能换成 B 模型做重构后天又要用 C 模型处理长文档。如果把模型配置混在settings.json里每次换模型都要动总控台很容易误伤其他设置。单独拆出来换模型就是改一个文件的事干净利落。这里有个容易被忽略的点上下文窗口大小这个参数一定要填准。填大了Pi 会以为能塞下更多内容结果请求超限报错填小了明明能放下的历史被提前截断代理就失忆了。这个后面会专门讲怎么估算。2.3 AGENTS.md项目级的入职手册AGENTS.md是我认为四个文件里性价比最高的一个。它本质上是写给代理看的项目说明书。新来的同事入职你会给他讲项目结构、代码规范、怎么跑测试、哪些目录别碰AGENTS.md就是把这套话写给 Pi 看。它通常放在项目根目录Pi 启动时会读取它把里面的内容作为上下文的一部分。所以它管的是**这个项目里该怎么干活**目录结构说明、构建和测试命令、代码风格约定、提交信息格式、已知的坑等等。我见过太多人把AGENTS.md写成一句这是一个 React 项目就完事了然后抱怨 Pi 老是乱改文件。问题不在 Pi在于你没告诉它边界在哪。一份好的AGENTS.md能让 Pi 的输出质量肉眼可见地提升一个档次。2.4 APPEND_SYSTEM.md追加到系统提示的行为约束APPEND_SYSTEM.md是追加在系统提示词后面的内容。系统提示词是工具内置的、定义 Pi 基本身份和行为准则的那段文字你改不了它但可以通过这个文件追加你的要求。它和AGENTS.md的区别在于作用层级AGENTS.md偏项目知识APPEND_SYSTEM.md偏行为准则。比如回答前先确认理解了我的意图不要在没有明确指令时执行破坏性命令解释代码时用中文这类跨项目的、偏风格和纪律的要求放这里更合适。注意APPEND_SYSTEM.md的内容会进入每一次请求的系统提示所以它越长占用的上下文越多。别把它当成许愿池什么都往里塞。控制在合理长度只放真正影响行为的关键约束。把四个文件的分工理清楚之后你会发现配置这件事突然变得有章法了。接下来逐个深入。3. settings.json 实战把全局偏好一次调到位这一节我按我实际会改哪些项的顺序来讲而不是照着文档罗列。因为文档里几十个字段真正天天用的就那么几个。3.1 默认模型与降级策略settings.json里最该先定的就是默认模型。我的建议是默认模型选综合能力均衡、响应速度可接受的那个而不是能力最强但最慢最贵的那个。原因很实际——日常编码里 80% 的操作是读文件、改小函数、跑测试这些用均衡模型完全够用顶配模型纯属浪费还拖慢节奏。真正需要顶配模型的复杂重构临时切换就行。如果工具支持降级策略比如主模型不可用时自动切备用一定要配上。我遇到过好几次主模型接口临时抽风如果没有降级整个工作流就卡死了。降级链一般配两到三级就够配太多反而增加不确定性。3.2 工具调用的安全开关这是我最看重的一块。Pi 这类工具能执行命令、能改文件能力越大风险越大。settings.json里通常会有控制是否自动执行命令是否需要确认的开关。我的配置原则很简单读操作放开写操作和危险操作收紧。读文件、列目录、搜索这类无副作用的操作让它自动跑别每次都弹确认否则你一天要点几百次同意很快就烦了。但删除文件、执行带副作用的脚本、推送到远端这类操作必须保留确认环节。有些工具支持命令白名单/黑名单机制。白名单是只允许跑这些黑名单是这些不许跑。我倾向于白名单为主——把常用的安全命令比如ls、cat、grep、项目里的测试命令加进去其余一律走确认。这样既流畅又安全。3.3 超时与重试参数怎么定超时时间这个参数很多人直接抄默认值其实值得根据你的实际网络和任务类型调一调。普通请求超时一般 30 到 60 秒够用。太短了稍微大点的文件处理就超时太长了真卡住的时候你要干等。长任务超时如果 Pi 会跑构建、跑测试这类耗时操作这个要单独设长一点比如 5 到 10 分钟。重试次数建议 2 到 3 次。重试太多遇到持续性故障会一直卡着重试浪费时间不重试偶发的网络抖动就直接失败。这里有个经验重试要配指数退避。也就是第一次失败等 1 秒重试第二次等 2 秒第三次等 4 秒。如果工具支持这个配置一定开上。因为很多接口故障是瞬时的立刻重试往往还是失败等几秒反而就通了。3.4 输出与日志偏好日志级别建议日常用info排查问题时临时调到debug。一直开debug会让日志文件疯长而且刷屏严重反而看不清关键信息。输出风格上我偏好让 Pi 简洁一点别每次都长篇大论解释。这个偏好可以写在settings.json也可以写在APPEND_SYSTEM.md看工具支持哪种。我一般放后者因为它是行为约束性质的东西。实操心得改完settings.json后别急着大改项目先在一个小项目或测试目录里跑几个典型任务确认行为符合预期。配置文件的错误往往不会立刻报错而是以行为诡异的形式出现早发现早省事。4. models.json 深挖模型清单、上下文窗口与路由models.json是四个文件里最技术的一个也是最容易配错的。这一节把关键参数一个个拆开讲。4.1 模型条目的基本结构一个模型条目通常包含这些字段模型标识名、接口地址、认证信息一般是引用环境变量别硬编码密钥、上下文窗口大小、最大输出长度、是否支持工具调用、是否支持视觉输入等。这里重点说两个坑第一认证信息千万别硬编码。密钥写死在文件里一旦这个文件被提交到代码仓库就是安全事故。正确做法是引用环境变量比如apiKeyEnv: MY_MODEL_KEY然后密钥放在环境变量里。这样文件可以安全地分享和版本管理。第二模型标识名要和接口实际接受的名称完全一致。差一个字符都会报模型不存在。我见过有人把gpt-4o写成gpt4o排查了半天。4.2 上下文窗口大小怎么估算这是最需要算的一个参数。上下文窗口指的是模型一次能处理的最大 token 数包括输入和输出。估算方法中文大约 1 个汉字对应 1 到 2 个 token英文大约 1 个单词对应 1.3 个 token代码介于两者之间。一个 1000 行的代码文件大概在 8000 到 15000 token 之间。为什么必须填准因为 Pi 需要根据这个值来决定能塞多少历史对话、能读多大的文件。填大了请求超限接口直接报错填小了明明能放下的上下文被提前丢弃代理就记不住前面聊了什么。我的做法是填模型官方标称的窗口大小但实际使用时留 20% 余量。因为系统提示、工具定义这些也要占 token标称值不等于你能全用上。4.3 能力路由什么任务用什么模型如果工具支持按任务类型路由模型这是提升效率的利器。我的路由思路任务类型推荐模型档位理由读代码、搜索、简单问答轻量快速模型这类任务不需要强推理快最重要日常编码、改函数均衡模型能力够用速度可接受复杂重构、架构设计顶配模型需要强推理慢一点值得长文档处理大窗口模型窗口大小是硬约束路由配好了日常体验会顺很多——简单任务秒回复杂任务才动用重武器。4.4 多模型切换的实操建议我建议在models.json里至少配两个模型一个日常主力一个备用/顶配。切换方式看工具支持有的是改配置有的是命令行参数有的是对话里直接指定。注意切换模型后之前对话的上下文可能不兼容不同模型的 token 计算方式不同。如果发现切换后行为异常开个新会话往往比硬撑着继续更省事。5. AGENTS.md 怎么写才真正有用AGENTS.md是投入产出比最高的文件但也是最容易被写废的。我见过两种极端一种是只有一行这是一个项目另一种是复制了整个 wiki 进去。都不对。5.1 该写什么四类核心信息一份实用的AGENTS.md我建议包含这四块第一项目结构速览。用几行说清楚主要目录是干嘛的。比如src/是源码tests/是测试scripts/是构建脚本vendor/是第三方代码不要改。这一条能避免 Pi 在错误的地方乱翻。第二构建与测试命令。明确写出怎么装依赖、怎么跑测试、怎么构建。Pi 需要跑验证的时候直接照这个来不用猜。比如跑测试用npm test跑单个测试文件用npm test -- 文件名。第三代码风格约定。比如缩进用几个空格、命名用驼峰还是下划线、import 怎么排序、注释用中文还是英文。这些约定写清楚Pi 生成的代码才能和现有代码风格一致减少你手动调整的工作量。第四已知的坑和禁忌。比如不要动config/legacy/目录改数据库 schema 前必须先看迁移文件某个函数有副作用调用要小心。这些是项目里口口相传的经验写进去 Pi 就不会踩。5.2 怎么写给代理看的说明书不是给人看的文档关键心态转变AGENTS.md的读者是 Pi不是人。所以写法要指令化而不是叙述化。对比一下叙述化差本项目采用了模块化的架构设计各个模块之间通过接口进行通信……指令化好模块间通信统一走src/interfaces/下的接口定义不要直接跨模块 import 内部实现。后者直接告诉 Pi该怎么做不该怎么做前者只是描述Pi 读完不知道该干嘛。5.3 长度控制够用就好AGENTS.md会进入上下文所以不是越长越好。我的经验是控制在 500 到 1500 字之间。这个长度足够说清楚关键约定又不会占用太多上下文。如果项目特别复杂可以分层根目录放通用的子目录放该子目录特有的。Pi 读取时通常会合并就近的优先。实操心得AGENTS.md要跟着项目演进。每次你发现 Pi 犯了同一个错误就想想是不是该往AGENTS.md里加一条约定。用久了这个文件就成了项目的活文档新人来了也能直接看。6. APPEND_SYSTEM.md给 Pi 立规矩的地方如果说AGENTS.md是项目知识那APPEND_SYSTEM.md就是行为纪律。它追加在系统提示后面影响 Pi 的每一次响应。6.1 适合放什么内容我总结了几类适合放这里的东西交互风格比如回答简洁不要复述我的问题解释代码时用中文不确定的时候直接说不确定不要编。行为约束比如执行破坏性操作前必须确认不要在没有明确指令时修改多个文件改代码前先读相关文件。工作流程比如改完代码后主动跑相关测试提交前检查是否有调试代码残留。安全边界比如不要读取.env等敏感文件不要执行来源不明的脚本。6.2 不适合放什么项目特有的东西那些放AGENTS.md。模型参数那些放models.json。全局开关那些放settings.json。超长的规则清单规则太多Pi 反而记不住重点还占上下文。挑最重要的几条。6.3 措辞技巧正向指令优于负向禁止这是个很实用的技巧。心理学上有个说法人和模型对不要做 X的执行力往往不如要做 Y。因为不要做 X只说了禁止没说替代方案。对比负向差不要写太长的函数。正向好函数尽量控制在 50 行以内超过就拆分。后者给了明确的标准和动作Pi 更容易执行到位。注意APPEND_SYSTEM.md里的规则如果和AGENTS.md冲突通常系统提示层的优先级更高。所以别在两个文件里写互相矛盾的要求否则行为会很飘。7. 配置冲突与优先级出问题时怎么排查配置多了冲突是难免的。这一节讲清楚优先级逻辑和排查方法。7.1 优先级的一般规律大多数工具遵循就近覆盖原则从高到低大致是命令行参数临时指定优先级最高项目级配置AGENTS.md、项目内的 settings全局配置用户目录下的 settings工具内置默认值优先级最低APPEND_SYSTEM.md因为是追加到系统提示通常独立于这个链条但它的内容会和系统提示合并冲突时以更具体的指令为准。7.2 常见冲突场景速查现象可能原因排查方向改了配置没生效被更高优先级覆盖检查项目级是否有同名配置行为时好时坏两个文件规则矛盾对比AGENTS.md和APPEND_SYSTEM.md模型切换后异常上下文不兼容开新会话老是超时超时参数太小调大settings.json里的超时上下文被截断窗口大小填小了核对models.json的窗口值7.3 排查的基本方法我的排查套路是从大到小逐层排除先确认是不是全局配置的问题——临时用命令行参数覆盖看行为是否变化。再确认是不是项目配置的问题——换个干净目录跑同样的任务。最后看系统提示层——临时清空APPEND_SYSTEM.md试试。一层层排除很快就能定位到是哪个文件在捣乱。实操心得养成给配置文件写注释的习惯如果格式支持。比如在settings.json里用注释说明这个超时值是因为某次构建任务调的。过几个月回头看你会感谢当时的自己。8. 一套可直接抄的配置模板与落地步骤讲了这么多原理最后给一套我实际在用的配置思路你可以直接参考。8.1 落地步骤先配models.json把常用模型列进去认证走环境变量窗口大小填准。再配settings.json定默认模型、安全开关、超时重试。然后写AGENTS.md按项目结构、命令、风格、禁忌四块来。最后写APPEND_SYSTEM.md放交互风格和行为约束控制在合理长度。小范围验证在测试目录跑几个典型任务确认行为符合预期。迭代用一段时间发现哪里不顺手就回去改对应文件。8.2 关键参数速查参数建议值说明普通请求超时30-60 秒视网络情况调长任务超时5-10 分钟构建、测试用重试次数2-3 次配指数退避日志级别info排查时临时调 debug上下文余量留 20%系统提示也占 tokenAGENTS.md 长度500-1500 字够用就好8.3 我踩过的几个坑坑一把密钥写进models.json提交了。后来改成环境变量引用并且加了.gitignore。这个教训很深刻密钥泄露的后果不用多说。坑二AGENTS.md写成了项目介绍。结果 Pi 读完还是不知道该干嘛。改成指令化写法后效果立竿见影。坑三上下文窗口填了标称最大值。结果经常请求超限。后来留了 20% 余量稳定多了。坑四APPEND_SYSTEM.md塞了太多规则。Pi 反而抓不住重点。精简到几条核心约束后行为清晰多了。配置这件事说到底就是把你脑子里的隐性知识变成Pi 能读到的显性规则。你越舍得花时间把项目约定、行为偏好写清楚Pi 就越像你的主力。反过来指望它自己猜那永远只能是个通用助手。这套配置调完你会发现 Pi 从能用变成了好用这个转变是实实在在的。