ThearchyHelios
2714890d0d
README.zh-CN.md / README.md 只留：这是什么、为什么用它、主要功能（按领域一行一条，链到文档）、快速开始、部署、文档索引、 开发与测试、许可（原文不动）。原来的每一节按读者和任务分到 17 篇主题文档：ask-data、workflows、evidence、 data-sources（新增：接入数据库、只读保证、上传表格、跨库合并、遮罩列）、data-catalog、tools（新增：工具、审批档位、 能力登记、端点、网络规则——它们管所有工作流，不只应用）、apps、evaluation-and-ledger、schedules（含通知）、deployment、 configuration、postgresql-and-scaling、identity-and-security、architecture、development、upgrade-notes（按时间倒序， 每波先写要做的事）、faq。删掉的只有模块名（api/copilot_gen.py、chat/drive.py、data/schema_view.py）、重复的话和 「以前…现在…」的叙述；操作步骤、命令、配置名、限制、权限边界都有归宿。中文是原文，英文按新的中文写；英文里界面文字 只写英文名，开头注明界面目前只有简体中文，中文占位符换成英文占位符，中文数字的例子改成不依赖中文的说法。 数据剖析可以同时剖析 2–3 张表（baf23998）收进 data-catalog。 新增 scripts/check-docs.py：英文文档（README.md、docs/en/**）不许有中日韩字符和全角符号（代码块也算）， README、docs/**、deploy/README.md 的相对链接和锚点都要通，docs/zh-CN 与 docs/en 文件一一对应、标题层级相同。 中文提示里指向 README 章节的地方改指新文档：cluster/guard.py、cluster/version.py、db/base.py 两处报错， data/schema_view.py 文档串，.env.example 三处，scripts/prod.sh、scripts/test-postgres.sh，terms.ts 两处、 DataSourcesTab.tsx、check-manage.mjs 注释，deploy/README.md 三处链接。deploy/agentlab.env 未动。 验收：check-docs 0 问题（英文文档 18 个 0 处中文，相对链接 369 条 0 断链，18 对标题层级一致）；相关后端测试 117 通过、7 跳过；tsc -b、check-copy 通过。
7.3 KiB
English | 简体中文
回归评测与口径账本
这篇讲两件事：回归评测（换模型、改提示词、改目录之后，问数据还答得对不对）和口径账本（问数据答案里的数和已发布的口径对不对得上）。给搭建者和管理员看。
回归评测
评测在导航的「评测」里，搭建者以上可见（快捷键 ⌥0）。
题集
每道题是一个问题加期望答案。期望可以是：
- 一条 SQL：选格或列，每次评测重算，不冻结数值；查到遮罩列的拒收。
- 一份已发布口径的指标。
- 从某次问数据运行里认定的查询。
- 「没有数据」，或者期望反问。
规则：
- 数值不许人填。
- 文字要点由裁判判，单列，不计入准确率。
- 口径升版后，用到它的题在顶部提示。每道题三选一：改为固定新版本、新旧两版各算一份期望、旧题归档另建新题。处置之前，评测时跳过这道题。
- 题集能导入导出。
发起评测
- 选变体：助手模型、写作模型、裁判开关、目录（当前 / 快照 / 只用已核实的 / 关）、重复几次。
- 看预估花费，确认发起。「目录贡献」预设一次跑「当前 vs 关」。
- 评测在后台跑，每题怎么走和用户在问数据里拿到的一样（建图、运行、复核）。停在审批上的不代批，照实记。
- 助手只给了思考、一个操作都没给时，自动重来一次。
- 并发、每题时限、单次和每日金额都有上限，在「设置 → 偏好设置 → 评测」里改。评测的花费单独记账。
- 每题的时限不算排队的时间。满载时评测会排在问数据后面（见运行并发）。
- 能停，能只重试没做完的题。服务重启时标成中断，不会自己续跑。
看结果
- 总览：准确率与可追溯准确率（带 Wilson 区间）、路径和出具档位的分布、按角色的用量与成本、耗时分位。
- 逐题表：结论、期望和答案里的数、SQL 差在哪、看了几次表、花费；点开去看运行。
- 对比：和上一次或基线比，看逐题转移与归因。
- A/B 配对表：精确 McNemar 检验，只展示，不卡门。
评测运行不进使用统计。评分规则现在是第 2 版；老评测可以在评测详情里按新规则重评（只读封存，不调模型）。
定时评测
定时任务的目标可以选题集。有一道题从通过变成不通过，就推「定时评测有退步」；消息里只有题集名、通过数、退步题数和链接。以题集为目标的定时任务不收 Webhook（回 422）。
口径账本
口径账本把问数据答案里的数，和已发布的口径对上。口径是一个指标怎么取数、怎么算的约定，固定在口径卡里。
逐个数标口径
探索运行封存后，系统在后台把答案和已发布的口径比对，给每个数标一种口径：
| 标签 | 含义 |
|---|---|
| 「等价已证明」 | SQL 被证明和口径等价 |
| 「助手选用」 | 助手选用口径拼出来的 |
| 「相关口径」 | 用到同一张表却不等价，写明差在哪 |
| 「这次的推理」 | 和哪份口径都不沾边 |
- 证据面板的出处链最上面多一步「口径」；问数据每一轮底下有一行摘要。比对还没出结果时，写「正在比对口径」并按退避重取。
- 比对结果是一条封存后追加的事件
ledger.matched，出现在时间线和可验证报告的「封存后追加」里，不在封存范围内。启动时会补比最近 7 天的运行（跟着AGENTLAB_SCHEDULER开关）。 - 逐个数判：报告引用了一条查询的几列（例如销售额、订单数、首末日）时，每个数按它那一列单独和口径的指标列比，多查的列不影响这个数。只在去掉别的列不会改变这个数时才这样比；有 DISTINCT、按别的列排序后截断、多出来分组列的，照旧整条比。
- 多行查询没有
ORDER BY时，引用其中一格不算「来自口径」，召回和对账里照实标「行序不定」。 - 整题要每个来自数据的数都被证明来自同一份口径，才自动出具。
写口径的取数 SQL 时，最好不要取整（ROUND(SUM(x), 2)），也不要套 COALESCE(…, 0)。取整和缺省值交给口径卡的小数位和展示；否则问数据里没取整的写法永远认不成等价（差在哪会照实写出来）。
按口径正式出具
整题等价于一份已发布的受管口径时（SQL 被证明等价、版本受管、图里没有人工节点和写入），系统按口径自动发起一次正式运行，来源记为「按口径正式出具」。
- 「设置」里的
ledger一组可以关掉自动出具（auto_issue）。 - 自动和一键出具合计每天最多 20 次。
- 标「助手选用」的答案给一键出具。
- 画布试跑、个人应用刷新这类不是问数据答案的运行，不自动出具。
- 使用者按口径正式出具，只限他有权使用的应用固定着的口径版本。
对账
对标「相关口径」的数，点「看差多少」发起一次只读的对账运行：这次的数、口径的数和差值，各自点得开出处。
- 对账的说明有没有用，可以反馈。
- 使用者也能对账。
- 要人选对照指标时，按逐个数核对过的那几列预选。
沉淀
同一类问题反复出现时，它会进工作流选择里的「可沉淀的问题」。判断标准：同一形状的查询 ≥3 次、来自 ≥2 段对话；或者问题聚成一类；或者答案被反复导出、做成应用。
可沉淀的问题可以固化成口径草稿：引用的查询变成取数节点，跨轮变化的字面量自动成为参数。审过再发布。
召回
受管口径发布新版本后，系统在后台反查用过旧版的问数据回答、正式运行、固定它的应用和导出，按参数分组，在同一份数据上重算两版之差（来源为「口径召回」的探索运行，差值在召回卡里算）。
- 只有数真变了，才给答案的主人开「召回」待办，并推
ledger.recall。待办里旧值、新值、差值和原答案当时的值都点得开，可以按新版重新出具。 - 没变的只记账，在原答案上记「已按 vN 核对，不影响」。
- 全部指标都行序不定的，结论写「核对不了」并开待办。
- 每次发布最多重算
ledger.recall_limit组（缺省 50；0 表示只列不算），超出的在版本历史里点「接着算」。发布弹窗先预告规模。 - 发布后自动的那一批，以及启动时接着做，都跟着
AGENTLAB_SCHEDULER开关。 - 数变了时可以推通知「口径升版，答案的数变了」（全局渠道、答案主人的个人渠道），消息里不放数字。
- 目录或表结构的变化也会让答案标「依据有变」（见数据目录）；只有按新目录新出现错误级问题的答案才开待办。
统计
四项统计由 GET /api/ledger/stats 现算：等价命中、对账、问题重复度、召回（E1–E4）。评测页的「口径命中与重复度」页签画趋势。
评测、口径对账、口径召回是系统代为发起的运行，不进使用统计，记录页默认不列。