企业官网建设流程全解析

• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用

导读

本文围绕 PaperSpine 的用量遥测机制展开，系统讲解paper_rewriting_output/usage_ledger.jsonl的字段契约、usage_source取值语义、"绝不从文件字节估算计费 token" 的诚实性铁律，以及usage_ledger.py校验与按阶段聚合命令的完整用法。读完本文，你将掌握如何为每次模型调用或委派阶段追加一条合法遥测事件、如何让一个"全部不可计量"的账本也能通过诚实性检查，以及如何把遥测接入最终审计硬门。

1. 遥测账本要解决什么问题

PaperSpine 的论文生产流程由多个阶段（research / planning / writing / latex / audit 等）和多个角色（sota-mapper、reviewer、renderer 等）组成，每一次模型调用或委派阶段都会消耗宿主（host）侧的资源。若每个阶段各自散落记录，最终无法回答两个基本问题：

• 同一输入快照上的未变更重试是否被重复计费、重复执行？
• 高开销的确定性操作（如 PDF 渲染、DOCX 渲染、格式转换）是否被安全复用？

usage-telemetry.md 给出的答案是：将每一次模型调用或委派阶段追加为paper_rewriting_output/usage_ledger.jsonl中的一行 JSON 对象，用统一的字段契约承载时间戳、阶段、角色、模型、推理力度、用量来源与 token 明细，从而让重试和复用都变得可审计。

该文档在 audit.md 的必需检查清单中位列第 17 项：

Usage telemetry contains measured usage or explicittelemetry_unavailablereceipts; file bytes never stand in for billed tokens.

也就是说，遥测账本不仅是成本台账，更是交付审计的一部分。

2. 账本文件与写入方式

• 文件位置：paper_rewriting_output/usage_ledger.jsonl
• 格式：JSONL（JSON Lines），每行一个独立的 JSON 对象，逐事件追加写入
• 写入时机：每次模型调用（model call）或委派阶段（delegated phase）完成后

从 usage_ledger.py 的读取逻辑（L46-57）可以看到校验器对每一行逐行json.loads解析，跳过空行；任何一行非法 JSON 都会产生一条line N: invalid JSON (...)的 finding。因此一行一个完整对象、UTF-8 编码是硬性要求。

3. 必填字段契约

usage_ledger.py 中定义了八个必填字段：

REQUIRED_FIELDS = ("timestamp", "stage", "role", "model", "reasoning_effort", "usage_source", "gate_result", "retry")

校验器要求这些字段存在且 strip 后非空，空值等同于缺失（L59）。stage与role同时用于把事件归入具体的阶段聚合桶。

4.usage_source：用量来源三态

usage_ledger.py 将用量来源严格限定为三个取值：

USAGE_SOURCES = {"api", "host", "telemetry_unavailable"}

一个常见误区是：当宿主不返回用量时，把 token 字段写成 0 再标api。校验器对此的回应是：telemetry_unavailable分支在 L65-68 直接continue，不会把 0 计入总额；而写成 0 的"伪测量"会被当作测量值参与累加，从语义上混淆了"未计量"与"真实为 0"。

5. Token 明细字段：仅在宿主暴露时记录

usage_ledger.py 定义了四个 token 字段：

TOKEN_FIELDS = ("input_tokens", "cached_input_tokens", "reasoning_tokens", "output_tokens")

校验规则（L69-75）：对telemetry_unavailable之外的事件，这四个字段必须是大于等于 0 的整数，否则产生 finding；合法的值会被累加到全局总额与对应stage的聚合桶中。若宿主不暴露用量，则省略 token 字段，只写telemetry_unavailable与telemetry_note。

6. 可选审计字段：让复用与重试可追溯

当宿主可用时，文档要求尽可能补充以下字段：

EXECUTION_REUSE_VALUES = {"hit", "miss", "not_applicable"}

关键联动规则（L88-89）：只要execution_reuse是hit或miss，就必须提供execution_receipt指向具体的执行回执文件；只有not_applicable（未做复用判定）才允许不带回执。这一约束使得"声称复用了昂贵的 PDF 渲染结果"必须有哈希绑定的回执背书，否则账本直接 FAIL。

