tako 文档 GitHub

82 · 可组合执行原语与后台任务

性质:已落地(2026-11-15 施工+验收;单测/契约 506/0、活体四脚本与 spotcheck 全绿、§12.3 走查与 §12.4 演示完成,证据与遗留见 tmp 台账与本节「未做项」)。 日期:2026-11-15。 代码落点:yk-tako-eino/internal/runengine/{bash_job,bash_job_sweeper,bash,sandbox,agent_task_tools,agent_task_delivery,agent_task_scheduler,agent_task_runner,agent_task_recovery,agent_task_attention,orchestration_journey,server,tools,worker,pgstore}.go、cmd/yktako/main.go、agents/{coder,researcher}.md、web/src/{TasksView,NotificationRecovery,api,mutation}.{vue,ts};机器验收在 scripts/acceptance/(bash_job_live.sh、bash_job_replica_live.sh、agent_task_wait_live.sh、orchestration_live.sh、agent_task_demo_live.sh)。 前置真源:doc/58(bash 留尾与全文落盘)、doc/70(持久 Task 与初始 DAG)、doc/72(有界修订)、doc/73(通知与交付恢复)、doc/74(工作现场与发布)、doc/75(重规划)、doc/76(项目目录)。 参照:DeepSeek harness 的「所有 bash 先登记 job;前台等待超时返回同一 job id;显式后台立即返回」、dsh 的「后台完成消息唤醒 Session」、Claude 的「少量可组合操作、延迟决定等待方式、需要结果时再等待」。只借这些分工,不照搬单机进程内注册表。

0. 结论

本方案不增加用户可见的「普通任务/异步任务/DAG 模式」选择,也不先造 JS 编排引擎。改的是三件具体事情:

  1. bash 的 30 秒只表示调用方先等多久,不再表示命令最多活多久。 到点命令继续跑,调用方拿到 bj_… 命令号,之后可以读输出、等待或停止。
  2. 持久 Task 创建后既能等通知,也能在确实需要结果时主动等待。 新增 wait_task;它读取数据库里的任务与结果,不依赖某台引擎进程里的等待者。
  3. DAG 只是同一目标下 Task 与依赖边的集合。 已知依赖仍由 create_orchestration 一次写入,执行中发现新工作仍由 revise_orchestration 追加;不新增用户模式,不给单件 delegate_task 硬加跨组 depends_on。

普通子代理继续表示「我现在就需要这份独立上下文的结果」,持久 Task 表示「这件工作要有独立身份、可以后台推进、能够恢复和交付」。二者可以复用执行能力,但不为了名词统一再造第三种后台子代理。

1. 背景:现在不是缺一张更大的图,而是三条链各自断了一截

1.1 一个会真实发生的失败故事

用户说:「让这个项目达到可交付状态,构建和测试都要通过;整理现有两份调研,最后给我一份报告。构建期间我还想问别的问题。」

今天可能发生三件不顺利的事:

mAgent 启动构建
→ 30 秒到,程序把构建杀掉
→ 工具回一段「超时,死前输出」
→ 用户以为构建仍在跑,实际已经停了

mAgent 又创建一件持久调研 Task
→ 工具返回 taskId
→ 工具说明要求「不要等待」
→ mAgent 下一步正需要这份调研才能写报告,却没有主动等待结果的工具
→ 它只能结束本轮等通知,或者反复创建无关工作来填时间

mAgent 一开始只知道要调研,不知道最后会遇到什么
→ create_orchestration 却要求一次交完整张图
→ 为了调用工具,它可能编造尚未确认的节点
→ 真正的新事实出现后,再靠修订纠正前面的猜测

这三段问题不能用同一个「打开 DAG 模式」解决。第一段缺的是进程生命周期与等待时间的分离;第二段缺的是按任务号读取和等待;第三段需要保留已有的增量修订,而不是再发明一套图语言。

1.2 现有能力已经走到哪里

所以本方案的主要工作是把已有对象接成可组合的链路,不是另建一套任务世界。

2. 范围与非目标

