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

`--parallel` 与 `--jobs`：多工具安装的并行控制

2026-08-09

agency-agents 这个仓库（github.com/msitarzewski/agency-agents）本质上是一批带 YAML frontmatter 的 markdown 文件，靠 scripts/convert.sh 渲染成各家 AI 编码工具认识的格式，再靠 scripts/install.sh 拷进对应配置目录。截至 2026-08-09 的快照，仓库里带 frontmatter 的 agent markdown 有 255 个，分布在 17 个 division；tools.json 登记的目标工具有 16 种。

数量一上来，安装就从”跑一条命令”变成了”要不要并行”的问题。install.sh 的 USAGE 段里给了两个开关：--parallel（并行安装各工具，输出按工具缓冲）和 --jobs N（最大并行数，默认 nproc 或 4）。这篇只讲这两个开关怎么用、产物落在哪、怎么验收、什么时候别用。

先搞清楚：并行的是”工具”，不是”agent”

这是最容易想岔的一点。USAGE 里 --parallel 的说明是”并行安装各工具”，并行的粒度是 16 种工具里被选中的那几个，而不是 255 个 agent 各起一个任务。

所以推论很直接：你只装一个工具的时候，--parallel 没有并行对象。

# 这条命令加不加 --parallel，并行维度上都只有一个目标
./scripts/install.sh --tool claude-code

真正能吃到并行的是这类场景——同时铺多个工具：

./scripts/install.sh --tool claude-code,cursor,codex,gemini-cli --parallel --jobs 4

逐项解释一下为什么这么写：

  • --tool <a,b> 是选择器，只装列出的这几个工具；选择器全空等于全装。
  • --parallel 打开并行，此时各工具的输出会按工具缓冲，而不是几路日志交错着往屏幕上刷。
  • --jobs 4 显式限定最大并行数。不给这个参数时默认取 nproc，取不到则是 4；显式写死的好处是同一条命令在不同机器上行为一致。

再往上还有另外两个选择器可以叠加：--division <a,b> 按 division 收窄，--agents-file <path> 从文件读 agent 列表（每行一个 slug 或名字，支持 # 注释）。它们和 --parallel 是正交的——选择器决定装什么，--parallel 决定怎么装。

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

并行之前，先把 convert 这一步摘出来

install.sh 从 integrations/ 目录读取已转换的文件往外拷。integrations/ 是 convert.sh 的产物目录，不是源目录。如果它缺失或过期，install.sh 默认会自动去调 convert.sh，也可以用 --no-convert 关掉这个自动行为。

这一条和并行有直接关系：转换是所有工具共用的前置步骤，你在一条并行命令里同时触发安装和转换，出问题时就分不清是转换阶段的锅还是拷贝阶段的锅。更干净的顺序是分两步：

# 第一步：先单独把转换产物生成好
./scripts/convert.sh

# 第二步：明确关掉自动转换，只做拷贝，此时再开并行
./scripts/install.sh --tool claude-code,cursor,codex,gemini-cli --parallel --jobs 4 --no-convert

--no-convert 在这里不是为了省时间，是为了把”两件事”拆成”两条命令”，让失败信号有明确归属。

先用 --dry-run 看一眼计划

在往 ~/.claude/agents/ 这种共享目录写两百多个文件之前，--dry-run 是这个仓库里对新手最有价值的一个开关——它把安装计划打印出来，不写任何东西。

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

配合着看的还有 --list [tools|teams|agents]，列出后直接退出，用来确认你写的工具名、division 名拼对了没有。

建议的用法是：并行开关也带上 --dry-run 跑一遍，因为并行会改变输出的组织方式（按工具缓冲），先在不落盘的前提下熟悉一下输出长什么样，比装完再回头读日志容易。

产出物会落在哪：家目录还是当前目录

并行同时往多个目录写，所以”写到哪”这件事必须在动手前搞清楚。install.sh 的注释列出的各工具落点里，有一个差别特别关键：

claude-code  -- ~/.claude/agents/
copilot      -- ~/.github/agents/ 和 ~/.copilot/agents/
gemini-cli   -- ~/.gemini/agents/
antigravity  -- ~/.gemini/config/skills/
codex        -- ~/.codex/agents/
opencode     -- 当前目录的 .opencode/agents/
cursor       -- 当前目录的 .cursor/rules/
aider        -- 当前目录的 CONVENTIONS.md
windsurf     -- 当前目录的 .windsurfrules

**opencode、cursor、aider、windsurf 这四个写的是当前目录，其余多为家目录。**并行的时候你只在一个 shell 里执行一条命令，但产物会同时落进两个层级的位置——如果你是在随便一个临时目录里跑的，那四个”当前目录”的产物就落在那个临时目录里了。

这里还有一处必须提醒的口径差异：上面这份清单是 install.sh 注释里的写法，而 tools.json 给 opencode 登记的用户级路径是 .config/opencode/agents/{slug}.md，和注释里的”当前目录 .opencode/agents/”根本不是同一个位置。两处分别对应不同的 scope（用户级还是项目级），不是谁写错了。要断言某个工具的具体落点，回 tools.json 和 install.sh 现查当前 scope，别把两套说法混着用——并行一次写多个目标，混着用的代价就是你事后不知道该去哪个目录找产物。

