tako 文档 GitHub

等人现场放哪里:进程内等待 vs 库里一行

模块:运行引擎 · 人审与追问(doc/47,复用 doc/41 Loop A 档案)|状态:已落地(2026-10-23,Q1–Q5 + P1–P3)|证据:doc/47-Plan审核与追问澄清.md §3、internal/runengine/questions.go、waittools.go、plangate.go

1. 场景与病灶

两个会真实发生的戏:

戏一(plan 无审核):租户里的运营同事发「把 workspace 里的旧文件清理一下,再把报告整理成归档目录」。模型对「旧文件」的理解和小张不同——rm 掉一批文件,里面混着没提交的配置和财务表。每一道现有防线都放行:沙箱围栏只挡租户目录之外的读写,这些操作全在目录之内,合法;PII 脱敏管敏感串外泄;看板只是让丢的过程可见。破坏发生在第几秒,人没有任何动手前的检查点。

戏二(追问无载体):小张的消息本身有歧义(「那个报告」是哪份?)。模型有两条路:猜——答错二十分钟的活全白干;把问题当终稿文本交出来等下一条消息——这条路能走,但问题没有身份(答案回来时「在答哪道题」靠自然语言维系)、前端画不出问题卡、模型「决定提问」这个承诺不留痕迹。

两个病灶同一副地基:「人」这个外部输入源在引擎里没有正式进入通道。今天人只能靠「发一条普通消息」影响 agent,既无结构化的问题/方案载体,也无「任务在等输入」的状态。

2. 核心候选:等待现场放进程还是放库

候选 做法 好处 代价
A 进程内 park(kimi / dsh / eino HITL 原语) 工具 handler 里起一个 promise / StatefulInterrupt,人在同进程回调里回答 实现最短;eino 有现成原语 进程一死现场全丢;裁决端点在别的副本够不着;eino 的 gob checkpoint 是进程内字节,v6 目标多副本直接不成立
B 库里一行 + 轮询(选定) 落 run_questions 行 → 发帧 → handler 阻塞轮询该行直到 status != pending 现场在库;任何副本都能答;崩溃后 resume 重建等待者;多副本天然正确 一次 1–2s 的轮询开销;挂起期间占用一个 goroutine
C 挂号立即返回、答案走下一条 user 消息 工具立刻返回「已挂号」,人的回答作为下一条用户消息进来 不阻塞、不占 goroutine run 被切成两段,看板/账目/上下文全断;runlog 语义变复杂;省的钱比看起来少
D 不做,模型自己猜 保持现状 零成本 戏一、戏二原样发生

选 B。v6 的既有哲学已经给出了答案(doc/30 §2.3):interrupted 是读侧派生视图,runs 行保持 status='running' + 租约过期,语义是「执行者死了」。挂起沿用同一哲学——不加第四种存储状态,挂起 = running + 存在 pending 行,读侧可派生「在等审批」。

准确表述:阻塞中的 goroutine 只是可重建的临时雇员。进程死了 → 租约过期 → interrupted → 客户端 resume 在任何副本重建等待者,现场全部从 PG(行 + journal + runs 租约 + plan_mode 列)恢复。家规原话:「现场在库不在进程」。

3. 三拍:落行 → 发帧 → 阻塞等

每个「等人」工具(ask_user、submit_plan)的 handler 都走同一套:

  1. 落行:INSERT run_questions(kind=question/plan,status=pending,tool_call_id)。不做会怎样:进程死了对不清在等什么。
  2. 发帧:AppendFrame 一条 kind=question(name 区分发起工具,args 是原始参数 JSON,text 是问题/方案全文,messageId = 行 id)。不做会怎样:前端不知道在等人,页面死寂。
  3. 阻塞等:goroutine 内 1–2s 轮询该行直到 status != pending;全程尊重 ctx(stopRun 能打断,run 走 stopped,行留 pending)。答案文本作为 tool_result 返回,模型同一轮继续。