2.1 本期完整交付

  1. 前台 bash 超时继续运行、显式后台启动、输出读取、有限等待、停止、完成通知、项目内可见与跨副本状态一致。
  2. wait_task 主动等待与结果读取;等待期间崩溃可恢复;已经由当前 run 读取并交付的结果不再触发第二次交付。
  3. 创建编排时返回最终 taskId,使调用方可以直接等待最终交付节点。
  4. 重写执行策略提示:直接做、同步子代理、后台 Task、等待、依赖和重规划各有清楚的使用条件。
  5. shared 编排组的并行写入边界改为程序可解释的规则;isolated 并行与既有发布链保持。
  6. 对话页右侧工作区能查看后台命令的状态、输出与停止入口;Task 仍复用现有任务详情,不新增第二张任务列表。

2.2 明确不做

3. 四个层次分别回答什么

层次 真身 回答的问题 不回答什么
执行单元 一次 bash、一次同步子代理、一件持久 Task 谁真正做工作,结果在哪里 调用方要不要现在等
等待方式 同步返回、bash_output(wait=true)、wait_task、持久通知 调用方现在离开,还是等到结果再继续 是否跨重启保留工作
依赖关系 agent_task_links 的 parent → child 边 child 是否必须等 parent 成功才能开始 两件工作是否会写同一文件
编排表达 当前模型工具调用、创建与修订 API 怎样产生和修改执行单元及依赖 是否必须用某种编程语言

async 与 persistent 不绑定。 async 只是「调用方此刻不等」;persistent 是「工作有持久身份,重启后仍能解释和恢复」。后台 bash 在本方案中有持久状态与输出,但不自动恢复执行;持久 Task 有显式恢复能力。两者都不是简单 goroutine 的别名。

await 与 async 不互斥。 调用方可以先启动 A、B,做一段既不消费它们结果、也不与它们争用同一写入目标的工作,再等待 A、B。独立性低不等于只能一开始就同步等待。

结果依赖与写入冲突分开。 「C 要读 A 的结果」应写成 A → C;「A、B 都写 report.md」不是依赖边能解决的问题,应使用隔离工作现场、先后执行或由下游解决冲突。

4. 模型侧使用规则

这些规则写进稳定的系统提示与相应工具说明。它们只帮助模型选择,程序仍负责权限、状态、依赖、执行权、恢复与发布。本节只规定选择条件、默认顺序与禁止项,不提供可直接上线的逐字 prompt;施工包必须先把工具契约与端点实打验收,再把规则落成稳定系统提示与工具说明。

  1. 当前上下文能顺利完成的工作直接做。 需要独立上下文、独立交付、后台推进或恢复时才创建执行单元;不为了显得有计划而创建 Task。
  2. 启动后先拿任务号或命令号。 只有存在既不依赖结果、又不争用写入目标的工作才继续;下一步需要结果时就等待,没有别的事可做时可以结束本轮等通知。
  3. 只有下游确实消费上游结果时才加依赖边。 不为了画出复杂图而增加节点,不把文件写入冲突伪装成结果依赖。
  4. 已知的节点一次创建,新发现的工作按事实追加。 不预先编造完整 DAG;最终节点尚未开始时走同组修订,原组已经交付后走 doc/75 的继任判断。
  5. 同步子代理与持久 Task 按生命周期选择。 需要立即拿结果继续,用同步子代理;需要离开当前工具调用、独立恢复或让程序推进依赖,用持久 Task。不要靠猜命令会跑几秒来决定。
  6. 固定工具调用已经能表达时,不请求另一门编排语言。 多次调用、条件分支与动态追加足以覆盖本期场景。

工具说明必须删除当前「调用后不要等待」的绝对措辞,改成:「有不依赖结果的工作就继续;需要结果时用 wait_task;也可以结束本轮,等待持久通知。」

这句提示是两把创建工具共用的,只改它不够——各工具自己的描述里还有反方向的句子,施工时同批改三处:

5. 端到端业务链

5.1 构建超过前台等待窗口

用户提出项目目标
→ mAgent 调 bash 启动构建
→ 程序先登记 bj_… 并确认进程已启动
→ 30 秒内未完成:工具返回同一个 bj_…,状态 running,不杀进程
→ mAgent 做不依赖构建结果的调研,或结束本轮
→ 构建输出持续写 runtime/tmp/bash/jobs/bj_…/
→ 构建结束:程序更新 PG 状态并写持久完成通知
→ 若 mAgent 正在等待:bash_output 返回终态、退出码与输出
→ 若原 run 已结束:来源会话空闲后创建一次结果处理 run
→ mAgent 根据真实输出修复、继续测试或向用户交付

