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

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

49 lines
9.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 计算口径:作者侧与审阅侧的优化决定
> 2026-11-04 复盘 11-03 至 11-04 的口径相关改动(指标定义卡与四种指标类型、口径目录与试跑、业务文档起草与多轮续跑、descriptor/usage)后的决定。本文只写结论和落地顺序;接口和数据模型的细节以代码与测试为准。
## 缺口
1. **能看,不能改。** 指标定义卡与四种指标类型进了 schema、校验、descriptor、目录和证据标签,但画布的指标编辑器只有 id / 名称 / 单位 / 表达式四栏;草稿页只读;规则编译只有接口。定义卡有形状、没有作者。
2. **审阅对象不对。** 草稿页不显示 SQL,试跑只回标量值;没有结果表、列映射、SQL 差异。业务的人判断不了数对不对,技术的人只能跳画布;目录页试跑成功后连运行记录都留不下。
3. **两处真相。** 草稿 payload 与 workflow graph 各说各话:改 payload 不重建图,画布改图后草稿页不更新。
4. **编排过重。** 10 轮串行、60 条上限、15 分钟轮询,靠截断抢救、问题去重、入口合并、日期预填、提示词补丁兜底;没有取消、重试、单组重试。
5. **概念与状态过载。** 文档起草、接一次运行、可沉淀的问题三套创建路径,7 种草稿状态;`questions_open` 不阻断试跑,`path_pending` 是遗留。
6. **资产面缺管理。** 目录只列每个工作流最新已发布版本,没有版本对比、使用情况、退役、试跑历史。
7. **定位没说清。** 设计文档写「不做从指标定义编译 SQL 的语义层」,起草主路径却由模型写 SQL;docstring 里的重新解释没有写进设计文档和界面文案。
## 决定
- **D1 口径图是唯一真相。** 草稿在第一次建图后,指标、取数、入口都以 workflow 当前版本里的图为准。画布与草稿编辑共用保存逻辑:每次实际修改新增版本,旧快照(含已发布版)不可覆盖。PATCH 在当前图上改口径卡,不从 payload 重建取数节点,保留节点 ID、SQL、入口和其他编排。试运行明确固定当前版本,强制只读,记录图、执行内容和输入的哈希;执行内容修改后旧结果显示待重新验证,只改布局则保留原版本证据。晚结束的旧试运行不能覆盖新结果或并发编辑。payload 里的指标快照只留给起草中途和旧草稿兼容。
- **D2 定义卡分两层。** 核心:名称、同义词、单位、小数位、定义说明、负责人、生效日期、引用原文;高级:适用范围、不包含、分子、分母、维度、过滤。四种指标类型都必须在界面上可编辑;规则与评估的结构先用 JSON 编辑,后续再换结构化表单。指标参数(`params`)目前没有运行时语义,先不承诺、不推广,后续要么实现「按参数生成口径实例」,要么从 schema 和目录里删掉。
- **D3 审阅面必须有证据。** 草稿页与目录页的试跑都要给:取数模板 SQL、执行后的结果表(前若干行、总行数、遮罩格如实显示)、列与指标的对应。目录页的试跑要留下运行链接,刷新不丢。发布前再给一份只读检查清单(图能过发布校验、SQL 单条只读且表在目录里、入口字段与占位符一致、试运行成功、每条指标有引用原文),不拦人,只把没通过的项说清。
- **D4 状态收敛。** 界面只有四种阶段:起草中 / 待审 / 已丢弃 / 失败;`ready`、`questions_open`、`path_pending`、`attached` 都归「待审」,细状态保留在接口和标签的悬停提示里,接口兼容不迁移存量数据。三套创建路径最终收敛为一个「新增口径」向导(从文档 / 从运行 / 手动),输出同一种草稿。
- **D5 起草分组。** 一次模型调用尽量交多组「能共用一条 SQL 的指标」;服务端逐组校验,一组不合格只丢这一组,并只对这一组重写一次(最多三组并行),修好就并入。一轮写不下时按 `uncovered` 再续,最多 4 轮;不再一组一轮、10 轮串行。起草是离线辅助,回答问题时仍不做「定义 → SQL」的编译;发布的是人审过、跑过的 SQL。
- **D6 目录按口径管理。** 目录按口径(工作流)分组,展开是版本列表:版本、发布时间、级别、变更摘要、指标数、入口、依赖、与上一版的差异、使用情况、退役动作、试跑历史。「新增口径」是主按钮,草稿箱独立。
- **D7 口径身份不动。** 不新建「口径」实体表;身份仍是「工作流@版本 / 口径卡」。账本、证据、召回、descriptor 都建在这个身份上,换身份牵一发动全身,收益不抵成本。
## 落地顺序
- **P0(本次)**:补全草稿指标的 grain / time_field / numerator / denominator / dimensions / filters;payload 记 `groups`;多组指标 id 建图前全局重排,payload、图、试跑值指同一件事;试跑响应带查询结果集;草稿页展示 SQL 与结果表;目录试跑留运行链接;画布指标编辑器补定义卡与四种类型。
- **P1(下一轮)**:草稿编辑写图、图回读草稿、界面四阶段、发布前检查、「新增口径」主入口都已落地。三来源向导(从文档 / 从运行 / 从可沉淀的问题)等起草流程稳定后再收成一个入口。
- **P2(已落地)**:起草改成一次交多组、逐组校验、坏组并行重写一次、最多 4 轮;前端按组显示「这条 SQL 出哪几个指标」。「指标清单」单独成阶段留作后续优化,等实际反馈再决定。
- **P3**:目录分组、版本对比、使用情况、退役、试跑历史(D6)。
## 验收
- 后端:相关 pytest 全过;试跑结果集的遮罩与截断有测试。
- 前端:`pnpm build`、`node scripts/check-copy.mjs` 全过;四种指标类型切换不丢字段;草稿页与目录页在旧数据(没有 `queries`)下不报错。
- 人工:拿一份真实业务文档走一遍「起草 → 看 SQL / 结果 / 引用 → 改定义 → 试跑 → 发布」,确认每一步都能拿到判断所需的信息。
## 2026-11-06 架构修复
- **验证分开执行和质量。** 试运行的 `validation` 给出 `pass / fail / unknown`;运行成功不等于口径验证通过。缺数、截断、SQL 错误、复算不一致、显式约束失败和可比性未知,都会进入质量结论与出具缺口。旧证据没有质量版本记录时要求重新验证。试运行指标值和查询表使用相同遮罩,接口不再附带未经处理的原始运行输出。
- **显式约束可以执行。** 指标 `contract` 支持结果形状、粒度唯一性、非空列、单位、数值范围,以及来自同一行的分子/分母、子集关系和倍率。自动起草的标量指标默认要求一行结果,不能静默取多行中的第一行。自然语言粒度、过滤等描述尚未被证明与 SQL 等价时仍显示待审;这不是通用的自然语言到 SQL 编译器。
- **分离指纹用途。** `definition_hash` 覆盖指标声明;`semantic_hash` 加入上游 SQL、数据源和绑定;`execution_hash` 忽略画布布局。旧 `graph_hash` 不改算法,历史封存仍可核验。可比性规则升级到分析方法版本 `@2`,复核历史结果会明确显示方法变化。
- **调查有完成条件和预算。** 追问原因或发现基线异常会触发继续调查,核对闭合、可比性、下钻关联与整体贡献覆盖;子层占比沿父层累计。默认最多追加两轮、最低下钻一层、覆盖程度为 0.8,仍受总步数、查询和费用预算约束。无法补齐时封存停止原因并限制正式出具,完成贡献分析也不等于证明因果。可用 `investigation` 评测期望检查状态、深度、查询预算和停止原因。
- **起草生命周期持久化。** `CaliberDraftJob` 记录属主、状态和尝试次数,支持停止和重试。启动时将遗留任务标为中断;只有用户重试才继续模型调用。同一材料可恢复已校验分组,材料变化则重新规划;并行分组修复使用独立会话。共用任务管理器拒绝重复启动同一任务。
- **应用服务与影响追踪。** 发布检查、封存证据读取和起草编排提取为公共服务。版本使用情况展示传递依赖的工作流与应用,退役时提供影响清单;无法解析的历史图明确列出,不能按无依赖处理。
- **一并修复的通用问题。** SQLite 证据追溯的编译兜底增加授权回调的 SELECT 计数,避免某些版本把复合查询编译成临时表、没有 Yield 时被误认为单表直接投影。microVM 在缺少可选 SDK 时返回明确的执行失败结果,不直接抛导入异常。评分输入拒绝 NaN/Infinity,起草任务操作错误在详情中可见,旧请求不覆盖后来打开的草稿。
接口和回归覆盖上述行为;真实业务口径的审阅、模型是否能选择有效业务维度、以及生产数据上的调查效果仍需用业务样例验收。