Superpowers 的 Pi 工具映射机制：把“动作语言”翻译成 Pi 原生工具

2026-09-06 14:58:06作者：董斯意

Superpowers 的技能文档刻意只描述“动作”（dispatch a subagent、create a todo、read a file），而不指名任何具体工具；在 Pi 运行环境下，这些动作究竟落到哪些真实工具，由 Pi 工具映射参考负责翻译。本篇围绕这份映射文档展开：它如何定义 subagent 派发与任务跟踪两条动作的 Pi 等价物、为什么这两项能力在 Pi 核心中都是“可降级”的，以及 Pi 扩展的引导注入（bootstrap）是如何把这份映射连同 using-superpowers 技能一起送进模型上下文的。读完后，你将能在 Pi 环境下正确运行 Superpowers 的全部技能，并理解“能力缺失时不伪造工具调用”这一设计原则的实现依据。

一、背景：技能说“动作”，映射表说“工具”

Superpowers 的跨平台设计有一条硬性规则：技能正文只写动作，不写工具名。在移植指南中，这一点被表述为“Skills name actions, not tools”——skills/ 下的内容是所有 harness 共享的唯一事实来源，每个 harness 各自提供一层“动作词表 → 真实工具名”的翻译，翻译内容放在 skills/using-superpowers/references/<harness>-tools.md 和/或引导注入器中。

入口是 using-superpowers 技能。它在每次会话开始时被注入模型上下文，要求模型在任何回应（包括澄清提问）之前先检查是否有适用的技能；其 Platform Adaptation 一节按 harness 分发到各自的参考文件：

Harness	参考文件
Codex	references/codex-tools.md
Pi	references/pi-tools.md
Antigravity	references/antigravity-tools.md

也就是说，pi-tools.md 不是独立文档，而是整条“会话启动 → 技能发现 → 动作执行”链路中，模型把技能指令翻译为 Pi 工具调用时的查阅依据。

二、Pi 工具映射表（完整继承）

pi-tools.md 的核心是一张两行映射表，完整保留如下：

Action skills request	Pi equivalent
Dispatch a subagent（`Subagent (general-purpose):` 模板）	若可用，使用已安装子代理工具，例如 `pi-subagents` 提供的 `subagent`
Task tracking（"create a todo"、"mark complete"）	若已安装 todo/task 工具则使用之；否则在 plan 文件或 `TODO.md` 中跟踪任务

这里的 Subagent (general-purpose): 模板指的是各技能自带的提示词模板格式，例如 code-reviewer.md、implementer-prompt.md、spec-document-reviewer-prompt.md 以及 dispatching-parallel-agents 技能中都以 Subagent (general-purpose): "..." 的形式描述一次子代理派发。在 Claude Code 上它对应 Task 工具；在 Pi 上则按上表解析为可选的 subagent 工具或顺序执行的降级路径。

值得注意的一个设计细节：映射表只覆盖“有降级空间”的两类动作（子代理、任务清单），而读文件、写文件、执行命令这类动作不需要专门映射，因为 Pi 的内置工具本身就是小写的 read、write、edit、bash（以及可选的 grep、find、ls），与动作语义一一对应——这一点由扩展内嵌的映射文本直接写明（见第五节）。

三、Subagents：核心不内置，禁止伪造 `Task` 调用

参考文档对子代理的立场非常明确，原文规则是：

Pi core does not ship a standard subagent tool. The pi-subagents package is a strong optional companion and provides a subagent tool with single-agent, chain, parallel, async, forked-context, and resume/status workflows. If no subagent tool is available, do not fabricate Task calls; execute sequentially in the current session or explain that the optional subagent capability is not installed.

拆解为三条可执行的判断逻辑：

