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

`--link` 符号链接模式：改动自动传播的好处与代价

2026-08-09

agency-agents 的 scripts/install.sh 在「模式」这一组里只给了两个开关，--link 是其中之一。USAGE 段对它的说明很短：用符号链接代替拷贝，改动会自动传播。

一句话的开关往往最容易被高估。很多人看到「改动自动传播」就默认：以后我改仓库里的 agent markdown，各个工具里就实时生效了。实际边界比这窄，而且窄在哪一段，直接决定这个开关对你有没有用。

一、先搞清楚 --link 作用在链路的哪一段

install.sh 头部注释写明了它的数据来源：从 integrations/ 读取已转换的文件，拷贝到每个工具对应的配置目录；如果 integrations/ 缺失或过期，会先跑 scripts/convert.sh（可用 --no-convert 关掉这个自动行为）。

所以完整链路是三段：

division 目录下的源 agent markdown
      ↓  convert.sh 渲染成各工具格式
integrations/（产物目录）
      ↓  install.sh 拷贝
各工具的配置目录，如 ~/.claude/agents/{slug}.md

install.sh 负责的是第二段。--link 说的「用符号链接代替拷贝」，替换掉的也是第二段那个拷贝动作——按这条数据流推，链接指向的应当是 integrations/ 下的转换产物，而不是 division 目录下的源 markdown。脚本的 USAGE 段没有逐字写明链接的两端分别是什么，这一步是我们按 install.sh 自述的数据来源推出来的，要在生产里依赖它，请回 scripts/install.sh 源码核一遍。

这个区分很要紧：它意味着你改了源 agent markdown，链接那一端不会自己变，你仍然要重新跑一次 convert.sh 把 integrations/ 刷新，改动才谈得上「传播」。--link 省掉的是「改完还得重装一遍」，不是「改完什么都不用做」。integrations/ 是产物目录不是源目录，这一点在 divisions.json 的 _note 里也被单独强调过。

顺带一提，--no-convert 与 --link 是两个正交的开关：前者管「要不要自动重新渲染」，后者管「渲染完怎么落到目标目录」。两个都用上，等于你完全自己掌控刷新时机。

二、命令怎么写

先给一条可以直接复制的完整命令，再逐项说为什么这些选项在这儿：

./scripts/install.sh \
  --tool claude-code \
  --division engineering \
  --link \
  --dry-run
  • --tool claude-code：只装 Claude Code 这一个工具。仓库一共支持 16 种工具，裸调用会往所有检测到的工具里装，第一次用务必收窄。
  • --division engineering：只装 Engineering 这一个 division。整个花名册是 255 个 agent、分布在 17 个 division，其中 Engineering 一家就占 58 个。
  • --link：本文的主角，用符号链接代替拷贝。
  • --dry-run：只打印计划、不写任何东西。

--dry-run 是这个仓库对新手最有价值的开关，在 --link 场景下尤其如此——你即将往 ~/.claude/agents/ 这种共享目录里放一批链接，先看一眼计划比事后收拾便宜得多。确认无误后，把最后一行去掉再跑一次即可。

选择器还可以更细，--agent 直接点名，--agents-file 从文件读列表（每行一个 slug 或名字，支持 # 注释）：

# 只链两个具体 agent
./scripts/install.sh --tool claude-code --agent design-ux-architect,design-ui-designer --link --dry-run

# 用清单文件管理你的常用组合
./scripts/install.sh --tool claude-code --agents-file ./my-agents.txt --link --dry-run

几个选择器可以自由组合，全部留空就是全装。另外三个相关开关：--path <dir> 覆盖安装目录（单一目标）、--parallel 并行安装各工具、--jobs N 设最大并行数（默认取 nproc 或 4）。还有 --list [tools|teams|agents]，列出后直接退出，用来确认名字拼写。

平台方面，脚本注释写的支持范围是 Linux、macOS（需要 bash 3.2+）、Windows 的 Git Bash / WSL。Windows 用户注意：脚本本身是支持的，但符号链接在 Windows 上的创建条件属于系统层面的问题，仓库注释没有对 --link 在 Windows 下的行为做任何说明，我们也没有验证过。在 Windows 上用这个开关，请先用 --dry-run 加小范围目标试一次，别直接全量。

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

三、产出物长什么样：三种 installKind 决定 --link 值不值

