奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

16 种工具、16 个落点：一张表搞清装到哪去了

2026-08-09

装 agency-agents 最常见的翻车不是装不上，而是装完之后不知道东西去哪了。这个仓库支持 16 种 AI 编码工具，落点没有统一规律：有的写家目录，有的写当前目录，有的把所有 agent 合成一个文件，还有一个连文件都不是。你要是不先把落点表摊开看一眼，回头想删都不知道删哪。

这篇就干一件事：把 tools.json 和 scripts/install.sh 里的落点整理成一张表，再讲清楚这张表怎么读、命令怎么写、装完检查哪几处。

先搞清楚链路：convert 在前，install 在后

install.sh 头部注释说得很直白：它从 integrations/ 目录读已经转换好的文件，拷到每个工具对应的配置目录；如果 integrations/ 缺失或过期，会先去跑 scripts/convert.sh（可以用 --no-convert 关掉这个自动行为）。

所以完整链路是：源 agent markdown → convert.sh 渲染成各工具格式 → integrations/ → install.sh 拷到目标目录。

这里有个坑得先说：integrations/ 是产物目录，不是源目录。divisions.json 的 _note 明确把它和 strategy/、examples/、scripts/ 一起排除在 division 之外。你要改 agent 内容，改的是各 division 目录下的源 markdown，改 integrations/ 里的东西下次转换就被覆盖了。

顺带把规模说清楚：截至 2026-08-09，仓库里带 frontmatter 的 agent markdown 共 255 个，分布在 17 个 division。仓库 markdown 文件总数比这个大，差额是 README、编排文档一类的非 agent 文件——别把那个数字当成 agent 数。

16 个落点全表

下面是 tools.json 里按 order 排的 16 种工具，路径列为用户级模板（dest.user）：

工具（label）formatinstallKind用户级目标路径
Claude Codeidentityper-agent.claude/agents/{slug}.md
Codexcodex-tomlper-agent.codex/agents/{slug}.toml
Gemini CLIgemini-mdper-agent.gemini/agents/{slug}.md
GitHub Copilotidentityper-agent.copilot/agents/{slug}.md 和 .github/agents/{slug}.md
Qwen Codeqwen-mdper-agent.qwen/agents/{slug}.md
Cursorcursor-mdcper-agent.cursor/rules/{slug}.mdc
opencodeopencode-mdper-agent.config/opencode/agents/{slug}.md
Osaurusskill-mdper-agent.osaurus/skills/{slug}/SKILL.md
Aideraider-conventionsrosterCONVENTIONS.md
Antigravityskill-mdper-agent.gemini/config/skills/{slug}/SKILL.md
Kimikimi-agentper-agent.config/kimi/agents/{slug}/agent.yaml + 同目录 system.md
OpenClawopenclaw-workspaceper-agent.openclaw/agency-agents/{slug}/SOUL.md + AGENTS.md + IDENTITY.md
Windsurfwindsurf-rulesroster.windsurfrules
Hermeshermes-router-pluginplugin.hermes/plugins/agency-agents-router
Mistral Vibevibe-tomlper-agent.vibe/agents/{slug}.toml + .vibe/prompts/{slug}.md
ZCodezcode-mdper-agent.zcode/agents/{slug}.md

部分工具还另有 dest.project（项目级）模板。例如 Claude Code 的 user 与 project 路径模板都是 .claude/agents/{slug}.md，区别只在于落在家目录还是当前项目目录。要断言某个工具的项目级路径，回 tools.json 现查，别照着上表类推。

这张表怎么读：三列各管一件事

installKind 决定产物形态。 tools.json 的 _note 把它定义为安装机制，并且说这是「上游真相，对每个消费方都成立」：

  • per-agent——每个 agent 渲染出一个文件或一个目录。你装 255 个 agent，就是 255 份产物。
  • roster——所有 agent 合并成一个文件。Aider 的 CONVENTIONS.md 和 Windsurf 的 .windsurfrules 是这一类。
  • plugin——一个构建出来的产物，按定义不能按 agent 渲染成字符串，在所有消费方都只能走 CLI。Hermes 是 16 种里唯一一个。

这条直接回答了一类问题：「为什么 Aider 里没法只装某一个 agent」——因为它的产物形态就不是一 agent 一文件。同理，Hermes 是 plugin，意味着连官方桌面 app 也装不了它，只能命令行。

format 是渲染契约。 _note 说明：同一个 format 名保证渲染出字节级相同的输出。所以两个工具能共用一个 format，前提就是产物完全一样——这也是 Claude Code 和 GitHub Copilot 都用 identity（原样输出、不做格式改写）、Osaurus 和 Antigravity 都用 skill-md 的原因。_note 最后还补了一句要如实带出的话：渲染器覆盖面是消费方自己的事（由 format 推导），目录本身不携带任何 app 发布状态。

路径列决定作用域。 install.sh 注释里列的落点和上表互为印证，但有个差别必须留意：opencode、cursor、aider、windsurf 这四个写的是当前目录（.opencode/agents/、.cursor/rules/、CONVENTIONS.md、.windsurfrules），其余多为家目录（~/.claude/agents/、~/.codex/agents/、~/.qwen/agents/ 等）。也就是说，前四个跑在哪个目录就装给哪个项目，后面那些是装给整个账户的。执行前先确认自己 cd 对了地方。

顺带说，tools.json 里 opencode 的用户级路径是 .config/opencode/agents/{slug}.md，和 install.sh 注释里「当前目录 .opencode/agents/」不是同一个位置——两处分别对应不同 scope，别混着说。

命令怎么写

install.sh 的 USAGE 段给的形式是：

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

