尧图网站建设 
1. 从一堆配置文件说起Pi 到底在解决什么问题第一次接触 Pi 的人大概率是被它那套极简的配置体系吸引过来的。打开一个 Pi 项目的根目录你通常只会看到两个核心文件AGENTS.md和SYSTEM.md。没有复杂的 YAML 编排没有层层嵌套的 JSON Schema也没有动辄几百行的插件注册表。这种“少即是多”的做法在当下 Agent 框架普遍追求大而全的环境里反而显得有点反直觉。但恰恰是这种反直觉让 Pi 在最近一段时间里被越来越多的人拿来当作日常编码 Agent 的底座。我自己的感受是Pi 把“Agent 应该怎么工作”这件事从框架层面下沉到了文档层面。你不需要去学一套新的 DSL也不需要理解某个抽象层级的生命周期钩子你只需要用自然语言把规则写清楚剩下的交给模型去执行。这个思路听起来简单但真正落地的时候考验的是设计者对“什么该由框架管、什么该由模型管”这条边界的判断力。Pi 的定位很明确它是一个极简编码 Agent核心场景就是帮你在终端里完成代码相关的任务——读文件、改代码、跑命令、查上下文。它不试图做一个通用智能体平台也不去卷多模态或者复杂工作流编排。它瞄准的就是开发者日常最高频的那件事让 AI 在真实项目里干活而不是在沙盒里表演。适合谁来用如果你已经用过一些 Agent 工具但被复杂的配置和不可预测的行为搞得有点烦Pi 值得试。如果你是完全的新手想找一个能看懂、能改、能掌控的 Agent 入口Pi 的门槛也足够低。前提是你得愿意接受一个事实极简不等于零配置它只是把配置从代码里挪到了文档里而写文档这件事本身就需要你想清楚自己到底要什么。2. 设计哲学拆解为什么是 AGENTS.md 和 SYSTEM.md2.1 两个文件的分工逻辑Pi 的配置体系里AGENTS.md和SYSTEM.md承担的是完全不同的职责。很多人第一次看到这两个文件会懵觉得都是 Markdown都是写规则为什么要拆成两个我的理解是这是一种关注点分离的设计。SYSTEM.md定义的是 Agent 的“人格”和“底层行为准则”——它是什么角色、遵循什么原则、遇到冲突时怎么取舍。这部分内容相对稳定不随具体任务变化。而AGENTS.md定义的是“在当前项目里怎么干活”——项目结构、编码规范、常用命令、注意事项。这部分内容是项目相关的换一个仓库就要换一套。打个比方SYSTEM.md像是员工的职业素养和公司文化手册AGENTS.md像是具体岗位的操作手册。前者管“你是个什么样的工作者”后者管“你在这个岗位上具体怎么做”。分开写的好处是当你切换项目时只需要替换AGENTS.mdSYSTEM.md可以保持稳定当你调整 Agent 的整体行为风格时也不会污染项目级的操作细节。2.2 为什么不用 JSON 或 YAML这是被问得最多的问题之一。用 Markdown 写配置机器怎么解析答案是不解析直接喂给模型。传统 Agent 框架用结构化配置是因为它们需要在代码层面做精确的路由、权限控制、工具调用编排。但 Pi 的假设是模型本身已经足够聪明能够理解自然语言描述的规则。你写“修改代码前先读一遍相关文件”模型能懂你写“不要动 migrations 目录”模型也能懂。既然模型能懂为什么还要把它翻译成一套只有框架能懂的中间表示这个选择带来的直接好处是表达力没有上限。JSON 能表达的东西Markdown 都能表达但 Markdown 能表达的细微语义JSON 往往表达不了。比如“尽量保持函数短小但如果业务逻辑确实复杂优先保证可读性而不是强行拆分”——这种带条件的、有取舍的规则用结构化配置写起来很别扭用自然语言写就很自然。代价当然也有。自然语言规则的解释权在模型手里不同模型、不同温度参数下执行效果可能有波动。Pi 的应对方式是把规则写得足够具体用例子代替抽象描述并且在SYSTEM.md里明确“当规则冲突时以更具体的规则为准”。这套机制不完美但在实际使用中配合能力较强的模型稳定性是够用的。2.3 极简背后的取舍Pi 的极简不是“什么都不做”而是“把复杂度转移到模型侧”。框架本身只负责最基础的事情读取配置文件、组装上下文、调用模型、执行模型返回的工具调用。剩下的全部交给模型判断。这种设计的好处是框架代码量小容易理解和修改出问题的时候排查路径短。坏处是它对模型的依赖度高模型能力不够的时候Agent 的表现会明显下降。所以 Pi 的用户群体里很多人会主动选择能力较强的模型来跑这不是偶然。另一个取舍是不做复杂的工具编排。Pi 的工具集很克制基本就是文件读写、命令执行、搜索这几类。它不提供可视化的工作流编辑器也不支持条件分支、循环这些编排原语。如果你需要复杂编排Pi 不是最佳选择。但如果你只是想让 AI 帮你改代码、跑测试、查文档Pi 的简单反而成了优势——你不需要先学会一套编排语言才能让 Agent 干活。3. 核心机制解析Pi 是怎么跑起来的3.1 上下文组装AGENTS.md 和 SYSTEM.md 怎么进入模型Pi 启动的时候会做一件很朴素的事情把SYSTEM.md的内容、AGENTS.md的内容、当前对话历史、以及当前工作目录的文件树摘要按顺序拼成一个大的上下文然后发给模型。这个顺序是有讲究的。SYSTEM.md在最前面因为它定义的是全局行为准则优先级最高。AGENTS.md紧随其后作为项目级规则补充。然后是文件树摘要让模型对项目结构有个整体感知。最后才是对话历史。文件树摘要的生成方式也值得说一下。Pi 默认不会把整个项目的文件内容都塞进去那样 token 消耗太大。它只列出目录结构和文件名让模型知道“有什么文件”但不告诉它“文件里有什么”。当模型需要看某个文件的具体内容时它会主动发起读取操作。这个设计模拟了人类开发者的行为先看目录再按需打开文件。注意AGENTS.md的内容会占用每一轮对话的 token 预算。如果你的项目规则写得特别长会挤占模型用于理解任务和生成回复的空间。建议把AGENTS.md控制在合理长度内把不常用的规则放到单独的文件里需要时再让模型去读。3.2 工具调用模型怎么和文件系统交互Pi 暴露给模型的工具集很精简核心就是几个读文件给定路径返回文件内容写文件给定路径和内容写入文件列目录给定路径返回目录下的文件和子目录执行命令给定命令字符串在项目根目录下执行返回输出搜索给定关键词在项目内搜索匹配内容这些工具的定义方式也是自然语言描述而不是 JSON Schema。模型看到的是类似“你可以使用 read_file 工具来读取文件参数是文件路径”这样的说明。模型返回的工具调用请求Pi 解析后执行再把结果拼回上下文。这个过程中Pi 不做复杂的权限校验。它假设模型会遵守AGENTS.md里的规则比如“不要修改 node_modules 目录”。如果模型违反了规则Pi 不会拦截但会在下一轮对话中把执行结果反馈给模型让模型自己意识到问题并纠正。这种“信任但验证”的模式在实际使用中效果不错因为模型通常会在看到错误结果后调整行为。3.3 对话循环一轮交互的完整生命周期Pi 的一轮交互大致是这样的用户输入任务描述Pi 组装上下文SYSTEM.md AGENTS.md 文件树 历史 用户输入调用模型模型返回文本回复或工具调用请求如果有工具调用Pi 执行工具把结果追加到上下文再次调用模型模型基于工具结果继续回复重复 3-5直到模型返回纯文本回复没有工具调用或达到最大轮次限制把最终回复展示给用户这个循环里最关键的是最大轮次限制。Pi 默认会设置一个上限防止模型陷入无限循环。比如模型读了一个文件发现不对又读另一个又不对一直读下去。轮次限制就是安全阀。实际使用中大部分任务在 5-10 轮内就能完成复杂任务可能到 20 轮左右。另一个细节是工具结果的截断。如果某个命令输出特别长比如跑了一个打印大量日志的测试Pi 不会把完整输出都塞回上下文而是截取关键部分。截断策略通常是保留开头和结尾中间用省略号代替。这个策略对模型理解结果影响不大但能显著节省 token。4. 实战从零搭一个 Pi 编码 Agent4.1 环境准备与安装Pi 的安装方式取决于你用的发行渠道。常见的有两种通过包管理器全局安装或者从源码构建。全局安装适合日常使用源码构建适合想改代码或者跟进最新特性的人。安装完成后你需要在项目根目录初始化配置。Pi 通常会提供一个初始化命令帮你生成AGENTS.md和SYSTEM.md的模板。模板内容比较基础你需要根据自己的项目情况去填充。提示初始化生成的SYSTEM.md模板里通常会包含一段关于“你是编码助手”的角色定义。如果你有特殊需求比如希望 Agent 用中文回复、或者希望它更保守改动前先确认可以在这部分调整。4.2 写一份能用的 SYSTEM.mdSYSTEM.md的核心是定义 Agent 的行为边界。我自己的写法是分三块角色定义、行为准则、冲突处理。角色定义部分我会写清楚这个 Agent 是干什么的。比如“你是一个编码助手帮助用户在终端中完成代码修改、调试和文档查询任务。你只处理与代码相关的问题不回答与当前项目无关的闲聊。”行为准则部分我会列几条硬规则。比如“修改文件前必须先读取该文件”“执行破坏性命令前必须先向用户确认”“不要修改 .env 和密钥相关文件”。这些规则要具体不要写“小心操作”这种模糊表述。冲突处理部分我会写“当 AGENTS.md 的规则与 SYSTEM.md 冲突时以 AGENTS.md 为准因为它是项目特定的”。这样模型在遇到矛盾时有个明确的优先级判断。4.3 写一份项目专属的 AGENTS.mdAGENTS.md是真正体现项目特色的地方。我通常会包含这些内容项目结构说明哪些目录是源码哪些是测试哪些是生成产物不要动编码规范缩进用几个空格、命名习惯、导入顺序、注释语言常用命令怎么跑测试、怎么构建、怎么启动开发服务器注意事项比如“修改 API 接口时要同步更新类型定义”“数据库迁移文件不要手动改”写AGENTS.md的时候我有个习惯用例子代替抽象描述。与其写“遵循项目的命名规范”不如写“变量名用 camelCase常量用 UPPER_SNAKE_CASE组件名用 PascalCase”。模型看到具体例子执行准确率会高很多。4.4 跑通第一个任务配置写好后跑一个简单任务验证一下。比如让 Pi 帮你“在 utils 目录下新建一个 formatDate 函数接收 Date 对象返回 YYYY-MM-DD 格式的字符串”。观察 Pi 的行为它有没有先列目录确认 utils 存在有没有读一下现有文件的风格生成的代码是否符合AGENTS.md里的规范如果哪里不对回去改配置再跑一次。这个迭代过程很重要。Pi 的配置不是一次写好的而是在实际使用中逐步调优的。我自己的AGENTS.md改了十几版才达到比较满意的状态。5. 常见问题与排查技巧实录5.1 模型不遵守 AGENTS.md 规则怎么办这是最常见的问题。表现是模型明明看到了规则但执行时还是按自己的习惯来。原因通常有三个规则写得太模糊、规则太多导致模型注意力分散、模型能力不够。排查顺序先检查规则是否具体。把“保持代码整洁”改成“函数不超过 50 行超过就拆分”把“注意错误处理”改成“所有异步调用必须用 try-catch 包裹”。然后检查规则数量如果AGENTS.md超过 200 行考虑精简把不常用的规则移到单独文件。最后考虑换模型能力强的模型对规则的遵循度明显更高。5.2 工具调用失败怎么定位Pi 的工具调用失败通常表现为模型请求读某个文件但文件不存在或者执行命令返回非零退出码。这时候要看 Pi 的日志输出确认是模型给错了路径还是命令本身有问题。如果是路径问题检查AGENTS.md里有没有说明项目结构。模型不知道src目录在哪就会猜猜错很正常。如果是命令问题检查命令是否依赖特定环境变量或工作目录。Pi 默认在项目根目录执行命令如果你的命令需要在子目录执行要在AGENTS.md里写清楚。5.3 上下文超限怎么处理长对话或者大项目里上下文很容易超限。Pi 的应对策略通常是截断历史消息保留最近的几轮。但这会导致模型忘记之前的约定。我的做法是把重要的约定写进AGENTS.md而不是依赖对话历史。AGENTS.md每一轮都会重新加载不会因为历史截断而丢失。另外对于特别长的任务我会拆成多个短会话每个会话聚焦一个子任务完成后再开新会话做下一个。5.4 常见问题速查表问题现象可能原因排查动作模型不读文件直接改规则未强调“先读后写”在 SYSTEM.md 加硬规则生成的代码风格不对AGENTS.md 规范不具体用例子代替抽象描述命令执行报错工作目录或环境不对检查命令是否依赖特定路径对话越来越慢上下文积累过多拆分任务开新会话模型反复读同一个文件轮次限制太宽松调低最大轮次或加规则禁止重复读6. 进阶玩法让 Pi 更贴合你的工作流6.1 多项目配置复用如果你同时维护多个项目可以把通用的规则抽出来放在一个基础SYSTEM.md里然后每个项目的AGENTS.md只写项目特有的内容。Pi 支持在SYSTEM.md里引用其他文件你可以把通用规则放在~/.pi/base.md然后在项目的SYSTEM.md里写“参考 ~/.pi/base.md 中的通用规则”。这样切换项目时只需要换AGENTS.md通用行为保持一致。6.2 结合 TypeScript 项目的特殊配置TypeScript 项目有一些特有的坑比如baseUrl和moduleResolution的弃用警告。你可以在AGENTS.md里写清楚“修改 tsconfig.json 时不要使用已弃用的选项优先使用bundler或node16解析策略。”这样模型在调整配置时就会避开这些坑。另外TypeScript 项目的类型检查比较严格可以要求模型“修改代码后必须跑一遍 tsc 确认没有类型错误”。这个规则能帮你省掉很多手动检查的时间。6.3 用 Pi 做代码审查Pi 不仅能改代码也能做审查。你可以让它“读一下最近修改的文件检查有没有潜在问题”。它会读文件、分析逻辑、给出建议。虽然不如专业审查工具全面但作为第一道过滤网能 catching 不少低级错误。我自己的用法是提交前让 Pi 过一遍改动重点看它有没有指出“未处理的边界情况”或者“可能为空的变量”。这些是人工审查容易漏掉的地方。6.4 和现有工具链的配合Pi 不试图替代你的编辑器、终端或版本控制工具。它更像是一个“命令行里的结对伙伴”在你需要的时候介入不需要的时候不打扰。你可以把它当成一个可以随时召唤的助手而不是一个需要全天候运行的服务。这种定位让 Pi 的集成成本很低。你不需要改现有的工作流只需要在需要的时候打开终端输入任务描述等它执行完然后继续用你习惯的方式工作。7. 我踩过的坑和后来想明白的事最开始用 Pi 的时候我犯过一个典型错误把AGENTS.md写成了“愿望清单”。我希望模型做这个、做那个列了几十条规则结果模型反而不知道该听哪条。后来我砍到只剩十条每条都具体到可以执行效果反而好了。另一个坑是过度依赖对话历史。我一开始觉得只要在对话里说清楚要求模型就能记住。但实际上长对话里模型会遗忘尤其是中间穿插了很多工具调用结果之后。后来我把所有重要约定都写进AGENTS.md对话里只描述当前任务稳定性提升了很多。还有一个体会是Pi 的效果和项目本身的规范程度正相关。如果项目本身结构清晰、命名一致、文档齐全Pi 的表现就很好。如果项目一团乱麻Pi 也会跟着乱。这其实不是 Pi 的问题而是 Agent 这个形态的共性——它放大的是项目本身的秩序而不是创造秩序。最后分享一个小技巧在AGENTS.md里加一条“每次修改后用一句话总结你改了什么”。这个规则能让模型在每轮结束时自我复盘既方便你追踪进度也能让模型在总结过程中发现自己的疏漏。实测下来这条规则对减少“改了一半就停”的情况很有帮助。 Pi 极简编码 Agent 实战：用 AGENTS.md 和 SYSTEM.md 配置你的终端 AI 助手
1. 从一堆配置文件说起Pi 到底在解决什么问题第一次接触 Pi 的人大概率是被它那套极简的配置体系吸引过来的。打开一个 Pi 项目的根目录你通常只会看到两个核心文件AGENTS.md和SYSTEM.md。没有复杂的 YAML 编排没有层层嵌套的 JSON Schema也没有动辄几百行的插件注册表。这种“少即是多”的做法在当下 Agent 框架普遍追求大而全的环境里反而显得有点反直觉。但恰恰是这种反直觉让 Pi 在最近一段时间里被越来越多的人拿来当作日常编码 Agent 的底座。我自己的感受是Pi 把“Agent 应该怎么工作”这件事从框架层面下沉到了文档层面。你不需要去学一套新的 DSL也不需要理解某个抽象层级的生命周期钩子你只需要用自然语言把规则写清楚剩下的交给模型去执行。这个思路听起来简单但真正落地的时候考验的是设计者对“什么该由框架管、什么该由模型管”这条边界的判断力。Pi 的定位很明确它是一个极简编码 Agent核心场景就是帮你在终端里完成代码相关的任务——读文件、改代码、跑命令、查上下文。它不试图做一个通用智能体平台也不去卷多模态或者复杂工作流编排。它瞄准的就是开发者日常最高频的那件事让 AI 在真实项目里干活而不是在沙盒里表演。适合谁来用如果你已经用过一些 Agent 工具但被复杂的配置和不可预测的行为搞得有点烦Pi 值得试。如果你是完全的新手想找一个能看懂、能改、能掌控的 Agent 入口Pi 的门槛也足够低。前提是你得愿意接受一个事实极简不等于零配置它只是把配置从代码里挪到了文档里而写文档这件事本身就需要你想清楚自己到底要什么。2. 设计哲学拆解为什么是 AGENTS.md 和 SYSTEM.md2.1 两个文件的分工逻辑Pi 的配置体系里AGENTS.md和SYSTEM.md承担的是完全不同的职责。很多人第一次看到这两个文件会懵觉得都是 Markdown都是写规则为什么要拆成两个我的理解是这是一种关注点分离的设计。SYSTEM.md定义的是 Agent 的“人格”和“底层行为准则”——它是什么角色、遵循什么原则、遇到冲突时怎么取舍。这部分内容相对稳定不随具体任务变化。而AGENTS.md定义的是“在当前项目里怎么干活”——项目结构、编码规范、常用命令、注意事项。这部分内容是项目相关的换一个仓库就要换一套。打个比方SYSTEM.md像是员工的职业素养和公司文化手册AGENTS.md像是具体岗位的操作手册。前者管“你是个什么样的工作者”后者管“你在这个岗位上具体怎么做”。分开写的好处是当你切换项目时只需要替换AGENTS.mdSYSTEM.md可以保持稳定当你调整 Agent 的整体行为风格时也不会污染项目级的操作细节。2.2 为什么不用 JSON 或 YAML这是被问得最多的问题之一。用 Markdown 写配置机器怎么解析答案是不解析直接喂给模型。传统 Agent 框架用结构化配置是因为它们需要在代码层面做精确的路由、权限控制、工具调用编排。但 Pi 的假设是模型本身已经足够聪明能够理解自然语言描述的规则。你写“修改代码前先读一遍相关文件”模型能懂你写“不要动 migrations 目录”模型也能懂。既然模型能懂为什么还要把它翻译成一套只有框架能懂的中间表示这个选择带来的直接好处是表达力没有上限。JSON 能表达的东西Markdown 都能表达但 Markdown 能表达的细微语义JSON 往往表达不了。比如“尽量保持函数短小但如果业务逻辑确实复杂优先保证可读性而不是强行拆分”——这种带条件的、有取舍的规则用结构化配置写起来很别扭用自然语言写就很自然。代价当然也有。自然语言规则的解释权在模型手里不同模型、不同温度参数下执行效果可能有波动。Pi 的应对方式是把规则写得足够具体用例子代替抽象描述并且在SYSTEM.md里明确“当规则冲突时以更具体的规则为准”。这套机制不完美但在实际使用中配合能力较强的模型稳定性是够用的。2.3 极简背后的取舍Pi 的极简不是“什么都不做”而是“把复杂度转移到模型侧”。框架本身只负责最基础的事情读取配置文件、组装上下文、调用模型、执行模型返回的工具调用。剩下的全部交给模型判断。这种设计的好处是框架代码量小容易理解和修改出问题的时候排查路径短。坏处是它对模型的依赖度高模型能力不够的时候Agent 的表现会明显下降。所以 Pi 的用户群体里很多人会主动选择能力较强的模型来跑这不是偶然。另一个取舍是不做复杂的工具编排。Pi 的工具集很克制基本就是文件读写、命令执行、搜索这几类。它不提供可视化的工作流编辑器也不支持条件分支、循环这些编排原语。如果你需要复杂编排Pi 不是最佳选择。但如果你只是想让 AI 帮你改代码、跑测试、查文档Pi 的简单反而成了优势——你不需要先学会一套编排语言才能让 Agent 干活。3. 核心机制解析Pi 是怎么跑起来的3.1 上下文组装AGENTS.md 和 SYSTEM.md 怎么进入模型Pi 启动的时候会做一件很朴素的事情把SYSTEM.md的内容、AGENTS.md的内容、当前对话历史、以及当前工作目录的文件树摘要按顺序拼成一个大的上下文然后发给模型。这个顺序是有讲究的。SYSTEM.md在最前面因为它定义的是全局行为准则优先级最高。AGENTS.md紧随其后作为项目级规则补充。然后是文件树摘要让模型对项目结构有个整体感知。最后才是对话历史。文件树摘要的生成方式也值得说一下。Pi 默认不会把整个项目的文件内容都塞进去那样 token 消耗太大。它只列出目录结构和文件名让模型知道“有什么文件”但不告诉它“文件里有什么”。当模型需要看某个文件的具体内容时它会主动发起读取操作。这个设计模拟了人类开发者的行为先看目录再按需打开文件。注意AGENTS.md的内容会占用每一轮对话的 token 预算。如果你的项目规则写得特别长会挤占模型用于理解任务和生成回复的空间。建议把AGENTS.md控制在合理长度内把不常用的规则放到单独的文件里需要时再让模型去读。3.2 工具调用模型怎么和文件系统交互Pi 暴露给模型的工具集很精简核心就是几个读文件给定路径返回文件内容写文件给定路径和内容写入文件列目录给定路径返回目录下的文件和子目录执行命令给定命令字符串在项目根目录下执行返回输出搜索给定关键词在项目内搜索匹配内容这些工具的定义方式也是自然语言描述而不是 JSON Schema。模型看到的是类似“你可以使用 read_file 工具来读取文件参数是文件路径”这样的说明。模型返回的工具调用请求Pi 解析后执行再把结果拼回上下文。这个过程中Pi 不做复杂的权限校验。它假设模型会遵守AGENTS.md里的规则比如“不要修改 node_modules 目录”。如果模型违反了规则Pi 不会拦截但会在下一轮对话中把执行结果反馈给模型让模型自己意识到问题并纠正。这种“信任但验证”的模式在实际使用中效果不错因为模型通常会在看到错误结果后调整行为。3.3 对话循环一轮交互的完整生命周期Pi 的一轮交互大致是这样的用户输入任务描述Pi 组装上下文SYSTEM.md AGENTS.md 文件树 历史 用户输入调用模型模型返回文本回复或工具调用请求如果有工具调用Pi 执行工具把结果追加到上下文再次调用模型模型基于工具结果继续回复重复 3-5直到模型返回纯文本回复没有工具调用或达到最大轮次限制把最终回复展示给用户这个循环里最关键的是最大轮次限制。Pi 默认会设置一个上限防止模型陷入无限循环。比如模型读了一个文件发现不对又读另一个又不对一直读下去。轮次限制就是安全阀。实际使用中大部分任务在 5-10 轮内就能完成复杂任务可能到 20 轮左右。另一个细节是工具结果的截断。如果某个命令输出特别长比如跑了一个打印大量日志的测试Pi 不会把完整输出都塞回上下文而是截取关键部分。截断策略通常是保留开头和结尾中间用省略号代替。这个策略对模型理解结果影响不大但能显著节省 token。4. 实战从零搭一个 Pi 编码 Agent4.1 环境准备与安装Pi 的安装方式取决于你用的发行渠道。常见的有两种通过包管理器全局安装或者从源码构建。全局安装适合日常使用源码构建适合想改代码或者跟进最新特性的人。安装完成后你需要在项目根目录初始化配置。Pi 通常会提供一个初始化命令帮你生成AGENTS.md和SYSTEM.md的模板。模板内容比较基础你需要根据自己的项目情况去填充。提示初始化生成的SYSTEM.md模板里通常会包含一段关于“你是编码助手”的角色定义。如果你有特殊需求比如希望 Agent 用中文回复、或者希望它更保守改动前先确认可以在这部分调整。4.2 写一份能用的 SYSTEM.mdSYSTEM.md的核心是定义 Agent 的行为边界。我自己的写法是分三块角色定义、行为准则、冲突处理。角色定义部分我会写清楚这个 Agent 是干什么的。比如“你是一个编码助手帮助用户在终端中完成代码修改、调试和文档查询任务。你只处理与代码相关的问题不回答与当前项目无关的闲聊。”行为准则部分我会列几条硬规则。比如“修改文件前必须先读取该文件”“执行破坏性命令前必须先向用户确认”“不要修改 .env 和密钥相关文件”。这些规则要具体不要写“小心操作”这种模糊表述。冲突处理部分我会写“当 AGENTS.md 的规则与 SYSTEM.md 冲突时以 AGENTS.md 为准因为它是项目特定的”。这样模型在遇到矛盾时有个明确的优先级判断。4.3 写一份项目专属的 AGENTS.mdAGENTS.md是真正体现项目特色的地方。我通常会包含这些内容项目结构说明哪些目录是源码哪些是测试哪些是生成产物不要动编码规范缩进用几个空格、命名习惯、导入顺序、注释语言常用命令怎么跑测试、怎么构建、怎么启动开发服务器注意事项比如“修改 API 接口时要同步更新类型定义”“数据库迁移文件不要手动改”写AGENTS.md的时候我有个习惯用例子代替抽象描述。与其写“遵循项目的命名规范”不如写“变量名用 camelCase常量用 UPPER_SNAKE_CASE组件名用 PascalCase”。模型看到具体例子执行准确率会高很多。4.4 跑通第一个任务配置写好后跑一个简单任务验证一下。比如让 Pi 帮你“在 utils 目录下新建一个 formatDate 函数接收 Date 对象返回 YYYY-MM-DD 格式的字符串”。观察 Pi 的行为它有没有先列目录确认 utils 存在有没有读一下现有文件的风格生成的代码是否符合AGENTS.md里的规范如果哪里不对回去改配置再跑一次。这个迭代过程很重要。Pi 的配置不是一次写好的而是在实际使用中逐步调优的。我自己的AGENTS.md改了十几版才达到比较满意的状态。5. 常见问题与排查技巧实录5.1 模型不遵守 AGENTS.md 规则怎么办这是最常见的问题。表现是模型明明看到了规则但执行时还是按自己的习惯来。原因通常有三个规则写得太模糊、规则太多导致模型注意力分散、模型能力不够。排查顺序先检查规则是否具体。把“保持代码整洁”改成“函数不超过 50 行超过就拆分”把“注意错误处理”改成“所有异步调用必须用 try-catch 包裹”。然后检查规则数量如果AGENTS.md超过 200 行考虑精简把不常用的规则移到单独文件。最后考虑换模型能力强的模型对规则的遵循度明显更高。5.2 工具调用失败怎么定位Pi 的工具调用失败通常表现为模型请求读某个文件但文件不存在或者执行命令返回非零退出码。这时候要看 Pi 的日志输出确认是模型给错了路径还是命令本身有问题。如果是路径问题检查AGENTS.md里有没有说明项目结构。模型不知道src目录在哪就会猜猜错很正常。如果是命令问题检查命令是否依赖特定环境变量或工作目录。Pi 默认在项目根目录执行命令如果你的命令需要在子目录执行要在AGENTS.md里写清楚。5.3 上下文超限怎么处理长对话或者大项目里上下文很容易超限。Pi 的应对策略通常是截断历史消息保留最近的几轮。但这会导致模型忘记之前的约定。我的做法是把重要的约定写进AGENTS.md而不是依赖对话历史。AGENTS.md每一轮都会重新加载不会因为历史截断而丢失。另外对于特别长的任务我会拆成多个短会话每个会话聚焦一个子任务完成后再开新会话做下一个。5.4 常见问题速查表问题现象可能原因排查动作模型不读文件直接改规则未强调“先读后写”在 SYSTEM.md 加硬规则生成的代码风格不对AGENTS.md 规范不具体用例子代替抽象描述命令执行报错工作目录或环境不对检查命令是否依赖特定路径对话越来越慢上下文积累过多拆分任务开新会话模型反复读同一个文件轮次限制太宽松调低最大轮次或加规则禁止重复读6. 进阶玩法让 Pi 更贴合你的工作流6.1 多项目配置复用如果你同时维护多个项目可以把通用的规则抽出来放在一个基础SYSTEM.md里然后每个项目的AGENTS.md只写项目特有的内容。Pi 支持在SYSTEM.md里引用其他文件你可以把通用规则放在~/.pi/base.md然后在项目的SYSTEM.md里写“参考 ~/.pi/base.md 中的通用规则”。这样切换项目时只需要换AGENTS.md通用行为保持一致。6.2 结合 TypeScript 项目的特殊配置TypeScript 项目有一些特有的坑比如baseUrl和moduleResolution的弃用警告。你可以在AGENTS.md里写清楚“修改 tsconfig.json 时不要使用已弃用的选项优先使用bundler或node16解析策略。”这样模型在调整配置时就会避开这些坑。另外TypeScript 项目的类型检查比较严格可以要求模型“修改代码后必须跑一遍 tsc 确认没有类型错误”。这个规则能帮你省掉很多手动检查的时间。6.3 用 Pi 做代码审查Pi 不仅能改代码也能做审查。你可以让它“读一下最近修改的文件检查有没有潜在问题”。它会读文件、分析逻辑、给出建议。虽然不如专业审查工具全面但作为第一道过滤网能 catching 不少低级错误。我自己的用法是提交前让 Pi 过一遍改动重点看它有没有指出“未处理的边界情况”或者“可能为空的变量”。这些是人工审查容易漏掉的地方。6.4 和现有工具链的配合Pi 不试图替代你的编辑器、终端或版本控制工具。它更像是一个“命令行里的结对伙伴”在你需要的时候介入不需要的时候不打扰。你可以把它当成一个可以随时召唤的助手而不是一个需要全天候运行的服务。这种定位让 Pi 的集成成本很低。你不需要改现有的工作流只需要在需要的时候打开终端输入任务描述等它执行完然后继续用你习惯的方式工作。7. 我踩过的坑和后来想明白的事最开始用 Pi 的时候我犯过一个典型错误把AGENTS.md写成了“愿望清单”。我希望模型做这个、做那个列了几十条规则结果模型反而不知道该听哪条。后来我砍到只剩十条每条都具体到可以执行效果反而好了。另一个坑是过度依赖对话历史。我一开始觉得只要在对话里说清楚要求模型就能记住。但实际上长对话里模型会遗忘尤其是中间穿插了很多工具调用结果之后。后来我把所有重要约定都写进AGENTS.md对话里只描述当前任务稳定性提升了很多。还有一个体会是Pi 的效果和项目本身的规范程度正相关。如果项目本身结构清晰、命名一致、文档齐全Pi 的表现就很好。如果项目一团乱麻Pi 也会跟着乱。这其实不是 Pi 的问题而是 Agent 这个形态的共性——它放大的是项目本身的秩序而不是创造秩序。最后分享一个小技巧在AGENTS.md里加一条“每次修改后用一句话总结你改了什么”。这个规则能让模型在每轮结束时自我复盘既方便你追踪进度也能让模型在总结过程中发现自己的疏漏。实测下来这条规则对减少“改了一半就停”的情况很有帮助。