subtask

子任务

一个面向编码 Agent 的本地任务委派调度器。一个 MCP 服务（以及配套的 CLI）即可让 Claude Code、Codex、Kimi Code 或 OpenCode 并行开始工作，通过一次调用等待任务完成，并读取附带证据的简短摘要。它会选择能够承接任务的引擎，在多个进程之间安全地预留资金和时段，并如实说明每次运行的隔离程度。

start_many([{task: "Fix the flaky test in tests/test_sync.py", repo: "/src/app", verify: "pytest -q tests/test_sync.py"},
            {task: "List every caller of parse_date()", kind: "read", readonly: true, cwd: "/src/app"}])
  -> st-4f2a91 started · sonnet-api · branch subtask/st-4f2a91 · sandbox
     st-77c0de started · haiku-api · /src/app · readonly
wait(["st-4f2a91", "st-77c0de"])          # Claude Code shows: Subtask · 01:16 · 1/2 ended — st-4f2a91 running tests: pytest -q
  -> st-4f2a91 done · sonnet-api · 6m · 0.412$ · verified · ...
     ## Summary (≤10 lines: the answer, files, commits, tests, what is left)
result("st-4f2a91", evidence=True)        # JSON: base/head, changed files, observed commands, verify exit code, cost

为什么使用

• 节省调用方的上下文。 工作进程的搜索、测试运行和无效尝试都留在自己的会话中；调用方只需阅读约 10 行内容。
• 减少往返次数。 start_many 加一次 wait，即可取代轮询循环。
• 使用有空余容量的引擎。 engine="auto" 会筛选能够强制执行所需隔离策略、已安装、符合预算且有配额的引擎，然后根据明确的效用函数排序（subtask routing explain）。
• 资金管理是基本机制。 付费引擎会在开始任何工作前预留预算，并与时段一起在同一把锁下处理；每笔预留都只结算一次。
• 提供证据，而非空口断言。 verify="..." 会针对工作进程留下的提交运行检查；result(evidence=True) 会区分 subtask 观察到的内容和工作进程报告的内容。

安装

发行包名为 subtask-mcp（PyPI 名称 subtask 属于无关项目）。完整指南按客户端提供，并包含原生命令：docs/install.md。

uv tool install "git+https://github.com/tedin7/[email protected]"   # or: uv tool install /path/to/checkout
subtask install --client all          # prints the plan for every detected client
subtask install --client all --yes    # applies it: MCP server + skill
subtask doctor --client all           # checks app, config entry and a real handshake

Claude Code 插件：运行 claude plugin marketplace add tedin7/subtask，然后运行 claude plugin install subtask@subtask。Codex：codex plugin marketplace add tedin7/subtask。 API 引擎会从 ~/.config/subtask/env 读取 ANTHROPIC_API_KEY（chmod 600）。

引擎

引擎	付费方式	只读	可强制执行的隔离方式
haiku-api、sonnet-api、opus-api	API 密钥，月度上限	是	沙箱（Claude Code 操作系统沙箱）
codex	Codex 登录（配额来自本地会话文件）	是	沙箱（workspace-write）、隔离
opencode-go	opencode-go 订阅	否	worktree、隔离
kimi	Kimi 登录	否	worktree、隔离
dsh	DeepSeek 密钥，共用同一上限（subtask-mcp[dsh]）	否	worktree
opencode	OpenCode 默认提供商（仅手动使用）	否	worktree、隔离

无需修改核心代码即可添加引擎：在 subtask.engines 入口点注册 EngineAdapter（参见 CONTRIBUTING.md）。

如实说明隔离

• worktree（默认）：每个写入任务使用一个 git worktree 和分支。它可以避免冲突；但不是主机沙箱。
• sandbox：引擎自带的沙箱。同一用户：提供一道防护。
• isolated：bubblewrap。系统为只读状态，仅 worktree 和 git 目录可写，并使用仅包含引擎自身状态的私有 HOME。需要 bwrap。
• untrusted：使用沙箱或更强隔离，并禁止工作进程的命令访问网络。

如果任务无法获得所请求的策略，就会被拒绝，绝不会降级。输出在保存或显示前会针对常见的机密格式进行脱敏；脱敏只是第二道防线，并不能提供保证。请参见 SECURITY.md。

工具（MCP）和 CLI

