Windows 上怎么装：Git Bash、WSL 与 bash 3.2 的门槛

agency-agents 这个仓库本身没什么神秘的：它是一堆带 YAML frontmatter 的 markdown 文件（截至 2026-08-09 的核对，带 frontmatter 的 agent markdown 共 255 个，分布在 17 个 division），外加一套 shell 脚本，负责把这批 markdown 翻译成 16 种 AI 编码工具各自认识的格式，再拷进对应的配置目录。

问题就出在「shell 脚本」这四个字上。scripts/install.sh 和 scripts/convert.sh 都是 bash 脚本，双击跑不了，CMD 里跑不了，PowerShell 里也不是直接能跑的东西。仓库脚本注释里写明的平台支持是：Linux、macOS（需要 bash 3.2+）、Windows Git Bash / WSL。这一行短短的注释，其实已经把 Windows 用户的所有选择都框定了。

下面这一篇就沿着这行注释往下走：先定终端，再定命令，最后定验收。

第一步：确认你手上的 shell 能跑

仓库把 bash 3.2 写成版本下限。它出现在 macOS 那一栏，但含义是通用的——脚本是按这个很低的 bash 基线写的，不是按你机器上最新的 bash 写的。所以你需要做的不是升级 bash，而是确认你打算用来跑脚本的那个终端里，bash 版本不低于 3.2：

bash --version

在 Git Bash 里跑一次，在 WSL 里再跑一次。这两个是两套完全独立的环境，版本、家目录、已安装工具都不共享，别拿其中一边的结果去替另一边下结论。

顺带把仓库拉下来，注意脚本要用相对路径从仓库根目录调用：

git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
./scripts/install.sh --list tools

--list 这个开关的语义是列出后退出，可选值是 tools、teams、agents。既然是列完就退出，它不会进入安装流程，适合拿来当第一条命令，确认脚本在你这个终端里跑得起来。

第二步：Git Bash 还是 WSL，按「落点在哪」来选

这是本篇唯一真正需要动脑子的决策，而判断依据不在文档的推荐里，在安装落点里。

install.sh 的注释列出了各工具的安装落点，其中有一个很容易被忽略的分野：

工具	落点
claude-code	~/.claude/agents/
codex	~/.codex/agents/
gemini-cli	~/.gemini/agents/
copilot	~/.github/agents/ 和 ~/.copilot/agents/
opencode	当前目录的 .opencode/agents/
cursor	当前目录的 .cursor/rules/
aider	当前目录的 CONVENTIONS.md
windsurf	当前目录的 .windsurfrules

绝大多数工具装到家目录，而 opencode、Cursor、Aider、Windsurf 这四个写的是当前目录。

这个差别在 Linux 上无所谓，在 Windows 上是决定性的：WSL 里的家目录和 Windows 侧的用户目录不是同一个位置。如果你的 Claude Code、Codex 是装在 Windows 侧、读的是 Windows 侧的家目录，你却在 WSL 里跑了一遍 install.sh，文件会老老实实写进 WSL 那个家目录里——脚本这边没做错什么，它就是按你给的环境算出的路径落的盘，只是工具那边根本不去那个位置读。

所以决策路径是这样的：

• 目标工具装在 Windows 侧（大多数人的情况）→ 用 Git Bash，它的家目录和 Windows 侧是一致的。
• 目标工具本身跑在 WSL 里（你的开发环境整体在 WSL）→ 用 WSL，让家目录对齐。
• 只装 opencode / Cursor / Aider / Windsurf 这四类「当前目录」工具 → 关键不是用哪个终端，而是 cd 到你要挂载这些规则的项目目录再执行。

顺带一提，tools.json 里 opencode 的用户级路径模板是 .config/opencode/agents/{slug}.md，与 install.sh 注释里的「当前目录 .opencode/agents/」不是同一个位置——它们分别对应不同的 scope。要断言某个具体路径，回源文件按当前 scope 现查，别在两处之间类推。

如果家目录实在对不齐，脚本还留了两个后门。一是环境变量：注释里列出的可覆盖变量包括 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，它们在硬编码默认值之前被检查。二是 --path <dir>，直接覆盖安装目录（单一目标）。

第三步：先看计划，再落盘

install.sh 裸调用的语义是「把所有 team 装到所有检测到的工具」，在 TTY 下默认进交互向导。对一个有 255 个 agent 的仓库来说，第一次就裸调用不是个好主意。

正确的顺序是先用 --dry-run：

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

逐项说明每个选项为什么在这：

• --tool claude-code：只装这一个工具。不加的话是所有检测到的工具，你会同时往十几个目录写东西。
• --division engineering：只装这个 division。Engineering 这一个目录下就有 58 个 agent，已经不少了。
• --dry-run：只打印计划、不写任何东西。这是这个仓库对新手最有价值的一个开关，在往 ~/.claude/agents/ 这类共享目录写几百个文件之前，先看一眼计划总是对的。

想再收窄到具体某几个 agent，用 --agent：

./scripts/install.sh --tool claude-code \
  --agent engineering-frontend-developer,engineering-backend-architect \
  --dry-run