为什么选「同轮注回」而不是 C:工具契约完整(工具返回的就是答案,不是「挂号凭证」)、run 连续性(runlog/看板/账目不切碎)。

4. plan gate:为什么是运行时守卫而不是装配剥工具

模型能自己判断「这个任务多步/破坏性/不可逆」,调 enter_plan_mode 把 runs.plan_mode 置 true。此后每一次写/执行类工具调用都过 planGuardHandler——isMutatingTool(name) 为真就 deny:解释文本当 tool_result 回模型,工具未执行、不落 intent。

候选 做法 好处 代价
A 装配剥工具 进 plan mode 时把写工具从池里拿掉 模型物理上看不见写工具 需要入口 flag(用户已否);池子在装配期定,运行中改要重建
B 运行时守卫(选定) handler 链上逐调用判定 触发权还给模型,与 kimi 全套同款 「进不进模式」仍是提示词(软约束)
C 首次写前必审 模型发第一把写工具时强制问人 硬保证,不依赖模型自觉 每个干活 run 多一次打断;留档为将来升级路径
D 不做 只靠提示词劝阻 零成本 戏一原样发生

硬保证的准确表述:「进模式后想写也没有通道」——deny 是 middleware 硬拦,不依赖提示词。「进不进模式」是提示词(软)。这是 A 形态与开关形态的取舍:残余风险是模型该进不进直接干,靠提示词 + deny 反馈 + 用户 stopRun 兜底。

批准与放行:人在方案卡上点「批准执行」或「编辑后批准」→ answer 端点 CAS(decision=approve)→ 行 answered → 轮询注回批准文本(有修改则附全文)→ 同时 runs.plan_mode 置回 false → 守卫放行,同一轮继续执行。

退回修改不是拒绝:decision=revise → 注回「方案被驳回,尚未执行;计划模式仍然开启…」+ 意见 → plan_mode 保持 true → 模型改完重新 submit_plan,落新行、新帧、新卡,旧卡标「已驳回」并留住意见。

5. 崩溃兼容:journal 重放的第三分支

挂起中进程死 → 租约过期 → 派生 interrupted(既有)→ 客户端 resume(既有 claim CAS)→ replayJournal 重放到这条 intent 时查 run_questions:

账本 intent 对到的行 重放行为
无行 维持现状:interruptedResultText 回注,不重跑(at-most-once)
pending 重新挂起:重发 question 帧(seedResume 已清空 runlive,天然幂等),继续轮询
answered 注回答案/批准:内容作为该次调用的 tool_result(submit_plan 行附带退出 plan mode),模型继续跑

没这个分支会怎样:批准了的调用在 resume 后被当成「结果未知」跳过——人白批了,且模型拿到的文本与批准语义矛盾。

resumeCount 语义不变:挂起不消耗次数(lease_epoch 不动),只有崩溃接管才 +1。

6. 同族小裁定

