完善口径管理、主动调查与后台任务,修复通用问题

- 完善口径编辑、只读试运行、统一质量验证与执行语义指纹
- 增加可执行指标约束、有预算的主动调查和过程评测
- 提取发布检查、证据读取与起草服务,支持任务停止、重试和检查点恢复
- 增加版本传递影响分析,修复并发覆盖、敏感值遮罩、异常评分及页面状态问题
- 修复 SQLite 复合查询追溯和 microVM 可选依赖缺失处理
- 纳入当前设计文档及部署配置调整

验证:相关主回归 3822 项通过,4 项跳过、8 项预期失败;补充回归通过。
前端构建、文案检查及 git diff --check 通过。
全量检查仍有环境权限、PostgreSQL 可选依赖和既有部署配置、SQLite 文件基线差异导致的未通过项。
This commit is contained in:
ThearchyHelios
2026-11-06 17:14:45 +08:00
parent 5f0b2359ac
commit 9d8b41430e
94 changed files with 9730 additions and 957 deletions
@@ -0,0 +1,82 @@
# 编排完善:问数据整轮服务端化、子工作流证据回传、驳回出口、数据事件触发、多进程与 PostgreSQL
状态:2026-10-18 用户已拍板(多进程做到「多进程 + 换 PostgreSQL」;触发接「上传表格出新一期」「上游工作流跑完」「数据源有要处理的变化」,不接「口径发布」;问数据掉线「整轮放到服务端跑」)。其余决定按本文推荐。
## 0. 调查结论:问数据为什么会因为前端掉线而失败
一轮问数据(建图 → 发起运行 → 复核 → 按复核重来、落库)是浏览器在推(frontend/src/store/chat.ts 的 plan / launch / settle):
- 建图是 `POST /api/copilot/generate-stream` 一条和页面绑在一起的流。网络一抖(`fetch` 抛 TypeError),前端 `onEnd(NETWORK_MESSAGE)` → `fail()`,这一轮记 error;服务端那边 Starlette 1.6 的 StreamingResponse 在客户端断开时取消生成任务,建了一半的图丢掉。代码注释原话:「建图跟着页面那条流走,页面一关就停」。只能整轮重试,已花的建图费用白花。
- 发起运行是页面发的 `POST /api/runs`:断网时直接失败,要手点「重新运行本轮」。
- 运行本身在服务端,页面的 WebSocket 断了会重连回放,这一段不怕掉线。
- 运行结束后的复核(`/copilot/review`)、按复核重来、落库(`PATCH /conversations/{id}/turns/{turn}`)都是页面发起的:页面不在,这一轮就没人复核、不会重来,库里停在 running,15 分钟(BUILD_STALE)后才被判成断了。
根因:问数据一轮的编排放在浏览器里(细案 01 D1 当时的选项 C「整轮编排搬到后端」,判断「方向对,但要重做重连、断点、取消,应单独立项」)。评测已经有一份在服务端跑完整一轮的驱动(app/eval/answer.Driver),问数据没用它。
## 1. 问数据整轮放到服务端(W1-a)
- **一轮是一个后台任务**:`POST /api/chat/turns {conversation_id, question, datasource_ids?, retry_of?, mode?}` → 202 `{turn_id}`。服务端用和评测**同一个驱动**跑:answer_ops → chat/turn.next_step → launch_run(origin=chat)→ 等终态(停在审批的照旧停着等人,不取消——这是和评测唯一的不同,用参数区分)→ 复核 → 按 retry 规则重来。评测、问数据各自的差异写成驱动的参数,不复制流程(总方案上一轮 X「一种说法」)。
- **事件日志**:每一步(助手的操作、心跳、look、final、usage、运行 id、复核结论、重来、终局)按 seq 写进这一轮的事件日志(新表,或复用 run_events 的写法;不进运行的封存范围)。`GET /api/chat/turns/{id}/stream?after=<seq>` 先回放、再推实时(SSE,带心跳);断了按 last seq 重连;刷新、关掉再打开都能接着看。`GET /api/chat/turns/{id}` 给当前状态。
- **停止**:`POST /api/chat/turns/{id}/cancel`(取消生成 / 运行,照现有取消规则)。
- **落库**:conversation_turns 那一行由服务端写(状态、运行 id、答案、复核、meta.usage),前端不再写这一轮的结局;老的 PATCH 接口保留给别的用途(改标题等),不再被这一轮依赖。
- **前端**:store/chat.ts 的 plan / launch / settle / retry 改成「发起 + 播放」:收到的操作照现在的渲染逻辑画(画布边收边长、过程步骤、答案、复核说明);断线自动重连、按 seq 补齐;界面上的「重试本轮」「重新运行本轮」「停止」都走新接口。问数据页的显示不变。
- **服务重启**:还在建图的这一轮标中断(照实说,可「重试本轮」);已经发起运行的,重启后接着等这次运行、照常复核收尾(运行本身的中断规则不变)。第 2 波有了租约后,别的进程也能接手。
- **单进程期间**:任务用 core/job_runtime;并发上限归入「交互」类(第 2 波的优先级)。
- 用户(user 角色)的问数据权限、遮罩、只读规则一字不变(这些在 launch_run 和 answer_ops 里)。
## 2. 子工作流的证据交回父图(W1-b)
现状:子图共享同一个 run 的事件流(节点 id 加前缀 `sub/x`),但只把出口的值交回父图(engine/nodes/multi.run_subgraph 的 `output`),子图里的查询快照、口径卡留在子图自己的状态里。父图报告引用不到子图里的数(ledger/compose.py 写明了这一点,口径账本为此改用内联实例化)。
- **出处随值走**:子图出口的每个字段,按出口模板解析出它的来源(cell(子图里的查询…) / 子图口径卡的指标 / 运行输入 / 别的),子图节点的产出带 `provenance {字段: 出处}`;父图里引用 `nodes.<子图节点>.output.<字段>` 的口径卡、报告,经 engine/lineage 跨子图往下追(同上一轮「转抄口径卡指标跨卡追」的机制:运行时、证据面板、静态检查三处同一套,限深度)。
- **报告能直接引用子图里的查询和口径卡**:报告撰写的目录(build_catalog)收进子图里的查询快照和口径卡(带前缀的节点 id,别名照常编号),引用标记、证据面板一路点到子图里的那一格;封存、可验证报告照常(事件本来就在同一个运行里)。
- **治理**:受管级里子工作流必须钉已发布未退役的版本(现有 lint);子图里追不到原始数据的,父图照样降档;子图的遮罩、只读规则照父图的运行。
- 口径账本的组合(use_caliber)继续用内联实例化,不改;但召回 / 比对按出处能认出子图里的查询(反查用得上)。
## 3. 驳回出口(W1-b)
现状:审批、补充输入、编辑稿件、动作确认、代码 / 工具审批、双盲裁决被驳回时抛 NodeRejected,运行记 cancelled + end_reason=rejected,节点照旧发 node.failed(reason=rejected)。没有「驳回之后走另一条路」。
- 这几类节点在画布上多一个可选的「驳回」出口(sourceHandle="rejected",和分支节点同一套连线机制)。接了它:驳回(含超时驳回 expired_reject)时节点**正常结束**,产出 `{rejected: true, decision, actor, note, kind}`,运行沿驳回那条边往下走;节点事件记「被驳回,走驳回出口」(node.finished 带 outcome=rejected,时间线、画布、航迹照「被驳回」画,颜色用中性色),运行照它的路径结束(成功结束也照实说「途经驳回」)。没接:行为一字不变(cancelled + rejected)。
- 动作确认被驳回走出口时:照旧不发送写入、记「未确认(被驳回)」;下游可以接「通知」「退回修改」等。
- 发布检查:驳回出口那条路要能走到出口或结束;受管级里驳回路径上的出具照常判档(契约照常核对)。应用:实例页、待办、通知照实写「被驳回,转到 X」。
- 「失败重试」「出错时继续」照旧不管驳回(驳回不是故障,X9 不变)。
## 4. 数据事件触发(W1-c)
一套定时机制(X4):Schedule 加触发方式。
- `trigger_kind`:cron(缺省,行为一字不变)| event。event 时 `trigger`:
- `table.version`:某张上传表格启用了新版本(按期累积的新一期,data/table_versions 启用那一下);可选只认某个期次规则;
- `workflow.finished`:某个工作流的正式运行成功结束(可选:只认某个应用 / 某种来源);B 的输入模板可引用 A 的出口字段;
- `source.changed`:某个数据源出现「要处理」级的变化(按源去抖:同一次探查 / 剖析产生的一批只触发一次)。
- 目标只能是工作流(target_kind=workflow);运行来源仍记 origin_kind=schedule,origin 里带 `trigger {kind, event, ...}`,界面写「由事件触发:…」。
- 输入模板变量:`{{ event.* }}`(table、version、period、activated_at;workflow_id、run_id、outputs.<字段>;source、counts)。
- 去抖与重叠:同一触发在 `debounce_s`(缺省 60 秒)内的多次事件合成一次;上一次还没结束照 overlap=skip 跳过(照实记 skipped_overlap)。
- 防环:保存时检查 workflow.finished 的串联不成环(A→B→A 拒收);运行时按 origin 里的触发链长度兜底(> 5 层拒发,照实记)。
- 事件送达:事件在发生处(启用表格版本、运行收尾、变化记录)写一条「待派发事件」(库里一张表),调度循环一拍取走、按触发条件派发、写 ScheduleFire(kind=event,inputs 带事件内容)——不在发生处直接发起运行(事务边界、重复与重启都好说清),也为第 2 波多进程做准备。AGENTLAB_SCHEDULER 关着时不派发(照旧:拷来的数据目录不替人跑)。
- 界面:定时页新建时选「定时 / 事件触发」,事件触发选事件种类和对象;列表、详情、触发历史照实显示;Webhook 通知照旧可配。
## 5. 多进程与 PostgreSQL(第 2 波:W2-a 数据库,W2-b 协调)
### W2-a 数据库可移植 + PostgreSQL
- `AGENTLAB_DATABASE_URL`:缺省 SQLite(单机、单进程照旧);`postgresql+asyncpg://…` 时用 PostgreSQL。
- 审计全部原生 SQL 和 SQLite 专用写法(json_extract、strftime、datetime('now')、INSERT OR REPLACE / ON CONFLICT、PRAGMA、按 rowid、LIKE 大小写、布尔与 JSON 列、时区),改成 SQLAlchemy 表达式或按方言分支;两种库都过全量测试(PostgreSQL 用本机 docker 的 postgres:16 起一个测试库,脚本化)。
- 迁移:现有 add-only 的列 / 索引迁移按方言生效;新增一个从 SQLite 数据目录导入到 PostgreSQL 的命令(`python -m app.db copy-to-postgres`),幂等、可核对行数。
- LangGraph 断点:PostgreSQL 时用官方 `langgraph-checkpoint-postgres`(要装 psycopg 3 / psycopg_pool,写进 pyproject 和 requirements.lock);SQLite 时照旧。
- 数据目录(工件、上传表格的版本库、知识库索引、沙箱)仍是文件:多进程同机直接共用;多台机器要把数据目录放在共享存储上(写进 README,写文件一律先写临时文件再改名)。本轮不做对象存储。
### W2-b 多进程协调
- **租约**:运行、后台任务(探查、起草、剖析、评测、影子起草、问数据一轮、召回、补算、维护)在库里认领:owner、lease_until、心跳;进程死了租约过期,别的进程按各自的规则接手或照实标中断(运行仍是「标中断、人接着跑」,不自动重跑有副作用的步骤)。
- **优先级与并发**:运行分类(交互:问数据、画布试跑;应用:入口、按需视图、钩子、接口;定时;系统:评测、召回、对账、补算、出具),每类有全站并发上限和优先级,按库里的计数认领;评测不再挤占交互。
- **调度循环**:只有一个进程当班(库里的租约),其余待命;定时认领本来就是条件 UPDATE。
- **实时流跨进程**:运行事件已落库;订阅方不在跑这次运行的进程时,从库里按 seq 追(PostgreSQL 用 LISTEN/NOTIFY 唤醒,SQLite 用短轮询);问数据一轮的事件同。
- **进程内的账和缓存**:每日花费账(裁判、核查、评测、按需视图、口径出具上限)、访问密钥的每分钟限流、按需探查锁、设置缓存、向量模型缓存、目录缓存等,改成库里的条件 UPDATE / 版本号失效;逐个列清单核对。
- **验收**:PostgreSQL 上起两个工作进程跑端到端:运行被任一进程认领、另一个进程上的页面收得到实时事件、定时只触发一次、评测和问数据并发时优先级生效、杀掉一个进程后租约过期被接手或照实标中断。
## 6. 分波与关口
- 第 1 波(并行三包):W1-a 问数据整轮服务端化;W1-b 子工作流证据回传 + 驳回出口;W1-c 数据事件触发。骨架先由编排者加好:Schedule 的 trigger_kind / trigger 两列与迁移。
- 第 2 波(顺序两包):W2-a 数据库可移植 + PostgreSQL;W2-b 多进程协调(建在 W2-a 之上)。
- 每包一个完整代理,统一复核一个代理,修复交回原代理(不另起代理)。关口:后端全量(SQLite;第 2 波另加 PostgreSQL 全量)、tsc、check-copy、相关浏览器检查、泄露扫描;第 2 波另加多进程端到端。
- 合 main 前问用户(本轮没有预先放行合 main)。