- 完善口径编辑、只读试运行、统一质量验证与执行语义指纹 - 增加可执行指标约束、有预算的主动调查和过程评测 - 提取发布检查、证据读取与起草服务,支持任务停止、重试和检查点恢复 - 增加版本传递影响分析,修复并发覆盖、敏感值遮罩、异常评分及页面状态问题 - 修复 SQLite 复合查询追溯和 microVM 可选依赖缺失处理 - 纳入当前设计文档及部署配置调整 验证:相关主回归 3822 项通过,4 项跳过、8 项预期失败;补充回归通过。 前端构建、文案检查及 git diff --check 通过。 全量检查仍有环境权限、PostgreSQL 可选依赖和既有部署配置、SQLite 文件基线差异导致的未通过项。
19 KiB
数据剖析重新设计:逐表剖析的后台任务
状态:方案已定(2026-10-14,§6 四项都按推荐),未动代码。基于 main
fc002bd。文中表名、列名都是虚构的举例。
1. 现状(已对照代码核实)
| 问题 | 代码里的样子 | 用户看到的 |
|---|---|---|
| 一次同步长请求 | POST /catalog/profile 做完整个剖析才返回(api/catalog.py);进程内集合 _RUNNING 防重入 |
进行中只有「已用时长 / 总时长上限」一条横条,代码注释原话「不是进度」;不能停;关掉页面报告就没了 |
| 预算按「一次剖析」算 | max_queries=60、max_total_s=120,注释原话「接口是同步的,不能让一个请求无限地挂着」 |
一张有 4 条关系、6 个码值列的表要 25–30 条查询(行数 1–2;每条关系抽样 1 + 父表核对按 1000 个一批 2 + 唯一性 1–2;码值每列 1;日期 1)。选 50 张表,前两三张做完,其余整张记「查询次数用完」——「剖析只做了几张」的根源 |
| 默认范围窄 | 不选表时只挑 10 张「目录里有待核实关系」的表;为跳过空表,先拿一半查询次数去估候选表的行数(_skip_empty) |
没有关系候选的表(码值、业务日期一样有用)默认永远轮不到 |
| 结果不留痕 | 行数估算、日期范围、跳过了什么只在那次响应里;日志只记查询次数 | 表清单、表详情看不出这张表剖析过没有、什么时候、结论是什么;对业务库发过哪些查询无从查 |
| 和起草没协调 | 起草任务核对有效记录条件也打业务库;剖析与起草可同时跑 | 业务库压力叠加;先剖析后起草时,起草新提的关系没被核对 |
起草在上一轮已经从同步请求改成后台任务(data/catalog_jobs.py:任务表 + 逐表表、进程内执行、停止、重启标中断、重试),剖析是同一类问题,应该走同一套做法。
2. 设计理念对照
| 理念 | 这次怎么落 |
|---|---|
| 照实说 | 每张表、每个检查项照实写状态和原因;「没查成 ≠ 结论错了」,旧结论原样保留(沿用 _Skip.carry);停下时写清已写进目录的和没做的 |
| 留痕 | 任务、逐表结果、发过的查询(字面量去掉)落库;表清单和表详情能看到最近一次剖析 |
| 只读遮罩 | 同一个只读守卫、同一条 run_query;遮罩列不进任何查询;留痕的 SQL 去掉字面量,AgentLab 自己的库里也不留抽样到的键值 |
| 一种说法 | 剖析和起草共用一套任务生命周期、状态词、接口形状、界面组件;预算的叫法全站一致 |
| 不挡生成 | 剖析从不挡运行和表助手;只和同源的起草任务排队 |
3. 目标体验(产品)
3.1 四个场景
- 新接入一个源:探查结构 → 起草(后台)→ 点「数据剖析」,范围选「需要剖析的表」→ 剖析排在起草后面自动开始 → 关掉页面去做别的,回来看逐表结果。
- 日常维护:表清单多一列「剖析」,一眼看出哪些表没剖析过、上次没做完、剖析之后又冒出了待核实的关系;按它筛出来一键剖析。
- 单张表:表详情里「数据剖析」一节,看上次的行数、日期范围、核实了什么、跳过了什么;点「剖析这张表」。
- 出问题:连接断了、库响应慢,任务自己停下并写明原因;「重试没做完的表」只跑剩下的。
3.2 剖析对话框(照起草对话框的结构重做)
开始前
- 范围:已选的表 N 张 / 当前筛选 N 张 / 需要剖析的表 N 张(默认) / 全部表 N 张(不含视图)。
- 预算按表写:「每张表最多 40 条查询、60 秒;单条查询 10 秒;每条关系抽 2000 个键值」,再给上限的估算「这次最多约 1,600 条查询」。
- 醒目一句:剖析会对业务库发只读查询,一条一条地发,可随时停止。
- 同源有起草任务在跑时:按钮写「排队剖析」,下面一句「起草任务结束后自动开始」。
进行中
-
头部:
12 / 40 张表 · 已发 318 条查询 · 用时 4 分 12 秒,按表数的进度条(真进度),「停止」按钮。 -
逐表一行:
[进行中] orders 关系 3/4 · 码值 5/6 · 日期 1/1 23 条查询 · 18 秒 正在核对 customer_id → customers.id [完成] customers 关系 1/1 · 码值 2/2 6 条查询 · 3 秒 核实 1 条关系,取到 2 列码值 [部分] events 关系 0/2 · 码值 1/3 40 条查询 · 60 秒 这张表的查询次数用完,剩 4 项没查 [跳过] tmp_log 1 条查询 空表 [排队] refunds -
点一行展开:这张表的检查清单(每项的状态、原因、用了几条查询)、发现(沿用现有报告里的关系、码值、业务日期写法)、「看发过的查询」。
结束后
- 汇总:
40 张表:完成 33,部分 4,跳过 2,失败 1;核实 14 条关系、取到 51 列码值候选(含义待填写 37 列)。 - 筛选:有发现 / 有跳过 / 失败;「重试没做完的表」;码值「填写含义」的入口照旧。
- 结束时页面右下角提示,可回到报告(对话框关着也行)。
开始不了(409):沿用现有五种情况的说法和下一步(未开启、停用、没有表结构、快照被改动、正忙),「正忙」改成说清楚是谁在跑、跑到哪。
3.3 其他位置
- 目录页头部:起草、剖析各一个进度入口(
起草 12/40剖析 排队中),点开对应对话框。 - 表清单:新列「剖析」:未剖析 / 3 天前 / 部分完成 / 失败 / 剖析中 / 排队;筛选项「需要剖析」。
- 表详情:「数据剖析」一节——上次剖析(时间、发起人、所属任务)、行数估算及来源(统计信息 / 数到上限)、日期范围、发现摘要、跳过的项、发过的查询;按钮「剖析这张表」(未开剖析时引到设置)。
- 剖析设置:「查询次数上限」「总时长上限」换成「每张表最多查询数」「每张表时长上限」;其余三项不变。
4. 架构
4.1 抽出共用的任务运行时,起草和剖析各自建表
新模块 data/catalog_job_runtime.py,从 catalog_jobs.py 里抽出来、不改行为:
JobManager:进程内一个 asyncio 任务一件事;start / stop(grace) / wait / running / shutdown。SerialWriter:同一个任务的库写入一条一条来、shield 起来(停止时不打断写到一半的库操作),收尾前settle。SourceLane:每个数据源一条队(FIFO 的 asyncio 锁)。任务建出来是queued,拿到这条队才running。起草和剖析同源串行,不同源并行。interrupt_on_startup(job_model, task_model, message):启动时把排队、进行中的标interrupted,没结束的表记cancelled。不自动续跑(复制出来的数据目录启动时不能自己去查业务库,比起草更要紧)。- 状态词常量:任务
queued / running / succeeded / partial / failed / cancelled / interrupted,逐表pending / running / ok / partial / failed / skipped / cancelled——起草已有的那套,剖析照用。
catalog_jobs.py(起草)改为用这些,现有起草测试一条不改、全部要过,这是抽取正确的判据。
剖析的任务在新模块 data/catalog_profile_jobs.py,新表(只加不改,迁移是加法):
catalog_profile_jobs:id, source_id, status, scope(selected|needed|all), settings(JSON,建任务时的快照), created_by, started_at, finished_at, queries, timeouts, errors, stop_reason(failed|slow|NULL), notice, error, retry_of。部分唯一索引:同源只有一个排队或进行中的剖析任务(同起草)。
catalog_profile_tasks:id, job_id, seq, table_name, status, checks(JSON:[{kind, target, path, state, reason, queries}]), queries, elapsed_ms, current(正在做哪一项的一句话), row_estimate(JSON), findings(JSON), skipped(JSON), date_ranges(JSON), query_log(JSON), added, updated, removed, version, error, started_at, finished_at。
否决「和起草合成一张通用任务表(kind + JSON)」:要迁移刚稳定的起草数据、丢掉起草进度那些强类型列,换来的只是少两张表;共用的是生命周期代码,不是表。
4.2 剖析引擎:从「一次剖析」改成「一张表」
catalog_profile.py 保留全部检查逻辑(关系、码值、日期、_apply 并入规则、乐观锁写入),只换编排:
profile_table(cx, table, notes, hooks) -> TableResult成为公开入口:先列全检查项(现在的_plan),逐项执行,每项开始、结束经 hooks 回调(任务据此写checks / current / queries),整张表结束写目录(现在的_write)。_Runner拆两层:SourceRunner(整个任务一个):只读守卫、单条时限(取设置和数据源时限中小的)、任务级止损、查询留痕。TableBudget(每张表一个):这张表的查询次数、时长。用完抛_Stop("budget"|"deadline"),只停这张表——剩下的项记「这张表的查询次数用完 / 时长用完」并保留旧结论,表记partial,下一张表拿满额预算。
- 任务级止损(替代原来的总量上限,见 §6 问题 1):
- 连续 3 条查询失败(沿用现规则:多半是连接断了、没权限)→ 任务停,
stop_reason=failed,写出第一行报错; - 最近 10 条查询里 7 条超时 → 任务停,
stop_reason=slow,「数据库响应慢,已停止,避免给业务库加压」; - 剩下的表记
cancelled并带上原因,可重试。
- 连续 3 条查询失败(沿用现规则:多半是连接断了、没权限)→ 任务停,
- 空表:每张表第一条查询就是估行数,确知是 0 行 → 表记
skipped「空表」(只花 1 条)。原来挑表前的批量预估(_skip_empty、PROFILE_DEFAULT_TABLES、PROFILE_PROBE_TABLES)删掉。 - 表的状态:每一项都有结论 →
ok;有项因为运行原因没查成(次数、时长、超时、出错、守卫拒)→partial;按规则不查的(遮罩、视图、取值太多不像码值、空表)不算没做完。写入一直冲突、整张表出错 →failed。 - 停止:正在跑的那条查询由数据库按单条时限截止(
run_query的_server_deadline),这张表做完的项照常写进目录,没做的保留旧结论;后面的表cancelled。 - 表助手的只读查询、起草时的有效记录条件核对继续走单条查询的路径(一条查询、守卫、时限),行为不变。
4.3 范围怎么定(服务端定,界面只显示个数)
- 需要剖析的表:在表结构里、不是视图、有可查的项(关系候选、像码值的列、日期列),并且满足其一:从没剖析过;上次剖析没做完(partial / failed / cancelled);上次剖析之后目录里出现了新的待核实关系。
- 全部表:表结构里有可查项的表,不含视图。
- 顺序:有待核实关系的在前 → 使用次数 → 表结构顺序(沿用现规则)。
GET /catalog的每行加last_profile(状态、任务、时间、发现与跳过计数)和profile_due,对话框据此显示个数,表清单据此画「剖析」列。
4.4 同源排队与互斥(一条规则)
- 同一个源:起草任务和剖析任务排队串行;同一种任务同时只有一个(排队或进行中),再建回 409 并说明正在跑的是哪个、到哪了。
- 从表详情点「剖析这张表」时如果已有剖析任务在跑:409,告诉他这张表在不在那个任务里、排第几。
- 导入目录、同步起草:同源有任一种后台任务时都是 409(
ensure_idle把剖析任务也算上)。 - 运行、表助手的对话和只读查询:不受影响。
否决「剖析和起草并行」:业务库压力叠加;先剖析的表看不到起草新提的关系。否决「互斥直接报忙」:「起草完接着剖析」是最常见的顺序,排队让人点一次就能走开。
4.5 查询留痕
每张表记下发过的查询:{at, kind, target, sql, ms, rows, outcome}。sql 经 sql_semantics.normalize_sql 把字面量换成 ?——IN 列表里抽样到的键值不进 AgentLab 的库;遮罩列本来就不进查询。条数受每张表的查询上限约束,大小有界。界面在逐表展开和表详情里「看发过的查询」。
价值:DBA 和数据负责人能回答「这次剖析对业务库查了什么」;出错、超时时能对着具体查询判断原因。
4.6 设置迁移
- 保留:
enabled、query_timeout_s、sample_size、max_scan_rows。 - 新增:
table_max_queries(默认 40,1–200)、table_max_s(默认 60,10–600)。 - 去掉:
max_queries、max_total_s。启动时一次性迁移,把库里数据源 options 中这两个键删掉、记日志。不把旧值折算成新值:旧值按「整次剖析」算,含义不同,硬折算才是不照实。保存时如果还带着旧键(老页面),只摘掉、不报错。
4.7 接口
| 接口 | 说明 |
|---|---|
POST /catalog/profile-jobs |
{tables?: string[], scope?: "needed"|"all"},202;未开启、停用、没有表结构、快照被改动、正忙 409(沿用机读码) |
GET /catalog/profile-jobs/active / latest / {id} |
任务和逐表状态 |
POST /catalog/profile-jobs/{id}/cancel |
停止;排队的直接取消 |
POST /catalog/profile-jobs/{id}/retry |
新任务,只含 failed / partial / cancelled 的表 |
GET /catalog |
每行加 last_profile、profile_due;active_job 旁边加 active_profile_job |
GET /catalog/{table} |
加 last_profile(完整的逐表结果,含发过的查询) |
POST /catalog/profile |
去掉(见 §6 问题 3) |
4.8 保留多久
每个源保留最近 50 个结束了的剖析任务;更早的删掉,但某张表最近一次剖析所在的任务不删——表详情的「上次剖析」永远有。起草任务的保留不在这次范围内。
5. 否决的备选
| 备选 | 为什么不 |
|---|---|
| 同步接口改流式(SSE)推进度 | 关页面就断;不留痕;不能排队;停止要另做 |
| 前端循环逐表调同步接口 | 最省事,但关页面就停、两个标签页会抢、停止不干净——起草以前「每 12 张表一个请求」就是这条弯路 |
| 保留整次总量上限当主预算,只是调大 | 正是现在「只做了几张」的根源;调大又失去对单张表的约束 |
| 一张表内多条查询并发 | 更快,但违背「少量只读查询、一条一条发」的承诺 |
| 剖析结果写进目录的表级字段 | 行数、日期范围是观测,不是要人确认的事实;写进目录会抬版本、引发冲突、被导出导入带走 |
6. 已拍板(2026-10-14,都按推荐)
- 整次任务要不要总量上限。推荐不设:每张表有上限、任务级止损(连续失败、超时比例)、可随时停止,和起草「不设总时长上限」一致。备选:设一个默认的总查询数上限(如 2,000 条),到了就停、剩下的表记已停止。
- 起草和剖析同源:推荐排队串行(§4.4)。备选:互斥直接报忙。
- 同步接口
POST /catalog/profile:推荐去掉(前端是唯一调用方,留着要多维护一套互斥)。备选:保留。 - 查询留痕:推荐记(字面量去掉,§4.5)。备选:不记,只记条数。
7. 项目:交付与验证
做法:集成分支 feat/catalog-profile-jobs(从 main fc002bd);workflow 两个完整代理按同一份接口约定并行(后端:运行时抽取 + 剖析任务 + 引擎改编排 + 接口 + 设置迁移;前端:对话框、头部入口、表清单列、表详情一节、设置、检查脚本),一个统一复核,各自修;我合并、跑全量关口、真实验收,合 main 前问你。
后端测试(虚构夹具)
- 抽取:现有起草任务测试原样全过。
- 逐表预算:A 表用完自己的次数记 partial,B 表照样拿满额。
- 止损:连续 3 条失败任务停、其余 cancelled 带原因;超时比例触发
slow。 - 停止:做完的项写进目录,没做的保留旧结论;重启标中断不续跑;重试只带没做完的表。
- 排队:起草在跑时剖析排队,起草结束自动开始;停掉排队的;同种任务 409;导入、同步起草在剖析时 409。
- 范围:需要剖析 / 全部 / 已选;空表 1 条查询记 skipped;视图跳过;
profile_due的三种情形。 - 留痕:IN 列表的值不出现在
query_log;遮罩列不出现在任何查询。 - 设置迁移:旧键启动时删掉;老页面带旧键保存不报错;表助手和有效记录条件核对行为不变。
- 保留:超过 50 个时删旧的,但不删某张表的最近一次。
前端:新检查脚本 check-catalog-profile.mjs(假接口 + 夹具):开始前的范围与个数、排队提示、进行中逐表行与检查项进度、停止、结束后的筛选与展开、重试、表清单列、表详情一节、设置两项新字段;同时把 check-catalog 里旧的剖析一节删掉(那一节并行时偶发点击超时,顺带解决)。check-all 变成 30 项。
真实验收(数据副本,副本里 Oracle 源的剖析关掉,不碰你的真实业务库):两个虚构零售 SQLite 源开剖析(一个带大表、视图、空表、遮罩列)。逐表进度对得上;中途停止不丢已写的;杀进程重启 → 中断 → 重试补齐;起草 + 剖析排队;拿你数据副本里那个带旧设置键的源验证迁移(只看设置,不发查询)。
规模:和起草可靠性那一轮相当(后端约 1,500 行含测试,前端约 1,000 行)。
部署:只加表、迁移是加法,升级步骤不变。10.0.0.11 还没重新部署:如果不急,等这一轮合入后一次部署到位;急的话按上次的清单先部署,这一轮之后再升级一次。
8. 不在这次范围
已在下一轮做掉(2026-10,next-round/00-总方案.md 第 7 节):剖析结果进 look 表详情(遗留 e、目录 A2,第 2 波);定时剖析改成数据源的定时维护(目录 B4:一条目标为数据源的定时任务,第 3 波接口、第 4 波界面);列级取值漂移改成取值观察(目录 B2,第 3 波)。下面的原文保留作对照。
- 剖析结果喂给表助手和对话助手(如「这张表约 120 万行,下单日 2023-01 至 2026-10」)——有价值,等这一轮和助手按需查看(docs/design/copilot-look-and-caliber-ledger.md)都落地后,放进 look 的表详情(
data/schema_view.py)里做,不另走一条路;遮罩照 look 的 D6。 - 定时剖析(按周重新剖析需要的表)——可以接到已有的定时任务上,单独一轮。
- 列级取值漂移检测(码值多了新取值)——依赖留痕的历史,下一步。