没有第 4 步的同一命令号,调用方无法确认超时前后是不是同一条命令;没有输出落盘与 PG 状态,换一台副本只能看到一段无法解释的本地进程;没有通知,原 run 结束后完成结果会无人消费。

5.2 两件调研后汇总

用户要 A、B 两份调研与最终报告
→ mAgent 创建当前已知的 A、B、C,只写 A→C、B→C 两条真实依赖
→ 创建响应返回 orchestrationId 与 finalTaskId=C 的 taskId
→ A、B 执行;C 因依赖未满足不能开始
→ mAgent 若没有独立工作,可调 wait_task(C)
→ 等待工具按 PG 当前状态返回:仍在跑则到等待窗口结束返回 running;
   A/B 失败则 C 返回 blocked;全部成功则 C 返回最终结果
→ mAgent 用结果回答用户
→ 对应的最终完成通知由当前 run 收尾,不再另起一场重复交付
→ 任务工作区同时能打开路径账本:计划版本、失败与取消节点、
   结果复用、继任组与交付尝试都可核,不只给最终报告

若 A 的结果显示还必须补充 D,且 C 尚未开始,协调 run 读取 planRevision 后追加 D 与 D→C;A、B 已完成的有效结果不重跑。若 C 已完成并交付,则按 doc/75 判断继任组,不重写历史。

5.3 几件互不依赖的后台工作

mAgent 可以在同一轮发起多个独立 delegate_task 调用,也可以先启动后台 bash 再创建 Task。它们不因为「同时存在」就自动组成 DAG;只有共同最终交付和真实结果依赖出现时,才进入同一个编排组。

6. bash 契约

本节是待 curl 验收的提案字节,不是已运行事实。施工时先用真实端点与工具结果钉死,再抄入机器期望。

6.1 启动与超时转后台

bash 入参增加一个可选字段,原 command 不变:

{"command":"npm run build","runInBackground":false}
{"jobId":"bj_01…","status":"running","reason":"foreground_timeout"}

程序必须先确认沙箱与进程启动成功再返回后台回执;启动失败不能把一条从未运行的命令说成 running。

6.2 读取与等待

新增模型工具 bash_output:

{"jobId":"bj_01…","wait":true}
{"jobId":"bj_01…","status":"succeeded","exitCode":0,"stdout":"…","stderr":"","stdoutPath":"runtime/tmp/bash/jobs/bj_01…/stdout.out","stderrPath":"runtime/tmp/bash/jobs/bj_01…/stderr.out"}

状态词表为 running / stopping / succeeded / failed / stopped / interrupted。stopping 是停止请求已持久化、执行者尚未确认进程组退出;它不是终态,仍算 Task 的未收口命令。failed 包括非零退出与启动后的执行失败;interrupted 表示执行者失联,不能解释成仍在运行,也不会自动重放。

新增 stop_bash:

{"jobId":"bj_01…"}

成功回:

{"jobId":"bj_01…","status":"stopping","stopRequested":true}

停止是异步动作:请求写库后返回 stopping,不把「信号已发」说成进程已退出。执行者实例收到停止请求后杀整个进程组,确认退出才写 stopped。已终态时重复停止返回当前终态与 stopRequested:false,不制造第二次通知。停止请求已写但 owner 失联时,job 保持 stopping,直到对账把它收成 interrupted;这段时间不允许提交 Task 结果。

停止必须作用于进程组,不能只停掉外层 bash -c 而留下孙进程。

6.3 产品 API

新增以下 JSON API,均使用 code → message → data 信封;写操作要求 member,读操作仍按项目与来源会话可见性校验:

端点 用途 成功 data
GET /api/workspaces/:id/jobs?sessionId=… 列当前项目后台命令;可选只看本会话 {"jobs":[…]}
GET /api/jobs/:id 状态、退出码、时间、来源 Task/run、输出路径 job 详情对象
GET /api/jobs/:id/output 当前尾部输出与全文路径 与 bash_output 同语义的 JSON
POST /api/jobs/:id/stop 请求停止 {"jobId":"bj_…","status":"stopping","stopRequested":true}
GET /api/orchestrations/:id/journey 一个目标实际走过的计划版本、节点结果、失败/取消、复用与交付尝试 路径账本对象(§10.3)

