agency-agents 安装选择器实战：--tool/--division/--agent/--agents-file 怎么组合

agency-agents 这个仓库的规模是有点吓人的：255 个带 frontmatter 的 agent markdown，分在 17 个 division 里，脚本能往 16 种工具的配置目录里装。而 scripts/install.sh 裸调用的语义，按脚本 USAGE 段的说法，是把所有 team 装到所有检测到的工具。

也就是说，你什么都不写，它就全装。往 ~/.claude/agents/ 这种全局共享目录里一次性铺开两百多个文件，是有代价的——上下文占用、工具启动时的加载、命名冲突都摆在那儿。具体代价有多大我们没测过，也不打算给数字，但「先想清楚装什么再动手」这个判断是成立的。

想清楚之后，收窄范围靠的就是四个选择器。

四个选择器分别管什么

按 install.sh 的 USAGE 段，选择器这一组一共四个，可自由组合，全空等于全装：

参数	含义
--tool <a,b>	只装这些工具
--division <a,b>	只装这些 division
--agent <slug,slug>	只装指定 agent
--agents-file <path>	从文件读 agent 列表（每行一个 slug 或名字，支持 # 注释）

四个参数分成两类维度，这是理解组合方式的关键：--tool 管的是往哪儿装，另外三个管的是装什么。所以真正需要你做决策的其实是两个问题——目标工具选谁，agent 集合怎么圈。

圈 agent 集合的三个参数又是三种粒度：--division 是按目录整块拿（比如 engineering 一下就是 58 个），--agent 是逐个点名，--agents-file 是把点名结果写进文件里复用。

至于把 --division 和 --agent 同时写上到底是求交集还是求并集，USAGE 段只写了「可自由组合」，没有给出集合运算的定义。我们没有运行过这个脚本，也不打算替它下结论——想确认，往下看第四节的 --dry-run 那一段，用它自己打出来的计划去看，比猜准。

另外提一句术语：USAGE 段里裸调用的描述用的是 team 这个词，--list 的取值也是 tools|teams|agents，而选择器参数名叫 --division。写命令时以参数名为准。

四种处境，四条完整命令

处境一：只给 Claude Code 装工程线

最常见的起手式。你只用 Claude Code，只想要工程类 agent：

./scripts/install.sh --tool claude-code --division engineering --dry-run

逐个选项解释：--tool claude-code 把落点锁死在一个工具，避免脚本去「检测到的所有工具」里乱铺；--division engineering 把范围收到 engineering 这一个目录；--dry-run 按 USAGE 的定义是只打印计划、不写任何东西。

第一次跑务必带 --dry-run。这是这个仓库对新手最有价值的一个开关——在往共享配置目录写两百多个文件之前，先看一眼计划，成本几乎为零。确认没问题了，把 --dry-run 去掉再跑一遍即可。

处境二：点名几个 agent，装到两个工具

跨工具的场景。--tool 收多个值用逗号分隔，--agent 同理：

./scripts/install.sh \
  --tool claude-code,codex \
  --agent engineering-frontend-developer,testing-api-tester,security-appsec-engineer

slug 必须写对。仓库里 agent 的 slug 是带 division 前缀的，像 engineering-frontend-developer、testing-reality-checker、design-ui-designer 都是这个形态。不确定就别硬猜，用 --list agents 先列一遍。

处境三：团队共用一份清单

--agent 的问题是命令会越写越长，而且没法进版本库。清单多于三五个、或者要让同事复现同一套配置时，换 --agents-file：

# team-agents.txt
# 前端与体验
engineering-frontend-developer
design-ui-designer

# 质量门
testing-api-tester
testing-reality-checker

# 安全评审
security-appsec-engineer

USAGE 说明这个文件是每行一个 slug 或名字，支持 # 注释。所以上面这种带分组注释的写法是合法的，而且注释本身就是给同事看的文档。

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

把这个文件签进项目仓库，新人 clone 下来跑一条命令就完事，比在群里发一串 slug 靠谱得多。

处境四：本地要改 agent 提示词

如果你打算按自家规范改这些 markdown，--link 值得一看。USAGE 对它的定义是用符号链接代替拷贝，改动会自动传播：

./scripts/install.sh --tool claude-code --division testing --link

拷贝模式下你改仓库里的源文件，已装的那份不会跟着变，得重装；符号链接模式下省掉这一步。代价是仓库目录不能随便挪走或删掉。Windows 上创建符号链接还涉及权限问题，动手前先确认自己的环境支持。

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

产出物会落在哪儿

选择器决定装什么，但产出物长什么样是由目标工具决定的，跟你怎么选没关系。tools.json 用 installKind 字段把它分成三类：

