Claude Code 在终端里很强，但一次只能盯着一条主线干活：你想让它同时改三个模块、写两份文档、跑一轮回归，就得自己开好几个窗口来回切换，谁改了什么、卡在哪一步全靠脑子记。CrewTower 解决的就是这件事——它把 Claude Code 从"一个会写代码的助手"变成一个"看得见的小队"：你定义角色、搭任务塔、一次性把任务并行派下去，最后统一回收产物。下面这套流程走完，你桌面上会多一个浏览器面板，里面是几个各司其职的智能体在同时干活。
适用场景
适合已经用 Claude Code 写过一段时间代码、开始觉得"串行太慢"的开发者：手上有一个中等规模的重构、迁移、批量补测试类的活儿，任务之间耦合不高，可以拆开并行。也适合想把 AI 编码流程沉淀成可复用模板的小团队——角色和任务塔配置好一次，后面换个仓库照样跑。如果你只是偶尔让它改一两行代码，那单兵模式更省事，不需要上这套。
环境与前置条件
- 操作系统：macOS、Linux，或 Windows 下的 WSL2。原生 Windows 终端在路径与进程管理上和这套工具链容易起摩擦，建议直接进 WSL。
- Claude Code CLI：必须已经装好并完成登录授权，能在终端里正常对话。CrewTower 本身不负责模型调用，它调度的是你本机这个 CLI。
- Node.js：使用当前 LTS 版本，随附 npm。具体最低版本要求以 CrewTower 官方文档当前版本为准，装 LTS 一般不会踩坑。建议用 nvm 之类的版本管理器装，避免和系统自带 Node 打架。
- Git：任务产物大多以补丁和分支形式回收，没有 Git 会很难回溯。
- 硬件：8GB 内存可以跑，但并行三四个任务时 16GB 更从容；磁盘至少留 2GB 给工作区、依赖缓存和历史运行记录。这套方案不依赖本地 GPU，显存无要求。
- 账号额度：并行意味着单位时间内消耗的 token 成倍上涨，动手前确认账户额度够用，否则跑到一半集体限流会很难受。
分步骤部署
第 1 步：确认 Claude Code 本体可用
先排除底层问题。在一个空目录里执行：
```bash
claude --version
claude
```
第一条能打印出版本号，第二条能进入交互界面并正常回答一句"你好"，说明 CLI 和授权都没问题。用 /exit 退出。
这一步很关键：后面所有报错里，超过一半最后都追溯到 CLI 没登录或版本过旧。如果这里就不通，先按 Claude Code 官方文档把 CLI 修好，不要往下走。
第 2 步：准备 Node 环境
```bash
node -v
npm -v
```
两条都能输出版本号即可。如果不是 LTS 版本，用版本管理器切一下：
```bash
nvm install --lts
nvm use --lts
```
顺手把 npm 的全局安装目录确认一下，后面排查 "命令找不到" 会用上：
```bash
npm config get prefix
```
把输出路径下的 bin 目录记下来，正常情况下它应该已经在 PATH 里。
第 3 步：安装 CrewTower
按官方文档给出的方式安装。常见的两种：通过包管理器全局安装，或从官方仓库的 Releases 页面下载对应平台的可执行文件。以包管理器为例：
```bash
npm install -g crewtower
crewtower --version
```
如果官方当前的包名或安装渠道与此不同，以官方文档为准，不要硬套。安装完成后能打印出版本号，说明二进制已经进了 PATH。
第 4 步：初始化工作区
新建一个专门的工作目录，不要直接在老项目根目录上试：
```bash
mkdir -p ~/work/crew-demo
cd ~/work/crew-demo
git init
crewtower init
```
crewtower init 会在当前目录生成一个配置目录（通常是 .crewtower/），里面大致包含：
config.yaml：全局设置，包括 Claude Code 的调用方式、并发上限、日志级别roles/：角色定义，一个角色一个文件tower/：任务塔定义runs/：每次运行的记录与产物
看到 "initialized" 之类的提示、并且 ls -a 能看到这个目录，就算成功。字段名和目录结构以官方文档当前版本为准，下面的配置示例按常见结构写，照抄前对一下自己的 init 产物。
第 5 步：定义角色
角色决定"这个智能体是谁、能干什么、不许干什么"。在 roles/ 下建几个文件，例如 roles/architect.yaml：
```yaml
name: architect
description: 负责拆解需求、给出接口设计与文件改动清单
prompt: |
你是这个仓库的架构角色。只做分析与设计，不直接修改业务代码。
输出必须包含：涉及的文件列表、每个文件的改动要点、风险点。
tools:
- read_file
- list_dir
- search
model: default
```
再建一个 roles/coder.yaml：
```yaml
name: coder
description: 按设计清单实现代码改动
prompt: |
你只实现分配给你的那一个子任务，不要顺手改别的文件。
完成后输出改动的文件路径和一句话说明。
tools:
- read_file
- write_file
- run_tests
model: default
```
还可以有 reviewer（只读、只提意见）和 tester（只跑测试、只写测试）。核心思路是收窄每个角色的工具权限：写代码的角色不给删文件的权限，做评审的角色不给写权限。这样即使某个智能体跑偏，损失也是可控的。
角色数量不要贪多，三到四个足够覆盖绝大多数任务。角色越多，协调成本越高，配置也越难调。
第 6 步：配置任务塔
任务塔描述"活儿怎么分层、谁依赖谁"。在 tower/main.yaml 里写：
```yaml
name: main
goal: 为现有模块补齐单元测试并修复暴露出的问题
roles:
- architect
- coder
- reviewer
tasks:
- id: design
role: architect
input: 阅读 src/ 下的模块，列出需要补测试的文件清单与优先级
depends_on: []
- id: test-module-a
role: coder
input: 为 src/module_a 补单元测试，覆盖主要分支
depends_on: [design]
artifacts: [patch, test_report]
- id: test-module-b
role: coder
input: 为 src/module_b 补单元测试，覆盖主要分支
depends_on: [design]
artifacts: [patch, test_report]
- id: review
role: reviewer
input: 汇总上面两个子任务的改动，检查是否有重复实现或遗漏边界
depends_on: [test-module-a, test-module-b]
artifacts: [review_report]
```
关键在 depends_on：design 是所有任务的前置，所以它会先单独跑；test-module-a 和 test-module-b 之间没有依赖，因此可以并行；review 必须等两个都完成。
任务粒度是这套方案成败的核心。两个并行任务如果都要改同一个公共文件，就会互相覆盖。拆任务时按"文件边界"切，而不是按"步骤"切。拿不准就先只开两个并行任务试水。
第 7 步：启动可视化面板
```bash
crewtower up --port 8787
```
终端会打印出监听地址，浏览器打开 http://localhost:8787 就能看到面板。面板上通常有三块内容：任务塔的层级图、每个角色的实时状态、以及运行日志流。
端口按自己习惯改，被占用就换一个。看到面板正常渲染出你配置的任务节点，这一步就成功了。
第 8 步：并行派发任务
在面板上点运行按钮，或者用命令行派发：
```bash
crewtower dispatch --tower main --parallel 3
```
--parallel 控制同时跑几个任务。第一次建议设成 2，观察一下稳定性再往上加。派发后终端会持续输出各任务的状态变化，面板上的节点会从"等待"变成"运行中"，再变成"完成"。
如果中途想停，Ctrl+C 中断调度，已经产生的中间产物会保留在 runs/ 下，不会丢。
第 9 步：回收产物
跑完后把产物收拢到一处：
```bash
crewtower collect --run latest --out ./deliverables
```
--run latest 指最近一次运行，也可以填具体的 run id（在 runs/ 目录名里能看到）。回收后的目录大致是这样：
```
deliverables/
test-module-a/
patch.diff
test_report.md
agent.log
test-module-b/
...
review/
review_report.md
```
查看具体改动：
```bash
cd deliverables/test-module-a && git apply --stat patch.diff
```
确认没问题再 git apply patch.diff，或者 --check 先干跑一遍。不要直接把补丁全量应用，逐个看过再合，这是并行方案里唯一的兜底动作。
验证部署是否成功
按顺序跑这几条，全部符合预期就说明整条链路是通的：
```bash
claude --version # 能打印版本号
crewtower --version # 能打印版本号
crewtower doctor # 自检，逐项列出 CLI、授权、配置、端口状态
crewtower status # 显示当前工作区与最近一次运行状态
```
crewtower doctor 是最有用的一条，它会把常见前置条件挨个检查一遍并给出结论，报错信息通常直接指向缺哪一环。如果这个子命令在你的版本里叫别的名字，以官方文档为准。
再做一次端到端验证：建一个只有两个并行子任务的最小任务塔，跑一遍，确认 deliverables/ 下出现两个独立目录、每个目录里都有 patch.diff 和日志。这个"最小可用验证"跑通了，再上真实项目。
预期结果：面板上两个节点先并行变绿，随后汇合节点变绿；runs/ 下多出一个带时间戳的目录；日志里没有 ERROR 级别的行。
常见报错与解决
1. command not found: crewtower
原因：npm 全局安装的 bin 目录没有进 PATH，或者装到了另一个 Node 版本下。
```bash
npm config get prefix
export PATH="$(npm config get prefix)/bin:$PATH"
```
把这一行写进 shell 的配置文件（.zshrc 或 .bashrc）里永久生效。如果用了 nvm，切换 Node 版本后需要重新安装一次全局包。
2. Claude Code CLI not found 或 authentication required
原因：CrewTower 找不到 claude 可执行文件，或者本机 CLI 没有完成授权。
```bash
which claude
claude
```
which 有输出但 CrewTower 仍报错，说明它读的是另一套环境变量，在 config.yaml 里显式指定 CLI 的绝对路径。如果是授权问题，在终端里跑一次 claude 完成登录再重试。企业代理环境下还需要确认 HTTPS 代理变量对子进程可见。
3. Error: listen EADDRINUSE :::8787
原因：面板端口被占用，多半是上一次没退干净。
```bash
lsof -i :8787
crewtower up --port 8788
```
确认占用进程后 kill 掉，或者直接换端口启动。同一台机器上跑多个工作区时，记得给每个工作区分配不同端口。
4. 429 Too Many Requests / 任务集体卡住
原因：并行数过高，短时间内请求量超出账户限流阈值。
```bash
crewtower dispatch --tower main --parallel 2
```
把并行数降到 2，观察单任务平均耗时是否明显拉长。如果还是频繁触发，在 config.yaml 里给重试加退避间隔。并行不是越多越快，卡在限流上反而比串行更慢。
5. YAML parse error 或任务没被识别
原因：缩进用了 Tab，或者 depends_on 引用了不存在的 task id。
```bash
crewtower validate --tower main
```
用这条命令做静态校验，它会指出具体行号。YAML 一律用两个空格缩进，任务 id 保持全局唯一。
6. 角色报 permission denied 无法写文件
原因：角色的 tools 列表里没给对应工具，或者工作目录权限不对。
回到 roles/*.yaml 补上 write_file 之类的工具声明。这其实是设计意图在起作用——先确认这个角色应该有写权限，再放开，而不是一律全开。检查工作目录归属：ls -ld .。
后续维护
备份：.crewtower/ 目录下的 roles/ 和 tower/ 是你的核心资产，直接纳入 Git 管理，和代码一起提交。runs/ 和 deliverables/ 属于可再生产物，加进 .gitignore。
清理：runs/ 会随时间线性膨胀，日志和中间补丁占空间不小。定期清理，比如只保留最近两周：
```bash
find .crewtower/runs -maxdepth 1 -mtime +14 -type d -exec rm -rf {} +
```
删之前确认没有还在跑的任务。
升级：升级前先看官方 changelog，注意配置文件结构是否有变动。升级后用 crewtower doctor 加一次最小端到端验证，确认老任务塔还能正常解析。生产用的工作区建议先在副本目录里升一次再切。
日志与监控：面板适合看当下，复盘要看日志文件。把 runs/*/agent.log 接到你常用的日志工具里，重点盯三类信号：任务失败率、单任务耗时变化、限流出现频率。失败率突然升高，通常是上游模型或 CLI 出了变化；耗时变长，往往是任务粒度拆得不够细，并行变成了互相等待。
成本视角：并行跑三个任务，token 消耗大致是串行的数倍。建议给每个任务塔设一个并发上限，并定期看账户用量趋势。如果发现某个角色大部分时间在重复做同样的探索，说明该把公共上下文抽到前置任务里，让后面的任务直接复用产出。