古法编程

要在 Codex 中使用 Superpowers，需将仓库克隆至 ~/.codex/superpowers 并在 ~/.agents/skills/ 下创建指向其 skills 目录的符号链接（Windows 为 junction）以激活原生技能发现。对于需要子代理的技能，需在 ~/.codex/config.toml 中启用 multi_agent = true。为适应 Codex App 的沙盒化 worktree 环境，相关技能内置了只读 git 环境检测机制（比较 git-dir 与 git-common-dir），确保核心工作流在受限环境下仍能安全执行。

Codex 中使用 SuperPowers：原生 Skill Discovery、multi_agent 与 App 兼容

Superpowers 为 OpenAI Codex 提供了一套可组合的技能（skills），引导 AI 编码代理遵循头脑风暴、编写计划、测试驱动开发（TDD）、系统化调试等结构化工作流。本文将指导你完成在 Codex CLI 及 Codex App 中的安装、配置，并理解其关键兼容性设计。

1. 安装与配置

Codex 具备原生技能发现（Native Skill Discovery）功能，它会在启动时自动扫描并加载 SKILL.md 文件。Superpowers 正是利用这一机制进行安装。

1.1 安装步骤（适用于 Codex CLI 与 Codex App）

  1. 克隆仓库到指定目录：

    git clone https://github.com/obra/superpowers.git ~/.codex/superpowers

  2. 创建技能符号链接，使 Codex 能够发现 Superpowers 的所有技能：

    • macOS / Linux：
      mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
    • Windows (PowerShell)：
      New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
      Windows 使用 junction 而非符号链接，无需启用开发者模式。

  3. 重启 Codex。退出并重新启动 Codex CLI 或 App 以使新技能被发现。

安装完成后，可通过验证链接是否存在来确认：

ls -la ~/.agents/skills/superpowers

应看到指向 ~/.codex/superpowers/skills/ 的符号链接或目录（Windows）。

更新与卸载极为简便。更新时，进入仓库目录执行 git pull，更改会通过链接立即生效。卸载时，只需删除符号链接或 junction，并可选删除仓库克隆。

1.2 启用子代理功能（可选）

像 subagent-driven-development 和 dispatching-parallel-agents 这类技能需要 Codex 的多代理支持。请在你的 Codex 配置文件（通常位于 ~/.codex/config.toml）中添加：

[features]
multi_agent = true

启用此功能将解锁 spawn_agent、wait_agent 和 close_agent 工具，这是执行子代理驱动开发等高级工作流的前提。

2. 原生技能发现的工作原理

理解 Codex 如何“看到” Superpowers 技能是正确使用的基础。其工作流程如下：

  1. 目录扫描：Codex 在启动时自动扫描 ~/.agents/skills/ 目录。
  2. 元数据解析：它会解析每个子目录中 SKILL.md 文件头部的 YAML frontmatter，特别是 name 和 description 字段。
  3. 触发与激活：当用户的任务描述匹配某个技能的 description 中定义的触发条件，或在对话中直接提到技能名称（如“使用 brainstorming”），或被 using-superpowers 这个核心技能指令调度时，该技能即被激活。

using-superpowers 技能本身被自动发现，并负责在整个工作流中强制执行技能使用纪律，确保代理遵循正确的流程顺序。

3. Codex 工具映射与子代理调度

Superpowers 技能文档通常使用 Claude Code 的工具名称。在 Codex 环境中，需使用等效的原生工具。根据 codex-tools.md，关键的映射关系如下：

技能中引用的工具 Codex 等效工具/方法
Task 工具（派发子代理） spawn_agent
多个 Task 调用（并行） 多个 spawn_agent 调用
TodoWrite（任务跟踪） update_plan
Skill 工具（调用技能） 技能原生加载，直接遵循其指令
Read, Write, Edit 使用 Codex 原生文件工具

