41 · 任务看板与人工审批
性质:已落地(2026-10-23)。B(PII 脱敏)+ C(任务看板)两线全部施工并验收;Loop A(人审回路)整条不做(留档备查,见 §3.1 与 §6 的 A1–A7)。 状态:✅ B1–B3、C1–C3 六拍 + P4 收口,全部完成。 验收结论(2026-10-23):
- PII 脱敏(B 线)三处挂载点全上:① 工具统一出口
wrapToolErrors(tools.go:49)——自家工具 / media / pdf / tool_search / MCP 的结果都走它,成功与错误两路都打码;② 模型输入的唯一转换口toSchemaMessages(midfold.go:373)——首轮 / 折叠 / 救援三条路一次覆盖;③ 记忆入库前writeMemoryJobResult(memory.go)——密钥类整条拒收(extractStats.Rejected计数),证件类打码后入库。 规则:7 条密钥正则(继承 doc/06 口径)+ 证件类(身份证 / 手机 / 邮箱 / 银行卡);掩码串与 span 由pii_test.go金样钉住,探针POST /api/dev/pii-check可手打复核。 ⚠️ 挂载点是踩坑后定的,别照旧方案抄:原计划「贴真工具内侧」会漏 MCP;只挂prepareInput会在折叠后让 PII 复活(折叠的原料是 mh 原文)——两条都已改,见 §3.2。- 任务看板(C 线):PG 表
run_tasks(正本在库里,不在进程内存)+ 四把工具(TaskCreate / TaskUpdate / TaskList / TaskGet)+kind=task帧 + 前端看板块(状态色)。活得过崩溃:实测kill -9引擎 → 重启 →POST /api/runs/{id}/resume(202,lease_epoch 1→2)→ 崩前建的行一条没丢,且在续跑里被继续更新(不是一张死表);机器可重跑的验收在scripts/acceptance/taskboard_crash.sh。- 帧 kind 词表 7→8(加
task;原计划的 8→9 随 Loop A 的approval帧一起取消)。task 帧的字节在 doc/19-v6-04「用例 8」登记为声明但暂不断言(要模型真的去调 TaskCreate 才造得出,模型行为不稳);帧词表由contract_test.go钉住。- 人工审批(Loop A):整条不做。 bash 的越界由沙箱围栏硬挡、MCP 的越界进了同款围栏(围栏根 = 该租户目录,doc/33)→ 没有需要「挂起问人」的场景。 日期:2026-10-22(方案)→ 2026-10-23(落地)。 随
fd6a489入库(2026-10-23):B/C 两线的代码、前端与验收脚本都在那一笔;本篇头注与 doc/16、doc/README 的状态翻转由它之后的 docs 笔回填。 代码落点:yk-tako-eino/internal/runengine/{pii.go,pii_test.go,pii_mount_test.go,tasktools.go,tasktools_test.go,tools.go,midfold.go,memory.go,worker.go,pgstore.go,server.go,contract_test.go,store_test.go};前端yk-tako-eino/web/src/{api.ts,chat.ts,App.vue};验收scripts/acceptance/taskboard_crash.sh+scripts/acceptance/expected.json(用例 8 登记为暂不断言);契约文档doc/19-v6/19v6-04-验收-curl.md;台账tmp/41-任务看板与人工审批/(本地,不入库)。 参照:doc/01、02、07(旧线看板,存档);doc/06(旧线三态守卫与 PII 打码,存档);doc/archive/old-line/specs/的 MAF 审批设计(冻结存档);doc/30(崩溃续跑底座);doc/40(响应信封与业务码表);doc/33(MCP 围栏)。 与 doc/16 的关系:不给总纲改排序,给 §5.1 第 1、2 项与 §2 表 #2/#3 行补一份已落地的方案真源(#7 行随 Loop A 一并不做)。 2026-10-28 追加(已落地 B5/B6):看板加run_tasks.skill_name列(doc/52 D32,B5)与「会话内跨 run 续做」读口(doc/52 D34,B6)——TaskList带上一场未完成行及说明、description语义升级为「这一步具体做什么」、写回执不带这一段;执行权按看板恢复(doc/52 D35,B6)。设计与验收口径见 §3.3、§5.1。 2026-11-06 追加(已落地,doc/64):看板加run_tasks.result列,TaskUpdate标completed时必须带 result,否则整笔拒写;TaskList/TaskGet/「上一场」段把结果带回模型眼前。字段、闸、放行口与渲染口径见 §5.1;台账在doc/log/2026-11-06-看板结果列/。
0. 为什么三件事捆成一份方案
背景:doc/16 §5.1 把「人工审批 + PII 脱敏」排为当前待做第 1 项(原话:agent 能写文件、能跑 bash,没有闸等于让租户数据裸奔),「v6 任务看板」排第 2 项;§2 表 #7 行还挂着一个 ⬜ 的「内存 checkpoint + interrupt 审批」。用户要求出一份结合现行代码状况的独立方案,本文就是。
先讲三个会真实发生的病灶故事:
病灶一(看板):用户发了条「把这三个接口改造成异步,顺便补测试」的长任务,run 跑了二十分钟。页面上只有一段段 tool_call 帧在滚,用户看不出整体进展——哪步做完了、卡在哪、还剩几件,全在模型脑子里。旧线的任务看板(doc/01)本来解决这个,但它的正本是进程内内存 Store(doc/01 §3:「进程退出即清空」),随 v1–v5 旧线一起删了,v6 至今空着。
病灶二(PII 与审批):租户 A 的 agent 跑 cat .env——bash 工具今天零守卫(bash.go:3-4 明文写着「不做危险命令表」),.env 里的厂商 API Key 原样进 tool_result 帧、进 mh(模型消息表)、进 runlog(历史真源),再被记忆抽取带进 memory_items 长期保存。多租户已经能区分人和组织(doc/28),但数据在 agent 工具链里是裸奔的。密钥之外,用户消息里的身份证号、手机号也一路原样喂给模型、抽进记忆。
病灶三(interrupt 审批):就算定出「危险命令要拦下来问人」的规则,v6 的 run 也只有三种活法:complete / error / stopped(worker.go 收尾三态)。引擎里没有任何「暂停等人」的生命周期——interrupted 存在,但那是崩溃后的读侧派生视图(server.go:864-872:status 仍 'running'、租约过期),语义是「执行者死了」,不是「挂起等人」。旧线用过 eino 的 compose.StatefulInterrupt + gob checkpoint(doc/06、doc/blog),v6 翻篇时明确不做 eino checkpoint 接入(doc/30 §15),这条技术路线没有随代码留下来。
三个病灶共用同一副地基:把 run 停在工具调用前、问人、按人的决定继续。PII 的「拒收/打码」要挂在同一处工具链上才能全覆盖;看板的「任务进度」挂在 PG 上之后才天然活得过崩溃续跑。分开做,等于三次重造同一套帧、端点、表和前端卡片。所以:一份方案,三个 loop(§6),人审回路只做一次。
端到端链路(每环可点名,机制在链路中的位置见 §3):
用户发消息 → POST /api/runs 起 run(会话闸:runs 行部分唯一索引)
→ worker 主循环 agent.Run(worker.go:620-774)
→ 模型决策 → tool_call 帧(AppendFrame 进 tk:runlive)
→ journalWrapHandler 先记意图(run_journal 表,intent 写失败不执行)
→ 审批闸 gateMW 判定:allow / deny / ask
deny → 解释文本当 tool_result 回给模型(不调工具、不打扰人)
ask → run_approvals 表落一行 + approval 帧 + 阻塞轮询该行
→ 人看帧/审批卡 → POST /api/approvals/:id/decide(PG CAS 一裁终裁)
→ 批准:真执行,结果照常回模型;拒绝:拒绝文本当 tool_result
→ PII 打码贴在真工具内侧:工具返回先打码再往外流(模型/mh/帧/runlog 全干净)
→ 模型继续或定稿 → terminal 帧 → EndRun 事务(mh + runlog 一笔落库)
→ 挂起期间进程死了:租约过期 → 派生 interrupted → 客户端 resume(doc/30 通路)
→ 重放 journal 时对到 run_approvals 行:pending → 重新挂起;approved → 补执行;rejected → 补拒绝文本
1. 名词准入(操作定义,后文不再重复解释)
- 人审回路:工具调用执行前的一道闸 + 一次等人。闸判 allow/deny/ask 三态;ask 时 run 挂起,人的决定回来后 run 继续。三态语义逐字继承 doc/06:allow 直接放行;deny 把解释性 string 当结果挡回给模型(不抛 error);ask 暂停问人。
- 审批行(run_approvals 表一行):一次 ask 的持久态。字段见 §5.1;状态机只有
pending → approved/rejected(外加终态 run 死亡后清扫的stale)。它是多副本下「人在另一个入口裁决、worker 在本进程等」的共享阵地——裁决不是进程间消息,是** UPDATE 这一行**。 - 挂起:worker goroutine 阻塞在审批轮询上(SELECT 该行,1–2s 间隔),run 不结束、租约照续、不烧 token、不消耗迭代数。与之相对的
interrupted是死了,挂起是活着在等。 - 裁决:人对一条审批行做出的 approve/reject。端点里用 PG 条件更新实现一裁终裁:
UPDATE run_approvals SET status=$2 WHERE id=$1 AND status='pending' RETURNING——影响 0 行就是被别人裁过了,回 409。没有「第二个副本一起判」的窗口。 - 打码:正则命中后把敏感串换成保留头尾的掩码(旧线口径:头尾各 4 位;证件类中间位全掩)。打码不是删除原文的唯一策略——三处挂载点策略不同,见 §3.2。
- tasktracker:任务看板在 v6 的统称(命名已裁定,doc/XX handoff,仓库零落点)。对外是 TaskCreate/TaskUpdate/TaskList/TaskGet 四把工具,状态词表
pending/in_progress/completed/deleted。 - checkpoint(v6 语义):本文不重建旧线意义的 eino gob checkpoint。v6 的等价物已经存在:mh(
run_model_messages,模型输入唯一读源)+ run_journal(意图账本)+ runs 行的租约/令牌。interrupt 审批新增的持久态只有 run_approvals 一行。理由见 §3.1 第四段。
2. 现状锚点(方案就建立在这些事实上)
结合现行代码(2026-10-22,main @ 7ef004e)逐条锚定:
- 工具链零守卫。一手工具池在
worker.go:192-245逐个 append,执行链 = ADKToolsNode直执行;唯一的包装是wrapToolErrors(错误回注)和journalWrapHandler(记账)。bash.go:3-4明文不做危险命令表。tools.go:47留了一句注释「interrupt 类错误原样透传,不挡未来 HITL」——eino 的错误通道是预留未用的出口。 - middleware 挂点现成。
journalWrapHandler就是adk.ChatModelAgentMiddleware,覆写WrapInvokableToolCall(journal.go:55-65),在 handler 链最内位。审批闸和 PII 打码用同一个钩子类再包两层即可。顺序即语义(doc/blog §3:handlers[0] 最外层),本方案的执行序:gate(外)→ journal(中,既有)→ pii(内,贴真工具)。 - 帧只有 7 种。
contract_test.go:148-158用生产代码字面量钉死词表:start/delta/tool_call/tool_result/usage/terminal/resume。写帧唯一口AppendFrame(Redis RPUSH 进tk:runlive),轮询与 SSE 两条运输都原样透传 kind——加第 8、9 种 kind 传输层无障碍,但词表测试会立刻红,这是显式的同步点,不是隐患。 - journal 意图先行,这就是挂起现场的半边。
journal.go:79-121:intent 写失败不执行工具;result 写失败 run 走 error。崩溃恢复replayJournal(journal.go:141-255)按 call id 归组重放,缺结果的调用回注固定文本interruptedResultText(at-most-once,不重跑)。审批挂起天然借这层:挂起时 intent 已在账本里,进程死了重放也对得上。 - interrupted 是派生视图,不是存储状态(doc/30 §2.3 的选择原文):runs 行保持
status='running'+ 租约过期,读侧派生。部分唯一索引one_live_run_per_session不放闸。本方案的挂起沿用同一哲学:不加第四种存储状态,挂起 = running + 存在 pending 审批行(读侧可派生「等审批」)。 - 恢复通路现成且已验收。
POST /api/runs/:id/resume(server.go:579-645):claim 用 PGFOR UPDATECAS、epoch+1、三个 409(112102/112103/112104);seedResume丢 runlive 重建;RunResume与 Run 共用主体(worker.go:428-430)。审批恢复是它的一个分支,不新造通路。 - PII 是彻底空白。记忆条目
MemoryItem(memory.go:65-77)只有 kind 词表(fact/preference/decision/episode),无敏感分级;抽取只有提示词劝阻「不抽密钥」(memory.go抽取提示词),无程序拦截;写入校验只查隐形字符与伪造块。全仓唯一带 mask 字样的是maskSecrets(product_store.go:874,租户配置密钥出 API 打***),与 PII 无关。bash.go:24-26的 env 白名单是唯一「密钥不进历史」的现役机制。 - 旧线的两份设计档案还在。doc/06 记录了三态守卫(allow/deny/ask)、命令/文件守卫规则(
.env/.git/.sshdeny、工作区外 ask)、7 条密钥正则打码(sk-proj-/AKIA/AIza等,头尾各 4 位)、两个挂载点;doc/archive/old-line/specs/的 MAF 设计记录了消息级请求-回执协议(框架替你把调用换成审批请求,人回执后按 call id 重入)。两者代码都已出仓,本文只继承结论,不继承实现。 - eino StatefulInterrupt 这次不用。旧线博客(doc/blog)记过它的真实成本:信号树、地址链、gob 序列化全链、文档与实现互斥的坑。更硬的理由是 v6 的 run 循环是 worker 直驱动(
agent.Run单调用 + 事件消费),没有可重入的执行图,StatefulInterrupt 的恢复语义(checkpoint + 地址重入)无用武之地;而「阻塞在工具包装里 + 决定落 PG 行」在多副本目标栈下天然正确——gob checkpoint 是进程内字节,DB 行是共享阵地。 - tasktracker 是空位。名字已裁定(doc/XX),代码零落点;旧方案的对外协议(四工具、四状态、约束写 tool description、明确不做三件)是重建时唯一的体内参照。
3. 总设计
3.1 人审回路(底座,只做一次)
闸的判定(纯函数,金样单测钉死):
gate(toolName, argsJSON, workspaceCtx) → allow | deny(理由) | ask(理由)
- deny 规则(硬拦,解释文本当 tool_result 回模型,不问人):写类文件工具目标命中
.env/.git/.ssh/id_rsa*;写系统目录(/etc、/usr、根);bash 命中危险命令正则一级表(rm -rf /、mkfs、dd of=/dev/sd*、fork bomb、chmod -R 777 /等,逐条金样)。继承 doc/06 口径:「能问的不拒,该拒的不问」,全 ask 会把审批弹窗变成噪音。 - ask 规则(挂起问人):写类文件工具目标在工作区外;MCP 工具(
mcp__*前缀)一律 ask——第三方 server 不可信,且它们本就走 deferred 档、调用低频,噪音可接受。- bash 不再「一律 ask」(2026-10-22 用户拍板):bash 的作用范围由沙箱围栏硬挡,不是问人。实测(
sandbox-exec的 seatbelt profile,sandbox.go):读/etc/hosts/~/.ssh/~/.zshrc与写工作区外全部 Operation not permitted;工作区内读写正常。→ 越界 = 禁止,模型自己改路(bash 的结果里会附一句人话提示,见bash.go的「沙箱围栏」提示)。 - 因此 A 拍(人审回路)可以缩到最小:bash 不再需要「一律 ask」,人审回路只剩 MCP 工具与写类工具越界两类需问的场景——若这两类也按范围/白名单硬挡(如 MCP 只允许白名单 server),整条人审回路都可不做,本文的 A 拍整个取消(见 §8 开放问题 1)。
- bash 不再「一律 ask」(2026-10-22 用户拍板):bash 的作用范围由沙箱围栏硬挡,不是问人。实测(
- allow:其余(读类文件工具在工作区内、memory、search_history、get_time 等)。
- 策略表一期硬编码在
gate.go+ 金样测试;租户级可配(挂 tenant_settings)登记为后续拍,不做进 v1。
ask 的三拍(每步四问齐全):
- 落行:
INSERT run_approvals(tenant_id/run_id/session_id/tool_name/args/reason/status=pending)。不做会怎样:进程死了解释不清在等什么。 - 发帧:
AppendFrame一条kind=approval的帧(字段映射见 §5.2)。不做会怎样:前端不知道在等人,页面死寂。 - 阻塞等:goroutine 内 1–2s 轮询该行,直到
status != pending;全程尊重 ctx(stopRun 能打断,run 走 stopped,行留 pending,裁决端点后补 409)。批准 → 调真 endpoint(原参数,不换);拒绝 → 返回拒绝文案(「用户拒绝了这次调用。不要重试相同命令;需要的话先跟用户商量替代方案。」语义继承 doc/06)。
挂起现场 = 账本 intent + 审批行,不新造 checkpoint。挂起期间 worker 活着:watchdog 照续租约(worker.go:519-526),帧流静止,agent loop 不消耗迭代数。这解决什么:一次 ask 不需要把内存里的消息列表、循环进度序列化到任何地方——模型输入的下一次装配本来就从 mh 全序 + 账本重放出发(prepareInput),中断 run 的行本就未进 mh(EndRun 才落),journal 已经记了 intent。没这层会怎样:要么退回旧线 gob checkpoint(多副本下是进程内字节,裁决端点在别的副本够不着),要么挂起期间进程一死现场全丢。
崩溃兼容是 journal 重放的一个分支。挂起中进程死 → 租约过期 → 派生 interrupted(既有);客户端 resume(既有 claim CAS)→ replayJournal 重放到这条 intent 时查 run_approvals:
| 账本 intent 对到的审批行 | 重放行为(对齐 doc/30 两个恢复分支的新第三分支) |
|---|---|
| 无行 | 维持现状:interruptedResultText 回注,不重跑(at-most-once) |
pending |
重新挂起:重发 approval 帧(seedResume 已清空 runlive,天然幂等),继续轮询 |
approved |
补执行:此刻真调 endpoint,结果落账本 |
rejected |
拒绝文案回注 |
没这个分支会怎样:批准了的调用在 resume 后被当成「结果未知」跳过——人白批了,且模型拿到的文本与批准语义矛盾。resumeCount 语义不变:挂起不消耗次数(lease_epoch 不动),只有崩溃接管才 +1(doc/30 既有语义)。
3.2 PII 脱敏(三个挂载点,三种策略)
PII 在本方案指两类:密钥类(API Key、token、密码——旧线 7 条正则口径,直接继承并扩到 AKIA/AIza/hf_/sk- 家族与赋值形式)与证件类(身份证号、手机号、邮箱、银行卡)。打码掩码规则:密钥类头尾各 4 位(旧线口径);证件类保留可人工核对的头尾、掩掉可直接利用的中段——逐条金样钉死。
| 挂载点 | 位置(执行序) | 策略 | 没它会怎样 |
|---|---|---|---|
| ① 工具返回 | 工具统一出口 wrapToolErrors(tools.go:49)——自家工具 / media / pdf / tool_search / MCP 都走它,成功与错误两路都打码 |
打码后返回:模型、mh、runlog、tool_result 帧全部只见过干净文本(打码即焚,原文不进任何持久层) | cat .env 的密钥落帧落库,被记忆抽走,多租户数据裸奔 |
| ② 模型输入装配 | 模型输入的唯一转换口 toSchemaMessages(midfold.go:373)——首轮 / 折叠 / 救援三条路一次覆盖 |
喂模型前打码:mh/runlog 保留原文(页面要显示用户原话),模型侧只见掩码 | 用户消息里的身份证号被模型复述进终稿、带进记忆 |
| ③ 记忆抽取入库 | memory.go 抽取管线 parseExtraction 之后、入库之前 |
密钥类拒收(整条丢弃,提示词劝阻变成程序拦截);证件类打码后入库(记忆要复用,拒收会把可用信息一起扔掉) | memory_items 慢慢攒成 PII 库,召回一次带一次 |
三个点共用同一个扫描函数(pii.go 纯函数 + 金样单测 + dev 探针端点)。①与②策略不同是刻意的:工具输出夹带的密钥没有「用户想在页面上看到原文」的需求,焚掉最干净;用户消息原文要留在 runlog 里给页面回放,模型侧出口打码就足够。③的拒收/打码分档是开放问题第 2 条。
⚠️ 挂载点落位是踩坑后改的(2026-10-23 落地时)——本节原写的是「① 贴真工具内侧、② prepareInput 出口」,两处都不能用:
| 原方案 | 为什么不能用 | 改成的 |
|---|---|---|
| ① 贴真工具内侧(每把工具各包一层) | 只覆盖第一方工具,MCP 工具的结果会漏——MCP 恰是最不可信的一路 | 挂 wrapToolErrors(所有工具结果的唯一必经之路) |
② 挂 prepareInput |
只管首轮;折叠的原料是 mh 原文(user 行按设计存原文给页面显示)→ 折叠一次 PII 就复活(短对话安全、长对话漏,越重要的对话越漏) | 挂 toSchemaMessages(模型输入的唯一转换口,三条路一次覆盖) |
本期不做:落库加密(at-rest)、向量库侧的 PII、对外 API 返回体的 PII 审查(记忆端点本来就是 dev 观测口)。这些是数据安全另案,不是 agent 工具链的闸。
3.3 任务看板(tasktracker)
对外协议逐字继承 doc/01(旧线被验证过的部分,不重新发明):
- 四把工具:
TaskCreate(subject, description?, activeForm?) → taskId、TaskUpdate(taskId, status?, ...)、TaskList()、TaskGet(taskId)。 - 状态词表:
pending → in_progress → completed,不再需要时deleted(TaskList 不列出)。 - 约束写在 tool description,不写状态机:≥3 步或用户列了多件事才建表;一步任务不建;动手前标 in_progress,同时尽量一条;做完立刻 completed;测试红/做了一半/未解报错不准 completed;卡住就 Create 一条 blocker。
- 每个工具输出 = 操作回执 + 当前看板紧凑视图 + 催更块(模型的眼睛始终能自校准)。
- Plan 层不重建:doc/01 既定——Plan 是给人审的文档,v1 没有人审 gate、没有 ExitPlanMode 式 interrupt,仅以提示词约定的口述方案形态存在。看板使用约定(什么时候建表)静态拼进系统提示——doc/blog 的同款答案:「提示词和工具,一个都不能少」。
- 明确不做三件(继承 doc/01 §6):Action↔︎Task 双射、模型漏 Update 时自动勾选、Graph 拓扑强制执行顺序。「要硬进度:收窄执行模型,不要在开放 ReAct 上做语义对齐。」
存储改掉旧线的死因:正本从「进程内内存 Store + eino session 镜像」(doc/01 §3,进程退出即清空)改成 PG 表 run_tasks(字段见 §5.1)。每个操作四问:做什么——工具 handler 直写一行;不做的后果——回到进程内存就是回到「崩溃即丢」;输入——TaskCreate/TaskUpdate 的参数(handler 拿到 args);输出——该行 + 回执文本。崩溃续跑兼容性免费获得:已执行的 TaskCreate 行在 PG 里活着,resume 后 TaskList 读到的就是真相;被中断未执行的调用按 doc/30 默认不回放,模型从 TaskList 自校准(这正是旧线「回执带紧凑视图」的跨进程版)。
注入方式从旧线的动态 middleware 改为静态注册:v6 没有「只在有看板语义下才有意义」的状态——每个 run 都是干活 run。四把工具直接 append 进一手池(worker.go:192-245 那段),子代理通过既有的 tools:/exclude_tools: 四态自行裁剪(对齐 doc/26 四态表,金样测试 TestShippedAgentSpecToolGuards 需要同步——出厂规格的 effective 名单会多四把工具,金样行逐条更新)。
会话内跨 run 续做(2026-10-28 落地,doc/52 D34,B6):现在的读口是按 run 的——ListTasks/GetTask 都拿 run_id 查(tasktools.go:132、:141,taskBox 在 worker.go:596 按 (sessionID, runID) 建)。用户发下一条消息就是新 run,于是上一场的看板在新 run 里完全看不见,而用户常说的是「第 3 步改一下」。补法:
TaskList除当前 run 的看板,再带一段「上一场」:取本会话里最近一个(排除当前 run)有任务的run_id,只列pending/in_progress的行,每行带description;上一场全完成时只给一行提示、不带说明。- 写操作回执不带这一段:
taskReceipt(tasktools.go:173)仍只渲染当前 run——否则每建/改一条任务就把上一场的说明重付一遍。只有显式调TaskList才有。 description的语义因此升级:从「可选补充说明」(tasktools.go:222)变成「这一步具体做什么;下一场靠它续上」。这是 schema 文案 + 提示词约定,靠模型自觉、不是结构闸——模型没写细时的兜底是重读 doc/52 的技能正文。- 用户口中的「第 N 步」是页面上看到的
task_no(#%d [%s] %s,tasktools.go:156),不是技能正文的步骤编号,两者不保证对齐。
帧:tool_result 文本始终带紧凑视图(模型的眼睛,零契约成本);另发 kind=task 帧给前端结构化渲染看板(契约 +1,见 §5.2)。没 task 帧会怎样:前端要解析自然语言文本才能画看板,换个提示词措辞就渲染错——帧是结构,文本是给人和模型的。
4. 顺序即语义:handler 链与装配点
一手池工具
└─ wrapToolErrors(既有,错误回注)
└─ gateMW(新增,最外):allow 透传 / deny 返回解释 / ask 三拍
└─ journalWrapHandler(既有):intent 记账——挂起前落账,崩溃重放对得上
└─ piiMW(新增,贴真工具):返回路径打码
└─ 真工具
- gate 在 journal 外:deny 的调用从未发生,不该有 intent;ask 的调用intent 必须先落(挂起现场的半边)。
- pii 在 journal 内、贴真工具:打码发生在结果返程上,意图与结果的分工不被打乱。
- MCP 工具与委派工具走同一个
WrapInvokableToolCall链(mcp.go:274、agents.go:507-509都在 handler 覆盖范围内)——审批与打码对 MCP/子代理调用天然生效,帧进当前 run 的 runlive。v1 验收只覆盖主代理;子代理调用触发审批时帧出现在父 run 帧面,属预期行为(登记为已知形态,不单独立拍)。
5. 契约
5.1 新表(autoMigrate 从 struct,沿用 pgstore.go:488-498 模式)
run_approvals(多副本阵地,闸的「等问题」):
| 列 | 类型 | 说明 |
|---|---|---|
| id | string ULID ap_ |
主键;同时进 approval 帧的 messageId 字段 |
| tenant_id / workspace | string | 可见性过滤键(对齐全部 PG 表的 scope 口径) |
| run_id / session_id | string | 回属;resume 重放按 run_id 对账 |
| tool_name / args / reason | string | 问人内容:工具名、原始参数 JSON、命中规则的人话 |
| status | string | pending → approved/rejected;run 终态后清扫器收 stale(挂 doc/37 同一轮) |
| decided_by / comment / created_at / decided_at | — | 审计面;comment 为可选的人填理由 |
run_tasks(看板正本):
| 列 | 类型 | 说明 |
|---|---|---|
| id | string ULID tk_ |
主键 |
| tenant_id / run_id | string | 一场 run 一块看板;TaskList 按 run_id 查。另有按会话的续做读(tenant_id + session_id,索引现成:index:run_tasks_scope),见 §3.3 与下方 D34 补记 |
| task_no | int | run 内自增,TaskUpdate 的 taskId(对齐旧线「taskId 只寻址看板行」) |
| subject / description / active_form | string | 逐字继承 doc/01 字段语义;description 升级为「这一步具体做什么」(doc/52 D34,2026-10-28) |
| result | string | 这一步的产出(数字、结论、路径、跑过的命令;2026-11-06,doc/64)。not null default '';标 completed 时必填(写闸在 UpdateTask),入库前截到 300 字 |
| status | string | pending/in_progress/completed/deleted |
| created_at / updated_at | time | — |
run_tasks 行的生命周期(2026-10-27 补记):
- 完成不删:
TaskUpdate把状态改成completed只改status列;deleted也只是个状态值,行还在。全仓DELETE FROM语句里没有一条指向run_tasks(2026-10-27 实读)。 - 删除单位是会话,不是 run:行带
session_id,与run_model_messages同一条生命周期——run 结束留着,项目删除也留着;会话软删(doc/37 §5.3)当时仍不动表,物理清除归清扫器的会话窗口(doc/37 §5.5)。 - 今天的缺口:
sweepDeletedSessionBatch(archive_sweep.go:190)只清run_model_messages;run_tasks与 doc/47 的run_questions都没进清单。两张表都带session_id,补法是同一批各加一条按会话过滤的DELETE+ 单测;要单独一拍,不在别的方案里顺手做。
run_tasks 加 skill_name 列(2026-10-28 登记,doc/52 D32;B5 已落地 2026-10-28):
- 为什么加:doc/52 的技能执行模型是「manager 自己读正文、自己执行」——正文里的步骤展开成看板任务,任务才是要完成的东西(正文是说明书,可折;任务在 PG 表里,不参与折叠)。于是需要回答「哪几条任务属于哪个技能」。
- 列:
skill_name string(gorm:"not null;default:''";空串 = 与技能无关的普通任务)。唯一写入点是TaskCreate:按本 run 最近一次成功use_skill(skill 盒子的末尾项)盖戳。程序不代建任务——read_skill不写盒子,use_skill之后没TaskCreate就一行都不多;「load_skill成功自动建兜底任务」的旧口径作废(doc/52 D32)。 - 两个读取口:①
taskBoardView每行带「(技能:名字)」,TaskList、写操作回执、kind=task帧三处同源;TaskGet详情多一行「技能:名字」。②kind=task帧另有顶层skillName字段(omitempty)= 触发这次写入的那一行所属技能(UpdatedAt最新、同刻取task_no大);逐行归属以text为准。第三个读者是 run 装配——按看板里已有的skill_name把技能根补回 bash 盒子(doc/52 D35,B6 拍)。compact 不查这张表——「技能 → 任务号范围」的映射由看板回答,压缩管线保持纯函数(doc/52 D31,选项乙)。 - 为什么不用
Subject前缀编码:前缀脆、且与「步骤 3/5」这类序号挤在一起;加列是可查询的事实。 - 落地证据(2026-10-28 隔离引擎 8943,真跑一场):
use_skill(demo)→ 两条TaskCreate→kind=task帧{"eventOffset":12,"kind":"task","agent":"","model":"deepseek/deepseek-flash","name":"TaskCreate","skillName":"demo","text":"看板:\n#1 [pending] 读演示技能的资源清单(技能:demo)\n#2 [pending] 用演示技能跑一次检查(技能:demo)\n(还有 2 项没完成:…)"};同场再use_skill(other)不建任务 →run_tasks仍两行、skill_name都是demo;新 run 只read_skill后TaskCreate→ 帧不带skillName、行skill_name为空。
TaskList 的会话续做读(2026-10-28 落地,doc/52 D34,B6):
查什么:
SELECT run_id FROM run_tasks WHERE tenant_id = ? AND session_id = ? AND run_id <> ? ORDER BY created_at DESC LIMIT 1,再取该 run 的pending/in_progress行。走(tenant_id, session_id)复合索引(tasktools.go:32-35),不加新列、不加新表。为什么是「最近一个有任务的」,不是「最近一个 run」:最新的 run 就是当前这场,看板还没建行;取它等于取空。要的是用户上一场干到一半的那块板。
为什么只列未完成:全完成时用户说的「改第 3 步」是重做,不是续做——这时 manager 该重读技能正文重新规划,列已完成的说明只会多付 token。所以全完成只回一行提示。
返回形状:仍是文本(与现有看板视图一致),当前看板在前、
上一场(r_…)段在后;description只在「上一场」段渲染,当前场的行仍只显示#序号 [状态] 主题——这是为了不让每张回执都变胖。风险登记:
description写得细不细由模型决定,写不细就没有可续的内容;兜底是 doc/52 的重读正文(技能正文永远在盘上)。落地(2026-10-28,B6):
PreviousBoardRun(同租户同会话最近一场、status <> deleted、按created_at倒序)→ListOpenTasks(pending/in_progress、按task_no)→previousBoardView渲染(上一场(r_…)还有 N 项没完成:+#N [status] subject+说明:description;全完成只一行上一场(r_…)已全部完成)。只在TaskList的闭包里拼(taskTenantOf(ctx) != ""才查),写回执与kind=task帧走原taskBoardView,签名未动;查询失败只记日志、不影响看板主段。工具描述与taskBoardPrompt同步写「description 写这一步具体做什么」。活体见 doc/52 B6 段:run A 建 3 条完成 #1 → run B 的TaskList出现上一场 #2/#3 及说明、写回执不带,且不调use_skill直接跑脚本成功;run C 回「已全部完成」;只 use 不建任务的 run D → run E 不给执行权、无「上一场」。
run_tasks 加 result 列与「标完成必须带 result」(2026-11-06 落地,doc/64):
- 病灶:第 2 步跑统计脚本输出三万 token、中间有
p95 = 1.8s;模型用它写了结论、把任务标 completed,继续做后面几步。上下文超窗后 mid-run 折叠把那次工具往返折掉,摘要器看到的原料已被截到 2000 字,关键数字没进「重要事实」;模型对第 2 步失忆,要么编一个数,要么重跑脚本。跨 run 更常见:TaskList只回#2 [completed] 统计延迟分布,没有任何产出,要看数只能重跑。数据本身没丢(mh 原文行、runlog、.tako/落盘文件都在),丢的是模型眼前那一份。 - 列:
result string(gorm:"not null;default:''")= 这一步的产出(关键数字、结论、产物路径、跑过的命令)。入库前truncateRunes(result, 300),超长截断并标原长(…〔截断:原 N 字符〕),不拒写——拒写会制造第二次涨停。 - 闸:
TaskUpdate把某行标completed时,effectiveResult= 本次传入 || 行上已有的结果;为空 → 返回哨兵ErrTaskResultRequired,整笔回滚(状态与 result 都不写,其它字段也不写)。已经有结果的行再改主题/状态不会被二次拦。闸只管「有没有字」不管「有没有用」:「已完成」三个字能过闸,质量靠 schema 文案与系统提示约束。 - 拒写文本(模型唯一能看见的信号;走
wrapToolErrors,toolErrorText对已带「错误:」的消息不重复加前缀):错误:标 completed 必须带 result——写这一步的产出(关键数字、结论、产物路径、跑过的命令),不是「已完成」「已修复」。 - 放行口:同 run 第 3 次因缺结果被拒起放行,
status落completed、result落固定串(未记录:连续 3 次没写结果);回执不追加任何催促。计数在taskBox(随 run 死,同 noteBox 先例)。没有它,模型固执时会在同一个调用上无限撞墙。 - 读者(写了没人读等于没写):①
TaskList用taskListView:completed 且有结果的行多一行结果:<前 100 字>;②TaskGet多一行结果:<全文,已 cap 300>;③ 「上一场」段加「已完成的结果」子段,一条一行前 100 字(ListCompletedResults)——跨 run 续做唯一的入口;④ 写回执与kind=task帧不变(沿用 D34 取舍:不让每张回执重付所有历史结果);⑤ 前端不显示 result(另拍)。 - 不做的:不自动回填旧行、不给「已完成但空结果」打标、不生成任何「回去补」的措辞(这类措辞是唯一能诱发重跑的东西);不改
TaskCreate(建任务时还没有结果);不改帧词表、expected.json与前端。 - 边界与证据:旧数据(本方案前完成的行)
result为空,不产生任何回补提示。机器证据在tasktools_test.go:taskResultGate判定金样、拒绝后状态与结果都没动、通过后两列一起写、350 字截断、taskListView与上一场段金样。活体(隔离引擎 8943):探针POST /api/dev/task-check已按转正点收成只读action=list,钉住视图字节;真跑一场时模型收到错误:标 completed 必须带 result…后没有当场补写、转而问「要不要带上 result 重新标一次」——这条行为断言不判红(模型行为不稳,不进expected.json)。
5.2 帧词表:7 → 9
contract_test.go:148-158 词表测试同步改(这是快闸显式同步点,红即提醒)。新帧复用现有 Frame 字段,不加列:
| kind | name | args | text | messageId | 语义 |
|---|---|---|---|---|---|
approval |
工具名 | 原始参数 JSON | 命中规则的人话(问什么) | 审批行 id | run 在等这条行的裁决 |
task |
工具名(TaskCreate/TaskUpdate) | 参数 JSON | 看板紧凑视图(当前全量;属于技能的行带「(技能:名字)」,doc/52 B5) | — | 看板结构态,前端据此渲染 |
task 帧另带顶层 skillName(omitempty)= 触发这次写入的那一行所属技能;空串省略(doc/52 B5,2026-10-28 落地)。
SSE 与轮询同真源透传(server.go:978 原样透传,零改动);前端 chat.ts:243-249 的分派加两个分支。
5.3 端点(信封走 doc/40;全部新端点,不动已验收端点的字节)
| 端点 | 契约(成功体在 data) |
失败码(提议;新增 115 审批段,施工拍同步在 doc/40 §4.2 补行) |
|---|---|---|
GET /api/runs/:id/approvals?status=pending |
[{approvalId,runId,toolName,args,reason,status,createdAt}] |
404 112002(run 不在) |
POST /api/approvals/:id/decide body {decision:"approve"|"reject",comment?} |
{approvalId,status} |
404 115002;409 115101(已裁决);403(非本会话属主,v1 仅属主可裁,对齐单场删除口径) |
POST /api/dev/seed-approval(仅 -dev) |
造一条 pending 行 | — |
POST /api/dev/gate-check body {tool,args} |
{verdict,reason} |
— |
POST /api/dev/pii-check body {text} |
{masked,hits:[{kind,span}]} |
— |
挂起期间「在等审批」的可见性不改 GET /api/runs/:id 的响应字节:前端 reconcile 时查 approvals?status=pending(PG 是真源,刷新/换窗口都不丢;长挂起不依赖 runlive 的 TTL)。这是刻意对齐 doc/30「读侧派生、不动存储状态」的哲学。
5.4 记忆端点与 dev 观测口
PII 拍的活体验收走 doc/29 已就位的记忆 dev 观测口(端点只读、dev 面);不新增产品面端点。
6. Loop 拆分(点头后逐拍施工;每拍先交 todos.md)
顺序 A(人审回路)→ B(PII)→ C(看板):A 是 doc/16 §5.1 第 1 项的硬项主体;B 的两个工具链挂载点贴着 A 的链,顺手全覆盖;C 最独立放最后。B1 是独立纯函数拍,可与 A1 并行。每拍粒度目标 ≤80 行 diff;每拍「怎么验收」第一行都是打在一个跑着的东西上(硬闸门)。
Loop A · 人审回路 —— 2026-10-22 整条不做(留档备查)
为什么不做:bash 的越界由沙箱围栏硬挡(实测:越界读/写全被沙箱拒绝),MCP 的越界也进了围栏 (围栏根 = 该租户目录,doc/33)→ 没有需要「挂起问人」的场景。真要人点头的场景只剩「MCP server 自己要往租户目录外写」——那已经在围栏里被拒了(启动前置检查就说清「依赖要预装在租户目录里」)。 下面 A1–A7 的设计(
run_approvals表 / 挂起 / 裁决端点 / 审批卡 / resume 第三分支)保留在案, 将来若出现真需要人拍板的场景(例如「删除项目」这种不可逆动作),可从这里直接取。
| 拍 | 改什么 | 怎么验收(curl 第一) | 回答什么 |
|---|---|---|---|
| A1 | run_approvals 表 + decide/list 端点 + seed-approval 造数口 |
seed-approval 造行 → decide 批 → 行 approved;再 decide 拿 409 115101;decide 不存在的 id 拿 404 115002 |
裁决的 CAS 一裁终裁成立 |
| A2 | gate.go 纯函数(deny 表 + ask 表) |
gate-check {"tool":"bash","args":{"command":"ls"}} → {"verdict":"ask","reason":"bash 一律问人"};rm -rf / → deny;read_text_file 工作区内 → allow |
三态判定与规则表钉死 |
| A3 | 活体:起 run 让模型读 .env 路径 → 帧里 tool_result 是解释文本、工具未执行(runlog 无该行) |
硬拦不进人、不打扰人 | |
| A4 | 活体:发「删掉 /tmp/tako-a.txt」→ 帧见 kind=approval;run 仍 running、帧流静止 → decide approve → run complete 且 tool_result 见执行结果;再来一次 decide reject → 拒绝文本进帧、run complete |
挂起-裁决-继续全链路 | |
| A5 | 活体:挂起中 kill -9 引擎 → GET /api/runs/:id 派生 interrupted → POST /resume(202)→ approval 帧重发 → decide → run complete |
挂起现场活得过进程死亡 | |
| A6 | 浏览器:A4 场景卡片出现,点批准后帧流继续 | 人在页面上能裁 | |
| A7 | go test ./internal/runengine 绿 + assert_contract.py 绿 + check-expected.sh 绿 |
两台机器都钉住新契约 |
Loop B · PII 脱敏
| 拍 | 改什么 | 怎么验收 | 回答什么 |
|---|---|---|---|
| B1 | pii.go 扫描纯函数(密钥 7 条继承 + 证件类)+ pii-check 探针 + 金样单测 |
pii-check {"text":"key=sk-proj-AbCdEfGhIjKlMnOp…"} → masked 保留头尾各 4 位;身份证号/手机号/邮箱/银行卡逐条金样 |
打码规则机器钉死 |
| B2 | 挂载①工具返回 + ②装配出口(piiMW 贴真工具;prepareInput 出口打码) | 单测金样(装配函数输入含 PIi、输出无);活体 smoke:发含假证件号消息 run 正常 complete(「模型不复述」类断言登记 declared_not_asserted) |
模型侧全程不见明文 |
| B3 | 挂载③记忆抽取(密钥拒收、证件打码入库) | 活体:发「我的身份证号是 110101…,请记住」→ 抽取后记忆 dev 观测口读到打码后条目;密钥类断言:构造夹带 sk- 的原文 → 该条不入库 |
记忆库不攒 PII |
Loop C · 任务看板
| 拍 | 改什么 | 怎么验收 | 回答什么 |
|---|---|---|---|
| C1 | run_tasks 表 + 四工具静态注册 + 回执文本(操作回执+紧凑视图+催更块)+ 系统提示约定 |
活体:发「三步任务:…」→ 帧里 TaskCreate 多次、tool_result 文本含紧凑视图;TaskUpdate 状态翻转后 TaskList 文本同步 |
模型有了进度账本 |
| C2 | task 帧 + 前端看板渲染 + 词表测试/expected 登记 |
浏览器:看板随帧渲染,状态色随 TaskUpdate 变;快闸绿 | 人看得到进度 |
| C3 | resume 兼容验证 + 金样同步(TestShippedAgentSpecToolGuards 有效名单 +4)+ 收口(test/vet/活体) |
活体:run 中 kill -9 → resume → TaskList 行仍在、视图连续;go test + assert_contract.py 绿 |
看板活得过崩溃 |
脚手架与转正:三个 dev 探针端点(seed-approval/gate-check/pii-check)是脚手架,转正点 = 对应 Loop 的活体验收通过后改为只读诊断口(对齐 doc/37 clean-sweep 探针先例);不登记转正点的脚手架会永远留在代码里。
7. 明确不做(本期)
- 不做 eino checkpoint / gob 快照:v6 已有等价物(mh + journal + 租约),doc/30 §15 裁断沿用。interrupt 审批的现场 = 账本 intent + 审批行。
- 不做 Plan 层人审 gate:doc/01 既定,Plan 只是口述方案。
- 不做看板三件:Action↔︎Task 双射、自动勾选、拓扑强制(doc/01 §6)。
- 不做 server 巡检自动恢复/自动裁决:挂起期间恢复触发沿用 doc/30 A6 裁断——客户端触发;用户不在场 run 一直挂着,是同一取舍的直接后果,不是缺陷。
- 不做 at-rest 加密、对外 API 的 PII 审查:数据安全另案。
- 不做沙箱:命令守卫是正则闸,不是隔离(doc/06 §8 自留口径)。围栏本身是既有的(
sandbox-exec的 seatbelt profile,写只在工作区根内、读是工作区根 + 系统路径白名单,2026-10-22 实测)——不做的是「再加一层目录级沙箱」。 - 运行中插话 steer 不做(doc/16 §5 纪律):挂起期间会话闸仍占着(running),与忙时拒绝同语义。
- 子代理半截重接不做(doc/39 v4):审批挂起不改变子代理的崩溃语义。
8. 开放问题(点头时一起拍)
bash 一律 ask 还是命中才 ask→ 已定(2026-10-22 用户拍板):bash 按范围判定,越界由沙箱硬挡(禁止),不问人(实测越界读/写全被拒)。MCP 工具仍一律 ask(第三方 server 不可信、调用低频)。→ 若 MCP 也按白名单硬挡,Loop A 整条可不做(待拍,见 §8 开放问题 7)。- 记忆 PII 分档:荐密钥类拒收、证件类打码入库。备选 = 全部拒收(保守但丢可用信息)/全部打码(密钥进库不可接受)。
- 挂起时长上限:荐无上限、lease 照续(人可能离开几小时)。备选 = N 小时未裁决自动拒绝(需新增超时清扫,复杂度 +1)。
- 码段:提议新增
115审批段(§5.3),与 doc/40 §4「前两位是模块」口径一致。 - Loop 顺序 A→B→C(B1 可与 A1 并行)。
MCP 工具要不要也按白名单硬挡→ 已定(2026-10-22,用户拍板「选 b」):MCP 进程也进 seatbelt 围栏,围栏根 = 该租户的存储根 → 它只能读写这个租户的文件;平台的系统 MCP 不围栏;没有沙箱 → 拒绝启动(fail closed)。连带 Loop A 整条不做(见 §6 Loop A 头注)。Loop A 做不做→ 已定:不做。本方案 = **B(PII 脱敏)+ C(任务看板)**两拍。连带 doc/16 的 #7(内存 checkpoint + interrupt 审批)一并退役。
9. 所以这解决了什么
doc/16 的地基硬项 #2(审批闸)从「裸奔」变成三态闸 + PG 裁决阵地,多副本下成立;#3(任务看板)从进程内存空位变成 PG 正本 + 四工具,活得过崩溃;#7(checkpoint + interrupt 审批)以 v6 自己的方式补上——不重建 gob checkpoint,用 journal 账本 + 审批行实现「暂停问人、死了能续」。三件事一份方案,人审回路只做一次,帧、端点、表、前端卡各加一层。点头后按 §6 拆 todos.md 开工。