这里的 engineering-frontend-developer 是 slug，也就是 agent markdown 的文件名主干，不是显示名 Frontend Developer。名单长了就写进文件，用 --agents-file（每行一个 slug 或名字，支持 # 注释）：

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

还有几个开关值得知道：--no-convert 表示集成文件缺失时不自动跑 convert.sh（默认是会自动跑的）；--link 用符号链接代替拷贝，好处是仓库里改动会自动传播；--parallel 并行安装各工具，--jobs N 控制最大并行数，默认取 nproc 或 4；--no-interactive 关掉交互向导。

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

关于 --link：符号链接在 Windows 上能不能顺利建立，取决于你的系统与终端的权限设置，脚本注释对这一点没有说明。稳妥起见，Windows 侧第一次装先用默认的拷贝模式，别一上来就上 --link。

Windows 专属的坑：行尾换行符

这一条几乎是给 Windows 用户量身定做的。

scripts/lint-agents.sh 的第 0 道检查就是拒绝 CRLF 行尾，级别是 ERROR。仓库标准是 LF，写在 .gitattributes 里。源码注释还解释了为什么要专门拦这一条：行尾多一个 \r 会让后面的 frontmatter 检查报出「missing frontmatter ---」这种令人困惑的错误——明明文件第一行就是 ---。

而 Windows 上 Git 的换行符自动转换设置，正好能在检出时把工作区里的 LF 变成 CRLF——这道检查要拦的就是这类文件。如果你打算改 agent 文件、或者自己往仓库里加 agent，克隆之后先跑一遍 lint 心里有底：

./scripts/lint-agents.sh

不给文件参数时它扫描所有 agent 目录，给了文件就只查这些文件。要区分清楚级别：frontmatter 缺失、必填字段（name / description / color）缺失、CRLF 行尾都是 ERROR；推荐章节缺失、正文词数低于 50 只是 WARN，不会让检查失败。

顺带说清楚一件事：lint 检查的是结构，不评估提示词写得好不好用。它跑绿了不代表这个 agent 有用。

产出物是什么形态

install.sh 拷贝的不是源 markdown，而是 convert.sh 渲染进 integrations/ 的产物。integrations/ 是产物目录，不是源目录——这一点在 divisions.json 的 _note 里有明说。

tools.json 把安装机制归成三种 installKind，形态完全不同，验收方式也不同：

• per-agent：每个 agent 渲染出一个文件或一个目录。装多少个 agent 就是多少份产物。绝大多数工具属于这一类。
• roster：所有 agent 合并成一个文件。Aider 的 CONVENTIONS.md 和 Windsurf 的 .windsurfrules 是这一类——所以「为什么 Aider 里没法只装某一个 agent」这个问题，答案就在这里，它的产物形态本来就不是一 agent 一文件。
• plugin：一个构建出来的产物，不能按 agent 渲染成字符串，在所有消费方都只能走 CLI。Hermes 是唯一一个。

怎么验收

装完之后人要检查的是这么几处：

1. 落点对不对。去你选定的那个家目录（或项目目录）看文件在不在，路径就是上面那张落点表里的那一条。注意确认你看的是 Git Bash / WSL 里的哪一侧家目录。
2. 文件数量与 installKind 对得上。per-agent 的工具应该看到一堆文件，roster 的工具只该看到一个文件。看到「只有一个文件」先别急着报 bug，回去看它是不是 roster。
3. Cursor 装完像没装，是设计如此。convert.sh 里 Cursor 的 .mdc 产物 frontmatter 是写死的：globs: ""、alwaysApply: false。也就是转换出来的规则默认不会自动生效，需要在 Cursor 里按需引用。这是最常见的「装完没反应」来源，不是你装错了。
4. 最容易出错的一步是第一步：终端选错、家目录不对齐。所以再强调一次先跑 --dry-run 看计划。

什么情况下别这么装

• 你只想试两三个 agent：不用跑脚本。这批东西本质就是 markdown，README 也把「当参考资料读」列为三种使用方式之一，直接 cp 你要的那几个文件更省事。
• 你在共享账户或团队统一环境上操作：往家目录一次性铺 255 个 agent 是有代价的（上下文占用、工具启动时的加载、命名冲突）。用 --division / --agent 收窄，或者用 --path 装到一个隔离目录里先看看。具体影响有多大我们没有测过，不给数字。
• 你需要的是自动化编排：仓库 strategy/ 目录下的 NEXUS 是写在 markdown 里的方法论文档，里面没有可安装的 agent，也没有任何代码在强制执行阶段顺序。它不是调度器，装不装脚本都跟它无关。
• 你的团队要把这些内容进生产流程：仓库标注为 MIT，但许可条款请以官方 LICENSE 原文为准。

最后附一句时间锚点：2026-08-09 的 GitHub 元数据快照显示该仓库 star 数为 140729。关注度高不代表它适配你的项目、也不代表稳定，装之前该看的还是得看。

延伸阅读

• 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 的实际输出为准。

许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。