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

验证:相关主回归 3822 项通过,4 项跳过、8 项预期失败;补充回归通过。
前端构建、文案检查及 git diff --check 通过。
全量检查仍有环境权限、PostgreSQL 可选依赖和既有部署配置、SQLite 文件基线差异导致的未通过项。
2026-11-06 17:14:45 +08:00

19 KiB
Raw Blame History

数据剖析重新设计:逐表剖析的后台任务

状态:方案已定(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 四个场景

  1. 新接入一个源:探查结构 → 起草(后台)→ 点「数据剖析」,范围选「需要剖析的表」→ 剖析排在起草后面自动开始 → 关掉页面去做别的,回来看逐表结果。
  2. 日常维护:表清单多一列「剖析」,一眼看出哪些表没剖析过、上次没做完、剖析之后又冒出了待核实的关系;按它筛出来一键剖析。
  3. 单张表:表详情里「数据剖析」一节,看上次的行数、日期范围、核实了什么、跳过了什么;点「剖析这张表」。
  4. 出问题:连接断了、库响应慢,任务自己停下并写明原因;「重试没做完的表」只跑剩下的。

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 并带上原因,可重试。
  • 空表:每张表第一条查询就是估行数,确知是 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,都按推荐)

  1. 整次任务要不要总量上限。推荐不设:每张表有上限、任务级止损(连续失败、超时比例)、可随时停止,和起草「不设总时长上限」一致。备选:设一个默认的总查询数上限(如 2,000 条),到了就停、剩下的表记已停止。
  2. 起草和剖析同源:推荐排队串行(§4.4)。备选:互斥直接报忙。
  3. 同步接口 POST /catalog/profile:推荐去掉(前端是唯一调用方,留着要多维护一套互斥)。备选:保留。
  4. 查询留痕:推荐记(字面量去掉,§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。
  • 定时剖析(按周重新剖析需要的表)——可以接到已有的定时任务上,单独一轮。
  • 列级取值漂移检测(码值多了新取值)——依赖留痕的历史,下一步。