Superpowers 在 Kimi Code 中的落地：插件清单、工具映射与完整安装实战指南

本文基于仓库内的 Kimi Code 专用指南，讲解 Superpowers 技能框架如何以插件形式接入 Kimi Code：包括通过插件市场或 GitHub 仓库地址安装的完整命令、.kimi-plugin/plugin.json 清单的三个核心职责、Kimi Code 工具映射（skillInstructions）的逐条细节，以及基于仓库测试脚本的清单校验方法与故障排查步骤。读完后你可以独立完成 Superpowers 在 Kimi Code 中的安装、更新与验收，并能从源码层面理解其"零拷贝、零 hook"的集成原理。

安装 Superpowers 插件

Superpowers 已上架 Kimi Code 的插件市场，这是推荐安装路径：

/plugins

打开插件管理器后，进入 Marketplace > Superpowers 完成安装。

也可以直接从本仓库安装：

/plugins install https://github.com/obra/superpowers

如果需要验证尚未发布的 dev 分支内容，必须显式钉住分支：

/plugins install https://github.com/obra/superpowers/tree/dev

会话生效规则（关键前提）：Kimi Code 只在新会话中应用插件变更。安装、更新、启用、禁用或重载插件之后，必须执行 /new 开启全新会话，改动才会生效。这一点是后续所有故障排查的第一检查项。

工作原理：.kimi-plugin/plugin.json 清单

Kimi 插件清单位于 .kimi-plugin/plugin.json，它与 Claude Code、Codex、Cursor 等其它 harness 的清单（如 .claude-plugin/、.codex-plugin/）平级共存，但只负责 Kimi Code 这一条接入路径。清单一共做三件事：

1. 指向已有的 skills/ 目录——即 "skills": "./skills/"；
2. 会话启动时加载 using-superpowers——通过 sessionStart.skill 字段实现；
3. 提供 Kimi 专属工具映射——通过 skillInstructions 字段注入。

从源码结构看，清单的核心字段集中在 plugin.json#L21-L24：

{
  "name": "superpowers",
  "version": "6.2.0",
  "skills": "./skills/",
  "sessionStart": {
    "skill": "using-superpowers"
  },
  "skillInstructions": "Kimi Code tool mapping for Superpowers skills: ..."
}

其中：

• skills 直接引用仓库根目录的 skills/ 目录。该目录下包含 brainstorming、systematic-debugging、test-driven-development、subagent-driven-development、writing-plans、using-git-worktrees 等 14 个技能目录，全部由 Kimi Code 从本仓库原样读取——没有拷贝的技能副本、没有符号链接、没有 hooks、没有额外运行时依赖；
• sessionStart.skill 指定每次会话启动时加载 skills/using-superpowers/SKILL.md。这个"元技能"负责建立整个框架的运行纪律：在任何响应（包括澄清式提问）之前必须先检查并调用相关技能、流程类技能（如 brainstorming、systematic-debugging）优先于实现类技能、以及一组"合理化借口"红旗清单（Red Flags）。它是 Superpowers 在 Kimi Code 中"自动生效"的入口；
• skillInstructions 是 Kimi 专属的适配层，详见下一节。

另外值得一提的是，Kimi Code 的参考适配并没有走 using-superpowers 中 references/ 目录那条路（该目录只有 Codex、Pi、Antigravity 三份工具参考文档），而是把适配说明内联在清单的 skillInstructions 字段里。这一差异在仓库的 harness 移植文档 docs/porting-to-a-new-harness.md 的对比表中也有记载：Kimi Code 一行的适配方式即"manifest 内联 skillInstructions"。

工具映射（Tool Mapping）

Superpowers 的设计原则是：技能描述的是动作语义，而不是写死某个运行时的工具名。"向用户提问""创建待办""派发子代理"这类表述在不同 harness 中解析为不同的具体工具。在 Kimi Code 中，这些语义解析为以下映射表：

技能中的动作描述	Kimi Code 工具
"Ask the user" / "ask clarifying questions"	AskUserQuestion
"Create a todo" / "mark complete in todo list"	TodoList
"Dispatch a subagent"	Agent
"Invoke a skill"	Kimi Code 原生 Skill 工具
"Read a file" / "write a file" / "edit a file"	Read、Write、Edit
"Run a shell command"	Bash
"Search file contents"	Grep
"Find files by path or pattern"	Glob
"Fetch a URL"	FetchURL
"Search the web"	WebSearch

上述映射并不是文档中的口头约定，而是完整写进了清单 skillInstructions 字段中，并配有几条比映射表更具体的执行细则：