裸调用等于把所有 team 装到所有检测到的工具；在 TTY 下默认进交互向导。

往共享目录写几百个文件之前，先把计划打出来看一眼：

# 只看计划，不写任何东西
./scripts/install.sh --tool claude-code --division engineering --dry-run

# 先看看到底有哪些工具 / team / agent 可选
./scripts/install.sh --list tools
./scripts/install.sh --list agents

各段可用的参数：

  • 选择器（可自由组合，全空即全装）：--tool <a,b> 只装这些工具、--division <a,b> 只装这些 division、--agent <slug,slug> 只装指定 agent、--agents-file <path> 从文件读列表（每行一个 slug 或名字，支持 # 注释）。
  • 模式：--link 用符号链接代替拷贝，改动会自动传播；--path <dir> 覆盖安装目录（单一目标）。
  • 行为：--interactive / --no-interactive 开关向导、--no-convert 集成文件缺失时不自动跑 convert、--dry-run 只打印计划、--list [tools|teams|agents] 列出后退出、--parallel 并行装各工具（输出按工具缓冲）、--jobs N 最大并行数（默认 nproc 或 4）。

选定之后再落盘，例如按名单装：

./scripts/install.sh --tool claude-code --agents-file ./my-agents.txt --no-interactive

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

还有一层逃生口：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。想把 agent 隔离到一个可随时整体删除的目录里，走这个比 --path 更细。

Windows 侧： 脚本注释写的平台支持是 Linux、macOS（需要 bash 3.2+）、Windows Git Bash / WSL。这是 .sh 脚本，PowerShell 和 cmd 直接跑不了，请在 Git Bash 或 WSL 里执行；在 WSL 里跑时注意家目录是 Linux 侧的家目录，不是 Windows 用户目录。

产出物长什么样，以及怎么验收

有依据可讲的只有形态和位置，不涉及运行效果：

  • per-agent 的工具，按上表路径模板一 agent 一份产物；{slug} 就是花名册里的 agent slug。后缀各不相同——Claude Code 是 .md，Codex 是 .toml，Cursor 是 .mdc，Osaurus / Antigravity 是每个 agent 一个目录里放 SKILL.md，OpenClaw 是一个目录里放三个文件，Mistral Vibe 和 Kimi 则同时写两个位置。
  • roster 的两个工具只产出一个文件：CONVENTIONS.md 或 .windsurfrules。
  • Hermes 落到 .hermes/plugins/agency-agents-router，install.sh 注释里写的是装进 ~/.hermes/plugins/ 并启用该插件。

验收就照着表逐项对：

  1. 先确认作用域对不对。 家目录那批去 ~/ 下看，当前目录那批（opencode / Cursor / Aider / Windsurf）去你刚才执行命令的那个项目根目录看。装错作用域是这里最容易犯的错。
  2. 数量对不对。 per-agent 的工具，选了几个 agent 就该有几份产物；roster 的工具只有一个文件，别去找一堆文件然后以为失败了。
  3. ★ Cursor 装完像没装，多半不是失败。 convert.sh 渲染 .mdc 时，frontmatter 里的 alwaysApply: false 和 globs: "" 是写死的。也就是说转换出来的规则默认不会自动生效，需要在 Cursor 里按需引用。看到文件在但「没反应」，先查这一行，别急着重装。
  4. opencode 的 frontmatter 多一个 mode: subagent。 这是 convert.sh 里 opencode-md 模板固定写入的字段，颜色值会经 resolve_opencode_color() 解析成十六进制。产物里没有这一行，说明你看的不是这条链路生成的文件。
  5. Codex 的 TOML 只有最小三字段：name、description、developer_instructions（整段正文塞在第三个里）。源码注释说明用 TOML basic string 是为了把正文里的控制字符安全编码、避免产出非法 TOML。所以打开发现正文被转义成一长串，是预期行为。
  6. OpenClaw 的目录是拆开的。 一个 agent 一个目录，正文按 ## 标题关键词分流：identity、learning & memory、communication、style、critical rules、rules you must follow 这几类进 SOUL.md，其余（源码注释举的例子是 mission、deliverables、workflow）进 AGENTS.md。看到内容「少了一半」先去另一个文件里找。

什么情况别这么装

  • 别一上来全装。 把 255 个 agent 一次性写进全局配置目录是有代价的：上下文占用、工具启动时的加载、命名冲突都在其中。用 --division 或 --agent 收窄更稳妥。具体影响有多大，我们没有测过，不给数字。
  • 想「只启用某一个 agent」的场景，Aider 和 Windsurf 不适合。 它们是 roster，产物就是一个合并文件；要按 agent 粒度控制，得选 per-agent 的工具。
  • Hermes 别指望图形界面。 它是 plugin，官方 app 也装不了，只能走 CLI。
  • --link 要想清楚再用。 符号链接意味着仓库那边一改，你的工具目录立刻跟着变——做本地实验、频繁改提示词时方便，但这也意味着你 git pull 一次上游更新就直接生效了。想要可控的版本，用默认的拷贝。
  • 共享仓库里慎装当前目录那四个。 CONVENTIONS.md、.windsurfrules、.cursor/rules/ 都会落在项目里，进 git 就是全组的事，先跟队友说一声。

最后提醒一句：这个仓库 2026-08-09 的快照是 140729 star，仓库标注的许可为 MIT。star 数只说明关注度，不能由它推导质量、稳定性或者是否适合你的项目；许可条款以官方 LICENSE 原文为准。仓库里 agent 自述的那些「You’ve built and deployed ML systems at scale」是写给模型看的人设文本，不是谁的真实履历，别当成能力背书。

延伸阅读

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

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员