执行回执本身由 execution_receipt.py 生成与校验：record写入、check核对，返回码0（REUSABLE）、3（MISS）、2（ERROR）。回执内容包含操作名、工具身份（--tool需精确到可执行文件版本或路径）、输入/输出快照的 SHA-256 摘要，且明确标记scientific_readiness_inferred: False、visual_readiness_inferred: False——计算上的缓存命中绝不等于科学或视觉就绪。

7. 诚实性铁律：禁止从文件字节估算计费 token

这是 usage-telemetry.md 的核心原则，也是一条不可妥协的边界：

Never estimate billed tokens from file bytes inside this ledger. If the host does not return usage, logtelemetry_unavailableexplicitly and omit token counts. This preserves the execution receipt without pretending it is a bill.

即：

1. 永远不要依据输出文件大小、输入字节数等推算"计费 token"并写入账本；
2. 宿主不返回 usage 时，显式记录usage_source: "telemetry_unavailable"并省略 token 字段；
3. 这样做的意义是：执行回执（execution receipt）依然完整保留，但账本不会假装自己是一张账单。

同样的精神贯穿 execution-efficiency.md（结尾处）："Record measured tokens ... when the host exposes them. Never estimate billed tokens from file size."——只有宿主真实暴露的测量值才能入账。

8. 完整事件示例

8.1 不可计量事件（文档原例）

{"timestamp":"2026-08-22T12:00:00Z","stage":"research","role":"sota-mapper","model":"host-managed","reasoning_effort":"unknown","usage_source":"telemetry_unavailable","telemetry_note":"host returned no usage object","input_hashes":[],"output_artifacts":["sota_gap_map.md"],"gate_result":"pass","retry":0}

字段解读：

• timestamp：ISO 8601 UTC 时间；
• stage/role：本事件归属research阶段的sota-mapper角色；
• model：宿主托管模型，无法获知具体型号，写host-managed；
• reasoning_effort：宿主未暴露，写unknown；
• usage_source：telemetry_unavailable，触发"必须带 note"规则；
• telemetry_note：说明具体原因host returned no usage object——这一字段是 unavailable 事件的强制字段（缺失即 FAIL，见 usage_ledger.py）；
• input_hashes：输入工件哈希列表，此处为空数组；
• output_artifacts：产出工件路径列表["sota_gap_map.md"]；
• gate_result：pass；
• retry：0，表示首次尝试。

注意：这个事件没有input_tokens等 token 字段——这正是"不可计量就不虚报"的标准写法。

8.2 可计量 + 复用命中事件

参照 tests/test_readiness_gates.py 的测试样例，一个带完整可选字段的事件形如：

{"timestamp":"2026-09-01T00:00:00Z","stage":"latex","role":"renderer","model":"host-managed","reasoning_effort":"unknown","usage_source":"host","input_tokens":0,"cached_input_tokens":0,"reasoning_tokens":0,"output_tokens":0,"input_hashes":["<sha256 hex of input snapshot>"],"output_artifacts":["visual_audit/pages"],"gate_result":"pass","retry":0,"elapsed_ms":42,"execution_reuse":"hit","execution_receipt":"execution_receipts/pdf-render.json"}

该样例同时验证了 L88-89 的联动规则：execution_reuse: "hit"必须伴随execution_receipt；测试随后pop掉回执字段重写文件，校验器立即报requires execution_receipt（L187-191）。

9. 校验与按阶段聚合命令

在仓库根目录执行：

python scripts/usage_ledger.py paper_rewriting_output --markdown --write

9.1 参数说明

由 usage_ledger.py 的parse_args定义：

不带任何参数时，main()（L125-137）默认打印 Markdown；同时给--markdown与--json时二者都输出。退出码：validate().ok为真返回0，否则返回1（L137）——这正是它能被progress_check.py --gate final_audit当作硬门依赖的原因。

9.2 输出：token_budget_by_stage.md

--write生成的报告由to_markdown()（L99-122）组织，结构如下：

• 标题# Token Budget by Stage；
• 元信息：账本路径、Status、Events（事件总数）、Telemetry unavailable events（不可计量事件数）；
• ## Measured Totals表格：按阶段聚合的Input | Cached input | Reasoning | Output四列；
• 若没有任何可计量事件，表格回退为一行| telemetry_unavailable | - | - | - | - |；
• ## Findings一节列出所有校验发现，无问题时为- None。

10. 状态语义：UNAVAILABLE / PASS / FAIL