• per-agent——每个 agent 渲染出一个文件或一个目录。选 10 个 agent 就是 10 份产物。16 种工具里绝大多数属于这一类。
• roster——所有 agent 合并成一个文件。Aider 的 CONVENTIONS.md、Windsurf 的 .windsurfrules 是这一类。
• plugin——一个构建出来的产物，不能按 agent 渲染成字符串，在所有消费方都只能走 CLI。Hermes 是唯一一个。

落点目录也要分清。install.sh 的注释里列了各工具的落点，其中有个差别必须记住：opencode、cursor、aider、windsurf 这四个写的是「当前目录」，其余多为家目录。所以 --tool claude-code 会往 ~/.claude/agents/ 写，--tool cursor 写的却是你执行命令时所在目录的 .cursor/rules/。在错误的目录里敲命令，结果就完全不是你想要的。

需要改落点的话，install.sh 支持一批环境变量，它们在硬编码默认值之前被检查，包括 CLAUDE_CONFIG_DIR、CURSOR_RULES_DIR、CODEX_AGENTS_DIR、GEMINI_AGENTS_DIR、OPENCODE_AGENTS_DIR、OPENCLAW_DIR 等。另有 --path <dir> 可以直接覆盖安装目录，但 USAGE 标注它是单一目标——跟 --tool a,b 这种多工具写法放一起时要格外当心。

还有一层：install.sh 是从 integrations/ 读已转换的文件往外拷的，integrations/ 缺失或过期时它默认会自动去调 scripts/convert.sh，--no-convert 可以关掉这个行为。也就是说完整链路是「源 markdown → convert.sh 渲染 → integrations/ → install.sh 拷贝」，选择器作用在这条链路的末端。

怎么验收

1. 先看计划再落盘。任何组合的第一遍都带 --dry-run，确认工具集和 agent 集合都是你想要的。前面那个「交集还是并集」的疑问，也在这一步得到答案。
2. 不确定取值就先 --list。USAGE 给的是 --list [tools|teams|agents]，列完就退出，不写任何东西。工具 kebab 名和 agent slug 都能这么核。
3. 去落点目录里数文件。per-agent 类工具应该看到一 agent 一文件（或一目录），roster 类只有一个合并文件。数不对就回第 1 步。
4. Cursor 用户额外注意一步。convert.sh 渲染 .mdc 时，frontmatter 里的 alwaysApply: false 和 globs: "" 是写死的——转换出来的规则默认不会自动生效，需要在 Cursor 里按需引用。装完发现「没反应」，多半就是这个，不是你选择器写错了。

最容易出错的一步，是在家目录和项目目录之间搞混。跑之前先确认当前工作目录，尤其是同时选了 claude-code 和 cursor 这种一个往家目录、一个往当前目录写的组合。

什么情况不适用

• 想在 Aider 或 Windsurf 里「只装某一个 agent」——做不到。 它们的 installKind 是 roster，所有 agent 合并成一个文件，产物形态本来就不是一 agent 一文件。选择器仍然作用在「装什么」这一侧，但目标端不会出现可单独启停的条目——真要确认合并结果，先用 --dry-run 看计划，再去落点文件里核。
• Hermes 不吃 agent 级挑选。 它是 plugin，是一个构建产物，在所有消费方都只能走命令行。
• --path 和多工具不要混着上。 它被标为单一目标，一次覆盖一个安装目录。
• 不在支持的平台上就别硬来。 脚本注释写的支持范围是 Linux、macOS（需要 bash 3.2+）、Windows 的 Git Bash / WSL。Windows 用户请在 Git Bash 或 WSL 里执行，不要指望 PowerShell 或 cmd 直接跑 .sh。
• 路径断言要回源文件核。 tools.json 里 opencode 的用户级路径是 .config/opencode/agents/{slug}.md，而 install.sh 注释写的是当前目录的 .opencode/agents/——这两处分别对应不同 scope，不是同一个位置。要断言某个具体路径，回源文件按你当前的 scope 现查，别类推。
• --parallel / --jobs N 是效率开关，不是正确性开关。 --parallel 会并行安装各工具、输出按工具缓冲，--jobs N 是最大并行数（默认 nproc 或 4）。第一次验证组合时建议先不开，输出串行着看更省事。

最后回到那个决策本身：--tool 先定落点，再用 --division 粗筛、--agent 精调，稳定下来就固化成 --agents-file 进版本库。这条路径走下来，比一条 install.sh 裸调用把 255 个 agent 铺满全盘要好收拾得多。

延伸阅读

• 16 种工具、16 个落点：一张表搞清装到哪去了
• --parallel 与 --jobs：多工具安装的并行控制
• 把 agency-agents 装进 Claude Code：从 convert 到 install 的完整链路

---

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