per-agent、roster、plugin：三种安装机制决定了你能不能只装一个

2026-08-09

很多人接触 agency-agents 的第一个念头都一样：这个仓库里 agent 太多了，我只想挑一两个装进自己的工具，别把配置目录搞成垃圾场。这个念头完全合理，但能不能实现，取决于你用的是哪个工具——不是取决于命令行怎么写。

答案藏在仓库 tools.json 的一个字段里：installKind。它只有三个取值：per-agent、roster、plugin。这三个词看着像分类标签，实际上是三种完全不同的产物形态，直接决定了「只装一个」这件事在你的工具里是否成立。

先分清两条链路：转换和安装是两回事

agency-agents 的核心资产是一批 markdown：每个 agent 一个 .md 文件，YAML frontmatter 加提示词正文，一共 255 个（核对日 2026-08-09），分布在 17 个 division 目录下。这些 markdown 本身不是任何工具能直接吃的格式。

所以链路是两段：源 agent markdown 先经 scripts/convert.sh 渲染成各工具认识的格式，落进 integrations/ 目录；再由 scripts/install.sh 从 integrations/ 拷贝到每个工具对应的配置目录。install.sh 头部注释写得很清楚：它读的是已转换的文件，如果 integrations/ 缺失或过期，会先去跑 convert.sh——这个自动行为可以用 --no-convert 关掉。

这里有个新手常犯的误会：integrations/ 是产物目录，不是源目录。divisions.json 的 _note 明确把它和 strategy/、examples/、scripts/ 一起排除在 division 之外。你在 integrations/ 里改东西，下次 convert 就冲掉了。

而 installKind 属于第一段——它描述的是 convert 这一步渲染出什么形态的产物。理解这一点，后面的事就顺了。

三种 installKind 分别意味着什么

tools.json 的 _note 把 installKind 定义为「安装机制」，并且强调它是上游真相，对每个消费方都成立。也就是说这不是某个脚本的实现细节，而是这批 agent 面向下游工具时的固有契约。

per-agent——每个 agent 渲染出一个文件或一个目录。装 255 个 agent 就是 255 份产物。16 种工具里有 13 种走这条路：Claude Code、Codex、Gemini CLI、GitHub Copilot、Qwen Code、Cursor、opencode、Osaurus、Antigravity、Kimi、OpenClaw、Mistral Vibe、ZCode。

roster——所有 agent 合并成一个文件。只有两个：Aider 的 CONVENTIONS.md，Windsurf 的 .windsurfrules。

plugin——一个构建出来的产物，_note 的说法是它不能按 agent 渲染成字符串，在所有消费方都只能走 CLI。全表只有 Hermes 一个，目标是 .hermes/plugins/agency-agents-router。

installKind	工具	产物形态
`per-agent`	13 种（Claude Code、Cursor、Codex、opencode 等）	一 agent 一文件或一目录
`roster`	Aider、Windsurf	全部 agent 合并成单一文件
`plugin`	Hermes	构建产物，只能走 CLI

判断依据：你的问题该往哪边归

把上面这张表当查询表用就行，但真正省事的是反过来读它——从你的困惑倒推。

「我在 Aider 里没法只装某一个 agent。」 这不是你命令写错了。Aider 的 installKind 是 roster，它的产物形态就不是一 agent 一文件，而是一个 CONVENTIONS.md。--agent 这类选择器本身没有失效——它们是安装环节的筛选，产物形态却是转换环节定死的，两件事不在同一层。所以无论你怎么收窄，落到 Aider 那边拿到的终究是一个文件，不是一份可以单独启停的 agent 清单。Windsurf 的 .windsurfrules 同理。

「Hermes 我在官方 app 里找不到入口。」 plugin 意味着连官方桌面 app 都装不了，只能命令行。README 里提到的那个原生 app 能一键装进 Claude Code、Cursor、Codex、Gemini、Osaurus 这些工具（我们没有下载或运行过它，只能转述 README 的说法），但按 _note 的定义，plugin 类产物在所有消费方都只有 CLI 一条路。

「我想按 division 批量装。」 这个诉求跟 installKind 无关，是选择器的事。--division <a,b>、--agent <slug,slug>、--agents-file <path> 三个选择器可以自由组合，全空就是全装。走 per-agent 的工具会按你的收窄产出对应数量的文件。

format 的字节级契约，以及它不承诺什么

tools.json 里跟 installKind 并列的还有一个 format 字段，两者常被混着理解，其实分工很清楚：installKind 管产物形态，format 管产物内容长什么样。

_note 给 format 的契约含义是：同一个 format 名保证渲染出字节级相同的输出。所以两个工具能共用一个 format，前提就是它们渲染出来的文件完全一样。这解释了表里两组看着奇怪的搭配——claude-code 与 copilot 都用 identity（顾名思义就是原样输出，不做格式改写），osaurus 与 antigravity 都用 skill-md。它们落点不同，但文件内容是同一份字节。

