OpenCode 的工具映射表可能未跟上上游：@mention 不是模型可调用的工具（上游 d7f47d350a 已修正）

[Qingzhujiu]

背景

先感谢维护这个项目 🙏 我这边在 OpenCode（V1.18.31，Windows）上用得很顺。

最近排查一个子代理调度的问题时，顺手核对了插件注入的 OpenCode 工具映射表，发现有一处似乎已经过期。不确定是否已知，先在这里报备一下，如果有打扰请见谅。

现象

插件通过 .opencode/plugins/superpowers.js 的 getBootstrapContent()，把下面这段注入每条会话的第一条 user 消息（逐字）：

**Tool Mapping for OpenCode:**
When skills reference tools you don't have, substitute OpenCode equivalents:
- `TodoWrite` → `todowrite`
- `Task` tool with subagents → Use OpenCode's subagent system (@mention)
- `Skill` tool → OpenCode's native `skill` tool
- `Read`, `Write`, `Edit`, `Bash` → Your native tools

Use OpenCode's native `skill` tool to list and load skills.

其中前两行（TodoWrite、Skill）是对的，另外两处和 OpenCode 实际暴露给模型的工具对不太上：

1. Task tool with subagents → "Use OpenCode's subagent system (@mention)"
   @mention 是 TUI 里用户侧的输入方式（用户在输入框里 @ 一个 agent 来选/切换），并不存在一个名叫「mention」的模型可调用工具。skill 正文要求「派遣子代理」时，模型实际能用的只有 task 工具，并传 subagent_type，例如 task(subagent_type="explorer", description=..., prompt=...)。

2. Read, Write, Edit, Bash → "Your native tools"
   比较笼统，没有落到具体工具名上。OpenCode 里实际是 read / write / edit / bash；另外 skill 正文会引用到的检索与抓取能力（grep / glob / webfetch）这里没有提到。

对照一下（「实际工具名」取自 V1.18.31 会话中暴露给模型的工具清单）：

skill 正文里的说法	当前映射	实际情况
TodoWrite	todowrite	✅ 一致
Skill	OpenCode 原生 skill 工具	✅ 一致
Task tool with subagents	"Use OpenCode's subagent system (@mention)"	@mention 不是模型可调用的工具；派遣子代理应使用 task + subagent_type
Read, Write, Edit, Bash	"Your native tools"	未给出具体工具名（read / write / edit / bash），且未覆盖 grep / glob / webfetch

影响面不算大，但所有涉及「派遣子代理 / 读写文件 / 执行命令」的 skill（subagent-driven-development、dispatching-parallel-agents、executing-plans、systematic-debugging 等）在 OpenCode 上都要靠这张表来翻译工具名，所以模型可能需要自己猜。

上游的情况

查了一下，上游 obra/superpowers 今年 5 月已经处理过这一处。

d7f47d350a（2026-05-06，Phase E: action-language tool vocabulary）的提交说明里逐字写着：

OpenCode INSTALL.md and docs/README.opencode.md: replace the old
"TodoWrite → todowrite, Task → @mention" mapping (which both
taught a vocabulary skills no longer use AND was wrong about
@mention being a real OpenCode syntax) with an action-language
mapping verified against the installed OpenCode CLI's tool
inventory.

随后 f030d6ef88（2026-05-14，Tighten cross-platform tool references）又调整了 plugin 文件本身。

上游现在的表（逐字，仅供对照）：

**Tool Mapping for OpenCode:**
When skills request actions, substitute OpenCode equivalents:
- Create or update todos → `todowrite`
- `Subagent (general-purpose):` → `task` with `subagent_type: "general"`
- Invoke a skill → OpenCode's native `skill` tool
- Read files → `read`
- Create, edit, or delete files → `apply_patch`
- Run shell commands → `bash`
- Search files → `grep`, `glob`
- Fetch a URL → `webfetch`

Use OpenCode's native `skill` tool to list and load skills.

可能的原因

本 fork 的 .opencode/plugins/superpowers.js 历史上只有两次提交：

fc9a2a40ca  2026/4/13  同步上游 v5.0.7：Copilot CLI 支持、OpenCode bootstrap 改进、版本统一
80bc100625  2026/3/20  superpowers 中文社区版：14 翻译 + 5 中国原创 skills

最后一次是 2026-04-13，时间点应该在上游 Phase E 之前，之后这个文件似乎没有跟着再同步过。

docs/README.opencode.md（「Task（子代理）→ OpenCode 的 @mention 系统」「文件操作 → OpenCode 原生工具」）与 .opencode/INSTALL.md（「Task 子代理 → @mention 语法」）里的对应说明是同一批文本的中译，状态一致。

另外看到 .upstream-sync.json 的 trackedPaths 是 ["skills", "hooks"]，.opencode/plugins/ 和 docs/ 似乎不在同步/校验范围内，所以这类漂移可能不容易被现有 audit 覆盖到。

建议（仅供参考）

1. 把插件里的 toolMapping，以及 docs/README.opencode.md、.opencode/INSTALL.md 的对应说明，对齐到上游 d7f47d350a 之后的版本
2. 如果觉得合适，也可以考虑把 .opencode/plugins 加进 .upstream-sync.json 的 trackedPaths，或在 verify-release 里加一条轻量断言（例如：映射表中出现的工具名需要存在于 OpenCode 的工具清单中）

这与 #45 里提到的思路是一致的——工具名交给映射表负责，skill 正文保持 harness 中立。

其他

再次感谢这个项目～