job 列表行与详情同一形状,键序固定、字段恒在(不适用为 null/空串):

{"jobId":"bj_…","workspaceId":"ws_…","sourceSessionId":"s_…","sourceRunId":"r_…",
 "sourceTaskId":"","sourceOrchestrationId":"","status":"running","exitCode":null,
 "stopRequested":false,"backgrounded":true,"command":"npm run build",
 "stdoutPath":"runtime/tmp/bash/jobs/bj_…/stdout.out",
 "stderrPath":"runtime/tmp/bash/jobs/bj_…/stderr.out",
 "createdAt":"…","startedAt":"…","endedAt":null}

路径是逻辑相对路径(相对运行资源根;无项目会话以 .tako/bash/jobs/<jobId>/ 开头),前端不拼宿主绝对路径。终态里 succeeded 退出码为 0、failed 为非零,stopped/interrupted 的退出码为 null——进程被杀没有有意义的退出码,不把 -1 或信号号伪装成业务结果。/output 的 data 与 bash_output 同形同序:jobId → status → exitCode → stdout → stderr → stdoutPath → stderrPath。

建议业务码:未知或不可见命令 404 117117,当前不可停止 409 117118,Task 尚有后台命令未收口 117119。117119 没有 HTTP 提交面——submit_task_result 是模型工具,路由表里没有等价端点,所以它只在 doc/40 词表登记,实际拒绝是工具错误句子。施工时同批更新 doc/40、expected.json 与人读验收文档。

鉴权落点:三个读端点按登录态与属主链判,不可见统一 404;停止是写面,viewer/非成员由既有 RequireTenantRole("member") 中间件直接 403 111203,不在 handler 里另造判定。没有项目的聊天会话也能跑命令:此时 job 的 workspaceId 为空串,跳过项目可见性、只按来源会话判定;单件查询、输出与停止照常可用,任何项目列表都不含它。

不新增 HTTP「等待 30 秒」端点。页面轮询读快照并跟事件重拉;主动等待只服务模型当前决策,不让浏览器长占请求。

7. Task 等待契约

7.1 wait_task

新增模型工具:

{"taskId":"at_01…","wait":true}
{"taskId":"at_01…","orchestrationId":"or_01…","status":"succeeded","result":{"summary":"…","artifacts":[],"metadata":{}},"error":null}

status 与 API 视图同一派生规则:存储为 running 且当前 run 租约已过期时返回 interrupted;这是读侧派生,不写回 Task 行。等待窗口内进入 interrupted 也立即返回,不等满窗口。

等待不启动新执行、不重放执行者的外部副作用,崩溃恢复时重复等待不会重复创建 Task。但它不是严格只读:按 §7.2,当前 run 读到最终节点成功时会先跑一次与调度器同一份的组收口(必要时把组收成终态、写出整组完成通知),并就地认领通知——等待本身读状态,收尾那几次写认领与收口。等待窗口结束返回 running 不是失败,模型可以决定继续等其他工作或结束本轮。

create_orchestration 与 POST /api/orchestrations 的成功体在原字段末尾追加 finalTaskId;原 orchestrationId → status 相对顺序不变。单件 delegate_task 已有 taskId,无需加字段。

落地时不能只在现有回执的 map 里加一个键:创建回执现在是 json.Marshal(map[string]string{...}),Go 按字母序输出键,现有 orchestrationId → status 恰好与字母序一致所以从未暴露,finalTaskId 加进 map 会排到最前面。施工要改成结构体或手写 JSON,并同批改 contract_test.go 的精确字节断言、scripts/acceptance/expected.json 与 doc/19-v6/19v6-04-验收-curl.md。

7.2 等待与通知不能重复交付

最终 Task 成功与整组收口不在同一笔事务里:Task 状态在 ReconcileRun 的事务中翻转(agent_task_scheduler.go:149-176),orchestration_finished 通知则要等调度器下一轮 AdvanceOrchestrations(:779)收口时,与组状态在同一笔事务中落库(:478-483)。所以 wait_task 看到最终成功后不能只按 dedup 键去找通知:中间这段时间通知还不存在,查找打空,run 结束后仍会多一场交付。规则是先收口、再认领:工具里先跑一次与调度器同一份的单组收口(把 AdvanceOrchestrations 的循环体抽成 advanceOrchestration(ctx, orchID):锁组行、锁后复查、组已非 active 直接空转——与调度器并发只是谁先写、结果一样),收口成功的那笔事务已包含通知,随后按 orchestration_finished:<组id>:<结果版本> 查找必然命中,再就地认领给当前来源 run;当前 run 接着使用结果生成用户回答,RunEnd 复用 doc/73 的完成/失败收尾。

