mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-02 22:54:06 +08:00
441d024cd6
## 我们装错了目录，一直没生效 #45 报告人说「项目级 .hermes/skills/ 里的 20 个 skill 全部返回 404，必须手动 复制到 ~/.hermes/skills/ 才被识别」。查官方文档核实，他是对的： hermes-agent.nousresearch.com/docs/user-guide/features/skills 明确 Hermes 只自动加载 ~/.hermes/skills/（原文 "the primary directory and source of truth"），项目级目录不被自动发现；外部目录必须写进 ~/.hermes/config.yaml 的 skills.external_dirs。 而我们从支持 Hermes 起就只装项目级 .hermes/skills/ —— 那个目录 Hermes 根本 不读。这不是「不好用」，是「装了完全不生效」，比不支持更糟。 ## 改法 - TARGETS 给 Hermes 加 global（~/.hermes/skills），全局成为推荐装法 - 项目级仍保留（skills 可随仓库分发），但装完打印**可直接粘贴**的配置片段： skills: external_dirs: - <项目绝对路径>/.hermes/skills 不替用户改 config.yaml —— 那是他们的文件。文档里也写明「配置里不存在的 路径会被静默跳过」，所以写错不会报错、只会没生效。 - 全局模式**不写 bootstrap**：Hermes 的用户级指令文件约定没有公开文档， 往 $HOME 根目录写 HERMES.md 是猜路径 + 污染主目录。实测确认全局装完 $HOME 根目录 0 个文件、卸载 0 残留。 ## 文档与清单 - docs/README.hermes.md 开头重写，把「必须全局」放在最前面，并注明 v1.7.8 及更早只支持项目级 = 装了不生效，是我们的实现错误 - 简繁 README：全局支持清单加 Hermes Agent，工具表的安装命令改为 --global - verify-release.sh 的 GLOBAL_OK 加 hermes、GLOBAL_NO 移除 ## 验证 - 全局：装 20 skills 到 ~/.hermes/skills、$HOME 根目录 0 文件、卸载 0 残留 - 项目级：正确打印 A/B 两种方案与绝对路径的 config.yaml 片段 - audit.sh 166 pass / 0 warn / 0 fail、verify-release.sh 90 pass / 0 fail 注：#45 的后半部分（7 个 skill 文件里 24 处硬编码 Claude 工具名）本次未动。 那属于行为塑造内容，且 references/hermes-tools.md 已有完整映射表， 应走「强化映射表引用」而非把正文改成某个 harness 专属工具名。
108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# Superpowers 中文版 — Hermes Agent 安装指南
|
||
|
||
在 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 中使用 superpowers-zh 的完整指南。
|
||
|
||
## ⚠️ 先看这一条：必须装到全局，否则不生效
|
||
|
||
[Hermes 官方文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)明确：Hermes **只自动加载 `~/.hermes/skills/`**（原文称其为 "the primary directory and source of truth"），**项目级目录不会被自动发现**。
|
||
|
||
所以推荐的装法是全局：
|
||
|
||
```bash
|
||
npx superpowers-zh --global --tool hermes
|
||
```
|
||
|
||
装到 `~/.hermes/skills/`，装完即生效，用 `skills_list` 就能看到 20 个 skill。
|
||
|
||
> 📌 v1.7.8 及更早版本只支持项目级安装（装到 `<项目>/.hermes/skills/`）—— 那个目录 Hermes 根本不读，等于装了不生效。这是我们的实现错误，v1.7.9 起修正。见 [#45](https://github.com/jnMetaCode/superpowers-zh/issues/45)。
|
||
|
||
## 如果你确实要项目级安装
|
||
|
||
项目级的好处是 skills 可以随仓库一起分发。但**必须显式登记**，否则 Hermes 看不见。
|
||
|
||
```bash
|
||
cd /your/project
|
||
npx superpowers-zh --tool hermes
|
||
```
|
||
|
||
安装器会打印出你需要粘贴的配置片段，形如：
|
||
|
||
```yaml
|
||
skills:
|
||
external_dirs:
|
||
- /your/project/.hermes/skills
|
||
```
|
||
|
||
把它加进 `~/.hermes/config.yaml`。路径支持 `~` 展开和 `${VAR}` 环境变量替换；**配置里不存在的路径会被静默跳过**，所以写错了不会报错，只会"没生效"。
|
||
|
||
**我们不替你改 `config.yaml`** —— 那是你的配置文件。
|
||
|
||
项目级安装还会生成 `HERMES.md` 引导文件（含核心规则和 skills 列表），让 Hermes 在合适时机主动检查 skill。全局安装**不写**这个文件 —— Hermes 的用户级指令文件约定没有公开文档，我们不猜路径、也不往你的主目录里写东西。
|
||
|
||
## 同名冲突
|
||
|
||
如果同一个 skill 名在 `~/.hermes/skills/` 和某个 `external_dirs` 目录里都存在，**本地（`~/.hermes/skills/`）的版本优先**。
|
||
|
||
## 其他 config.yaml 用法
|
||
|
||
如果希望全局使用 superpowers-zh skills，可以在 `~/.hermes/config.yaml` 中配置：
|
||
|
||
```yaml
|
||
skills:
|
||
external_dirs:
|
||
- /path/to/superpowers-zh/skills
|
||
```
|
||
|
||
## 工具映射
|
||
|
||
Skills 中引用的 Claude Code 工具名称对应 Hermes Agent 的等价工具：
|
||
|
||
| Claude Code | Hermes Agent |
|
||
|-------------|-------------|
|
||
| `Read` | `read_file` |
|
||
| `Write` | `write_file` |
|
||
| `Edit` | `patch` |
|
||
| `Bash` | `terminal` |
|
||
| `Grep` / `Glob` | `search_files` |
|
||
| `Skill` | `skill_view` |
|
||
| `Task`（子智能体） | `delegate_task` |
|
||
| `WebSearch` | `web_search` |
|
||
| `WebFetch` | `web_extract` |
|
||
| `TodoWrite` | `todo` |
|
||
|
||
完整映射参见 `skills/using-superpowers/references/hermes-tools.md`。
|
||
|
||
## 使用技能
|
||
|
||
Hermes Agent 支持三级渐进式加载：
|
||
|
||
```
|
||
# 浏览所有可用技能
|
||
skills_list
|
||
|
||
# 加载某个技能的完整内容
|
||
skill_view("brainstorming")
|
||
|
||
# 查看技能的引用文件
|
||
skill_view("using-superpowers", "references/hermes-tools.md")
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### Skills 未发现
|
||
|
||
1. 确认 `.hermes/skills/` 目录存在且包含 skill 文件夹
|
||
2. 每个 skill 目录下需要有 `SKILL.md` 文件
|
||
3. 使用 `skills_list` 查看已发现的技能
|
||
|
||
### HERMES.md 未加载
|
||
|
||
1. 确认文件在项目根目录（与 `.hermes/` 同级）
|
||
2. 文件名可以是 `HERMES.md` 或 `.hermes.md`
|
||
|
||
## 获取帮助
|
||
|
||
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
|
||
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
|
||
- Hermes Agent 文档：https://hermes-agent.nousresearch.com/docs/
|