AgentLab/docs/zh-CN/evidence.md

English | 简体中文

证据与出具

这篇讲报告里的数字从哪来、怎么核对：口径卡和出具契约、三档出具、报告撰写节点的引用标记、点开一个数能看到什么、封存与核对、两种导出。给搭建者和看报告的人看。

基本思路

所有算术都发生在口径卡节点里，叙述只能引用，不能自己算出新数字。口径卡是受控指标集：每个指标怎么取数、怎么算，写成表达式，带口径名和版本。报告里的数字由系统照快照填进去，每一个都点得开出处。

有两个内置模板示范这条链路：

• 模板 ⑧：叙述由模型调用节点写，出口把叙述里的数字按数值回指到指标集。
• 模板 ⑨：叙述换成报告撰写节点，数字按引用填值。

flowchart LR
    A["取数<br/><i>固定步骤</i>"] --> B["口径卡<br/><i>受控指标集</i>"]
    B --> C["叙述<br/><i>LLM</i>"]
    C --> D["出具契约<br/><i>数字回指校验</i>"]
    D --> E1["formal"]
    D --> E2["degraded"]
    D --> E3["withheld"]
    A -.快照.-> S[("工件库<br/>sha256 寻址")]
    B -.口径名 + 版本.-> S

出具契约与三档

出具契约配在 output 节点上，决定这份成果按哪一档出具：formal（完整出具）、degraded（降档）或 withheld（不予出具）。判定结果和缺数据声明随成果一起印出。数据不全时降档，不硬出。

按数值回指

契约只核对数值时，校验器从叙述里抽出全部数字，逐个回指指标集：

• 支持千分位、百分数与比率互转、千 / 万 / 亿后缀，以及按书写精度的舍入容差。
• 日期、枚举序号、引用标记不参与回指。
• 中文数字同样回指，否则换一种写法就绕过去了：成、倍、百分之、分之、一半按比例回指；「两千余」按区间 [2000, 3000] 回指。「一个问题」「十分重要」「从三个方面看」「三季度」「几十家」这类虚指、序数、季度名、结构性列举不算结论数字。

实测：Opus 5 写的正文数字全部回指成功，但结尾「（约 100 字）」里的 100 被判为集合外数字，触发降档。处置方式是改 prompt，不是扩大白名单——这正是校验器应有的行为。

按引用核对

契约写了 report_from 时按引用核对：取回报告文档时复验哈希、独立重算一遍，全部数字都带引用才判为完整出具。

指标出具

纯指标看板（契约只写 metrics_from，上游没有报告撰写节点，成果里也没有模型写的话）按指标出具。没有叙述可核，就核指标本身：

• 必需的指标齐不齐；
• 每个指标的输入是否追到原始数据（查询快照的格、运行输入）；
• 成果字段里的数是否都回指到指标。

受管级要求每个指标都静态地追到原始数据。

契约指标的来源查询有 SQL 检查错误时，出具降档（见数据目录）。

口径卡

• 表达式可以写 cell(nodes.pull, 0, 'gmv')，出处精确到单元格。
• 取整和缺省值交给口径卡的小数位和展示，不要写进取数 SQL（原因见口径账本）。
• 受管级发布时，口径卡的输入不能来自计算角色的沙箱代码（门禁 G4）。

口径升版

钉住的方法卡出现新版本时，正式运行拒绝启动，直到模板显式声明升版策略：

策略	做法
recompute	回算历史
dual	新旧两版双印
incomparable	标注前后不可比

这里没有默认值。口径变更最容易静默出错的形态是「数字看起来都对，只是与上周不可比」。应用固定的版本升版时也要选处置，见应用。

报告撰写节点

报告撰写节点（report）里，模型只写引用标记，数值由系统照快照填进去。流式输出里看到的就是最终数字。

引用标记

[[m:gmv]]  [[m:gmv|万]]                    口径卡指标；换算显示也由系统完成
[[i:week]]                                 运行输入
[[v:Q1.r0.gmv]]                            查询快照里的一格，取回时复验哈希
[[table:Q1 cols=region,amount rows=0-4]]   系统照快照生成整张表，每一格都点得开
[[t:orders]]  [[c:orders.week]]            表名、字段名；写在反引号里的名字同样核对
[[q:K1|原话]]                              知识库原话，须在那次检索命中的片段里逐字出现
[[see:m:gmv,Q1]]                           结论句的依据，挂在句末，不渲染

违规怎么处理

• 裸数字、解析不了的引用当场判违规，交回去重写（max_repairs，默认 1 次）。
• 仍不过关时，按 on_violation 处理：让节点失败（正式运行的默认），或把违规标在报告里（探索运行的默认）。

取数链路