检测优先：先判断会话中是否存在子代理工具（如 pi-subagents 包提供的 subagent，支持单代理、链式、并行、异步、分叉上下文、恢复/状态查询等模式）。存在则直接使用它执行 Superpowers 的子代理工作流。
不伪造调用：不存在时，严禁虚构 Task 调用。模型不能假设某个不存在于当前工具清单的工具名并“调用”它。
降级路径：无子代理工具时，在当前会话内顺序执行相应工作，或直接向用户说明“可选的子代理能力未安装”。

这条规则与移植指南的能力清单一致：子代理/任务派发被归类为“Degradable”能力——“skill 已为缺失工具写好降级话术；你的映射职责是工具存在时指向真实工具、不存在时复用降级话术”。Codex 参考文件也是同一思路的另一实例：Codex 需要在 ~/.codex/config.toml 中显式开启 multi_agent = true 才有 spawn_agent/wait_agent/close_agent，开启前子代理类技能同样只能走降级。

这一“可降级”定位在仓库测试中也有对应物：Claude Code 集成的测试脚本 test-subagent-driven-development-integration.sh 会以 TodoWrite/TaskCreate 等工具名为基准统计会话行为，而 Pi 场景下的行为验收标准则是“按映射表和降级路径执行”。

四、Task lists：`TodoWrite` 的语义归属

参考文档对任务清单的规定：

Pi core does not ship a standard task-list tool. If a todo/task extension is installed, use its documented tool. Otherwise use Superpowers plan files, checklists in Markdown, or a repo-local TODO.md for task tracking. Older Superpowers docs may refer to TodoWrite; treat that as the task-tracking action above.

这里解决了一个真实的兼容性问题：Superpowers 的早期技能文档使用 Claude Code 的工具词表写作，因此可能直接出现 TodoWrite 这个名字。pi-tools.md 的裁决是——在 Pi 上，TodoWrite 不是一个工具名，而是一个“任务跟踪动作”的旧称，它应解析为上表第二行的 Pi 等价物：

已安装 todo/task 扩展 → 用该扩展文档中的工具；
未安装 → 用 Superpowers 的 plan 文件、Markdown checklist，或仓库本地 TODO.md 跟踪进度。

这个“旧工具名 → 动作语义”的归一化并非 Pi 独有。移植指南的 Part 8 附录对 create/update todos 动作同样注明“把旧的 TodoWrite 引用视为该动作”；而 OpenCode 支持设计文档中 TodoWrite → update_plan 的映射则是另一个 harness 的同构例子。对 Pi 而言，降级方案（plan 文件 / TODO.md）与 Superpowers 其他技能本身的工作方式自洽——例如 executing-plans、writing-plans 等技能本来就以 Markdown plan 文件为载体，任务清单落在 plan 文件里并不破坏任何既有流程。

五、源码佐证：映射如何进入 Pi 会话

参考文档是“静态”的查阅材料，而真正让它在每个 Pi 会话生效的是 superpowers Pi 扩展。从源码结构看，注入链路如下：

1. 包清单声明 Pi 集成。 根 package.json 中：

keywords 包含 pi-package，使包可被 Pi 识别为可安装包；
pi.skills: ["./skills"] 声明技能目录，让 Pi 原生技能系统发现全部技能；
pi.extensions: ["./.pi/extensions/superpowers.ts"] 声明扩展入口。

2. 扩展注册五个生命周期钩子。 superpowers.ts 中依次注册：

resources_discover：上报 skillPaths: [skillsDir]，把整个 skills/ 目录交给 Pi 的技能发现机制；
session_start / session_compact：把 injectBootstrap 标记置为 true——会话启动和会话压缩（compaction）后都需要重新注入引导；
context：在构造发给模型的上下文时执行注入（见下）；
agent_end：把标记置回 false，清除一次性注入状态。

3. 引导消息 = SKILL.md 正文 + 内嵌 Pi 映射。 getBootstrapContent()（L59-L81）读取 skills/using-superpowers/SKILL.md，剥离 YAML frontmatter 后拼成如下结构，作为一条 user 角色消息注入，并整体包在 <EXTREMELY_IMPORTANT> 标记中：

