using-superpowers

# Antigravity CLI（`agy`）工具映射

Skills 说的是动作（"分派一个子智能体"、"建一条待办"、"读一个文件"）。在 Antigravity CLI（`agy`）上，这些动作对应下面这些工具。

| Skill 请求的动作 | Antigravity CLI 等价工具 |
|----------------|----------------------|
| 分派子智能体（`Subagent (general-purpose):` 模板） | `invoke_subagent`，配一个内置的 `TypeName` —— 全能力工作用 `self`，只读调研用 `research` |
| 任务跟踪（"建一条待办"、"标记完成"） | 一个 **task artifact** —— 用 `write_to_file` 并带上 `IsArtifact: true` 与 `ArtifactType: "task"`（见下方[任务跟踪](#任务跟踪)）。**不是** `manage_task`，那个是管后台进程的。 |

## 任务跟踪

Antigravity **没有 todo 工具**（`manage_task` 管的是后台进程 —— `list`／`kill`／`status`／`send_input` —— 它**不是**清单工具）。当某个 skill 说要创建待办清单或跟踪任务时，改为维护一个 **task artifact**：一份用 `write_to_file` 保存的 markdown 清单（`IsArtifact: true`、`ArtifactMetadata.ArtifactType: "task"`），过程中用 `replace_file_content` ／ `multi_replace_file_content` 来编辑。

任何多步任务一开始，就创建这个 task artifact，把你计划里的每一步都列上。每完成一步，就编辑该 artifact 把它标记为完成（`- [x]`）。计划有变就更新清单。**保持它是最新的** —— 它是"还剩什么没做"的唯一事实来源；一旦对话变长，每开始一步之前先重读它。

# Codex 工具映射

> 🇨🇳 **本节的工具映射表是 superpowers-zh 的增量内容，上游 obra/superpowers 没有。** 其余章节为上游内容的翻译。

Skills 使用 Claude Code 的工具名称。在 Codex 中遇到这些名称时，请使用对应的平台等价工具：

| Skill 中的引用 | Codex 等价工具 |
|---------------|---------------|
| `Task` 工具（派遣子 agent） | `spawn_agent` |
| 多个 `Task` 调用（并行） | 多个 `spawn_agent` 调用 |
| Task 返回结果 | `wait_agent` |
| Task 自动完成 | V2 无需处理（用完自动回收）；仅 V1 需要 `close_agent` 释放槽位 |
| `TodoWrite`（任务跟踪） | `update_plan` |
| `Skill` 工具（调用 skill） | Skills 原生加载——直接按说明操作 |
| `Read`、`Write`、`Edit`（文件） | 使用原生文件工具 |
| `Bash`（执行命令） | 使用原生 shell 工具 |

## 子 Agent 派遣需要多 Agent 支持

在 Codex 配置文件（`~/.codex/config.toml`）中添加：

```toml
[features]
multi_agent = true
```

启用后，`dispatching-parallel-agents` 和 `subagent-driven-development` 这类 skill 所用的多智能体工具就可用了。**你拿到哪些工具，取决于你的模型预设选中的多智能体版本**（当前的预设跑 V2，较老的跑 V1）。当你的实际工具列表与任何表格（**包括本文这张**）不一致时，以实际工具列表为准。

- **派生（Spawning）：** 用 `spawn_agent {fork_turns: "none"}` 给子代理一个干净的上下文；默认值 `"all"` 会把你的**整份对话记录**复制进子代理。在 Codex 0.145+ 上，`~/.codex/agents/` 下的角色文件通过 `agent_type` 挂到隔离 fork 上。全历史 fork 接受 `model` 与 `reasoning_effort` 覆盖（在那里只有 `agent_type` 会被拒绝）—— 隔离 fork 是 SDD 的默认选择，理由是上下文卫生，**不是**因为覆盖参数需要它。
- **修复轮次（Fix rounds）：** 用 `followup_task` 唤回实现者 —— 它会送达你的消息、触发一个回合，并在 harness 已经回收该子代理时透明地把它重新装载回来。绝不要因为「派生出去的 agent 不能再被发消息」这种想当然而重新派一个新的实现者；在 V2 上它**总是**可以。
- **生命周期（Lifecycle）：** **V2 没有 `close_agent`。** 完成的子代理会在需要槽位时被自动回收，放着不管不产生任何成本。只有 V1 会话才有 `close_agent` —— 在那里，审查者返回审查结果后就关掉它，每个实现者在其任务的审查通过后关掉。
- **模型名：** 绝不要把 skill、表格或旧会话里的模型名直接抄进 `spawn_agent` 而不先对照你**当前**的 spawn 允许列表 —— V2 只接受具备 V2 能力的预设，其余会直接硬报错。

## 等待子代理

`wait_agent` 是**事件订阅，不是轮询**：一次长等待会在子代理产生信箱活动的那一刻醒来，延迟和短等待完全一样。短超时轮询什么也换不到，却每次都要付一次工具调用 —— 以及一次上下文重新计费。在实测会话里，大约**三分之二**的 wait 调用都是超时的短轮询。

- 只要你手上还有本地工作，就**完全不要等**。已完成子代理的最终回答会被推进你的信箱，随你的下一个回合一起到达。
- 当你确实空闲、且还有子代理在跑时，按**有界的时间段**等待：`wait_agent` 的 `timeout_ms` 设 300000-600000（5-10 分钟）。每一段结束后 —— 无论是被唤醒还是超时 —— 发一行状态、跑一次 `list_agents`，并追查任何「已完成但没汇报」的子代理。绝不要把小于五分钟的轮询叠着用；事件订阅唤醒一个有界时间段的速度和唤醒一次短轮询一样快。
- 完成邮件**无法唤醒一个空闲的控制者**（它送达时不触发回合）；覆盖这个空闲窗口正是 `wait_agent` 唯一的职责。一段等待在毫无活动的情况下超时，是让你去做对账的信号，**不是**让你把下一段缩短的理由。

## 派生时的模型路由

你发出的**每一次** `spawn_agent`（包括你自己就是一个正在做扇出的子代理时），都要按你正在执行的那个 skill 的「模型选择」规则，**同时显式设置 `model` 和 `reasoning_effort`**。只设 `model` 是个陷阱：子代理的 effort 会静默重置为那个模型的默认值，而不是你的。

请你的人类伙伴在 `~/.codex/config.toml` 里加一道机器级兜底，这样任何漏设的派生仍然会路由到一个刻意选定的档位，而不是静默继承本次会话最贵的那个模型：

```toml
[agents]
default_subagent_model = "<你的 spawn 允许列表里的一个中档模型>"
default_subagent_reasoning_effort = "medium"
```

## 环境检测

创建 worktree 或收尾分支的 skill，应当在动手之前用**只读**的 git 命令检测环境：

```bash
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)
```

- `GIT_DIR != GIT_COMMON` → 已经在一个链接的 worktree 里（跳过创建）
- `BRANCH` 为空 → detached HEAD（无法从沙箱里建分支/推送/开 PR）

各 skill 如何使用这些信号，见 `using-git-worktrees` 的第 0 步与 `finishing-a-development-branch` 的第 1 步。

## Codex App 的收尾

当沙箱阻止建分支/推送操作时（在外部托管的 worktree 里处于 detached HEAD），agent 应提交全部工作，并告知用户改用 App 的原生控件：

- **"Create branch"** —— 命名分支，然后通过 App UI 完成 commit/push/PR
- **"Hand off to local"** —— 把工作转交到用户的本地检出

agent 仍然可以跑测试、暂存文件，并输出建议的分支名、commit message 和 PR 描述供用户复制。

# Copilot CLI 工具映射

技能使用 Claude Code 的工具名称。当你在技能中遇到这些工具时，使用你平台的等价工具：

| 技能中引用的工具 | Copilot CLI 等价工具 |
|-----------------|----------------------|
| `Read`（读取文件） | `view` |
| `Write`（创建文件） | `create` |
| `Edit`（编辑文件） | `edit` |
| `Bash`（运行命令） | `bash`（Windows 上常为 `powershell`，见[异步 Shell 会话](#异步-shell-会话)） |
| `Grep`（搜索文件内容） | `grep` |
| `Glob`（按名称搜索文件） | `glob` |
| `Skill` 工具（调用技能） | `skill` |
| `WebFetch` | `web_fetch` |
| `Task` 工具（分派子智能体） | `task`（参见[智能体类型](#智能体类型)） |
| 多个 `Task` 调用（并行） | 多个 `task` 调用 |
| Task 状态/输出 | `read_agent`、`list_agents` |
| `TodoWrite`（任务跟踪） | `sql` 配合内置 `todos` 表 |
| `WebSearch` | 无等价工具 — 使用 `web_fetch` 配合搜索引擎 URL |
| `EnterPlanMode` / `ExitPlanMode` | 无等价工具 — 留在主会话中 |

## 智能体类型

Copilot CLI 的 `task` 工具接受 `agent_type` 参数：

| Claude Code 智能体 | Copilot CLI 等价 |
|-------------------|----------------------|
| `general-purpose` | `"general-purpose"` |
| `Explore` | `"explore"` |
| 命名的插件智能体（形如 `<插件名>:<智能体名>`） | 从已安装的插件中自动发现 |

## 异步 Shell 会话

Copilot CLI 支持持久化的异步 shell 会话，这在 Claude Code 中没有直接等价物。

> ⚠️ **shell 工具面随平台和版本而异，下面两套工具名不会同时出现。** 动手之前先确认你这个 build 实际注册的是哪一套 —— 照着不存在的工具名调用，agent 会找不到工具然后即兴发挥。Windows 上常见的是 powershell 那一套（实测 Copilot CLI 1.0.69-1 / Windows 只有 powershell，没有任何 `bash` / `async` 家族工具）。

**Unix / macOS —— bash 一套：**

| 工具 | 用途 |
|------|---------|
| `bash` 配合 `async: true` | 在后台启动长时间运行的命令 |
| `write_bash` | 向运行中的异步会话发送输入 |
| `read_bash` | 读取异步会话的输出 |
| `stop_bash` | 终止异步会话 |
| `list_bash` | 列出所有活跃的 shell 会话 |

**Windows —— powershell 一套：**

| 工具 | 用途 |
|------|---------|
| `powershell` 配合 `detach: true` | 在后台启动长时间运行的命令（参数名是 `detach`，**不是** `async`） |
| `read_powershell` | 读取会话的输出 |
| `stop_powershell` | 终止会话 |
| `list_powershell` | 列出所有活跃的 shell 会话 |
| （无 `write_powershell`） | 这一套**没有**向运行中会话发送输入的工具 |

### Windows 上的两个坑

**1. `.sh` 脚本不能裸跑。** powershell 下直接执行 `scripts/start-server.sh` 会报 `The term 'scripts/start-server.sh' is not recognized...`，必须显式走 Git Bash：

```powershell
& "C:\Program Files\Git\bin\bash.exe" scripts/start-server.sh
```

**2. `stop_powershell` 停不掉 `detach: true` 启动的进程。** detached 进程要按 PID 停：

```powershell
Stop-Process -Id <PID>
```

所以**不要把 `stop_*` 当作 detached 常驻进程的唯一清理路径** —— 必须先拿到真实的 Windows PID（不是 MSYS PID），再 `Stop-Process`。涉及长驻 server 的 skill（如 brainstorming 的视觉伴侣）在 Windows 上尤其要注意这一点。

## 额外的 Copilot CLI 工具

| 工具 | 用途 |
|------|---------|
| `store_memory` | 持久化代码库相关事实供未来会话使用 |
| `report_intent` | 更新 UI 状态行显示当前意图 |
| `sql` | 查询会话的 SQLite 数据库（待办、元数据） |
| `fetch_copilot_cli_documentation` | 查阅 Copilot CLI 文档 |
| GitHub MCP 工具（`github-mcp-server-*`） | 原生 GitHub API 访问（issue、PR、代码搜索） |

# Gemini CLI 工具映射

Skills 说的是动作（"分派一个子智能体"、"建一条待办"、"读一个文件"）。在 Gemini CLI 上，这些动作对应下面这些工具。

| Skill 请求的动作 | Gemini CLI 等价工具 |
|----------------|-------------------|
| 读取一个文件 | `read_file` |
| 一次读取多个文件 | `read_many_files` |
| 创建新文件 | `write_file` |
| 编辑文件 | `replace` |
| 执行 shell 命令 | `run_shell_command` |
| 搜索文件内容 | `grep_search` |
| 按名称查找文件 | `glob` |
| 列出文件和子目录 | `list_directory` |
| 抓取 URL | `web_fetch` |
| 搜索网页 | `google_web_search` |
| 调用一个 skill | `activate_skill` |
| 分派子智能体（`Subagent (general-purpose):` 模板） | `invoke_agent`，`agent_name: "generalist"`（也可用 `@generalist` 聊天语法调用——见[子智能体支持](#子智能体支持)） |
| 多个并行分派 | 同一条响应里发多个 `invoke_agent` 调用 |
| 任务跟踪（"建一条待办"、"标记完成"） | `write_todos`（状态：pending、in_progress、completed、cancelled、blocked） |

## 指令文件

当某个 skill 提到"你的指令文件"时，在 Gemini CLI 上指的是 **`GEMINI.md`**。Gemini CLI 按层级加载 `GEMINI.md`：全局的在 `~/.gemini/GEMINI.md`，项目级的在工作区目录及其各级父目录里，另外当某个工具访问子目录中的文件时，该子目录下的 `GEMINI.md` 也会被加载。

## 个人 skills 目录

用户级 skills 放在 **`~/.gemini/skills/`**，**`~/.agents/skills/`** 是跨运行时的别名目录（与 Codex、Copilot CLI 共用）。当同一层级下两个目录都存在时，`.agents/skills/` 优先。每个 skill 是一个子目录，里面有一份带 `name` 和 `description` frontmatter 的 `SKILL.md`。

## 子智能体支持

Gemini CLI 通过 `invoke_agent` 工具分派子智能体，该工具接收 `agent_name` 和 `prompt` 两个参数。同一个分派动作也有聊天语法快捷方式：输入 `@generalist <prompt>` 等价于以 `agent_name: "generalist"` 调用 `invoke_agent`。内置的 agent 名包括 `generalist`、`cli_help`、`codebase_investigator`，以及（启用浏览器工具后的）`browser_agent`。

Skills 用 `Subagent (general-purpose):` 来分派，并且要么引用一个提示词模板文件（例如 `subagent-driven-development` 的 `./implementer-prompt.md`），要么直接给出内联提示词。在 Gemini CLI 上：

| Skill 里的分派形式 | Gemini CLI 等价做法 |
|------------------|-------------------|
| 引用某个 `*-prompt.md` 模板（implementer、task-reviewer、code-reviewer 等） | 把模板填好，然后以 `agent_name: "generalist"` 和填好的提示词调用 `invoke_agent` |
| 引用 `requesting-code-review` 的 `./code-reviewer.md` | 以 `agent_name: "generalist"` 和填好的审查模板调用 `invoke_agent` |
| 内联提示词（没有引用模板） | 以 `agent_name: "generalist"` 和你的内联提示词调用 `invoke_agent` |

### 填写提示词

Skills 提供的提示词模板里有 `{WHAT_WAS_IMPLEMENTED}` 或 `[FULL TEXT of task]` 这类占位符。把所有占位符都填好，再把完整提示词交给 `invoke_agent`。模板本身就包含了该 agent 的角色、审查标准和期望的输出格式——子智能体会照着它执行。

### 并行分派

Gemini CLI 支持并行分派子智能体。在同一条响应里发出多个 `invoke_agent` 调用（或在一个提示词里写多个 `@generalist` 调用），即可让相互独立的子智能体工作并行跑。有依赖关系的任务保持串行，但**不要**为了让历史记录简单一点就把相互独立的子智能体任务串起来。

## Gemini CLI 额外工具

以下工具是 Gemini CLI 独有的：

| 工具 | 用途 |
|------|------|
| `save_memory`（旧版） | 当 `experimental.memoryV2 = false` 时，跨会话持久化事实 |
| `get_internal_docs` | 查阅 Gemini CLI 自带的文档 |
| `ask_user` | 向用户提出结构化问题（文本 / 单选 / 多选） |
| `enter_plan_mode` / `exit_plan_mode` | 进入和退出只读的计划模式 |
| `update_topic` | 更新当前会话的主题 / 战略意图元数据 |
| `complete_task` | 表示某个 Gemini 子智能体已完成，并把结果返回给父 agent |
| `tracker_create_task`、`tracker_update_task`、`tracker_get_task`、`tracker_list_tasks`、`tracker_add_dependency`、`tracker_visualize` | 功能完整的任务跟踪器，支持依赖关系与可视化 |
| `read_mcp_resource`、`list_mcp_resources` | 访问 MCP 资源 |

# Hermes Agent 工具映射

## 工具

| Skill 里要做的动作 | Hermes 工具 |
|------------------|------------|
| 读取文件 | `read_file` |
| 创建新文件 | `write_file` |
| 编辑文件（定点补丁） | `patch` |
| 运行 shell 命令 | `terminal` |
| 搜索文件内容 | `search_files` |
| 按文件名查找 | `terminal` 配合 `find` |
| 抓取 URL / 读网页 | `web_extract(urls=[...])` |
| 搜索网络 | `web_search(query=...)` |
| 派遣子智能体 | `delegate_task(goal=..., context=..., toolsets=[...], role="leaf")` |
| 任务跟踪 | `todo` 工具 |
| 调用 skill | `skill_view("skill-name")` |

## 指令文件

当某个 skill 提到「你的指令文件」时，在 Hermes Agent 上指的是项目目录里的 **`AGENTS.md`**，或全局的 **`~/.hermes/SOUL.md`**。

> 🇨🇳 **本节是 superpowers-zh 的增量内容，上游 obra/superpowers 没有。**
>
> 补充一条实践区分：`SOUL.md` 是**身份/人格**文件（Hermes 官方文档明确说项目工作流指令不属于它），所以 `npx superpowers-zh --tool hermes` 的**项目级**安装只写 `AGENTS.md`；**全局**安装只装 skills、不写 bootstrap —— 往 SOUL.md 里塞技能清单是误用那个文件。

## 调用 skill

Hermes Agent 有一个 `skills` 工具集，包含 `skill_view` 和 `skills_list` 两个工具。
要调用某个 superpowers skill，使用：

```
skill_view("brainstorming")
skill_view("test-driven-development")
```

如果 `skill_view` 找不到某个 superpowers skill（在插件完全注册之前，它可能还没出现在目录里），退回到直接读取 SKILL.md：

```
read_file(path="~/.hermes/plugins/superpowers/skills/<skill-name>/SKILL.md")
```

这个回退机制与其他没有原生 skill 加载能力的 harness 用的是同一套。

## 子智能体派遣

用 `delegate_task` 为并行或串行的工作流派生隔离的子智能体：

```
delegate_task(goal="...", context="...", toolsets=[...], role="leaf")
```

如果 `delegate_task` 不可用，就把工作内联做完，不要凭空编造工具调用。

## 任务跟踪

会话内的任务跟踪用 `todo` 工具。多智能体的任务看板，如果可用则使用 `hermes kanban` CLI。遇到旧文档里的 `TodoWrite` 引用，按「任务跟踪」这个动作理解即可。

# Pi Tool Mapping

Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Pi these resolve to the tools below.

| Action skills request | Pi equivalent |
| --- | --- |
| Invoke a skill | Pi native skills: load the relevant `SKILL.md` with `read`, or let the human use `/skill:name` |
| Read a file | `read` |
| Create a file | `write` |
| Edit a file | `edit` |
| Run a shell command | `bash` |
| Search file contents | `grep` when active; otherwise `bash` with `rg`/`grep` |
| Find files by name | `find` or `bash` with shell globs |
| List files and subdirectories | `ls` when active; otherwise `bash` with `ls` |
| Dispatch a subagent (`Subagent (general-purpose):` template) | Use an installed subagent tool such as `subagent` from `pi-subagents` if available |
| Task tracking ("create a todo", "mark complete") | Use an installed todo/task tool if available, otherwise track tasks in the plan or `TODO.md` |

## Skills

Pi discovers skills from configured skill directories and installed Pi packages. A Superpowers Pi package should expose `skills/` through its `pi.skills` manifest entry. Pi does not expose Claude Code's `Skill` tool, but the agent should still follow the Superpowers rule: when a skill applies, load and follow it before responding.

## Subagents

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.

## Task lists

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.

# Qoder 工具映射

Skills 使用 Claude Code 的工具名称。Qoder（阿里 AI IDE）大部分工具与 Claude Code **同名**，只有少数差异：

| Skill 中的引用 | Qoder 等价工具 |
|---------------|---------------|
| `Read` / `Write` / `Edit` | 同名（`Read` / `Write` / `Edit`） |
| `Bash` | 同名 |
| `Grep` / `Glob` | 同名 |
| `Task`（派遣子 agent） | 同名（`Task`） |
| `WebFetch` / `WebSearch` | 同名 |
| `AskUserQuestion` | 同名 |
| `Skill` | 同名 |
| `TodoWrite` | 同名 |
| `EnterPlanMode` / `ExitPlanMode` | **`EnterSpecMode` / `ExitSpecMode`**（Qoder 把"计划模式"称为"Spec 模式"）|

## Task 子 Agent 类型

> **适用范围：Qoder CLI。** 下表逐条核对自 [Qoder 官方文档 · 子代理](https://docs.qoder.com/zh/cli/subagent)（核对于 2026-08）。
> **Qoder IDE 的内置 subagent 集合与此不同，我们尚未核实** —— 见下方「IDE 与 CLI 的差异」。

| Claude Code Agent | Qoder CLI 等价 | 说明 |
|------------------|---------------|------|
| `general-purpose` | `general-purpose` | 通用研究型，适合复杂搜索、多文件分析、调用链追踪、多步骤任务 |
| `Explore` | `Explore` | 同名。只读代码探索 |
| `Plan` | `Plan` | 同名。只读设计与规划 |
| `claude-code-guide` | `qoder-guide` | 非 SDK 模式下可用 |

文档另列出 `statusline-setup`（TUI 模式）。**没有内置的 `code-reviewer`** —— 文档里出现的 `api-reviewer` 是用户自建 subagent 的示例，不是内置项。需要专职审查者时，用 `general-purpose` 配 `requesting-code-review` 的 `code-reviewer.md` 模板。

### IDE 与 CLI 的差异

[#119](https://github.com/jnMetaCode/superpowers-zh/issues/119) 报告：在 **Qoder IDE** 里跑 `subagent-driven-development` 时，Qoder 说它只提供 `CodeReview` subagent、**没有** `general-purpose`，于是自行降级为「控制者直接实现 + CodeReview agent 做审查」。

官方 subagent 文档只覆盖 CLI，没有说这套内置集合同样适用于 IDE。**所以上表在 Qoder IDE 上不保证成立。** 如果你在 IDE 里遇到「找不到 general-purpose」，那是预期内的差异，不是 superpowers-zh 装错了 —— Qoder 的自动降级本身是合理适配。

## Quest MCP 工具（Qoder 原生）

Qoder 内置 Quest 系统提供以下工具，Claude Code 没有等价物，可在 skill 流程中直接调用：

| 工具 | 用途 |
|------|------|
| `mcp__quest__search_codebase` | 语义化代码搜索（按意图找代码） |
| `mcp__quest__search_symbol` | 按符号名搜索代码及关系 |
| `mcp__quest__get_problems` | 获取文件编译/语法错误 |
| `mcp__quest__run_preview` | 启动本地 Web 服务器预览 |
| `mcp__quest__search_memory` / `update_memory` | 跨会话记忆管理 |
| `mcp__quest__fetch_rules` | 查询规则文件 |

## 加载方式

Qoder 在每个会话自动加载 `.qoder/rules/superpowers-zh.md`（`trigger: always_on`），里面包含 skill 索引。`.qoder/skills/<name>/SKILL.md` 由模型按 description 自主调用，也可输入 `/<skill-name>` 手动触发。