Pi Agent 生产级扩展清单：从吞吐提效到工程防翻车实战

在 CLI Coding Agent 的日常使用中，它常被当成纯终端提示词工具。但应对复杂业务时，裸跑 Agent 会在命令吞吐、上下文消耗、长任务协作和最终交付物质量上遇到诸多阻碍。

我们在长期使用 Pi Agent 开发严肃业务的过程中，沉淀了一套按需组合的扩展工具链。这套工具链不讲概念，核心只解决实际开发中的具体阻碍：压缩无效输出、异构模型分工、交付面防污染。

以下是具体扩展与自研脚本的实战整理：

---

一、 Token 吞吐与上下文窗口压缩

CLI Agent 最大的上下文杀手不是代码本身，而是未经压缩的 Shell 标准输出。

1. rtk (CLI Proxy) + rtk.ts：底层透明拦截并改写 Bash 命令

在提示词里提醒模型“输出精简一点”通常很难保证执行。最稳妥的方式是在 ~/.pi/agent/extensions/rtk.ts 挂载 tool_call 拦截器，将原生命令透明代理到 Rust 编写的紧凑输出代理 rtk：

// ~/.pi/agent/extensions/rtk.ts 核心拦截逻辑
pi.on("tool_call", async (event, ctx) => {
  if (event.toolName !== "bash") return;
  const cmd = event.input.command;
  if (!cmd || cmd.startsWith("rtk ") || process.env.RTK_DISABLED === "1") return;

  // 调用 rtk rewrite 自动将原生命令改写为 token 优化后的代理命令
  const result = await pi.exec("rtk", ["rewrite", cmd], { timeout: 2000, signal: ctx.signal });
  if ((result.code === 0 || result.code === 3) && result.stdout.trim()) {
    event.input.command = result.stdout.trim();
  }
});

• 改写效果：当 Agent 执行 git diff、find .、pnpm test、ls -la 时，扩展在底层将其静默转换为 rtk diff（只提取变更行）、rtk test（只保留失败用例）、rtk find（紧凑树状输出）。
• 解决的问题：在命令行这一维度，rtk 生产统计对 8,748 次命令调用的实测显示，进入上下文的 Token 从 6.7M 压缩到 1.9M，降幅约 71.7%（口径与原理详见姊妹篇 Token 节流与上下文工程），有效防止长日志瞬间撑爆 Context。

⚠️ 退出码保真是硬约束：透明代理真正的风险不是压掉日志，而是悄悄改变命令的成败语义。Agent 靠退出码判断成功失败，一旦 rtk 改写后的返回码与原命令不一致（尤其 rtk test、rtk diff 这类包装），就会出现最危险的一类事故：原本失败的测试返回 0，Agent 误判为通过。因此 rtk.ts 必须：透传原命令退出码；保留全部逃生口（RTK_DISABLED=1 关闭、--raw 单条回退原生输出）；默认白名单化，只代理 git diff / find / ls / 测试类只读高频命令，&&、管道、重定向、sudo、rm、kubectl、部署脚本一律不碰；改写支持 dry-run 预览并落审计日志。

2. npm:context-mode：大体积检索切片化

• 解决的问题：处理超大日志、大范围排查或阅读冗长文档时，避免一次性读取几万行文件。
• 机制：把外部大体积输出隔离在沙箱中并构建 FTS5 索引，仅把针对当前意图的精准提取切片返回给模型，大幅节约窗口预算。
• 注意事项：检索质量决定正确性——索引陈旧会把“外部检索”变成“外部幻觉源”，切片必须携带文件路径与行号；日志与文档在入索引前需脱敏（可能含 token、密码、客户数据）。

3. npm:@diousk/pi-warm-cache：思考间隙的 Prompt 缓存保活

• 解决的问题：我们在人工查看方案或打字思考时，经常会暂停数分钟。支持 Prompt Caching 的模型提供商在空闲超时后会使缓存失效，导致下一次交互全量重新计费且首字延迟增加。
• 机制：在后台以探针维持前缀缓存，探针只在客户端网络层吞吐，不写入会话历史，以免破坏业务前缀。但保温不是免费的：探针输入端仍按 Cache Read 计费（50K 上下文 ≈ 每次等效消耗 5,000 输入 Token），因此必须设熔断（如最多保活 2~3 个周期）且默认关闭，只在上下文足够大、且预计仅暂停几分钟时启用。成本账本与盈亏平衡点见 Token 节流与上下文工程。

---

二、 智能体调度与协作体系

在单个任务里让同一个模型处理所有工种，要么成本高昂且响应慢，要么在关键审查时遗漏边界。

4. npm:pi-subagents：多子智能体分工协同

