Pi 三层 Harness（AGENTS.md / Skills / Packages）

Summary

Chasen Liao 在切到 pi-mono 三周后给出的可拼装 coding harness：核心保持很小（读改代码、跑 Shell、加载规则、按需 SubAgent、改完验证），纪律、能力、控制面分成三层，而不是把工具全塞进系统提示词。

Key Points

为什么切 Pi

Claude Code 开箱即用，但不好调：上下文和验证跟着产品走，子 Agent 分工不透明。
作者认为真正拉开差距的是：哪些规则常驻、哪些能力按需加载、哪些任务丢给子 Agent、什么情况下必须停下来问人。
体感结果：Pi 缓存命中经常 98% 以上（CH = cache hit），连续对话更快。这是结果，不是原因。

三层

AGENTS.md，管纪律（常驻）
- 全局一份 + 项目级一份。
- 写不怎么变的边界：先看结构和调用路径、只做必要改动、不顺手重构、需求模糊先问、改完跑最相关测试、最后看 diff、不确定就说假设。
- 启动即加载，不每轮重写进 Prompt。
Skills，管能力（按需）
- 常驻约 4–6 个：tdd、diagnosing-bugs、code-review、research，外加自写的 parallel-agent。
- 一个 Skill 一种活；堆多了路由错。不常用的用 skillful 隐藏，保持上下文干净。
Packages，管控制面
- 作者全局约 10 个，常用：
  - pi-subagents：并行调度底座。workflowScript；runs.all 独立 lanes；runs.run 串行阶段；fresh 隔离上下文；父 Agent 汇总拍板。
  - pi-skillful：Skill 发现/加载/隐藏；支持仓库外 .agents/skills/；$ 显式展开。
  - @eko24ive/pi-ask：歧义处结构化 ask_user。
  - pi-simplify：只盯最近改动，不借 review 重构整个项目。
  - @zigai/pi-mention-skill：用 $ 模糊搜并展开 Skill。
  - @tavily/pi-extension：researcher 联网；搜和改代码分 Agent。
  - @narumitw/pi-goal：/goal + goal_complete / goal_blocked / goal_wait。
  - pi-context-usage：看 system prompt / 工具 / 对话占比，满了再 compact 或换 lane。
  - @narumitw/pi-btw：侧边线程，不污染主对话。
  - @ff-labs/pi-fff：Rust 索引替代 find/grep（常驻索引、frecency、git 感知）。

默认工作流

确认目标与验收 → 读代码和规则 → 最小改动 → 跑最相关测试 → 看 diff → 需要时 fresh reviewer。没有证据就不说完成。

有歧义先 ask_user，scout 只读侦察，worker 再改，reviewer 并行看 diff/测试/边界，父 Agent 汇总。

硬约束：同一目录同一时间只留一个 writer。reviewer 只读可并行。真并行实现用 managed worktree，由父 Agent 合并。并行应对不同信息源，而不是复制同一句话给两个 Agent。小任务不要为并行而并行。

踩过的坑

pi-todo 对 coding 任务用处不大：要追的是子 Agent 状态、产物和验证证据，不是 checkbox。
Skill/Package 全放开会让路由变差；默认只留常用的，需要时用 $ 拉出。
第三方 Package 能跑任意代码，装前看源码和权限。
Pi 默认最高权限、没有沙箱。

最小起步

pi install npm:pi-subagents npm:pi-skillful npm:@eko24ive/pi-ask

先写 ~/.pi/agent/AGENTS.md 边界，再留每周会用的 4–6 个 Skill。

Open Questions

文中的 98% cache hit 是作者环境观测，未给出可复现测量。
Claude Code「夹带私货 / 限制第三方 API」是作者立场，未交叉验证。

Evidence Timeline

2026-08-27: Chasen Liao X Article，Wayback 快照同日 13:11:07 UTC

My Brain Wiki

探索