mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-03 07:23:56 +08:00
fix(installer): DeerFlow 检测标记不存在（Aider 同款）+ 文档里一个查无实据的环境变量
## 安装路径是对的
官方文档（bytedance-deer-flow.mintlify.app/concepts/skills）确认 DeerFlow 自动
扫描两个**写死**的目录找 SKILL.md：
for base_dir in ["skills/public", "skills/custom"]:
public 是自带的、进 git；custom 是用户装的、默认被 gitignore。无任何配置项。
我们装到 skills/custom/ 是对的。
## 但检测标记从来没匹配过
detect 写的是 deer_flow —— 用 GitHub API 列了 deer-flow main 分支的顶层目录：
.agent .github backend contracts deploy docker docs frontend plans
pr-build scripts skills tests
**没有 deer_flow。** 跟 Aider 的 .aider 是同一个毛病：真实检出从来没被自动检测
到过，用户必须手动 --tool deerflow。
改认 skills/public —— 它是 skills 机制本身、随仓库版本控制，任何 DeerFlow 检出
都有；deer_flow 保留作 1.x 兼容。实测模拟真实检出（skills/public + backend +
frontend）能正确识别为 DeerFlow 并装进 skills/custom/。
## 文档里一个查无实据的环境变量
旧文档给了 `export DEERFLOW_SKILLS_DIR=...` 的写法，容易被读成「DeerFlow 认这个
环境变量」。官方文档里没有它，目录是写死的。已删除，改为直接用绝对路径。
顺带补上原文档没说的两件事：容器挂载（skill 在沙箱里跑，两个目录挂到
/mnt/skills/，附属脚本要写容器内路径），以及由此带来的限制 —— brainstorming
的可视化伴侣是宿主机 harness 用的，在 DeerFlow 容器沙箱里不可用。
## 验证
- 模拟真实 DeerFlow 检出：自动识别 -> skills/custom/
- 卸载精确：只删我们装的 20 个，skills/public/ 与用户自建的 custom skill 不动
- verify-release B 段补 skills/public 标记，109 -> 110 pass
- audit 166 pass / 0 warn / 0 fail
This commit is contained in:
AI不止语
@@ -1,65 +1,90 @@
|
||||
# Superpowers 中文版 — DeerFlow 2.0 安装指南
|
||||
# Superpowers 中文版 — DeerFlow 安装指南
|
||||
|
||||
在 [DeerFlow 2.0](https://github.com/bytedance/deer-flow)（字节跳动开源 SuperAgent）中使用 superpowers-zh 的完整指南。
|
||||
在 [DeerFlow](https://github.com/bytedance/deer-flow)（字节跳动开源 SuperAgent）中使用 superpowers-zh 的完整指南。
|
||||
|
||||
## 快速安装
|
||||
|
||||
在你的 **DeerFlow 仓库根目录**下运行：
|
||||
|
||||
```bash
|
||||
cd /your/deerflow-project
|
||||
npx superpowers-zh
|
||||
cd /your/deer-flow
|
||||
npx superpowers-zh --tool deerflow
|
||||
```
|
||||
|
||||
安装脚本会自动检测 `deer_flow/` 目录并将 skills 复制到 `skills/custom/`。
|
||||
skills 会装到 `skills/custom/`。
|
||||
|
||||
> 📌 v1.7.10 及更早版本的自动检测标记写的是 `deer_flow/` —— **DeerFlow 2.0 的顶层目录里根本没有它**（实际是 `backend/` `frontend/` `skills/` `docker/` 等）。也就是说真实的 DeerFlow 检出从来没被自动检测到过，必须手动 `--tool deerflow`。v1.7.11 起改认 `skills/public/`（skills 机制本身、随仓库版本控制），`deer_flow/` 保留作 1.x 兼容。
|
||||
|
||||
## 工作原理
|
||||
|
||||
[DeerFlow 官方文档](https://bytedance-deer-flow.mintlify.app/concepts/skills)明确了两个**固定**目录：
|
||||
|
||||
| 目录 | 用途 | 是否进 git |
|
||||
|---|---|---|
|
||||
| `skills/public/` | DeerFlow 自带的 skill，社区维护 | 是 |
|
||||
| `skills/custom/` | 用户自建或安装的 skill | 否，默认被 gitignore |
|
||||
|
||||
加载方式是**自动扫描这两个目录**，找每个子目录里的 `SKILL.md`：
|
||||
|
||||
```python
|
||||
for base_dir in ["skills/public", "skills/custom"]:
|
||||
for skill_dir in os.listdir(base_dir):
|
||||
...
|
||||
```
|
||||
|
||||
**无需任何配置**，也没有可改路径的配置项 —— 这两个目录名是写死的。所以我们装到 `skills/custom/`，装完即被发现。
|
||||
|
||||
### 容器挂载
|
||||
|
||||
DeerFlow 的 skill 在沙箱容器里执行，两个目录会挂到容器内的 `/mnt/skills/`：
|
||||
|
||||
```
|
||||
/mnt/skills/
|
||||
├── public/
|
||||
└── custom/
|
||||
```
|
||||
|
||||
所以 skill 内部若要引用自己的附属脚本，路径要写容器内的形式，例如 `python /mnt/skills/custom/my-skill/scripts/process.py`。
|
||||
|
||||
> superpowers-zh 的 20 个 skill 以 Markdown 指令为主，`brainstorming` 带的 `scripts/` 是给宿主机 harness 用的可视化伴侣服务，在 DeerFlow 的容器沙箱里不适用 —— 这部分能力在 DeerFlow 上不可用，其余 skill 的方法论正常生效。
|
||||
|
||||
## 手动安装
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jnMetaCode/superpowers-zh.git
|
||||
mkdir -p /your/deerflow-project/skills/custom
|
||||
cp -r superpowers-zh/skills/* /your/deerflow-project/skills/custom/
|
||||
cd /your/deer-flow
|
||||
mkdir -p skills/custom
|
||||
cp -r /path/to/superpowers-zh/skills/* skills/custom/
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
DeerFlow 2.0 使用 **Custom Skills** 机制扩展 Agent 能力：
|
||||
|
||||
- **目录**：`skills/custom/`
|
||||
- **格式**：每个 skill 是一个目录，包含 `SKILL.md` 文件（Markdown + YAML frontmatter）
|
||||
- **加载方式**：DeerFlow 自动扫描 `skills/custom/` 下的所有目录，通过 `description` 字段匹配 skill
|
||||
|
||||
### Skills 格式兼容
|
||||
|
||||
superpowers-zh 的 SKILL.md 文件格式与 DeerFlow 自定义 skills 完全兼容。安装后，DeerFlow 会自动发现并加载所有 skills。
|
||||
|
||||
### 环境变量
|
||||
|
||||
如果你的 DeerFlow 项目不在当前目录，可以手动指定安装路径：
|
||||
装到别处的 DeerFlow 检出时，用绝对路径即可：
|
||||
|
||||
```bash
|
||||
export DEERFLOW_SKILLS_DIR=/path/to/deerflow/skills/custom
|
||||
cp -r superpowers-zh/skills/* $DEERFLOW_SKILLS_DIR/
|
||||
cp -r /path/to/superpowers-zh/skills/* /path/to/deer-flow/skills/custom/
|
||||
```
|
||||
|
||||
> 📌 v1.7.10 及更早的本文档给了一段 `export DEERFLOW_SKILLS_DIR=...` 的写法，容易被读成「DeerFlow 认这个环境变量」。**官方文档里没有这个环境变量**，目录是写死的。已删除。
|
||||
|
||||
## 使用
|
||||
|
||||
安装后，在 DeerFlow 对话中引用 skill 名称即可：
|
||||
装好后在 DeerFlow 对话中直接描述任务，或点名 skill：
|
||||
|
||||
- 「使用头脑风暴来分析这个需求」
|
||||
- 「用测试驱动开发来实现这个功能」
|
||||
- 「按系统化调试流程排查这个 bug」
|
||||
|
||||
DeerFlow 会根据 skill 的 `description` 自动匹配并加载。
|
||||
DeerFlow 按 skill frontmatter 里的 `description` 匹配并加载，所以 `description` 写得越具体，被正确选中的概率越高 —— 这也是官方文档强调的一点。
|
||||
|
||||
## 更新
|
||||
## 卸载
|
||||
|
||||
```bash
|
||||
cd /your/deerflow-project
|
||||
npx superpowers-zh
|
||||
cd /your/deer-flow
|
||||
npx superpowers-zh --uninstall
|
||||
```
|
||||
|
||||
重新运行安装命令即可更新到最新版本。
|
||||
只删除我们装进 `skills/custom/` 的那些 skill 目录，`skills/public/` 和你自己的 custom skill 不动。
|
||||
|
||||
## 获取帮助
|
||||
|
||||
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
|
||||
- DeerFlow 文档：https://github.com/bytedance/deer-flow
|
||||
- DeerFlow 仓库：https://github.com/bytedance/deer-flow
|
||||
- DeerFlow Skills 文档：https://bytedance-deer-flow.mintlify.app/concepts/skills
|
||||
|
||||
Reference in New Issue
Block a user