• 核心机制：支持在 Pi Agent 内部派生独立的 Subagents，按任务阶段拆解流水线，并允许为不同角色（如侦察、实施、代码审查、证据审计）单独覆盖底层模型与思考级别（Thinking Level）。
• 职责划分：
  • 检索侦察（Scout / Researcher）：负责跨目录扫文件与符号定位，使用轻快、高吞吐的模型快速返回上下文坐标；
  • 代码实施（Worker）：专注按既定方案出码与修接口；
  • 审查与审计（Reviewer / Evidence Auditor）：由高逻辑推理模型接管，专职在改动落地前审查逻辑回归与边界盲区。
• 汇报契约：Subagent 隔离了过程噪音，却会引入“二手信息失真”——主模型只看摘要，摘要把字段名说错就会带偏后续实现，因此必须锁定汇报契约：结论携带 文件路径:行号、低置信度回交原文。详见 Token 节流与上下文工程。

5. npm:pi-goal-x：结构化目标池与独立审计

• 提供 /goal 交互式命令，把复杂需求拆解为结构化任务池。
• 自带独立的 Completion Auditor，只有在实际验证通过后才允许将目标标记为完成，防止模型“半途而废但自行宣告完成”。

6. npm:pi-bg-tasks：长耗时任务后台化

• 针对运行耗时超过数分钟的编译或测试，支持自动或手动转入后台执行。
• 任务完成后通过事件回调主动提醒主会话，不阻塞开发者与主 Agent 的持续交互。

---

三、 规则系统模块化

7. 自研扩展 shared-rules.ts：突破单目录单规则文件限制

