Agent 开发环境一键初始化

场景

新机器/新仓库，目标是从零把 Agent 开发环境装到「立刻能干活」：读代码（骨架）、带技能（技能包）、跑会话（终端/编排）、记得住（跨会话记忆）。现状是 6 个工具各有一篇安装指南，但「装什么、什么顺序、哪些会互相踩」没有成套答案——这正是需求清单 REQ-01（求助量 365d 合计 943，全部 up 趋势）。

本组合包给出完整链路：agent-framework（环境骨架）+ agent-skills / superpowers（技能包）+ herdr / ruflo（会话与编排）+ claude-mem（记忆），并明确写面冲突与安装顺序（实测 5/6 成员成套共装，ruflo 因 1.6GB 缓存未纳入共装实测）。

组合成员（6）

agent-framework（环境骨架）

下载：pip 包 `agent-framework`（官方 PyPI）；国内必须带清华镜像（PyPI 官方直连超时）
版本要求：1.15.0；Python 3.10~3.13（3.14 全量安装部分依赖无预编译轮子，建议 core 精简路径）

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple agent-framework
# 精简路径（只跑核心编排）：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple agent-framework-core==1.15.0

工具手册 →

agent-skills（技能包）

下载：GitHub `addyosmani/agent-skills`（codeload tarball 0.6.7；本环境 codeload 直连可用）
版本要求：0.6.7；Node >= 18（skills CLI 路径）

# 方式 A：skills CLI（官方推荐，装到 agent 技能目录）
npx -y skills add addyosmani/agent-skills --yes --global
# 方式 B：手工复制（国内稳，装到 ~/.claude/skills/agent-skills）
curl -sL https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz
cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills

工具手册 →

superpowers（方法论技能框架）

下载：GitHub `obra/superpowers`（codeload tarball v6.3.0；直连 1.7s 实测）
版本要求：6.3.0；无运行时依赖（纯技能目录）

curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0
mkdir -p ~/.codex/skills && tar xzf /tmp/superpowers.tar.gz -C /tmp --strip-components=1 superpowers-6.3.0/skills
cp -r /tmp/skills ~/.codex/skills/superpowers

工具手册 →

herdr（终端运行时）

下载：GitHub release 二进制 `herdr-linux-x86_64`（国内走 gh-proxy 加速，22.7MB）
版本要求：0.8.2；Linux x86_64（无运行时依赖）

curl -sL -o /usr/local/bin/herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64
chmod +x /usr/local/bin/herdr && herdr --version

工具手册 →

ruflo（元编排）

下载：npm 包 `ruflo`；国内用 npmmirror
版本要求：3.38.20；Node >= 20

npm_config_registry=https://registry.npmmirror.com npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

工具手册 →

claude-mem（跨会话记忆）

下载：npm 包 `claude-mem`；国内用 npmmirror
版本要求：13.16.1；Node >= 18；worker 运行时需 Bun

npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem
claude-mem install --ide claude-code

工具手册 →

方案总览

工具	管什么	写面
agent-framework	环境骨架（多 Agent 编排 Python 库）	无配置目录/后台进程（最无侵入）
agent-skills	技能包（24 技能 + 8 斜杠命令）	技能目录 `~/.claude/skills/`（方式 B 手工复制）
superpowers	方法论技能框架（14 技能）	`~/.codex/skills/`（用 Codex 形态避开 Claude 写面）
herdr	终端运行时（持久会话/工作区/后台 server）	`~/.config/herdr/` + `~/.local/state/herdr/`（专属）
ruflo	元编排（会话/记忆/swarm 增强）	工作区 `.claude/ .claude-flow/ .agents/ .swarm/ .mcp.json` + HOME 指针（写面最大）
claude-mem	跨会话记忆（MCP + worker）	`~/.claude.json` + `~/.claude/plugins/` + `~/.claude-mem/`（注册面，安装器自带备份）

顺序逻辑：先无侵入的（库 → 技能目录）→ 再专属写面的（herdr）→ 最后写面大的（ruflo）与注册面（claude-mem），避免安装期互相纠缠。

快速开始

一键脚本由本文档自动生成（渲染后位于 pages/combos/combo-env-init.sh），逐条执行：

bash pages/combos/combo-env-init.sh

装完你会得到：Agent 开发环境六件套——读代码、带技能、跑会话、记得住。
预计耗时：15-25 分钟。最大卡点 = ruflo 首次安装（约 5 分钟 + 1.6GB npx 缓存，磁盘余量建议 >= 3GB）。
前置条件：Node >= 20（ruflo 硬性；agent-skills/claude-mem >= 18）；Python 3.10~3.13（agent-framework 全量）；Bun（claude-mem worker）；Linux x86_64（herdr）。

想弄明白每一步在干什么、装错了怎么恢复 → 看「逐步教学」。一键脚本出问题 → 按逐步教学手动执行定位。