组当时收不了口(plan_hold 为真,或还有别的节点没终态)时不认领、只返回 Task 当前状态:组还没完成,就不该有「整组交付」这件事,交付归组收口后的正常路径,工具不重试、不自己标。计划暂停时这本来就是有意的——用户还要做一次计划决定,组完成发生在决定之后。

这样几条路径各只有一个消费者:

认领范围只覆盖「这次等待已经看见、并由当前 run 交代的事实」:最终节点成功的整组交付通知(先按上段收口,再按组与结果版本找;组当场收不了口就不认领)、当前 Task 的失败通知(按 task_id 取 pending 的最新一条,dedup 里的 run/epoch 不重建)、已落库为 pending 的中断通知。读侧派生的 interrupted 与 blocked 不认领——派生由租约过期算出、不写回,中断通知可能还没落库;这时认领打空,留给正常交付,工具不重试、不自己标。plan_review_required 等其它 kind 一律不认领。

两个入口抢同一行通知时,靠行锁和锁内复核分胜负,不靠先后直觉:

若当前 run 在读到结果后崩溃,通知的 claim_run_id 仍指向该 run,恢复走 doc/73;若它明确 error/stopped,保留失败并可人工重新处理。后台 bash 的终态通知采用同一条规则:bash_output 在来源 run 中读到终态、且该 run 的会话就是通知接收会话时认领对应通知,避免稍后再弹一次相同结果;哪些后台命令写通知、接收会话是谁,见 §10.1。

这里的「认领」必须是就地认领,不能复用调度器的 claimNotification:后者会铸一场新 run,而来源 run 此刻还活着,忙检查必然退回 pending,等它结束再弹一次——恰好造成要避免的重复交付。就地认领只锁通知行、校验接收会话与 pending、把 claim_run_id 指向当前 run 并置 claimed_in_place=true;不建 runs 行、不做忙检查、不写 attempt 行。不写 attempt 是结构约束:agent_notification_attempts.run_id 是唯一索引,一场 run 可以先后就地认领 job 与 Task 两条通知,第二条 attempt 会撞索引;attempt 行同时是「这场 run 是交付 run」的身份标记,混入就地认领会让普通聊天 run 在 resume 时被当成交付 run、工具面被裁成只读。为此通知加 claimed_in_place 列,CoordinationClaimForRun 与启动回填补 attempt 的回填 SQL 都按它排除。整组通知还要把组置 delivering 并写 delivery_run_id=当前 run,否则该组永远停在 pending;bash 通知与单件 Task 通知没有组状态可写。收口交给该 run 的 RunEnd 对账,对账按 claim_run_id 取全部 claimed 行逐条裁决(一场 run 可以同时认领多条):complete → consumed(整组再 delivering→delivered),error/stopped → failed;崩溃保持 claimed + 死 run,读面按 interrupted 派生,恢复入口是 resume 那场 run,不是重试通知。

7.3 为什么不加通用 executionId

bash 输出与 Task 结果的读取方式、恢复承诺和权限归属不同。用一个大联合类型把二者包起来,只会让调用方继续分支判断类型。本方案统一的是「启动后拿编号,需要时读取/等待/停止」的操作顺序,不强行统一所有返回体。

7.4 三把新工具各进哪个池

现有装配有两道:执行者基座按黑名单减(agentTaskNoTools),子代理规格再按 tools: 白名单裁——coder 就是白名单规格。submit_task_result 正是因为这道白名单才必须在规格过滤之后追加,否则执行者永远交不出结果。新工具不点名归属,就会在这两道里走错:

8. 后台命令的存储与生命周期

8.1 一张 job 表,输出仍在共享文件

新增 background_jobs,至少保存:

每条 bash 都在启动时登记,短时完成后也能按命令号回查。输出从首字节起写共享文件,不能只在超过内存尾窗后才开始落盘;否则超时转后台后的早期输出会消失。文件沿用 doc/58 的 64MB/流上限与 30 天清理,落点为:

runtime/tmp/bash/jobs/<jobId>/stdout.out
runtime/tmp/bash/jobs/<jobId>/stderr.out

没有项目的纯会话没有运行资源根(runWorkspace 返回空 runtimeRoot):输出落该会话目录下的 .tako/bash/jobs/<jobId>/,job 的 workspace_id 为空串,单件查询/输出/停止按来源会话判定,项目列表不含它。

PG 保存状态与归属,共享持久卷保存输出。不能用共享文件代替跨副本状态裁决,也不能把完整输出塞进 PG。

登记与清理成对写清:

8.2 单执行者与失联处理

后台命令不采用「共享磁盘上的 JS 自己继续跑」作为恢复协议;文件可以共享,进程执行权仍需明确。

8.3 与 run、Task、项目删除的关系

9. DAG 与工作区规则

9.1 保留两种创建生命周期

单件 delegate_task 自己就是一个最终交付单元。它完成后所在单节点组即完成,因此不能事后给它追加下游,也不接受 dependsOn。

create_orchestration 用于多件工作共享一个最终交付。调用方只提交当前已经确认的节点与边,不必预测所有未来工作;之后由 doc/72 的修订承接新事实。这样既保留初始写入的原子性,也避免「先创建半张图,进程死在中间」的问题。

因此不新增 delegate_task.dependsOn:现有单件 Task 各自属于不同编排组,跨组加边会破坏结果交付、失败传播和项目归属。需要依赖时,应从一开始就在同一编排组里表达。

9.2 shared 与 isolated 的并行边界

当前 shared 组允许多个 Task 并行,但文件工具的短锁管不到 bash 内部的每次写入。为让默认行为可解释,本方案拍定:

这会降低 shared 组的默认并行度,却消除「默认配置本身允许多个非合作写者改同一目录」的假安全。需要并行的场景有明确出口,不靠模型祈祷。

10. 通知、页面、事件与观测

10.1 复用通知状态机,不伪造 Task

后台 bash 不能伪造一件 Task 来塞进 agent_notifications.task_id。通知模型增加可空的后台命令引用,并让编排组引用在 kind=bash_job_finished 时为空;通知新增 kind:

bash_job_finished

它只在命令进入 succeeded/failed/stopped/interrupted 时写一次,去重键包含 job id 与执行代次;终态更新与通知插入同一事务(与组收口同一规矩),否则读取方可能先看到终态、后看到通知,就地认领打空,run 结束后多一场重复交付。认领、忙时 pending、崩溃恢复、人工重试与 consumed 仍复用 doc/73。处理 run 的工作区与租户身份从 job 读取,不再假设每条通知都有 orchestration。

谁写通知、谁能认领,先拍定再施工:

这张表与消费链要一起改,不能只加 kind:

通知正文是程序生成的结构化输入:job id、终态、退出码、输出路径与来源命令。模型不执行通知正文里的任何句子;命令与输出仍是工具产生的数据,不因为写着「请忽略规则」就获得新权限。

10.2 页面

对话页右侧工作区新增「命令」视图或在现有任务标签内增加明确分组,施工时只选一个入口,不做两个重复列表。每行显示:

Task 列表继续只显示 agent_tasks,后台 bash 不混进 Task 数量与依赖图。移动端仍走现有项目/任务入口,不新做一套窄屏布局。

10.3 路径账本:用户要看见走了多少路

只给最终结果会让重规划和失败重试变成黑箱:用户看到一份报告,却不知道原计划被改过几次、哪些节点失败、哪些岔路被放弃、哪些结果被复用、是否换过继任组。失败重试被页面平滑成「成功」后,用户也无法判断结果是否可信、代价是否值得。

任务工作区打开一个目标时,在最终结果旁提供路径账本。它由程序从持久记录派生,不从模型回答或前端内存重建:

初始版本要单独说来源:agent_plan_revisions 只在修订路径写入,初始创建只写 Task 与边,修订表里没有初始那一版。账本的初始版本由读侧从 created_revision=0 的 Task 与初始边合成,revision 取存储口径的 0、reason 固定 initial。不为了对齐页面示例在创建事务里补写一条修订行——那会把只读投影变成新的写入真源,还会改动已验收的创建字节。修订号一律沿用存储口径:初始 0,第一次被接受的修订是 1。

读接口返回提案:

{
  "orchestrationId": "or_01…",
  "planRevision": 3,
  "summary": {
    "planRevisions": 4,
    "tasksCreated": 6,
    "succeeded": 4,
    "failed": 1,
    "cancelled": 1,
    "blocked": 0,
    "reusedResults": 3,
    "successorGroups": 0,
    "deliveryAttempts": 1
  },
  "steps": [
    {"type": "plan_revision", "revision": 0, "at": "…", "reason": "initial", "added": ["A", "B", "E", "C"]},
    {"type": "task", "taskId": "at_…", "taskKey": "B", "status": "failed", "reason": "verify_failed"},
    {"type": "plan_revision", "revision": 1, "at": "…", "reason": "recover_failed_research", "cancelled": ["E"], "added": ["B2"]}
  ],
  "relatedOrchestrationIds": []
}

steps 是只读投影,不是新的事件真源;施工时从现有计划修订、Task 状态与结果、通知尝试、继任 handoff 组装,初始版本按上面的规则合成。summary.planRevisions 是含初始版本的版本总数,即 planRevision + 1;planRevision 本身是存储里的当前修订号。跨租户或不可见统一 404。页面刷新、换副本后读到的账本必须相同。

10.4 事件与 trace

11. 权限、安全与既有行为

12. 施工顺序

开工前仍需把本篇细化成 tmp/82-可组合执行原语与后台任务/施工包.md 并由用户点头;本方案点头不等于可以直接改代码。

施工内部连续完成,不逐拍向用户交审:

  1. 先打真实契约:启动隔离引擎,用 curl 验证现有 Task/编排响应;落最小登记路径——真实 bash 工具调用插入 job 行并从首字节写输出文件,但还不拆前台窗口、不接管停止;然后实现并实打 job 的读取、输出与停止端点。确认请求/响应后才展开存储和调度。
  2. 后台 bash 完整链:分离前台等待与进程寿命,完成 job 表、输出文件、进程组停止、执行代次、跨副本读取、失联处理与通知;接 Task 停止和结果提交校验。
  3. Task 主动等待:实现 wait_task、finalTaskId、当前 run 认领通知与 RunEnd 收尾,处理崩溃和重复交付。最终成功走「先在工具里收口组、再认领」(§7.2),不能假设调度器已经 tick。
  4. 依赖与工作区规则:shared 组串行、isolated 并行保持,修订工具说明与系统提示;不新增跨组依赖。
  5. 页面与观测:命令列表、输出、停止、事件重拉、路径账本与 trace;复用现有任务面板壳,账本从持久记录派生,不让前端从回答文本重建。
  6. 验收与终审:机器测试、隔离活体、双副本、kill -9、浏览器与自然语言演示分别留证;主 Agent 审查实际 diff,不能只凭开发自报完成。

JS 若将来有真实消费者,必须另立方案证明「现有调用与修订为什么表达不了、JS 调用哪些原语、状态如何恢复、沙箱权限是什么」;本篇不留一个只能打印 hello 的 JS 空壳。

13. 验收与完成线

13.1 bash 确定性与活体

  1. 用可注入的短前台窗口启动会写标记文件的命令:窗口到后返回 running 与 job id,进程未死,之后文件与输出继续增长,最终可读到退出码。
  2. 显式后台与前台转后台使用同一套读取、等待、停止与通知;前台窗口内结束的旧工具结果字节不变。
  3. stdout/stderr 从首字节可在共享文件读到;超过尾窗只回尾部,全文路径可分页读取;超过全文上限按既有规则不报假路径。
  4. 停止包含孙进程的命令:首次停止回 stopping 且进程组仍在退出过程中;确认退出后才读到 stopped。重复停止返回当前状态且不制造第二次通知;读取未知 id、跨租户读取分别 404,viewer 停止由写面中间件 403。
  5. 两个副本同时读取与停止同一 job,只产生一个终态与一条通知;旧执行代次不能覆盖新状态。
  6. kill -9 自己启动的隔离 owner:重启后 job 显示 interrupted,输出仍在,不自动重跑;通知恢复后不重复交付。
  7. 普通聊天 run 结束后 job 继续;结果处理 run 能把输出带回会话。当前 run 已用 bash_output 读到终态时,通知就地认领且不新增 runs 行、不新增 attempt 行(claimed_in_place=true),该 run 正常结束后通知 consumed,会话空闲时不再出现第二场交付。一场 run 同时认领 job 与 Task 两条通知时,RunEnd 对账把两条都收口。
  8. Task 有 running 或 stopping job 时提交结果被拒;等待或停止并确认终态后才可提交。Task 停止会请求停止其 job;项目/会话删除在仍有非终态 job 时按忙拒绝,而不是删完后进程继续写。
  9. 真实执行者 run 的工具清单里同时有 bash_output/stop_bash、没有 wait_task(§7.4);researcher 规格能正常装载(排除清单只列父池存在的名字),实际清单里 bash/bash_output/stop_bash/wait_task 都不出现。执行者来源的后台命令终态后不产生通知,也不会有人认领;聊天来源的通知只被接收会话的 run 认领,执行者读自己 job 的终态只读不写。前台窗口内完成的短命令有登记行(backgrounded=false)、不进默认列表,终态后不写通知。
  10. 清理任务按 30 天周期删 job 行与输出文件,可多副本同时跑且幂等;被清理的 job 按 404 返回。执行者在自己的 run 中能读、能停自己 Task 的 job(来源 Task 身份),但读不到同项目其他会话的 job。
  11. 没有项目的会话也能起命令:单件查询、输出与停止可用,输出落会话目录 .tako/bash/jobs/<jobId>/,任何项目列表都不含它。