• 痛点：Pi Agent 默认每个目录只能加载一个规则文件（如 AGENTS.md），无法将代码风格、证据链要求、前端规范分开按模块维护。
• 解法：在 ~/.pi/agent/extensions/shared-rules.ts 放置轻量扩展，动态聚合 ~/.agents/rules/*.md 下的所有规则，去重后自动注入 System Prompt：

// ~/.pi/agent/extensions/shared-rules.ts
import { readdirSync, readFileSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";

const RULES_DIR = join(homedir(), ".agents", "rules");

export default (pi) => {
  pi.on("before_agent_start", async (event) => {
    let names = [];
    try { names = readdirSync(RULES_DIR).filter((f) => f.endsWith(".md")).sort(); } catch { return {}; }

    const prompt = event.systemPrompt ?? "";
    const blocks = [];
    for (const name of names) {
      const p = join(RULES_DIR, name);
      if (!statSync(p).isFile()) continue;
      const text = readFileSync(p, "utf-8").trim();
      const heading = text.split("\n").find((l) => l.startsWith("# "))?.trim() ?? text.slice(0, 60);
      if (text && !prompt.includes(heading)) blocks.push(`${text}\n\n<!-- source: ${p} -->`);
    }
    if (!blocks.length) return {};
    return { systemPrompt: `${prompt}\n\n# Shared machine rules\n\n${blocks.join("\n\n---\n\n")}` };
  });
};

后续需要补充新的编码约定，只需在规则目录增加一个独立的 .md 即可生效。

缓存提示：聚合规则追加在 System Prompt 末尾且顺序固定，规则文件内避免写入时间戳、随机 ID、本机绝对路径等易变内容——否则每次变更都会击穿前缀缓存（见 Token 节流与上下文工程 的“铁律 1”）。规则总量也要设预算，高频常驻、低频按需，避免开局“公摊底噪”。

---

四、 交付面安全与防污染

8. npm:@gotgenes/pi-permission-system

• 针对破坏性文件改动、环境变量泄露与越权网络请求提供前置拦截与确认机制，防止无人值守运行时破坏本地环境。
• 边界提醒：权限层是软约束——若 Agent 能修改自身配置、读取 secret 或执行任意 shell，它就能绕过审批。真正的底线需要 sandbox / 容器 / 只读挂载 / 网络白名单 / 最小权限账号兜底。

9. 自研扩展 no-negative-echo-surface.ts：杜绝交付物中的会话痕迹

• 痛点：Agent 在修改代码或文档时，常喜欢在注释或正文中留下类似“此前曾尝试 A 方案失败，按要求改为 B”的会话过程叙述（反刍叙事）。这些内容属于中间调试废话，污染主干交付面。
• 解法：在 turn_end 挂载检查钩子，只要该轮动过文件系统，自动跑扫描脚本。发现产物正文中包含会话反刍与解释性残留时抛出告警，要求模型仅保留干净的最终实现。
• 注意：不是“一律删除解释”——有价值的“为什么不用 A 方案”应改落到 ADR / PR 说明 / 设计文档，而不是散落在代码注释里；扫描规则需可配置，避免误伤本就要求详细注释的迁移或历史代码。

---

五、 开发者体验与硬件守护

• npm:@narumitw/pi-caffeinate：在长任务执行期间自动阻止系统进入睡眠，防止测试跑到一半因休眠断连。
• npm:@raidou/pi-notify：任务执行完毕或需要人工确认时，发出系统级桌面通知。
• npm:pi-agent-browser-native & npm:pi-tavily-tools：分别提供无头浏览器 DOM 级验证能力与精准网络技术搜索。
• npm:archify：基于代码事实与标准规范，生成结构清晰、支持深浅色且可交互缩放的独立 HTML/SVG 架构图与时序图，替代经常排版错乱的传统文本图表。

---

六、 使用前须知：思路生产级，组件需自验

本文把问题域（Token 成本、上下文污染、多模型切换、长任务、权限、交付面污染）按生产环境的真实痛点整理，这部分是生产级的。但文中列出的第三方 npm 扩展，并不等于经过审计的生产组件：AI Agent 生态变化极快，这些包多为个人维护、迭代频繁、缺少公开安全审计。

安装任一“能执行命令 / 读写文件 / 访问网络”的扩展前，至少核对：仓库活跃度与维护者、下载量与近期版本发布、是否会把上下文或密钥外发、是否与你的 Pi Agent 版本兼容。把本文当成一张能力地图，而不是一份官方推荐安装清单——你完全可以按图自建轻量等价物，也不必全量安装。（文中标注“自研扩展”的 shared-rules.ts、no-negative-echo-surface.ts 属于可自行审计的本地源码，与第三方包性质不同。）

---

七、 从宿主扩展到工程底座：全局配置管不住什么？

上述扩展体系解决了 Pi Agent 宿主环境（Host Layer） 的效率瓶颈：Token 省下来了、速度提上去了、多智能体协作也运转顺畅。

但真正的分水岭不在“效率高低”，而在确定性从哪来。

宿主扩展做出的判断，本质是模型在单次任务内、基于当时上下文的概率性判断——即便是 pi-goal-x 自带的 Completion Auditor 也不例外：它守的是“这一个任务看起来做完没有”，判据仍是自然语言推断，不落库、不跨会话、不做机器对账，换一个会话窗口就归零。

而代码的工程正确性需要的是另一种东西：固化在仓库里、机器可复现、跨需求持久的硬判定。例如：

• 改底层接口时，改动的影响面是否被穷举穷尽（而不是模型凭印象列几个文件）；
• 声明了多条验收条件（AC）时，测试用例是否与 AC 逐条集合对齐（而不是写了几个 PASS 就算数）；
• 前端交互锚点与 E2E 用例声明是否双向集合严格相等（而不是“看起来覆盖了”）。

这类判定无法由任何全局目录下的插件承担，必须由沉淀在代码仓库内的 Project Harness 来做——它不依赖模型的“记忆自觉”，而是把应然资产（PRD 验收准则、代码图谱事实、E2E 用例）直接固化进仓库，用双向集合对账门给出硬性 0/1 判定，并以退出码 1 阻断合入。

这也是我们在实战中演进出 Atlas 体系的原因。两者在架构上有着非常清晰的分工：

┌─────────────────────────────────────────────────────────────────┐
│ 全局宿主层 (~/.pi/agent 扩展工具链)                              │
│ 职责：输出压缩 (rtk) / 异构调度 (subagents)                     │
│ 性质：单会话内的概率性判断（含单任务级校验，如 goal-x auditor）    │
│ 目标：让 Agent 跑得更快、更省、交互更顺畅                       │
└───────────────────────────────┬─────────────────────────────────┘
                                │ 落地执行
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│ 项目工程层 (.atlas 仓库级 Harness)                               │
│ 性质：固化在仓库内、机器可复现、跨需求持久的确定性对账           │
│ 职责：                                                          │
│  1. 代码知识图谱 (Code Graph)：修改前分析依赖拓扑与变更影响面     │
│  2. AC 双向对齐：需求条目与测试断言双向对齐校验，防止需求遗漏    │
│  3. 变异测试校验 (Mutation Proving)：对代码注入突变，验证单测有效性│
│  4. 四态铁门禁体系：ok / WARN / SKIP / FAIL，以退出码 1 阻断交付  │
│ 目标：守住工程质量底线，确保代码合入主干前具备确定性验证        │
└─────────────────────────────────────────────────────────────────┘

全局扩展赋予 Agent 执行能力，项目级 Harness 负责在代码落地时提供可信验证。一旦出现“AI 写得快但管不住”的治理痛点——假完成、测试全绿但业务错、文档与代码长期漂移、改一处坏三处——就值得为项目引入 Project Harness。

• Atlas 官方文档：https://sunwenzhe-git.github.io/atlas/
• Atlas GitHub 仓库：https://github.com/sunwenzhe-git/atlas

欢迎在评论区分享你日常使用 Pi Agent 时常用的扩展或配置思路。