产物形态也不是一种。tools.json 把安装机制记在 installKind 字段上，三种取值意味着三种完全不同的产出：

installKind产物形态典型工具
per-agent每个 agent 渲染出一个文件或一个目录Claude Code、Cursor、Codex、Gemini CLI 等多数工具
roster所有 agent 合并成一个文件Aider（CONVENTIONS.md）、Windsurf（.windsurfrules）
plugin一个构建出来的产物，不能按 agent 渲染成字符串Hermes（唯一一个）

这张表在并行语境下的读法是：per-agent 的工具，选中多少 agent 就产出多少份文件或目录；roster 的两个工具无论选多少 agent，最终都只有一个文件被写；plugin 的 Hermes 走的是构建产物路径，落点是 ~/.hermes/plugins/，和前两类不是一回事——tools.json 的 _note 说得很直白，plugin 这一类不能按 agent 渲染成字符串，在所有消费方都只能走命令行。所以并行的几路之间，工作量本来就不是一个量级：一路在写几十上百份文件，另一路只写一个文件，还有一路在跑构建。哪一路先结束，我们没有依据去断言，只能说别拿”某一路还没动静”当失败信号。

另外两个和落盘直接相关的开关：--link 用符号链接代替拷贝，改动会自动传播；--path <dir> 覆盖安装目录，USAGE 段标注为单一目标。--path 和 --parallel 同时用的具体行为，脚本 USAGE 段没有明说，要用就先 --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。

怎么验收

并行跑完之后，人要检查的是这么几处：

  1. 每个工具的输出块都读一遍。--parallel 的输出是按工具缓冲的，意味着屏幕上是一块一块的，不是交错的流。好处是不用在混杂日志里挑行；代价是按缓冲的语义推断，某一路的失败信息不会插到屏幕最下方，而是留在它自己那一块里，等你往回翻才看得到。所以别只看最后几行，每个工具的块都要扫一遍。
  2. 按 installKind 对着落点数产物。per-agent 的工具去它的目标目录看文件数量是否与你选中的 agent 数一致；roster 的两个工具去看那一个文件是不是被写了、内容是不是把所选 agent 都合进去了。
  3. **确认”当前目录”那四个工具落在了你想要的项目里。**这是最容易返工的一步。
  4. Cursor 装完像没装是预期行为，不是失败。convert.sh 渲染 .mdc 时 frontmatter 里的 alwaysApply: false 和 globs: "" 是写死的，也就是转换出来的 Cursor 规则默认不会自动生效，需要在 Cursor 里按需引用。不知道这一条的人很容易把它当成并行安装出了错。

顺带说明一句边界：仓库里 scripts/ 下还有 check-tools.sh 这类脚本，但它守的是 tools.json 与 install.sh 的 ALL_TOOLS、convert.sh 转换器集合三者是否一致，属于仓库自身的配置漂移检查，不是对你机器上安装结果的校验。别指望它替你验收落盘。

什么情况下别开并行

  • **只装一个工具时。**没有并行对象，加了也只是多一层输出缓冲。
  • **正在排查安装失败时。**并行加缓冲会打乱事件的时间关系，串行跑一遍、让输出按顺序出来，定位起来更省事。
  • 需要一份可读的顺序日志时（比如放进 CI 或者要贴给同事看）。USAGE 段对 --parallel 的全部承诺只有”输出按工具缓冲”这一句，并没有承诺这些块的先后顺序会和你写在 --tool 里的顺序一致；要一份顺序可预期的日志，串行更省心。
  • **打算一次性把 255 个 agent 全塞进全局配置目录时。**并行只解决”快”，不解决”多”。全量装进共享目录是有代价的——上下文占用、工具启动时的加载、命名冲突都跑不掉，先用 --division 或 --agent 收窄范围，比调 --jobs 更有意义。
  • **Windows 上不在 Git Bash / WSL 里执行时。**脚本注释写的平台支持是 Linux、macOS（需要 bash 3.2+）、Windows Git Bash / WSL。在 Git Bash 里还要多留意一点：--jobs 不给值时默认取 nproc，取不到才回落到 4，与其赌环境里有没有 nproc，不如显式写 --jobs 4。另外 WSL 里跨文件系统往 Windows 侧目录写，路径与权限都要自己确认清楚，这属于通用的运维注意事项，不是该项目文档的内容。

最后提醒一句常被忽略的前提：仓库的 lint-agents.sh 检查的是文件结构（frontmatter 必填 name/description/color 缺一报 ERROR，推荐章节缺失只是 WARN），check-agent-originality.sh 检查的是与已有 agent 的重复度（默认阈值 ORIGINALITY_FAIL=40、ORIGINALITY_WARN=20，源码注释给出的库内校准值是最差约 1.5%、中位数 0%）。这些质量门管的是结构与重复，不评估提示词好不好用。并行装得再快，也不代表装进去的东西对你的项目合适。

延伸阅读

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

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

浏览课程 加入会员