13.2 Task 等待与 DAG

  1. wait_task(wait=false) 立即返回当前快照;wait=true 在成功、失败、blocked、interrupted 派生与等待窗口结束五种情况下返回正确状态;命中终态立即返回,不等满窗口。
  2. 等待期间重启并显式恢复,不重复创建 Task、不重复执行已完成的工具副作用。
  3. 等待非最终节点成功返回其结果版本,且没有可认领的通知;等待最终节点成功时由工具自身先收口组、再就地认领,本次 run 交付后整组交付通知只收尾一次(调度器是否已 tick 都不影响;plan_hold 或还有 running 节点时不认领)。等待中读到 Task 失败时认领该 Task 的 pending 失败通知,会话空闲后不再出现同一失败的第二次交付;读侧派生的 interrupted 不认领。
  4. 编排创建响应含 finalTaskId,旧字段顺序不变;delegate_task 请求不接受 dependsOn。
  5. shared 组两个 ready Task 不并行;isolated 组仍可在限额内并行,既有结果交接与发布验收全绿。
  6. A 结果后发现 D:同组修订追加 D 与 D→C,C 不提前,A 不重跑;C 已交付后不能借修订重开,仍走继任组规则。
  7. 路径账本逐项对得上持久记录:计划版本、失败节点、取消但未开始节点、替代节点、结果复用、继任 handoff 与交付尝试都不缺;初始版本 revision=0 由 created_revision=0 的 Task 与初始边合成,创建事务没有新增修订行。刷新与换副本后字节一致,跨租户 404,模型回答里没写的失败节点仍然出现。

13.3 页面与自然语言演示

浏览器走查命令出现、输出增长、终态刷新、停止、跨会话过滤与移动端既有布局;打开目标时同时检查路径账本的计划版本、失败/取消节点、复用与交付记录,刷新后状态来自 PG 而不是前端内存。

另外做一次不打分模型智能的端到端演示。用户只提供目标与环境,不出现工具名、不指示何时建任务、不提示失败后怎么做:

让这个项目达到可交付状态,构建和测试都要通过;整理现有两份调研,最后给我一份报告。构建期间我还想问别的问题。

验收观察程序事实:是否有命令活过前台窗口、来源会话能否开始另一场 run、结果是否能回到会话、依赖是否阻止提前汇总。模型没有采取预期策略时登记为模型行为问题,不能用脚本预建 DAG 或伪造输出冒充通过;接口与执行机制必须先由确定性测试独立证明。

13.4 标准检查

14. 参照取舍

15. 所以这解决了什么

用户不需要先选择一种任务模式。模型可以直接做、同步委派、后台启动、需要时等待、按真实结果加依赖;程序则保证长命令不会被前台等待窗口误杀、任务结果能等也能收通知、图不会提前推进、后台写者不会越过 Task 与项目生命周期。

DAG 回到它该在的位置:只是同一目标下真实依赖关系的持久表示,不是用户要理解并手动开启的另一款产品。

16. 落地记录(2026-11-15)