usage_ledger.py 对整份账本给出三态结论：

status = "UNAVAILABLE" if events and unavailable_count == len(events) and not findings else ("PASS" if not findings else "FAIL")

"全 unavailable 但格式良好"是一个合法的通过态——这是本文档最容易被忽视也最重要的语义：诚实申报"没有测量值"好过伪造测量值。反之，账本缺失（L43-44 报usage_ledger.jsonl does not exist）、空账本（L92-93 报usage ledger contains no events）或格式损坏都会 FAIL。

该行为有测试背书：tests/test_readiness_gates.py 中test_usage_ledger_accepts_explicit_unavailable_telemetry用与文档示例同构的事件写入临时账本，断言validate_usage(path).ok且status == "UNAVAILABLE"。

11. 与执行效率约束的联动

usage-telemetry.md 明确要求阅读 execution-efficiency.md，其核心约束是：

同一命令、同一输入快照，不允许超过"一次初始尝试 + 一次修正重试"。

即同一命令同一输入下最多执行两次：首次执行 → 分类失败（输入 / 依赖 / 环境 / 瞬态 / 权限 / 契约 / 科学阻塞）→ 做一次针对性修正 → 重试一次；第三次实质性相同的尝试就是阻塞（blocker），而不是进展。retry字段正是为了在账本中暴露这一序列——retry: 0是首次尝试，retry: 1是那次受允许的修正重试。

同时，execution_reuse: "hit"指向的执行回执（execution_receipts/pdf-render.json等）由 execution_receipt.py 维护，存放于paper_rewriting_output/execution_receipts/目录、位于被哈希的输出目录之外，避免回执本身污染输出快照。

12. 在最终审计硬门中的位置

遥测账本不是可选项，而是 audit.md 定义的审计阶段必需产物与硬门输入：

1. 必需输出（audit.md 第 105 行）：usage_ledger.jsonl、token_budget_by_stage.md；
2. 硬门重跑（audit.md 第 135-139 行）：progress_check.py --gate final_audit作为权威硬门，会重跑 usage-ledger 检查，任一非零退出码即失败；
3. 阶段契约（phase-contracts.md）：严格模式下每个专职阶段"只读列出输入、只写自己的输出，并向usage_ledger.jsonl追加一条执行回执"。

progress_check.py 的final_audit阶段定义中，usage_ledger.jsonl与token_budget_by_stage.md均被列为该阶段必须存在的产物。

13. 测试验证：账本行为是被锁定的

除了上文引用的两个测试，tests/test_readiness_gates.py 的UsageAndVisualTests覆盖了：

• 不可计量即通过：telemetry_unavailable+telemetry_note→UNAVAILABLE（L147-160）；
• 复用必须有回执：execution_reuse: "hit"缺execution_receipt→ FAIL，finding 含requires execution_receipt（L162-191）。

这些测试证明"诚实性优先 + 复用可审计"不是文档口号，而是validate()中被逐行执行并锁定的行为契约。

14. 遥测在相邻检查器中的同源原则

同一诚实性原则也出现在其他检查器中，可作为交叉印证。例如 evidence_grounded_review.py 对每条工具回执的usage.telemetry_status只接受measured/unavailable，并统计telemetry_unavailable_count；遇到不可计量时给出警告："usage telemetry is unavailable; zero values are not measured cost"——零不是测量的成本。这与账本的UNAVAILABLE语义完全一致：宁可明确申报不可计量，也不要用零值假装已计量。

结语：一张诚实的账本比一张漂亮的账本更重要

PaperSpine 的用量遥测设计反复强调同一件事：遥测记录的是"资源使用事实"，不是"账单"。通过usage_ledger.jsonl的八项必填字段、三态usage_source、可选的复用审计字段，以及"全 unavailable 也通过"的宽容语义，它同时满足了三个目标：

1. 可审计：重试次数、复用命中与回执路径逐事件可查；
2. 可聚合：token_budget_by_stage.md给出按阶段、分 token 类型的预算视图；
3. 诚实：没有测量值就如实申报，绝不从文件字节虚构计费数字。

无论是接入 progress_check.py 的final_audit硬门，还是作为 audit.md 的第 17 项检查，这张账本都只回答一个问题：资源是怎么用的——而论文是否可交付，仍然由科学与视觉就绪性等独立维度裁决，遥测永远不能替代它们。

• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用