tools.json 把 installKind 定义为安装机制，共三种。这三种下面，「符号链接」的含义完全不同：

installKind产物形态代表工具
per-agent每个 agent 渲染出一个文件或一个目录Claude Code、Codex、Cursor 等多数工具
roster所有 agent 合并成一个文件Aider（CONVENTIONS.md）、Windsurf（.windsurfrules）
plugin一个构建出来的产物，不能按 agent 渲染成字符串Hermes（唯一一个）
  • per-agent：这是 --link 最顺的场景。以 Claude Code 为例，用户级目标是 .claude/agents/{slug}.md，一个 agent 一个文件，链接粒度和 agent 粒度对得上。
  • roster：产物本身就是一整份合并文件。想「只更新其中一个 agent」在形态上就不成立——这也是「为什么 Aider 里没法只装某一个 agent」的答案。
  • plugin：Hermes 的产物是构建出来的，tools.json 的 _note 明说它不能按 agent 渲染成字符串，在所有消费方都只能走 CLI。--link 对这种产物意味着什么，脚本没有交代，别默认它和前两种一样。

还有一类容易忽略的：产物是目录而不是单文件。OpenClaw 是一个 agent 一个目录（SOUL.md + AGENTS.md + IDENTITY.md），Kimi 是 agent.yaml + system.md，Mistral Vibe 会同时落在 .vibe/agents/{slug}.toml 和 .vibe/prompts/{slug}.md 两处。链接建在目录级还是文件级，tools.json 与 USAGE 段都没有写，需要断言就回源码看。

四、怎么验收

装完人要检查的是这四处：

  1. 落点对不对。install.sh 注释里列的落点，opencode、cursor、aider、windsurf 这四个写的是当前目录，其余多为家目录。你在哪个目录敲的命令，直接决定是给这个项目装还是给整个账户装。
  2. 是不是真的成了链接。用 ls -l 看目标文件是不是符号链接、指向哪里——这是通用 shell 做法，不是仓库文档的内容。
  3. 环境变量有没有在悄悄改路径。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 配置里设过其中之一，实际落点就不是文档里那个默认路径。
  4. Cursor 的老问题不会因为 --link 消失。convert.sh 渲染 .mdc 时，frontmatter 里的 alwaysApply: false 和 globs: "" 是写死的，转换出来的规则默认不会自动生效，要在 Cursor 里按需引用。装完发现「没反应」多半是这个，跟用不用链接无关。

最容易出错的一步是第 1 步：在家目录里敲了一条本该在项目目录里敲的命令，或者反过来。--dry-run 打出来的计划就是给你核这一步的。

五、什么情况别用 --link

  • 要可复现的环境时别用。链接的语义就是跟着上游走，一次 git pull 加一次 convert.sh，所有链过去的工具同时跟着变，中间没有灰度。要冻结版本，老老实实拷贝。
  • 仓库目录会被挪走或删掉时别用。链接会悬空——这是符号链接的通用性质，不是这个项目特有的行为，但代价由你承担。
  • roster 与 plugin 类工具上别指望它。前者产物是一整份合并文件，后者是构建产物，两者的「自动传播」都不是一 agent 一文件那种直觉。
  • 别一次性把 255 个 agent 全链进全局配置目录。上下文占用、工具启动时的加载、命名冲突都是实实在在的代价（我们没有测过量化影响，也不给数字）。用 --division 或 --agent 收窄，是更稳的起手式。
  • 需要在目标目录里就地改一份定制版时别用。链接过去以后你改的其实是上游产物，下一次 convert.sh 会覆盖掉。想做本地定制，要么拷贝安装，要么改源 agent markdown 再重新渲染。

最后提醒一句边界：仓库自带的两道质量门管的都不是「提示词写得好不好用」。scripts/lint-agents.sh 查的是结构——frontmatter 必填 name / description / color，缺了报 ERROR；推荐章节（Identity / Core Mission / Critical Rules）缺失只报 WARN，不会让检查失败。scripts/check-agent-originality.sh 查的是重复度，默认阈值是相似度达到 40% 判失败、20% 出警告，两个值都能用环境变量覆盖。这两道门都不会告诉你某个 agent 的提示词在你的项目里管不管用。--link 让改动传得更快，传的是什么内容仍然由你负责。

延伸阅读

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

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

浏览课程 加入会员