逐步教学

第 1 步：装 agent-framework（环境骨架，最无侵入）

agent-framework 是多 Agent 编排的 Python 库——它是「骨架」，先装不影响任何其他工具（无配置目录、无后台进程）。全量安装依赖较多（Python 3.10~3.13）；只要核心编排可走 agent-framework-core 精简路径（3.14 环境建议此路）。

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple agent-framework
# 精简路径（只跑核心编排）：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple agent-framework-core==1.15.0

预期输出: pip 安装完成（无版本冲突）

装好确认：

python3 -c "import agent_framework; print(agent_framework.__version__)" 输出 1.15.0（实测通过）。

卡住怎么办：

pip 超时 → 命令已带清华镜像；重试一次。
Python 3.14 全量装不上（部分依赖无预编译轮子）→ 走 agent-framework-core 精简路径。

第 2 步：装 agent-skills（技能包）

agent-skills 提供 24 个技能 + 8 个斜杠命令。官方推荐 skills CLI（npx 装到技能目录）；国内更稳的是手工复制（codeload 直连可用）。装到 ~/.claude/skills/agent-skills。

# 方式 A：skills CLI（官方推荐，装到 agent 技能目录）
npx -y skills add addyosmani/agent-skills --yes --global
# 方式 B：手工复制（国内稳，装到 ~/.claude/skills/agent-skills）
curl -sL https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz
cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills

预期输出: 技能目录出现（ls ~/.claude/skills/agent-skills 能看到技能子目录）

装好确认：

技能目录存在且有内容（24 技能就位，实测）。

卡住怎么办：

npx 慢 → 用方式 B（codeload 直连）；或给 npx 加 npmmirror 前缀。
技能目录不存在 → 先 mkdir -p ~/.claude/skills。

第 3 步：装 superpowers（方法论技能框架）

superpowers 是 14 个方法论技能（纯技能目录、无运行时依赖）。用 Codex 形态（~/.codex/skills/superpowers），不要用 Claude 插件形态——后者与 ruflo 的 ~/.claude 写面存在 possible-conflict 推断态，用 Codex 形态即避开。

curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0
mkdir -p ~/.codex/skills && tar xzf /tmp/superpowers.tar.gz -C /tmp --strip-components=1 superpowers-6.3.0/skills
cp -r /tmp/skills ~/.codex/skills/superpowers

预期输出: ~/.codex/skills/superpowers 目录出现（SKILL.md 就位，实测）

装好确认：

ls ~/.codex/skills/superpowers 看到技能子目录与 SKILL.md。

卡住怎么办：

下载失败 → 换网络窗口重试（codeload 直连实测 1.7s，很快）。
与 agent-skills 目录混淆 → 两个技能集子目录名唯一，实测共存无冲突。

第 4 步：装 herdr（终端运行时）

herdr 提供持久会话/工作区/后台 server 能力。单二进制（22.7MB），下载即用，无运行时依赖；写面专属 ~/.config/herdr/ + ~/.local/state/herdr/，无共享面。

curl -sL -o /usr/local/bin/herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64
chmod +x /usr/local/bin/herdr && herdr --version

预期输出: herdr 0.8.2

装好确认：

herdr --version 输出版本号；herdr status exit 0（不拉起 server，实测）。

卡住怎么办：

下载慢/失败 → 命令已带 gh-proxy；换网络窗口重试。
Permission denied → 确认 chmod +x；或装到 ~/.local/bin/ 并加入 PATH。

第 5 步：装 ruflo（元编排，写面最大）

ruflo 做会话/记忆/swarm 增强，是写面最大的成员：工作区 .claude/ .claude-flow/ .agents/ .swarm/ .mcp.json CLAUDE.md + HOME ~/.claude/CLAUDE.md 指针。首次安装约 5 分钟 + 1.6GB npx 缓存（磁盘余量建议 >= 3GB），放靠后避免下载期阻塞其他成员验证。

npm_config_registry=https://registry.npmmirror.com npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

预期输出: ruflo --version 输出版本号 3.38.20

装好确认：

ruflo --version 输出版本号；
工作区出现 .claude-flow/ 等目录。

卡住怎么办：

首次安装很慢（5 分钟 + 1.6GB）→ 正常，等；磁盘不够先 df -h 确认再装。
与 superpowers/claude-mem 的 Claude 写面冲突 → superpowers 用 Codex 形态已避开；claude-mem 先装后装 ruflo（见下步），异常时 claude-mem uninstall 有备份可恢复。

第 6 步：装 claude-mem（跨会话记忆，最后装）

claude-mem 做跨会话记忆（MCP + worker）。最后装：它注册 ~/.claude.json + ~/.claude/plugins/ + ~/.claude-mem/，安装器自带 ~/.claude.json 备份可恢复。worker 运行时需 Bun（先 command -v bun 确认，没有先装 Bun）。

npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem
claude-mem install --ide claude-code

预期输出: Installation Complete（Plugin dir + Worker port 37700）

装好确认：

claude-mem --version 输出版本号；
插件目录出现（实测：marketplace 添加、插件 CLI 注册、worker 端口 37700、status=Worker is not running 预期态）。

卡住怎么办：

安装器内部 git 克隆走 SSH 失败（本机绑定冻结账号）→ git config --global url.https://github.com/.insteadof git@github.com: 强制 HTTPS（2026-08-29 实测修复）。
与 ruflo 的 Claude 配置面冲突（推断态）→ 按「先 claude-mem 后 ruflo」顺序装；异常时 claude-mem uninstall 用备份恢复。

装完验收（一步到位）

作用：装完跑下面一条命令块，全绿 = 本组合包就绪；某条失败 → 回「逐步教学」对应步骤定位。

python3 -c "import agent_framework; print('agent_framework OK', agent_framework.__file__)"
ls ~/.claude/skills/agent-skills 2>/dev/null | head -3
test -f ~/.codex/skills/superpowers/SKILL.md && echo 'superpowers OK'
herdr --version
npx -y ruflo --version
claude-mem --version

预期输出: agent_framework OK（site-packages 路径）；agent-skills 技能子目录可见；superpowers OK；herdr 0.8.2；ruflo 3.38.20；claude-mem 版本号。六件套全绿 = 环境骨架就绪

注：成员级命令已实测（herdr 0.8.2 / ruflo 3.38.20 / superpowers SKILL.md 实测）；组合包级串跑待补验。

日常使用

启动与入口

agent-framework：Python 库，代码里 import 使用。
agent-skills / superpowers：技能随 Agent 自动加载（技能目录就位即可）。
herdr：herdr 命令（持久会话/工作区）；启动客户端会拉起后台 server，不用时 herdr server stop。
ruflo：ruflo doctor / ruflo start（拉起 daemon），用完 ruflo daemon stop。
claude-mem：worker 随 Claude Code 启动（端口 37700）。

常用操作

环境自检：node --version && python3 --version && herdr --version && ruflo --version && claude-mem --version。
会话管理：herdr 持久会话；ruflo doctor 检查编排状态。
记忆检索：claude-mem 的 MCP 搜索历史记忆。
技能生效确认：让 Agent 列出已加载技能（应含 agent-skills/superpowers 的技能名）。

数据与目录

herdr：~/.config/herdr/ + ~/.local/state/herdr/。
ruflo：工作区 .claude/ .claude-flow/ .agents/ .swarm/ .mcp.json CLAUDE.md + HOME ~/.claude/CLAUDE.md 指针。
claude-mem：~/.claude-mem/（记忆）+ ~/.claude/plugins/ + ~/.claude/backups/。

卸载与清理

按安装相反顺序卸载：

# 1. claude-mem（注册面，先卸载，安装器自带备份恢复）
npm uninstall -g claude-mem && claude-mem uninstall --ide claude-code
# 2. ruflo（工作区写面清理）
npx -y ruflo uninstall 2>/dev/null; rm -rf .claude-flow .agents .swarm .mcp.json
# 3. herdr（二进制 + 配置）
rm -f /usr/local/bin/herdr && rm -rf ~/.config/herdr ~/.local/state/herdr
# 4. superpowers / agent-skills（技能目录）
rm -rf ~/.codex/skills/superpowers ~/.claude/skills/agent-skills
# 5. agent-framework（pip）
pip uninstall -y agent-framework

提示：ruflo 的 1.6GB npx 缓存在 ~/.npm/_npx/，如不再用可一并清理释放磁盘。

安装顺序

预检：node --version（>= 20）+ python3 --version（>= 3.10）+ command -v bun（claude-mem worker 用）。
agent-framework（pip 库形态，无配置目录/后台进程，最无侵入，先装不影响其他）。
agent-skills（技能目录写入，先装避免与后续技能集覆盖纠缠）。
superpowers（用 Codex 形态 ~/.codex/skills/superpowers；不要用 Claude 插件形态——与 ruflo 的 ~/.claude 写面存在 possible-conflict 推断态）。
herdr（单二进制，写面专属 ~/.config/herdr/ + ~/.local/state/herdr/，无共享面）。
ruflo（写面最大：工作区 .claude/ .claude-flow/ .agents/ .swarm/ .mcp.json CLAUDE.md + HOME ~/.claude/CLAUDE.md 指针；首次安装约 5 分钟 + 1.6GB 缓存，放靠后避免下载期阻塞其他成员验证）。
claude-mem（最后装：注册 ~/.claude.json + ~/.claude/plugins/ + ~/.claude-mem/，安装器自带 ~/.claude.json 备份可恢复）。

