mirror of https://github.com/jnMetaCode/superpowers-zh.git synced 2026-09-02 22:54:06 +08:00

Files

AI不止语 fb63548c9d fix(installer): Codex 项目级装到 Codex 从不扫描的目录；CodeArts 补 --global

## Codex：项目级又是「装了完全不生效」

官方 skills 文档（developers.openai.com/codex/skills，现 308 跳到官方新文档站）
给出的扫描目录**完整清单**：

    $CWD/.agents/skills、$CWD/../.agents/skills、$REPO_ROOT/.agents/skills
    $HOME/.agents/skills、/etc/codex/skills、内置 skill

**没有 .codex/skills。** 两次分别追问确认「.codex/skills 是否曾被扫描」，答案都是
从未出现。而我们项目级正是装到 .codex/skills。

全局（~/.agents/skills）一直是对的 —— 原注释也写明了「不是 ~/.codex/skills」，
说明当初查过全局却没顺手核项目级。改为 .agents/skills，并在安装时清理旧位置
（只清我们装的那些，用户自己放在 .codex/skills 下的不动，已实测）。

与 Antigravity 共用 .agents/skills 是 Agent Skills 开放约定，不是冲突。

## 这个改动暴露出一个既有 bug：检测有顺序依赖

改完后测试立刻报「检测 .codex/ -> 得到「Antigravity,Codex CLI」，期望「Codex CLI」」。

根因：自动检测是**边装边判**的。Codex 装到 .agents/skills 会创建 .agents/，
循环走到 Antigravity（detect: '.agents'）时它就被误判为「项目里有这个工具」，
于是多装一份。这个坑在任何「装了 A 会创建 B 的检测标记」的组合上都会犯。

改为先把所有工具的检测结果一次性算完再开始装 —— 检测必须基于**安装前**的项目
状态。实测：只有 .codex 时只装 Codex；同时有 .codex 与 .agents 时两款都装且
.agents/skills 下仍是 20 个（不重复）。

## CodeArts：官方已证实用户级路径，补上 --global

原注释只写「用户在 #20 确认」，没有官方出处。已补华为云官方用户指南出处：

    项目级：项目根目录的 ./.codeartsdoer/skills/
    个人级：%USERPROFILE%/.codeartsdoer/skills   即 ~/.codeartsdoer/skills

既然已证实，--global 从拒绝名单移出并加落盘断言。实测装 20 个到
~/.codeartsdoer/skills、卸载后 HOME 零残留。仍是 skills-only —— 其 bootstrap
约定未证实，不猜。

## 顺带核实

- Cursor：官方 skills 文档确认 .cursor/skills/<name>/SKILL.md ✅
- OpenCode：官方 skills 文档确认项目级与全局都对 ✅（唯二全对的之一）
- Kimi / Pi：不在 TARGETS 里，走 plugin manifest 与扩展分发；已确认 docs 没有
  承诺 --tool kimi/pi，installer 也正确拒绝这两个名字，无虚假承诺

audit 168 pass / 0 warn / 0 fail；verify-release 115 pass / 0 fail。

2026-08-13 05:54:52 +08:00

3.1 KiB

Raw Permalink Blame History

Superpowers 中文版 — Codex CLI 安装指南

⚠️ v1.7.10 及更早的项目级安装装错了地方

官方文档（developers.openai.com/codex/skills，现 308 跳 learn.chatgpt.com/docs/build-skills）给出的扫描目录完整清单是：

$CWD/.agents/skills
$CWD/../.agents/skills
$REPO_ROOT/.agents/skills
$HOME/.agents/skills
/etc/codex/skills

没有 .codex/skills。 而 v1.7.10 及更早的 npx superpowers-zh --tool codex 正是装到 .codex/skills —— Codex 不扫那里，等于装了完全不生效。全局（~/.agents/skills）一直是对的，只有项目级错。

v1.7.11 起项目级改装 .agents/skills，重装时会自动清掉旧位置里我们装的那些（你自己放在 .codex/skills 下的东西不动）：

cd /your/project
npx superpowers-zh --tool codex

顺带说明：.agents/skills 与 Antigravity 共用，这是 Agent Skills 开放约定，不是冲突。装过其中一个，另一个也能读到。

在 Codex 中使用 superpowers-zh 的完整指南。

快速安装

告诉 Codex：

Fetch and follow instructions from https://raw.githubusercontent.com/jnMetaCode/superpowers-zh/refs/heads/main/.codex/INSTALL.md

手动安装

前置条件

OpenAI Codex CLI
Git

步骤

克隆仓库：

git clone https://github.com/jnMetaCode/superpowers-zh.git ~/.codex/superpowers-zh

创建 skills 符号链接：

mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers-zh/skills ~/.agents/skills/superpowers

重启 Codex。
子代理 skills（可选）： dispatching-parallel-agents 和 subagent-driven-development 需要 Codex 的多代理功能。在 Codex 配置中添加：
```
[features]
multi_agent = true
```

Windows

使用 junction 代替符号链接（无需开发者模式）：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers-zh\skills"

工作原理

Codex 原生支持 skill 发现——启动时扫描 ~/.agents/skills/ 目录，解析 SKILL.md 的 frontmatter，按需加载 skills。通过一个符号链接即可注册所有 skills：

~/.agents/skills/superpowers/ → ~/.codex/superpowers-zh/skills/

using-superpowers skill 会自动被发现并强制执行 skill 使用纪律——无需额外配置。

使用

Skills 自动发现。Codex 在以下情况激活 skills：

你提到 skill 名称（如 "use brainstorming"）
任务匹配 skill 的描述
using-superpowers skill 指示 Codex 使用某个 skill

更新

cd ~/.codex/superpowers-zh && git pull

Skills 通过符号链接即时更新。

卸载

rm ~/.agents/skills/superpowers

Windows (PowerShell):

Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"

可选：删除克隆的仓库 rm -rf ~/.codex/superpowers-zh

获取帮助

提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
项目主页：https://github.com/jnMetaCode/superpowers-zh

3.1 KiB Raw Permalink Blame History Unescape Escape