Pi Coding Harness 实践：用 AGENTS.md、Skills 与 Packages 重建可控的编程 Agent

开发工具2026-08-2914 මිනිත්තු කියවීමPi Coding AgentCoding HarnessAGENTS.mdAgent SkillsSubAgent上下文管理AI 编程

很多人使用 AI 编程工具时，第一反应是比较模型：谁的代码能力更强、谁的上下文更长、谁的响应更快。

但当任务从“写一个函数”变成“理解一个仓库、修改多个文件、运行测试、调用子 Agent 并保留可审计结果”时，决定效率的往往不是模型本身，而是模型外面的 Coding Harness：它如何加载规则、如何提供能力、如何拆分任务、如何控制权限，以及如何证明最终结果真的可用。

本文整理 Chasen 于 2026 年 8 月 27 日发布的 Pi Coding Agent 实践，并将其中的经验重新组织为一套通用方法。重点不是照搬某个人的插件清单，而是理解如何为自己的 Agent 搭建一套更清晰、更可控、更容易恢复的工作环境。

先看结论：效率来自减少模糊，而不是堆更多插件

一个实用的 Coding Harness，至少要解决五件事：

加载项目规则
  → 按需提供能力
  → 选择合适的 Agent / Tool
  → 执行最小改动
  → 通过测试、审查和 diff 证明结果

Pi 的价值不只是“核心更小”，而是让开发者可以自己决定 Agent 的工作方式：

哪些规则每次都必须遵守；
哪些能力只有特定任务才需要；
哪些任务适合交给子 Agent；
什么情况下必须停下来询问用户；
上下文快满时是压缩、换 lane，还是拆分任务；
写操作、Shell 和外部网络访问需要什么级别的确认。

可以把这种设计概括为：

纪律 → 能力 → 控制面 → 验证

不是安装越多越强。过多的规则和插件会增加路由歧义、上下文开销和权限风险，反而让 Agent 更难稳定工作。

Pi Coding Harness 的三层结构

原文将自己的 Harness 分成三层。这种分层也适用于其它 CLI Agent、IDE Agent 和自建 Agent Runtime。

层级	核心职责	典型内容
`AGENTS.md`	管纪律和边界	项目规则、修改原则、验收要求、提问条件
Skills	管能力和方法	TDD、排障、代码审查、研究、并行工作流
Packages	管控制面和运行时	子 Agent 调度、Skill 发现、上下文、目标、侧边线程

这三层不要互相替代：

AGENTS.md 不应该变成几十页的知识库；
Skill 不应该偷偷执行与任务无关的副作用；
Package 不应该在没有说明的情况下接管所有配置和权限。

第一层：用 AGENTS.md 固定工作纪律

AGENTS.md 最适合存放不经常变化、每次任务都需要遵守的规则。它的作用不是教 Agent 完成所有事情，而是规定 Agent 在什么边界内工作。

建议固定的规则

一份全局规则可以包含：

修改前先了解目录结构和调用路径；
需求不明确时先提问，不自行猜测关键目标；
优先做必要的最小改动，不顺手重构无关代码；
改动后运行与本次修改最相关的测试或检查；
最后阅读 diff，确认没有意外文件、密钥或大范围格式变化；
对不确定的事实明确写出假设；
没有验证证据时，不声称任务已经完成。

项目级 AGENTS.md 再补充仓库特有规则，例如：

使用哪一种包管理器；
哪些目录禁止直接修改；
测试、构建和 lint 命令是什么；
哪些环境变量不能出现在日志中；
哪些接口需要人工确认后才能调用。

一条可复用的 Coding Loop

确认目标和验收标准
  → 阅读代码与项目规则
  → 做最小必要改动
  → 跑最相关的测试或检查
  → 阅读 diff
  → 必要时让全新 reviewer 复核

这条循环的价值在于把“完成”从一句主观判断，变成一组可以检查的状态变化。

第二层：用 Skills 按需加载能力

Skill 适合描述一类任务应该如何完成，例如：

TDD：先写失败测试，再实现，再重构；
diagnosing-bugs：复现、缩小范围、假设、加观测、修复、回归；
code-review：关注边界、回归风险和可维护性；
research：检索资料、抽取证据、区分事实和推断；
parallel-agent：规范子 Agent 的拆分、产物和汇总方式。

Skill 和 Tool 的边界可以这样记：

Skill = 这类任务应该怎么做
Tool  = 现在执行哪个受控动作

如果把所有 Skill 都常驻在系统提示词里，会产生三个问题：上下文变长、能力路由变模糊、无关规则干扰当前任务。更稳妥的策略是：

