multitask

多任务技能

用途

并行执行多个互不相关的开发任务。每个工作流都在隔离的 /tmp 克隆中运行，并由各自的 Recipe Runner 进程按照代码强制执行的工作流步骤进行处理。

主要优势：使用 Recipe Runner YAML 配方，而不是基于提示词的 Markdown 工作流。Python 控制步骤执行，因此不可能跳过步骤。

快速开始

内联任务

/multitask
- #123 (feat/add-auth): Implement user authentication
- #124 (feat/add-logging): Add structured logging
- #125 (feat/update-api): Update API endpoints

JSON 配置

创建 workstreams.json：

[
  {
    "issue": 123,
    "branch": "feat/add-auth",
    "description": "User authentication",
    "task": "Implement JWT-based authentication with login/logout endpoints",
    "recipe": "default-workflow"
  },
  {
    "issue": 124,
    "branch": "feat/add-logging",
    "description": "Structured logging",
    "task": "Add structured JSON logging across all API endpoints"
  }
]

然后运行：/multitask workstreams.json

工作原理

User provides task list
        |
        v
For each task:
  1. Clone branch to /tmp/amplihack-workstreams/ws-{issue}/
  2. Write launcher.py (Recipe Runner with CLISubprocessAdapter)
  3. Write run.sh (sets session tree vars, runs launcher.py)
  4. Launch subprocess via Popen
        |
        v
Monitor all workstreams (60s intervals)
        |
        v
Report: PR numbers, success/failure, runtime

为什么选择 Recipe Runner？

方面	传统方式（Markdown）	Recipe Runner（YAML）
步骤顺序	基于提示词（可跳过）	由代码强制执行（Python 循环）
模板变量	无	{{task_description}}、{{repo_path}}
错误处理	隐式	每个步骤快速失败
进度跟踪	不透明	逐步显示状态

关键实现细节

1. /tmp 克隆（而非 worktree）：worktree 符号链接会干扰嵌套的 Claude 会话。干净的克隆可以避免此问题。
2. --subprocess-safe：传统模式会传递此标志，以跳过暂存和环境更新，防止并发写入 ~/.amplihack/.claude/ 时发生竞争（问题 #2567）。
3. Recipe Runner 适配器：CLISubprocessAdapter 会在配方中为每个 Agent 步骤调用 claude -p（不使用 amplihack 封装程序，因此不会发生暂存竞争）。
4. 清理子进程环境：共享的 build_child_env() 工具会移除阻塞环境变量，并传递会话树上下文。

执行模式

配方模式（默认）

每个工作流都通过 Python 启动器运行 run_recipe_by_name()：

from amplihack.recipes import run_recipe_by_name

result = run_recipe_by_name("default-workflow",
    user_context={"task_description": task, "repo_path": "."})

传统模式

回退到基于提示词的单会话执行，并使用 --subprocess-safe 以避免并发暂存竞争（参见问题 #2567）：

amplihack claude --subprocess-safe -- -p "@TASK.md Execute autonomously following DEFAULT_WORKFLOW.md."

--subprocess-safe 标志会跳过所有暂存和环境更新，从而避免并行 工作流在 ~/.amplihack/.claude/ 上发生竞争。父级 amplihack 进程已暂存框架文件。

当 Recipe Runner 不可用，或任务需要完整会话上下文时，请使用 --mode classic。

可用配方

amplifier-bundle/recipes/ 中的任何配方都可用于各个工作流：

配方	步骤	最适用场景
default-workflow	52	功能、缺陷、重构（默认）
investigation-workflow	23	研究、代码库分析
verification-workflow	5	简单更改、配置更新
auto-workflow	9	自主迭代直至完成

在 JSON 配置中按任务指定："recipe": "investigation-workflow"。

监控

# Watch all logs
tail -f /tmp/amplihack-workstreams/log-*.txt

# Check specific workstream
tail -f /tmp/amplihack-workstreams/log-123.txt

# Check running processes
ps aux | grep launcher.py

# Final report
cat /tmp/amplihack-workstreams/REPORT.md

何时阅读辅助文件

需求	文件
完整 API、配置选项、架构	reference.md
真实使用示例	examples.md
Python 编排器源代码	orchestrator.py

磁盘管理与清理

了解磁盘使用情况

每个工作流都会创建一个完整的 Git 克隆（约 1.5 GB）。并行运行 10 个工作流时，临时磁盘使用量约为 15 GB。

位置：

• /tmp/amplihack-workstreams/ws-{issue}/ - 每个工作流的工作目录
• /tmp/amplihack-workstreams/log-{issue}.txt - 日志文件（单独保留）
• /tmp/amplihack-workstreams/REPORT.md - 最终执行报告

何时清理

✅ 可以安全删除：

• PR 已合并到 main
• 已完成对工作流的调试或检查
• 需要腾出磁盘空间来开展新的工作流
• 多任务会话中的所有 PR 均已完成

❌ 不可安全删除：

• PR 仍在审核中
• PR 存在需要手动解决的合并冲突
• 你可能需要检查工作目录以进行调试
• 工作流失败，且你尚未诊断问题

手动清理命令

# Check disk usage first
du -sh /tmp/amplihack-workstreams/*

# Clean up specific workstream (after PR merged)
rm -rf /tmp/amplihack-workstreams/ws-123

# Clean up all workstreams (after all PRs merged)
rm -rf /tmp/amplihack-workstreams/ws-*

# Keep log files, delete only working directories
find /tmp/amplihack-workstreams -type d -name "ws-*" -exec rm -rf {} +

# Check available disk space
df -h /tmp

自动清理（辅助命令）

合并 PR 后，使用清理辅助工具自动删除已合并的工作流：

# Clean up all workstreams with merged PRs
python .claude/skills/multitask/orchestrator.py --cleanup workstreams.json

# Dry run (show what would be deleted)
python .claude/skills/multitask/orchestrator.py --cleanup --dry-run workstreams.json

清理辅助工具：

• 使用 gh CLI 检查每个工作流的 PR 状态
• 仅删除状态为 MERGED 的工作流
• 保留日志文件以供日后参考
• 报告释放的磁盘空间

磁盘空间监控

协调器会在启动工作流前自动检查磁盘空间：

⚠️  WARNING: Only 8.2GB free in /tmp
Each workstream requires ~1.5GB. Consider cleaning up:
  rm -rf /tmp/amplihack-workstreams/ws-*
Continue anyway? (y/N):

经验法则： 至少保留 20GB 可用空间，以便顺畅地进行多工作流开发。

防止磁盘问题

1. 进行大型多任务运行前（10 个以上工作流）：

   df -h /tmp  # Check available space
   rm -rf /tmp/amplihack-workstreams/ws-*  # Clean old workstreams
   

2. 合并 PR 后：

   python orchestrator.py --cleanup workstreams.json
   

3. 执行期间监控：

   watch -n 60 'du -sh /tmp/amplihack-workstreams && df -h /tmp'
   

故障排除

日志文件为空：进程已启动，但立即退出。检查克隆环境中是否可以导入 amplihack 包。

未找到配方：确保克隆分支中存在 amplifier-bundle/recipes/。配方发现逻辑会优先检查此目录。

备用方案：如果配方模式失败，请使用 --mode classic 重试，以采用基于提示词的方式。

执行期间磁盘已满：可用空间少于 10GB 时，协调器会发出警告。如果执行过程中磁盘空间耗尽，请手动清理：rm -rf /tmp/amplihack-workstreams/ws-*（停止正在运行的工作流后）。