AskUserQuestion 的使用规范：当技能要求向用户提问、给出多选选项或等待用户选择时，调用 AskUserQuestion 而不是把选项渲染成纯文本（除非该工具不可用或会话处于自动授权模式）。每次提供 1 个问题、2~4 个具体选项，并把推荐选项放在第一位、标签后加 (Recommended) 后缀。

子代理派发规范：当技能提到 Task tool (general-purpose) 或要求派发 implementer/reviewer 子代理时，使用 Kimi Code 的 Agent 工具并指定 Kimi 的子代理类型，不要把 general-purpose 作为 subagent_type 传入。具体分三类：

• 实现类工作（implementation、code review、spec review、quality review，以及填写好的 Superpowers 子代理提示词模板）：Agent + subagent_type: "coder"，把完整填写的提示词贴入 prompt，并给出简短 description；
• 只读代码库探索（需要多轮搜索时）：subagent_type: "explore"；
• 只读规划或架构设计：subagent_type: "plan"。

并发与依赖约束：相互依赖的 Superpowers 子代理步骤必须串行执行；只有在工作相互独立、且后台代理可用时，才可以使用多个 Agent 调用或 run_in_background: true。

MCP 工具：映射表末尾还规定，Read、Write、Edit、Bash、Grep、Glob、FetchURL、WebSearch 以及 MCP 工具一律按 Kimi Code 实际暴露的工具名调用。

清单校验：tests/kimi 中的自动化测试

这套集成有一个轻量但严格对应的测试套件 tests/kimi/test-plugin-manifest.sh（由 tests/kimi/run-tests.sh 驱动）。测试用 Python 解析清单，断言的内容可以逐条对照理解"什么会让 Kimi 集成失效"：

1. 基础字段：name 必须为 superpowers；skills 必须恰好是 ./skills/；sessionStart.skill 必须恰好是 using-superpowers；
2. 工具映射完整性：skillInstructions 必须是非空字符串，且必须包含全部 12 个工具 token（AskUserQuestion、TodoList、Agent、Skill、Read、Write、Edit、Bash、Grep、Glob、FetchURL、WebSearch）——任何一条映射被误删都会让测试失败；
3. 版本联动：.version-bump.json 的 files 列表中必须存在 { "path": ".kimi-plugin/plugin.json", "field": "version" } 条目，确保每次发版脚本统一抬升清单版本（与 package.json、.claude-plugin/、.cursor-plugin/、.codex-plugin/、gemini-extension.json 保持同步）；
4. 无越界字段：断言清单中不得出现 tools、commands、hooks、apps、inject、configFile、config_file、bootstrap 这些字段——即测试从反面约束了"Superpowers 在 Kimi Code 上不引入 hook 或额外运行时"这一设计承诺。

更新与故障排查

更新插件

通过 Kimi Code 的插件管理器更新：

/plugins

选中 Superpowers 执行更新，更新完成后同样执行 /new 开启新会话。

排查一：插件未加载

1. 运行 /plugins info superpowers 查看诊断信息；
2. 确认插件处于启用（enabled）状态；
3. 安装或更新后，用 /new 开启新会话。

排查二：直接 GitHub 安装装到了旧版本

当仓库存在 GitHub Release 时，Kimi Code 对"裸仓库 URL"的安装会取最新 release，而不是最新提交。如果要在下一个 Superpowers release 之前测试未发布变更，必须显式安装分支：

/plugins install https://github.com/obra/superpowers/tree/dev

排查三：技能不触发

1. 用 /plugins info superpowers 确认插件已启用；
2. 执行 /new 开启新会话；
3. 使用验收提示语测试：Let's make a react todo list。一次正常工作的安装，应该在写任何代码之前先加载 brainstorming 技能——这正是 sessionStart.skill: using-superpowers 建立的"先查技能、再响应"纪律在 Kimi Code 中的预期表现。

小结

Superpowers 接入 Kimi Code 的完整链路可以概括为：一份清单文件（.kimi-plugin/plugin.json）+ 一套零拷贝技能目录（skills/）+ 一段内联工具映射（skillInstructions）+ 一组可运行的清单测试（tests/kimi/）。清单负责把会话启动、技能发现、工具语义三件事绑定到 Kimi Code 的原生能力上，而所有技能内容都直接读取自仓库本身，不产生任何副本或额外依赖。这也是该仓库多 harness 移植体系（详见 docs/porting-to-a-new-harness.md）中 Kimi Code 一行的标准实现形态。