依赖警告

冲突（15 对全查，出处：站内文档）：
compatible 6 对：agent-framework × {agent-skills, superpowers, herdr, claude-mem}（agent-framework×claude-mem 为流水线实测，其余推断）、agent-skills × {superpowers, claude-mem}（技能子目录名唯一）
possible-compatible 7 对：agent-framework×ruflo、agent-skills×ruflo、agent-skills×herdr、superpowers×herdr、superpowers×claude-mem、herdr×ruflo、herdr×claude-mem（写面互不重叠推断）
possible-conflict 2 对（均涉 ruflo，推断态未实测）：superpowers×ruflo（ruflo 写工作区 .claude/skills 与 HOME ~/.claude/CLAUDE.md；superpowers Claude 形态写 ~/.claude/skills——用 Codex 形态即避开）、claude-mem×ruflo（双方都改 Claude 配置面：~/.claude.json 注册 vs ~/.claude/CLAUDE.md 指针；建议先装 claude-mem 后装 ruflo，异常时用 claude-mem uninstall 备份恢复）
版本：Node >= 20（ruflo 硬性；agent-skills/claude-mem >= 18）；Python 3.10~3.13（agent-framework 全量）/ 3.14 core；Bun（claude-mem worker）；Linux x86_64（herdr）
环境：ruflo 首次安装 ~5 分钟 + 1.6GB npx 缓存（磁盘余量建议 >= 3GB）；claude-mem worker 端口 37700；herdr 启动客户端会拉起后台 server（socket + session 文件），不用时 herdr server stop；ruflo doctor/start 拉起 daemon，用完 ruflo daemon stop
国内网络：pip → 清华镜像；npm → npmmirror；herdr → gh-proxy；技能包 → codeload 直连；claude-mem 安装器内部 git 克隆走 SSH 时，本机若绑定已冻结账号会失败——加 git config --global url.https://github.com/.insteadof git@github.com: 强制 HTTPS（2026-08-29 实测修复）

FAQ

六个工具先装哪个？ → 按「无侵入 → 专属写面 → 大写面/注册面」：agent-framework → agent-skills → superpowers → herdr → ruflo → claude-mem（见「安装顺序」）。
superpowers 与 ruflo 会冲突吗？ → 推断态 possible-conflict：superpowers 用 Claude 插件形态会写 ~/.claude/skills，与 ruflo 写面重叠；改用 Codex 形态（~/.codex/skills/）即避开（实测）。
ruflo 装得很慢/占很大空间？ → 首次约 5 分钟 + 1.6GB npx 缓存，属正常；磁盘余量建议 >= 3GB，不用后可清 ~/.npm/_npx/。
claude-mem 安装时 git 克隆失败？ → 本机 SSH 绑定时会失败，加 git config --global url.https://github.com/.insteadof git@github.com: 强制 HTTPS（实测修复）。
这套环境实测过吗？ → 5/6 成员成套共装实测（agent-framework + agent-skills + superpowers + herdr + claude-mem）；ruflo 因 1.6GB 缓存未纳入共装实测（矩阵推断态）。

验证证据

每份组合包在隔离环境实测（冒烟 + 写面检查），未实测项在文中如实标注；实测日期见下方验证证据。

验证于 2026-08-29 · TTL 到期 —（180 天）

2026-08-29：隔离环境轻量实测（fake HOME + venv + 临时工作区）5/6 成员成套共装：agent-framework（pip core 1.15.0 import 过）+ agent-skills（技能目录 24 技能就位）+ superpowers（Codex 形态 SKILL.md 就位）+ herdr（0.8.2 --version/status 过，server 未拉起）+ claude-mem（npm 装 + install 注册完整：marketplace thedotmack 添加、插件 CLI 注册、worker 端口 37700、status=Worker is not running 预期态），写面检查无同名文件冲突；证据：实测复现日志（2026-08-29）

本站实测记录

关联问题

← 全部组合包｜工具货架｜遇到问题？去问题空间提交求助卡

场景

组合成员 （6）

agent-framework（环境骨架）

agent-skills（技能包）

superpowers（方法论技能框架）

herdr（终端运行时）

ruflo（元编排）

claude-mem（跨会话记忆）

方案总览

快速开始

逐步教学

第 1 步：装 agent-framework（环境骨架，最无侵入）

第 2 步：装 agent-skills（技能包）

第 3 步：装 superpowers（方法论技能框架）

第 4 步：装 herdr（终端运行时）

第 5 步：装 ruflo（元编排，写面最大）

第 6 步：装 claude-mem（跨会话记忆，最后装）

装完验收（一步到位）

日常使用

启动与入口

常用操作

数据与目录

卸载与清理

安装顺序

依赖警告

FAQ

验证证据

关联问题

组合成员（6）