小问题 裁定 代价 / 备注
表叫什么 run_questions(doc/41 的 run_approvals 改名) kind 列区分 question/plan,P/Q 共用一张表、一种帧、一套 resume 分支
状态机 pending → answered(外加终态清扫的 stale) 2026-10-27 发现:stale 没有生产者——全仓 UPDATE run_questions 只有 pending → answered 那一处 CAS,进程收摊或被 stop 的 run 会留一行永远 pending。补法与 doc/37 会话清理同一拍
一答终答怎么保证 PG 条件更新 WHERE id=? AND status='pending',影响 0 行回 409 115101 CAS 在多副本下成立,无「第二个副本一起判」的窗口
挂起时长上限 无上限、lease 照续、stopRun 可打断 人几天不答,会话闸就占几天——与 doc/41 同款取舍。代价:不需要超时清扫
授权语义 没有拒绝分支——answer 只可能是回答/批准 想撤回用 stopRun
答案形态 ask_user 带可选 options: string[],前端快捷按钮 + 自由文本框 有明确候选取值时给 2–4 个;option 文本就是 answer,端点和表不变
方案审批几态 批准 / 编辑后批准 / 退回修改三态 decision 列承载 approve/revise;编辑后全文走 answer 列
plan mode 放在哪 runs.plan_mode bool 列,不出 API 崩溃恢复后仍在(durable);前端靠 list 端点感知等待,既有端点字节零变更
plan mode 内放行什么 读类工具、看板四工具、ask_user、enter/submit 看板工具只改 run_tasks、不动工作区,放行是为了方案阶段先把步骤立成 todo
为什么能悄悄退出 不做 exit_plan_mode 无审退出 进了模式要么 submit_plan 过人审、要么 stopRun
帧词表 8 → 9,新增 question(P/Q 共用一个 kind) contract_test.go 词表测试是显式同步点,红即提醒
刷新后怎么恢复待答面板 前端查 questions?status=pending 从 PG 重建 不依赖 runlive 的 300s TTL;换窗口、换副本都不丢
子代理继承 ask_user 静态注册进一手池,researcher 走 exclude 路会继承它;coder 白名单不含 中途问人符合 researcher 定位;金样 TestShippedAgentSpecToolGuards 同步一行
脚手架 seed-question / plan-gate-check 两个 dev 探针 转正点已走完:seed-question 换成只读 question-check;plan-gate-check 本就是纯判定,保留为长期诊断口

7. 证据

方案:doc/47-Plan审核与追问澄清.md §3.1(共享机器)§3.2(plan gate)§3.3(ask_user + resume 第三分支)§3.4(外部参照对照)§5.1(表与改列)§5.2(帧)§5.3(端点)§5.4(批准/答案形态)§6(十拍收口)§7(不做清单)§8(1–6 全拍)。取档来源:doc/41-任务看板与人工审批.md §3.1(Loop A 原设计,整条不做但设计在案)。

台账:tmp/47-Plan审核与追问澄清/(本地,不入库);tmp/审批回路/决策记录.md(Loop A 时代的三项拍板,其中「走队列」思路被 Q 线继承)。

代码符号:

位置 是什么
internal/runengine/questions.go:52 RunQuestion struct(PG 表 run_questions)
internal/runengine/questions.go:78 Store.InsertQuestion:第 1 拍落行
internal/runengine/questions.go:123 Store.AnswerQuestion:CAS 一答终答
internal/runengine/questions.go:184 Server.listQuestions:GET /api/runs/:id/questions
internal/runengine/questions.go:226 Server.answerQuestion:POST /api/questions/:id/answer
internal/runengine/waittools.go:44 handleAskUser:三拍主机
internal/runengine/waittools.go:62 openWaitRow:落行
internal/runengine/waittools.go:100 emitQuestionFrame:发帧
internal/runengine/waittools.go:129 newSubmitPlanTool
internal/runengine/waittools.go:192 reconcileResumeWaits:resume 第三分支
internal/runengine/waittools.go:262 waitForAnswer:轮询
internal/runengine/plangate.go:54 isMutatingTool:写/执行黑名单纯函数
internal/runengine/plangate.go:73 planGuardDenies
internal/runengine/plangate.go:83 planGuardHandler:守卫 middleware
internal/runengine/plangate.go:125 newEnterPlanModeTool
internal/runengine/plangate.go:157 Store.SetPlanMode

复核命令:

cd yk-tako-eino
grep -n "run_questions\|status='pending'\|\"stale\"" internal/runengine/questions.go
grep -rn "stale" internal/runengine/*.go | grep -v _test     # 看有没有写入点
grep -n "isMutatingTool\|planGuardDenies" internal/runengine/plangate.go
bash ../scripts/acceptance/question_crash.sh                 # 需起隔离引擎,见 README

活体验收(2026-10-23):问题卡瀑布、方案卡编辑后执行、question_crash.sh 16 条断言全过(挂起中 kill -9 → interrupted → resume 202 → 帧重发 → answer → complete)。交互层重做后重跑:提问 → 选项 → 看板 → 方案 → 驳回 → 重提 → 编辑后批准 → 执行,看板 5/5。

8. 现状