mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-02 22:54:06 +08:00
fb63548c9d
## 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。
115 lines
3.1 KiB
Markdown
115 lines
3.1 KiB
Markdown
# 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` 下的东西不动）：
|
||
|
||
```bash
|
||
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
|
||
|
||
### 步骤
|
||
|
||
1. 克隆仓库：
|
||
```bash
|
||
git clone https://github.com/jnMetaCode/superpowers-zh.git ~/.codex/superpowers-zh
|
||
```
|
||
|
||
2. 创建 skills 符号链接：
|
||
```bash
|
||
mkdir -p ~/.agents/skills
|
||
ln -s ~/.codex/superpowers-zh/skills ~/.agents/skills/superpowers
|
||
```
|
||
|
||
3. 重启 Codex。
|
||
|
||
4. **子代理 skills（可选）：** `dispatching-parallel-agents` 和 `subagent-driven-development` 需要 Codex 的多代理功能。在 Codex 配置中添加：
|
||
```toml
|
||
[features]
|
||
multi_agent = true
|
||
```
|
||
|
||
### Windows
|
||
|
||
使用 junction 代替符号链接（无需开发者模式）：
|
||
|
||
```powershell
|
||
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
|
||
|
||
## 更新
|
||
|
||
```bash
|
||
cd ~/.codex/superpowers-zh && git pull
|
||
```
|
||
|
||
Skills 通过符号链接即时更新。
|
||
|
||
## 卸载
|
||
|
||
```bash
|
||
rm ~/.agents/skills/superpowers
|
||
```
|
||
|
||
**Windows (PowerShell):**
|
||
```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
|