_note 最后一句更要如实带出：渲染器的覆盖面是消费方自己的事（由 format 推导），目录本身不携带任何 app 发布状态。翻译成人话——tools.json 里有某个工具，不等于官方 app 已经支持它，也不等于那个工具当前版本一定能正常识别这份产物。这一列是仓库对格式的声明，不是对下游生态的背书。

选完 installKind 还有一脚容易踩空。install.sh 注释里列的各工具落点，绝大多数指向家目录，但有四个写的是当前目录：opencode、Cursor、Aider、Windsurf。

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

这个差别决定了你是给某个项目装还是给整个账户装。在错误的目录里敲下这条命令，后果是两个方向的：要么你以为装到项目里、结果落进了家目录被所有项目共享；要么你以为全局生效、结果只在当时那个目录下有。

还有一处更细的坑值得单独点出来：tools.json 里 opencode 的用户级路径是 .config/opencode/agents/{slug}.md，而 install.sh 注释写的是「当前目录的 .opencode/agents/」——这两处分别对应不同 scope，不是矛盾。要断言某个具体路径，回源文件按当前 scope 现查，别混着说，也别从一个工具的路径类推另一个。类似地，Claude Code 的用户级与项目级模板都是 .claude/agents/{slug}.md，区别只在落到家目录还是当前项目目录。

如果默认落点不合你的目录规划，install.sh 支持用环境变量在硬编码默认值之前覆盖，注释里列出的包括 CLAUDE_CONFIG_DIR、CURSOR_RULES_DIR、CODEX_AGENTS_DIR、OPENCODE_AGENTS_DIR、GEMINI_AGENTS_DIR、HERMES_PLUGIN_DIR 等，也可以用 --path <dir> 直接覆盖单一目标。

落盘之前先看一眼计划

理清了机制，实操上最该养成的习惯只有一个：--dry-run。它只打印安装计划、不写任何东西。往 ~/.claude/agents/ 这类共享目录一次性写进两百多个文件之前，先把计划打出来看看，比事后清理便宜太多。

# 先看计划，不落盘
./scripts/install.sh --tool claude-code --division engineering --dry-run

# 只要指定的几个 agent
./scripts/install.sh --tool claude-code \
  --agent engineering-code-reviewer,design-ux-architect --dry-run

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

配套的还有几个开关：--list [tools|teams|agents] 列出后退出，适合先摸清可选项；--link 用符号链接代替拷贝，改动会自动传播，适合你打算跟着上游更新或自己改 agent 正文；--parallel 配 --jobs N 并行装多个工具，默认并行数取 nproc 或 4；--interactive / --no-interactive 控制交互向导，在终端里默认是开的。

至于要不要一口气把 255 个 agent 全塞进全局配置目录——上下文占用、工具启动时的加载、命名冲突，这些代价客观存在，用 --division 或 --agent 收窄是更稳的做法。具体影响有多大我们没有测过，不给数字。

平台方面，脚本注释写的支持范围是 Linux、macOS（需要 bash 3.2 以上）、以及 Windows 的 Git Bash 或 WSL。Windows 用户注意这一条：这些是 shell 脚本，在 PowerShell 或 cmd 里直接跑是不行的，得开 Git Bash 或进 WSL。

一个反直觉的收尾：Cursor 装完像没装

最后补一个跟 installKind 不直接相关、但同一批人一定会撞上的设计。convert.sh 渲染 Cursor 的 .mdc 文件时，frontmatter 是写死的：

## 延伸阅读

- [同名 format 保证字节级相同输出：一条被写进注释的契约](/learn/agency-agents-format-qiyue/)
- [给 agent 章节起标题其实是在写路由：agency-agents 的 SOUL.md / AGENTS.md 分流机制](/learn/agency-agents-zhangjie-biaoti-luyou/)
- [16 种工具、16 个落点：一张表搞清装到哪去了](/learn/agency-agents-16zhong-gongju-luodian/)

---
description: ${description}
globs: ""
alwaysApply: false
---
${body}

globs: "" 和 alwaysApply: false 都是硬编码的。意味着转换出来的 Cursor 规则默认不会自动生效，需要你在 Cursor 里按需引用。装完发现「没反应」，多半就是这里，而不是路径装错了。

把这三层理顺，你的决策路径其实很短：先查目标工具的 installKind，确定「只装一个」在它那儿成不成立；再确认落点是家目录还是当前目录，决定在哪敲命令；最后用 --dry-run 把计划打出来核一遍。三步走完，剩下的才是这批 agent 本身好不好用的问题——那是另一个话题，也不是一份目录清单能替你回答的。

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