常驻每周都会使用的少量 Skill；
其它能力按任务需要显式展开；
区分用户级 Skill 和仓库级 Skill；
定期隐藏或移除不再使用的能力；
每个 Skill 只负责一种清晰的工作。

对于 GPT88 文档和 Agent 项目，也可以把“研究外部资料”和“修改本地代码”拆成不同 Skill。研究 Agent 只读外部内容，实施 Agent 负责写入，reviewer 负责审查，这样错误来源更容易定位。

第三层：Packages 管理控制面

Packages 不只是功能插件，更像 Coding Harness 的控制面。它们决定 Agent 如何发现能力、启动子 Agent、管理上下文、处理歧义和控制运行状态。

下面按职责整理原文提到的典型能力。具体包名、安装方式、兼容版本和权限范围可能变化，使用前应检查项目 README、源码和发行说明。

1. 子 Agent 调度

并行调度底座应明确区分：

独立 lane：互不依赖的任务并行执行；
串行阶段：后一步依赖前一步产物；
fresh 上下文：为 reviewer 或独立调查创建干净上下文；
父 Agent：汇总证据、处理冲突并做最终决策。

一条适合代码任务的结构是：

父 Agent
  ├── scout：只读侦察入口、调用链和风险
  ├── worker：在明确范围内修改代码
  └── reviewer：独立检查 diff、测试和边界

这里有一条非常重要的并发约束：同一个目录同一时间只保留一个 writer。 reviewer 可以并行，因为它只读；多个 writer 同时修改同一目录，会让结果依赖落盘顺序，冲突也更难解释。

如果确实需要并行实现，应该使用隔离的 worktree 或独立分支，最后由父 Agent 合并，而不是让多个 Agent 直接写同一份工作区。

2. Skill 发现与加载

Skill 管理器的关键能力不是“安装更多 Skill”，而是：

能发现用户级和仓库外层的 Skill；
支持显式展开某个 Skill；
默认隐藏低频能力；
让当前 Prompt 只携带相关方法；
能看到 Skill 的来源、版本和加载范围。

这样做的目标是让上下文保持干净，而不是把所有可能的说明一次性塞给模型。

3. 在歧义处暂停询问

高质量 Agent 不应该在所有地方都自动化。以下情况适合使用结构化询问：

修改原文件还是新建文件不清楚；
目标目录或目标环境不明确；
验收标准存在多个合理解释；
任务可能影响生产数据；
需要选择多个互斥实现方向。

询问不是效率损失。一次短问题，往往比错误实现后返工更省时间。

4. 只审查最近改动

简化工具应关注本次改动引入的重复和不必要复杂度，而不是借 review 的名义重构整个项目。

审查范围应该与任务范围匹配：

本次改动
  → 直接依赖
  → 受影响测试
  → 明确的回归边界

如果 reviewer 开始提出与当前任务无关的大规模架构重写，应该把它记录为后续任务，而不是混入当前交付。

5. 外部研究与代码执行分离

需要联网时，建议把“查资料”和“改代码”分给不同 Agent：

researcher：搜索、抓取、整理外部资料；
worker：只使用已经确认的结论实施修改；
reviewer：检查引用、实现和假设。

这种分离可以降低外部资料误导代码修改的风险，也能让失败更容易归因：是资料不可靠，还是实现不正确。

6. 长目标与上下文管理

长任务需要显式目标和停止条件。一个好的目标管理器至少应该能区分：

已完成；
被阻塞；
等待外部事件；
需要用户确认；
仍在执行。

上下文管理则要回答：

System Prompt 占用了多少空间；
工具定义占用了多少空间；
历史对话占用了多少空间；
是否需要 compaction；
是否应该换 lane 或拆分任务。

不要等上下文已经溢出才处理。接近上限时，先保存关键结论、当前文件、未完成事项和验证证据，再压缩或切换上下文。

推荐的默认工作流：先问清，再侦察，最后修改

把上面的三层结构组合起来，可以形成一条稳定的 Coding Harness 流程。

阶段一：确认目标

先明确：

目标文件和目录；
是修改原文、创建新文件还是迁移内容；
预期行为和验收标准；
是否允许联网、写文件、运行命令和调用外部服务；
哪些内容必须保留，哪些内容可以删除。

有歧义就暂停询问，不要让 Agent 自己选择影响范围很大的方案。

阶段二：只读侦察

让 scout 只读检查：

项目结构；
入口文件和调用链；
相关测试；
当前工作区状态；
潜在风险和依赖关系。

侦察结果应该输出为短报告，而不是直接修改文件。

阶段三：限定范围实施

