往 `~/.claude/agents/` 写 200 多个文件之前，先跑 `--dry-run`

2026-08-09

装第三方 agent 集合这件事，风险不在「装不上」，在「装得太顺利」。

agency-agents 这个仓库（github.com/msitarzewski/agency-agents）本质上是一批带 YAML frontmatter 的 markdown 提示词文件，按 2026-08-09 的核对结果，带 frontmatter 的 agent markdown 共 255 个，分布在 17 个 division 里，最大的 engineering 一个目录就有 58 个，specialized 57 个，marketing 36 个。仓库的 scripts/install.sh 支持把它们装进 16 种 AI 编码工具，其中绝大多数工具的安装机制是 per-agent——一个 agent 渲染成一个文件或一个目录。

这两个数字乘起来意味着什么，tools.json 的 _note 里说得很直白：per-agent 的工具，装 255 个 agent 就是 255 份产物。而 install.sh 的 USAGE 段写明，裸调用（不带任何参数）等于把所有 team 装到所有检测到的工具上。

所以在真正落盘之前，先跑一遍 --dry-run。

一、这个开关在 USAGE 里的位置

install.sh 的命令行契约是三段式：

./scripts/install.sh [selection] [mode] [behavior]

selection（选择器）：--tool、--division、--agent、--agents-file，可自由组合，全空就是全装
mode（模式）：--link（用符号链接代替拷贝，改动会自动传播）、--path <dir>（覆盖安装目录，单一目标）
behavior（行为）：--interactive / --no-interactive、--no-convert、--dry-run、--list、--parallel、--jobs N

--dry-run 属于第三段，脚本 USAGE 对它的定义是：只打印计划、不写任何东西。

同一段里还有一个 --list [tools|teams|agents]，语义是列出后退出。两者用途不同：--list 回答「有哪些东西可选」，--dry-run 回答「按我现在这组参数，会往哪里写什么」。新手容易只用前者，然后在真正执行时才发现范围不对。

二、命令怎么写

最保守的第一条，什么都不选，只看默认行为会做什么：

./scripts/install.sh --dry-run --no-interactive

--no-interactive 在这里不是可有可无的。USAGE 说明，在 TTY 下裸调用会默认进交互向导；加上它可以让脚本直接按命令行参数走完，输出一份稳定的计划，而不是停在向导里等你选。

看完全量计划，通常你会想收窄。按工具收窄：

./scripts/install.sh --tool claude-code --dry-run --no-interactive

按 division 收窄，比如只要工程和测试两块：

./scripts/install.sh --tool claude-code --division engineering,testing --dry-run --no-interactive

按具体 agent 收窄，slug 用花名册里的原样：

./scripts/install.sh --tool claude-code \
  --agent engineering-code-reviewer,engineering-backend-architect \
  --dry-run --no-interactive

如果你的选择清单要长期维护，--agents-file 更合适。它从文件读 agent 列表，每行一个 slug 或名字，支持 # 注释：

./scripts/install.sh --tool claude-code --agents-file ./my-agents.txt --dry-run

还有一个容易被忽略的组合：--path。它覆盖安装目录，指向单一目标。想在真正动 ~/.claude/agents/ 之前先把计划的落点挪到一个临时目录看看，就用它：

./scripts/install.sh --tool claude-code --path <你的临时目录> --dry-run

以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 --help 的实际输出为准。

关于 --no-convert：仓库的链路是源 agent markdown → convert.sh 渲染成各工具格式 → integrations/ → install.sh 拷贝到目标目录，install.sh 在集成文件缺失时会自动调 convert.sh，--no-convert 就是关掉这个自动调用。--dry-run 与自动 convert 的先后关系，USAGE 段没有写明；如果你连 integrations/ 这个产物目录都不希望被动过，可以把两个开关叠加使用，但叠加后的实际行为请以 ./scripts/install.sh --help 与脚本本身为准。

三、计划打出来之后，人要盯哪几处

--dry-run 的价值全在你看计划时的注意力上。有依据可讲的检查点是这四个。

第一，落点是家目录还是当前目录。 install.sh 的注释列出了各工具的落点，这里的差别很要命：

claude-code  -- ~/.claude/agents/
codex        -- ~/.codex/agents/
gemini-cli   -- ~/.gemini/agents/
opencode     -- 当前目录的 .opencode/agents/
cursor       -- 当前目录的 .cursor/rules/
aider        -- 当前目录的 CONVENTIONS.md
windsurf     -- 当前目录的 .windsurfrules

opencode、cursor、aider、windsurf 这四个写的是当前目录，其余多为家目录。也就是说，同一条命令在不同的工作目录下执行，后果完全不一样——在家目录里随手跑一次，可能给你的家目录本身生成了一套项目级配置。跑 --dry-run 时第一眼就该确认 pwd 对不对。