<EXTREMELY_IMPORTANT>
superpowers:using-superpowers bootstrap for pi

You have superpowers.
...（using-superpowers SKILL.md 正文）...

## Pi tool mapping
...（piToolMapping() 内嵌映射文本）...
</EXTREMELY_IMPORTANT>

其中 piToolMapping()（L88-L98）内嵌的映射文本与 pi-tools.md 参考文件同源同义，补充了参考文件之外的两点 Pi 事实：其一，Pi 有原生技能系统但没有 Claude Code 的 Skill 工具，技能适用时用 read 加载相应 SKILL.md，或由人工显式调用 /skill:name；其二，内置编码工具是小写的 read、write、edit、bash 加可选 grep、find、ls，分别对应读文件、建/改文件、跑 shell 命令、搜内容、按名找文件、列目录这些动作。

4. 防重复与压缩后重注入。 context 处理器（L35-L56）先检查消息中是否已含 BOOTSTRAP_MARKER（superpowers:using-superpowers bootstrap for pi），已存在则直接返回、不重复注入；否则用 firstNonCompactionSummaryIndex() 找到首条非 compactionSummary 消息的位置，把引导消息插在它之前——即位于所有压缩摘要之后、真实对话之前。agent_end 事件则清除“待注入”状态，避免启动注入跨越回合残留。

5. 测试锁定上述行为。 tests/pi/test-pi-extension.mjs 用 node --experimental-strip-types --test 运行，覆盖了：

清单断言：pi.skills 为 ["./skills"]、pi.extensions 指向扩展文件、keywords 含 pi-package（L45-L52）；
钩子断言：五个事件各注册且仅注册一个 handler，且不注册 session_before_compact（引导只在压缩后注入，不在压缩前注入）（L54-L61）；
注入断言：启动上下文恰好注入一条 user 消息，内容同时匹配 /You have superpowers/ 与 /Pi tool mapping/；重复请求不产生第二条；agent_end 后不再注入（L72-L101）；
压缩断言：session_compact 之后，引导消息插入在 compactionSummary 消息之后（L103-L119）；
参考文档断言：L121-L137 确认 skills/using-superpowers/references/pi-tools.md 存在，并只针对映射表的表格行（| 开头的行）断言其中有一行匹配 /subagent/i、一行匹配 /todo|task/i。注释特别说明只匹配表格行的原因：整篇文档的散文里同样出现这些词，若匹配全文，则即使表格被删掉测试也会通过——这正是该测试要防的回归。

这套测试与映射参考文档构成了“文档—注入—回归”三层闭环：即使有人删掉映射表，扩展行为测试与文档测试会立即变红。

六、适用前提与限制

适用对象：Pi（pi-coding-agent）作为 harness 运行 Superpowers 的场景。pi-tools.md 仅覆盖 Pi 特有的差异项，Pi 上无差异的动作不需要查阅它。
能力前提：子代理工作流依赖可选的 pi-subagents 包；任务清单工具同样以“已安装扩展”为前提。两者缺失时技能仍可运行，但 dispatching-parallel-agents、subagent-driven-development 等技能会退化为当前会话顺序执行——从仓库文档的表述看，这是设计内行为而非缺陷。
与内嵌映射的关系：pi-tools.md 参考文件与 superpowers.ts 中 piToolMapping() 的文本内容语义一致，但后者是会话内实际送达模型的版本，前者是技能文档树中的查阅版本（SKILL.md 的 Platform Adaptation 指向它）。若两者出现分歧，从移植指南的“code wins”原则看，以扩展实际注入的文本为准。
版本依据：以上全部结论基于本仓库当前代码（package.json 版本 6.2.0）及其测试；Pi 事件名、pi-subagents 的接口能力等属于外部生态事实，文中仅转述仓库文档与测试所确认的范围。