工具	功能
start(task, kind, repo, cwd, files, readonly, engine, max_usd, effort, base, max_turns, policy, verify, isolation, max_retries, adversarial, context_refs, auto_repomap, tier, invariants, allowed_paths, symbol_scope, oracle_cmd)	启动一个任务（见下文）
start_many(tasks)	启动多个任务；每项的部分成功情况会单独列出。带有 id 和 depends_on 的项会组成一个组（grp-…），以 DAG 方式运行，不额外占用轮次；foreach=<parent id> 会为父项的 .subtask/fanout.json 中每个条目创建一个副本（最多 8 个），依赖项会等待所有副本完成；after="any" 会在任一父项成功时启动
integrate(ids, action="apply", auto_resolve=False)	处理工作树任务：diff、apply（全部应用或全部不应用，且不提交）、discard；发生冲突时，auto_resolve 会启动一个协调任务
consensus(prompt, engines, verify_cmd, isolation="worktree")	让 2 到 4 个引擎在各自的工作树中盲解问题，然后由一个任务将它们的 diff 作为匿名补丁进行比较并编写一个解决方案，再用 verify_cmd 和不变量进行检查；返回组 ID
bisect(good_ref, bad_ref, test_cmd, parallelism=4, auto_fix=False)	找出第一个导致 test_cmd 失败的提交；每轮在临时工作树中最多测试 parallelism 个提交（最多 8 个）；返回提交、作者和 diff；auto_fix 会启动一个经过验证的修复任务
map_reduce(glob_pattern, prompt_template, batch_size=5, concurrency=3, verify_cmd, isolation="worktree")	每批文件启动一个任务（模板中使用 {{files}}），同时运行的任务最多为 concurrency 个；返回组 ID
wait(ids, timeout=300, mode="all", since=None, stall_timeout=None)	阻塞等待任务结束（any：等待第一个；first_success：等待第一个已完成且已验证的任务，并停止其他任务）；任务停滞时提前返回；等待期间发送进度通知；供不支持进度通知的客户端使用的 since 游标
steer(id, action, instruction=None)	hint（排队等待，尝试结束时作为回复发送）、abort、retry（根据指令创建新任务）
inspect(id, tail=80, grep=None)	查看原始日志行，仅在摘要不够时使用
status(id) / result(id, full, evidence)	单行状态 / 摘要、完整文本或 JSON 信封
reply(id, message) / stop(id) / cleanup(id)	继续 / 停止工作 / 移除干净的工作树（保留分支）
engines()	各引擎的可用容量、来源、新鲜度和置信度，以及支出
step(title, path, how, decisions)	由一个独立的轻量模型根据仓库的实际状态描述该步骤

start 的选项：

• isolation="worktree"：使用独立的工作树和分支（类似于 repo=），并设置 SUBTASK_PORT（从 18100 开始）、SUBTASK_ID 和私有 TMPDIR。结果会列出 files_modified 和 diff_stat。
• verify + max_retries：检查失败时，会将输出传入作业并恢复执行；所有重试都失败时，工作树会回退到表现最佳的尝试（按“通过 N 项 / 失败 N 项”评分）。
• adversarial=True：Breaker 作业仅根据规范编写边界情况测试；这些测试会复制到 Builder 的工作树，并通过 verify 运行。
• context_refs：file:PATH[:A-B]、git:diff[:REF]、subtask:ID:summary|diff，会在开始前解析。auto_repomap=True 会添加跟踪文件及其顶层符号（按 HEAD 缓存）。
• invariants（默认为 ["no_test_deletion", "no_suppression"]，设为 [] 可关闭）：在统计 verify 结果前，测试函数数量不得减少，不得新增 skip/xfail 标记，也不得新增 # type: ignore、# noqa 或 # pragma: no cover。违反规则会被视为检查失败，并附上原因，以便重试时参考。
• allowed_paths：这些路径以外被更改的文件会被还原，并提交还原操作。
• symbol_scope=["path.py::name", ...]：这些文件中只有指定的顶层函数或类可以更改。之后，integrate 会按符号将多个作业对同一个 Python 文件的修改合并；重叠修改、导入或常量更改，以及目标分支上同时被修改的符号，都会被视为冲突，不会猜测如何处理。
• oracle_cmd：verify 通过后，会同时在作业的基线和结果上运行该命令，并报告退出代码和标准输出是否一致，以及 duration_ms_before、duration_ms_after、speedup_pct。
• tier：fast（投入低）、deep（投入高，类型为 hard）、free_only。月度额度使用超过 75% 后，auto 和 balanced 会改用免费引擎，回复中也会包含 budget_warning。

记忆：检查失败后，若重试修复了问题，subtask 会在 $SUBTASK_HOME/engrams/ 中为该仓库保存一条简短经验（最多 50 条，优先删除最久未使用的条目）。处理相同路径的作业会获取排名前三的经验。 组内有一个用于共享备注的公告板文件；新备注会显示在 wait(since=...) 中。

仅限 CLI：subtask board [--json]（OpenCode 插件渲染的视图）、subtask doctor、gc [--apply]、du、roi、routing explain|calibrate、watch ID...、install、uninstall，以及启动时使用的 --model、--no-sandbox、--untrusted。

聊天中的进度

客户端	在 wait 期间
Claude Code 2.1 (TUI)	工具调用下方显示实时进度行，已验证
OpenCode 2.0	收到通知但不显示：使用 wait(since=...)
Kimi Code 2.1	客户端不会请求进度：使用 wait(since=...)
Codex 0.162	尚未验证（账户已达到使用限额）

详细信息和证据：docs/progress-matrix.md。

设置

变量	默认值
SUBTASK_HOME	~/.local/share/subtask（作业、工作树、账本、遥测数据）
SUBTASK_ENV_FILE	~/.config/subtask/env
SUBTASK_MONTHLY_CAP_USD / SUBTASK_DEFAULT_MAX_USD / SUBTASK_MAX_JOB_USD	180 / 2 / 20
SUBTASK_MAX_RUNNING	4（所有进程共用）
SUBTASK_ROUTING	~/.config/subtask/routing.json（权重，"mode": "legacy"）
SUBTASK_JOB_RETENTION_DAYS / SUBTASK_TELEMETRY_DAYS	30 / 90
SUBTASK_PROGRESS_MIN_S / SUBTASK_PROGRESS_HEARTBEAT_S	2 / 10

API 引擎的费用来自 SDK 的估算；如果运行的实际费用未知，则按全部预留费用计费。遥测数据仅保留在本机。

平台

Linux：支持。macOS：功能受限（没有 /proc 启动时间用于判断进程是否存活，也没有 bwrap：拒绝使用 isolated）。Windows：不支持（fcntl）。

文档

架构 · 需求矩阵 · 优势与测量结果 · 基准测试协议 · 安装 · 发布 · 贡献

许可证

MIT