AgentLab/docs/design/caliber-authoring-optimization.md

计算口径：作者侧与审阅侧的优化决定

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，起草任务操作错误在详情中可见，旧请求不覆盖后来打开的草稿。

接口和回归覆盖上述行为；真实业务口径的审阅、模型是否能选择有效业务维度、以及生产数据上的调查效果仍需用业务样例验收。