• agent、工具节点、代码节点、知识检索取数时都记进证据台账。报告的来源清单按台账编号：查询是 Q1…，知识库片段是 K1…。
• agent 打开 cite_fields（配合 output_schema）后，每个字段标出取自哪次查询的哪一格，再到快照里核对：对不上以快照为准并告警；查不到的记为空值，不兜底成 0。
• 代码节点的 evidence_role：source 是取数，compute（默认）是计算。沙箱算出来的数不能被报告直接引用，要进口径卡。
• 上传表格的单元格可以追到原表的格子（推断的来源）。
• 登记端点读回的表格也能作证（见工具）；子工作流的出处一路带回父图（见工作流）。
• 数据源可以设遮罩列（mask_columns）。对搭建者、管理员和未开启登录时的所有人，遮罩只减少暴露，不是安全边界；对开了登录的使用者是边界（见哪些角色看得到原值）。

点开一个数看到什么

_{记录页的「证据」页签：点开「环比 8.7%」，右栏从口径卡的原式、代入式一路指到两次查询里被引用的那一格，末尾是封存核对；左下是证据清单。Mock 写不出带引用的报告，这次运行用前端测试夹具（frontend/src/run/__tests__/evidence-query.json，示例数据）伪造，列表里其余几条是 Mock 真跑的。}

• 数字：指标的原式、代入式和复算结果；输入与快照是否一致；查询的 SQL；被引用的行加前后各 2 行，高亮到格；最后是封存状态。只认封存范围内的事件交回过的工件。出处链最上面还有一步「口径」（见口径账本）。
• 表名、字段名：出现在哪次查询、类型、所属的表。表结构快照、SQL、结果列里都没有的名字标成可疑实体（「可能是编造的名字」，附最接近的 3 个）。快照被截断、核对不了的，只说核对不了，不冤枉成编造。
• 知识库原话：须在那次检索命中的片段里逐字出现。

结论句

报告节点的 claims 决定怎么管结论句：

取值	做法
off（默认）	不管
require_citation	结论句要挂依据，没挂的计入缺口
judge	再请另一个模型按证据逐句判为支持 / 部分支持 / 不支持 / 不是结论

• 裁判只标注，不改写正文。裁判模型和写作模型相同时给警告。
• 正式运行在节点内判，判定随报告一起封存；有不支持的结论句时，按 on_unsupported 让出具降档或不予出具。
• 探索运行点开哪句判哪句，判定作为封存之后追加的事件记下，封存核对照样一致。
• 有上限：每份报告 40 句、$0.05、30 秒，每次点击 $0.01，每天 $2（都是默认值）。每一项都能设成不限。

旧运行与一键升级

• GET /api/runs/{id}/evidence/audit 把条目按无证据 / 可疑实体 / 有出处 / 旧运行猜测分组，可以导出 JSON 和 CSV。
• 没有契约的旧答案，按数值和已封存的查询单元格、口径卡值比对，每个数最多 3 个候选，默认折叠，写明「猜测的来源，不能当证据」。
• 老工作流可以一键升级为可追溯结构：模型调用写的报告换成报告撰写节点；问数据的 input → agent → output 中间插一个报告撰写；配了 output_schema 的 agent 打开 cite_fields。给口径卡供数的沙箱代码只建议标成 source，不替人改。
• 升级只给预览，人确认后才保存（升级要过发布前检查，见工作流）。

封存与核对

• 每次运行的完整证据存进内容寻址的工件库（data/artifacts/）：sha256 就是地址，取回时复验哈希。
• 运行终态的事件清单哈希记在运行上，封存到 run.finished 为止。事后修改流水就对不上了。
• 在运行详情页一键核对，接口是 GET /api/runs/{id}/verify。
• 封存之后追加的事件不在核对范围内，例如探索运行里点开结论句的判定、口径比对的 ledger.matched。它们出现在时间线和可验证报告的「封存后追加」里。

导出

有两种导出，用途不同：要证明没被改过，用可验证报告；要让人读报告、查数字的来历，用报告导出。

报告导出：问数据答案和运行详情成果上的「导出」，接口 GET /api/runs/{id}/report.html，导出一个自包含的 HTML 文件。

• 正文由服务端渲染，不执行脚本也读得到（邮件附件预览常常不执行脚本）。
• 执行脚本后，每个数字、无证据的数字、可疑的表名字段名都点得开。面板是网页上证据面板同一个拼法的出处链（口径、来源、计算方式、SQL、被引用的行），封存状态逐项标明。
• 遮罩列照网页上的规矩写「已遮罩」。
• 没封存的运行照常导出，和在网页上读报告一个道理。

可验证报告：记录页「凭证详情」里的「导出可验证报告」，接口 GET /api/runs/{id}/bundle.html，是一份封存核对件。

• 收件人不连服务，在浏览器里重算哈希，核对每个数字、文档和运行记录没被改过。
• 数字的出处面板同样带口径、原式、代入式、输入和复算；口径卡输入指向的查询快照也随文件附带。

两种导出各记一条审计 report.exported。

复核套件

运行之外还有一组复核工具：双盲复算、反方审稿、审批质询、数字推演沙盘。双盲复算的裁决是人工步骤，可以驳回，也可以接驳回出口（见工作流）。裁判和核查的每日花费在多进程时全站一起算（见 PostgreSQL 与多进程）。