worker 只处理已经确认的文件和目标：

只做必要改动；
不顺手升级依赖；
不重构无关模块；
不覆盖用户现有改动；
不在日志和提交中泄露密钥。

阶段四：独立验证

让 fresh reviewer 检查：

diff 是否符合目标；
是否引入回归；
测试是否覆盖关键路径；
错误处理和边界条件是否完整；
是否存在不必要的复杂度或安全问题。

父 Agent 汇总 worker 和 reviewer 的结果，必要时再进行一轮最小修复。

为什么不建议无条件堆 Skill 和 Package？

原文提到，曾经把几十个能力全部开放，结果是路由更差、管理成本更高。这是很多 Agent 项目都会遇到的问题。

上下文污染

每个 Skill 都会带来说明、示例、工具和约束。无关能力越多，模型越需要在多个相似选项中选择，真正相关的规则反而不突出。

选择歧义

多个工具都能“搜索文件”、多个 Skill 都能“检查代码”时，Agent 可能选择不合适的路线，或者重复执行同一件事。

权限扩大

第三方 Package 可能执行任意代码、读取本地文件、启动进程或访问网络。安装前至少应检查：

源码和发行仓库；
维护者与最近更新时间；
安装脚本和依赖；
文件系统、Shell、网络和环境变量访问；
配置写入位置；
卸载和回滚方式。

性能与预热

带索引的文件搜索工具进入大型仓库时，第一次可能需要预热或建立索引。这通常是可预期的初始化成本，但要记录索引目录、忽略规则和资源占用，避免把它误判成 Agent 卡死。

一个最小可用的搭建方案

不要一开始复制十个 Package。可以从下面的最小组合开始：

第一步：先写纪律

在用户级 Agent 规则中写清楚：

简单优先
最小改动
需求模糊先问
改完必跑相关测试
最后必须看 diff
没有证据不说完成

项目级规则只补充该仓库的特殊约束。

第二步：只保留高频能力

优先选择每周都会用到的 4—6 个 Skill，例如测试驱动、排障、代码审查、研究和并行任务。低频的简历、PPT 或一次性迁移能力可以隐藏，需要时再展开。

第三步：先安装控制面，再按痛点扩展

先解决两个基本问题：子 Agent 如何调度，Skill 如何发现和加载。之后再根据实际痛点增加“歧义询问”“上下文监控”“侧边线程”或“索引搜索”等能力。

安装第三方 Package 时，不要只复制一条安装命令。应同时记录：

包名和版本；
来源仓库；
读取和写入权限；
配置文件位置；
首次测试任务；
卸载和回滚步骤。

安全提醒：Pi 的高权限模型需要额外防护

原文特别提醒，Pi 默认可能以较高权限运行，且不一定提供沙箱。对能读取文件、运行 Shell 和访问网络的 Coding Agent 来说，这意味着：

不要在包含生产密钥的目录中直接运行未知 Package；
先在测试仓库或隔离 worktree 中验证；
对删除、部署、支付、外部消息和批量写操作增加人工确认；
限制环境变量、工作目录和网络权限；
不要把完整 Prompt、Authorization 头或敏感文件内容写进公开日志；
保留原配置、版本信息和回滚点。

Agent 能执行命令，不代表它应该自动执行所有命令。权限越高，越需要明确的 allow-list、预览、审批和验收。

验收清单

完成一次 Coding Harness 配置后，可以用下面的清单验收：

总结

Pi Coding Agent 的吸引力，不在于它天然替你解决所有问题，而在于它把 Harness 的控制权更多交给使用者。你可以用 AGENTS.md 固定纪律，用 Skills 按需提供方法，用 Packages 管理子 Agent、上下文、目标和工具发现，再用测试、review 和 diff 证明结果。

这套方法也适用于 GPT88 API 接入的其它 Coding Agent：先把模型请求跑通，再把规则、工具、权限、子 Agent 和验证逐层加进去。最终效率的来源不是插件数量，而是模糊更少、上下文更干净、执行更可控、失败更容易恢复。

本文整理自 Chasen 于 2026 年 8 月 27 日发布的 X 文章《当我从放弃 Claude Code 转向 Pi 并且搭建了自己的一套 Coding Harness 才知道什么叫做效率》。原文中的 Package 名称、命令、版本和兼容性会随项目更新变化；本文保留其方法论并重新组织为通用实践，不代表 GPT88 对第三方 Package 的官方背书。安装前请查看对应项目的源码、README、权限和许可证，并以当前版本说明为准。

අදාළ මාර්ගෝපදේශය

为什么 Agent 要把 Skill 和 Tool 分成两个能力层？