关于命名代理派发的变通方法：某些 Claude Code 技能可能引用如 superpowers:code-reviewer 的命名代理类型。Codex 当前没有命名代理注册表。当遇到此类指令时，需要执行一个变通流程：

  1. 找到对应代理的提示文件（如 agents/code-reviewer.md 或技能内的提示模板）。
  2. 读取并填充模板占位符。
  3. 使用 spawn_agent 创建一个通用 worker 代理，并将填充后的内容作为 message 参数传入。

使用任务委托式 framing（例如“你的任务是…”）而非人设式 framing（例如“你是…”）结构化消息，有助于提高指令遵循度。

4. Codex App 兼容性：沙盒环境适配

Codex App（图形化应用）会在其管理的 git worktree 中运行代理，这些 worktree 可能处于分离头指针（detached HEAD） 状态，并且应用沙盒（如 Seatbelt）会阻塞 git checkout -b、git push 等操作。这与默认假设拥有完整 git 访问权限的技能行为存在冲突。

为了解决这个问题，Superpowers 实施了只读环境检测机制。相关技能会在执行关键操作前运行以下 git 命令来判断环境：

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：表示已在一个由外部（如 Codex App）管理的链接 worktree 中。此时 using-git-worktrees 技能会跳过 worktree 创建，直接进入项目设置和测试基线验证步骤。
  • BRANCH 为空：表示处于分离头指针状态。

在 finishing-a-development-branch 技能中，如果检测到外部管理的 worktree 且处于分离头指针状态（沙盒阻塞了分支和推送操作），代理会转而向用户输出一个交接有效载荷（handoff payload），包含提交的 SHA、建议的分支名和提交信息，并提示用户使用 Codex App 的原生控件（如“创建分支”按钮）来完成最后步骤。

此兼容性设计确保了使用-git-worktrees技能在受限环境下也能“确保隔离的工作空间存在”，而非总是尝试创建新的。

5. 同步到 openai-codex-plugins 仓库

对于维护者和贡献者，Superpowers 项目包含自动化脚本 scripts/sync-to-codex-plugin.sh，用于将主仓库的技能文件同步到 prime-radiant-inc/openai-codex-plugins 插件仓库。该同步过程由 tests/codex-plugin-sync/test-sync-to-codex-plugin.sh 测试脚本进行验证。

同步脚本的核心逻辑包括：

  • 使用 rsync 同步技能文件，并遵循预定义的排除列表。
  • 保留目标仓库中已存在的 OpenAI 元数据（如 openai.yaml）。
  • 支持 --dry-run 预览模式和 --bootstrap 模式（用于首次创建插件目录）。

FAQ

Q: 安装后 Codex 没有识别到任何 Superpowers 技能，怎么办？ A: 请按顺序检查：1) 确认符号链接或 junction 已正确创建并指向 ~/.codex/superpowers/skills。2) 确认 skills 目录下包含 SKILL.md 文件。3) 最关键的一步是重启 Codex，因为技能发现发生在启动时。

Q: 是否所有 Superpowers 技能都能在 Codex 中使用？ A: 大部分技能可以直接使用。但涉及创建子代理（如 subagent-driven-development）的技能，必须先在 Codex 配置中启用 multi_agent = true。此外，一些依赖特定平台特性的技能（如 Claude Code 的 Agent 工具）需要通过工具映射和变通方法来适配。

Q: 如何在 Codex 中更新 Superpowers 技能？ A: 进入你克隆仓库的目录（默认为 ~/.codex/superpowers），然后执行 git pull 命令。由于 ~/.agents/skills/superpowers 是一个指向仓库内 skills 目录的链接，更新会通过该链接自动生效，无需重新创建链接或重启 Codex（新技能需重启发现）。

Q: Codex App 和 Codex CLI 的行为有区别吗？ A: 主要区别在于沙盒环境。Codex CLI 通常拥有完整的 git 权限，而 Codex App 可能运行在受限的 worktree 中。Superpowers 通过环境检测机制自动适配这两种情况，确保核心工作流（如计划执行、TDD、代码审查）在两种环境中都能正确推进，仅在最终权限操作（如推送、创建 PR）上提供不同的引导路径。