顺带一提，tools.json 里 opencode 的用户级路径是 .config/opencode/agents/{slug}.md，与 install.sh 注释里的「当前目录 .opencode/agents/」不是同一个位置，这两处分别对应不同的 scope。要断言某个具体路径，回源文件按当前 scope 现查，别类推。

第二，有没有 roster 类型的工具混在里面。 tools.json 定义了三种 installKind：per-agent 每个 agent 一份产物；roster 是所有 agent 合并成一个文件；plugin 是一个构建产物，不能按 agent 渲染成字符串。Aider 的 CONVENTIONS.md 和 Windsurf 的 .windsurfrules 属于 roster，Hermes 是唯一的 plugin。

roster 意味着产物是单文件。如果你的项目里已经有一份手写的 CONVENTIONS.md 或 .windsurfrules，那么这次安装的目标正好是这个文件。dry-run 计划里出现这两个路径时，先去看看它们现在有没有内容、有没有进版本库。

第三，环境变量有没有在悄悄改路径。 install.sh 的注释列了一批可覆盖变量，并说明它们在硬编码默认值之前被检查：CLAUDE_CONFIG_DIR、COPILOT_AGENT_DIR、CURSOR_RULES_DIR、GEMINI_AGENTS_DIR、OPENCODE_AGENTS_DIR、OPENCLAW_DIR、QWEN_AGENTS_DIR、CODEX_AGENTS_DIR、OSAURUS_SKILLS_DIR、HERMES_HOME、HERMES_PLUGIN_DIR、VIBE_HOME。如果你的 shell 配置里恰好设过其中某一个，计划里的路径就不会是默认那套。发现路径和文档对不上，先 env | grep 这几个名字。

第四，范围是不是真的收窄了。 选择器是可自由组合的，全空等于全装。检查计划里出现的工具数和 agent 数是否符合预期——比如你只想给 Claude Code 装，就不该在计划里看到 Cursor 或 Windsurf 的路径。

四、什么情况下这个开关兜不住底

--dry-run 只回答「会写哪些路径」，不回答别的。以下几种情况别指望它。

Hermes 走不了普通路子。 它的 installKind 是 plugin，tools.json 的 _note 说明这类产物不能按 agent 渲染成字符串，在所有消费方都只能走 CLI。它的落点是 ~/.hermes/plugins/ 并需要启用该插件。这一条不是 dry-run 能帮你看清的。

--link 模式的后果比拷贝长远。 它用符号链接代替拷贝，仓库里的改动会自动传播。你 git pull 一次上游更新，已装的内容就跟着变。dry-run 只会告诉你链接建在哪，不会告诉你以后会变成什么。

装完之后的内容质量它不管。 dry-run 检查的是安装计划，不是提示词内容。另外提醒一句：agent markdown 里那些「我在大规模生产环境里做过 X」式的自我描述，是写给模型看的人设文本，不是任何人的真实履历，别当成能力背书。

转换产物的默认状态它也不显示。 一个具体例子：Cursor 的 cursor-mdc 格式，frontmatter 里的 alwaysApply: false 和 globs: "" 是在 convert.sh 里写死的。也就是说转换出来的 Cursor 规则默认不会自动生效，需要在 Cursor 里按需引用。装完发现「没反应」，多半是这个原因，而 dry-run 阶段看不出来。

一次性把 255 个 agent 塞进全局配置目录是有代价的——上下文占用、工具启动时的加载、命名冲突都可能出现。具体影响有多大我们没有测过，不给数字；能给的建议就是用 --division / --agent 先收窄，而不是先全装再删。

五、Windows 上怎么跑

脚本注释里的平台支持写的是 Linux、macOS（需要 bash 3.2+）、Windows Git Bash / WSL。

也就是说 Windows 用户不要在 PowerShell 或 cmd 里直接调 ./scripts/install.sh，走 Git Bash 或 WSL。这两者的家目录不是一回事：WSL 里的 ~ 在 Linux 文件系统内，Git Bash 里的 ~ 指向 Windows 用户目录。你在哪个 shell 里跑 --dry-run，就要按那个 shell 的家目录去理解计划里的 ~/.claude/agents/——这也是 dry-run 值得多跑一次的理由：换个 shell，计划里的路径就换了一批。

延伸阅读

最后说一句关于这个仓库的关注度。截至 2026-08-09 的 GitHub 快照，它有 140729 star、22985 fork、110 个 open issue，仓库标注为 MIT。star 数只说明关注的人多，不能由它推出质量、稳定性或者「适合你的项目」这类结论。真正决定要不要装、装哪些的，还是你自己那份 dry-run 计划。

本文依据 agency-agents 官方仓库（github.com/msitarzewski/agency-agents）的 README、 tools.json、divisions.json、scripts/ 下的安装与校验脚本整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装或运行过其中任何 agent。目录、脚本与安装路径随上游更新而变动，请以仓库最新内容与 ./scripts/install.sh --help 的实际输出为准。许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。