企业官网建设流程全解析

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

导读

本文以 PaperSpine5 的 usage-telemetry.md 为骨架，系统讲解学术写作流水线中的"模型用量遥测"规范：每个模型调用或委托阶段如何向paper_rewriting_output/usage_ledger.jsonl追加一条 JSON 事件、当宿主不返回用量数据时如何以telemetry_unavailable诚实记账、以及如何用 usage_ledger.py 校验与聚合账本并接入final_audit硬门。读完本文，你将掌握可复制的 JSONL 事件字段契约、验证命令与三种状态语义（PASS/UNAVAILABLE/FAIL），并理解"遥测只记录资源消耗、不代替科研完成"这条设计边界。

一、遥测的定位：资源记录，不是完成证明

PaperSpine5 是一个 local-first、证据绑定的论文研究/写作/图表/审稿/交付工作流。在它的多阶段流水线中（研究、写作、审阅、LaTeX 组装、Word 交付、投稿包装等），每一次调用模型或委托某个阶段执行，都会产生真实的资源消耗。遥测账本的目的有两个：

• 可审计：让"同一命令在相同输入快照上"是否真的只执行了一次初始尝试加一次纠正重试、昂贵的确定性操作（如 PDF 渲染）是否被复用，都有据可查；
• 诚实：当宿主（host）不暴露用量数据时，绝不根据输出文件字节数估算计费 token，而是显式标记telemetry_unavailable。

SKILL.md 的守则同时划定了边界：任务状态本身绝不授权上传、发布、投稿、支付、许可、遥测或外部联系，任何此类动作都需要用户显式授权；遥测只是资源使用记录，不代表任何科研结论或完成状态。这与 current-method-routing.json 对 usage-telemetry.md 的定位一致："真实 usage 与调用/阶段绑定；只表示资源记录，不是科研完成"。

二、账本文件与事件结构：usage_ledger.jsonl 格式契约

遥测账本统一写入paper_rewriting_output/usage_ledger.jsonl，采用JSONL（JSON Lines）格式：每一行一个独立、完整的 JSON 对象，对应一次模型调用或一个被委托的阶段执行。追加写入（append）意味着历史事件不会被覆盖，天然形成可回放的审计轨迹。

从 usage_ledger.py 的源码常量可以还原完整的字段契约：

2.1 必填字段（每个事件都必须出现）

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

校验逻辑（usage_ledger.py）要求这些字段必须存在且非空字符串，否则该行记为 finding：missing <field>。

2.2 可选计量字段（宿主暴露 token 时记录）

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

只有宿主真实暴露这些数值时才写入。校验器要求它们必须是非负整数，否则记为must be a non-negative integer for measured usage（usage_ledger.py）。

2.3 可审计字段（宿主可用时补充记录）

当宿主提供以下信息时一并写入，它们让"未变化重试"与"昂贵操作复用"变得可审计：

• elapsed_ms：耗时毫秒数，非负整数；
• execution_reuse：取值hit（命中复用）、miss（未命中）、not_applicable（不适用）；
• execution_receipt：执行回执路径，如execution_receipts/pdf-render.json；
• failure_category：失败分类（如输入、依赖、环境、瞬时供应商、权限、契约、科研阻塞等）；
• input_hashes：Skill/输入工件的哈希（列表或对象），用于把事件绑定到具体输入快照；
• output_artifacts：输出工件路径列表，如["sota_gap_map.md"]、["visual_audit/pages"]。

值得注意的交叉校验：当execution_reuse为hit或miss时，execution_receipt必须同时存在（usage_ledger.py）；failure_category若出现则必须非空；input_hashes必须是 list 或 dict，output_artifacts必须是 list（usage_ledger.py）。

三、usage_source 三态与"不可用"的诚实处理

usage_source只有三个合法取值，这在源码中直接定义为集合：

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

核心规则：绝不允许根据文件字节数估算计费 token。如果宿主没有返回用量对象，就把usage_source记为telemetry_unavailable，并在telemetry_note中写清原因（如host returned no usage object），同时省略全部 token 计数字段。这样既保留了执行回执的完整性，又不假装它是账单。

校验器对telemetry_unavailable事件有一条专门的强制约束：telemetry_unavailable必须附带非空的telemetry_note，否则记 finding（usage_ledger.py）。也就是说，"诚实声明不可计量"本身是一等公民，而不是放任缺字段。

四、完整事件示例与字段解读

原文档给出了一条典型的"计量不可用"事件，可直接复用：

{"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}

解读：该事件属于research阶段的sota-mapper角色，模型由宿主管理（无法获知型号）、推理强度未知，宿主未返回 usage 对象，因此在telemetry_note中如实说明；输入哈希为空列表、输出工件为sota_gap_map.md，关卡结果为pass，这是首次尝试（retry: 0）。

对照测试 test_readiness_gates.py，仓库用几乎完全一致的事件验证了该形态：validate_usage返回ok=True，且状态为UNAVAILABLE。

再看一条"宿主可计量 + 执行复用"的完整事件（来源同样是测试用例 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":["a"*64],"output_artifacts":["visual_audit/pages"],"gate_result":"pass","retry":0,"elapsed_ms":42,"execution_reuse":"hit","execution_receipt":"execution_receipts/pdf-render.json"}

这里usage_source为host，四个 token 字段均为非负整数，execution_reuse为hit且携带了execution_receipt路径。测试同时证明：一旦把execution_receipt从该事件中移除，校验即失败，并报出requires execution_receipt的 finding——这正是"复用必须可审计"的落地体现。

五、重试边界与执行复用：execution-efficiency 契约

遥测字段里的execution_reuse、execution_receipt、retry并不是孤立的统计项，它们由 execution-efficiency.md 定义的行为契约约束：

• Bounded Failure Recovery（有界失败恢复）：对同一条命令、同一个未变化的输入快照，最多"运行一次 → 分类失败 → 做一次具体纠正 → 重试一次"，绝不允许第三次实质相同的尝试。第三次失败应报告阻塞点、确切证据、责任人和恢复动作，而不是继续重试。这正是retry字段存在的意义——它让"未变化重试"在账本里一目了然。
• Expensive Operation Receipt（昂贵操作回执）：对于 PDF 渲染、DOCX 渲染、格式转换、引文审计快照等确定性昂贵操作，可通过 execution_receipt.py 记录/校验哈希绑定的回执：

python scripts/execution_receipt.py check \ --receipt paper_rewriting_output/execution_receipts/pdf-render.json \ --operation pdf-render --tool "pdftoppm@<exact-version-or-path>" \ --input paper_rewriting_output/final_paper/paper.pdf \ --output paper_rewriting_output/visual_audit/pages

退出码语义（源码见 execution_receipt.py）：0/REUSABLE（操作、工具身份、输入快照、输出快照全部匹配，可复用输出）；3/MISS（需执行一次并校验结果后以record记录新回执）；2/ERROR（回执缺失或畸形，修复后重试，不得宣称缓存命中）。

• 诚实边界：回执复用只能证明"计算同一性"，不能推断scientific_content_ready、visual_ready、引文正确性、作者认可、投稿就绪或授权。一条 receipt 标识的是字节而非质量。这解释了为何遥测字段中execution_reuse: hit必须附带execution_receipt：复用必须基于可验证的哈希绑定，而不是口头声明。

phase-contracts.md 进一步把账本写入了阶段契约：严格模式的专家分工中，每个阶段"只读列出的输入、只写自己的输出，并向usage_ledger.jsonl追加一条执行回执"。

六、验证与聚合：usage_ledger.py 使用指南

原文档给出的标准验证命令：

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

该脚本在仓库中的权威位置是 usage_ledger.py（dist/claude/skills/paper-spine/scripts/usage_ledger.py等分发目录下存在字节级一致的副本，已用 diff 确认IDENTICAL）。

6.1 命令行参数

6.2 状态语义：PASS / UNAVAILABLE / FAIL

脚本逐行解析 JSONL（按utf-8-sig读取以兼容 BOM），对每一行执行字段契约校验，最终汇总出三种状态（usage_ledger.py）：

• PASS：账本存在、所有事件格式良好、无任何 finding；
• UNAVAILABLE：账本所有事件都是telemetry_unavailable、且格式完全良好、无 finding。这是"全部不可计量但诚实"的合法状态，原文档明确说明它通过诚实性检查；
• FAIL：账本缺失（usage_ledger.jsonl does not exist）、有空事件、存在非法 JSON、缺失必填字段、非法usage_source、token 字段非负整数约束被破坏、execution_reuse缺少回执等任何一项不满足。

脚本退出码为0（通过）或1（失败），可直接用于 CI 或门禁判断。

6.3 聚合输出：Token Budget by Stage

--write会把 Markdown 报告写入token_budget_by_stage.md。报告结构（usage_ledger.py）包含：

• 账本路径、状态、事件总数、不可用事件数；
• Measured Totals表：按stage分组的Input | Cached input | Reasoning | Output四类 token 合计；
• Findings列表：逐条列出校验发现的问题（无问题时为None）。

# Token Budget by Stage - Ledger: `paper_rewriting_output/usage_ledger.jsonl` - Status: PASS - Events: 12 - Telemetry unavailable events: 1 ## Measured Totals | Stage | Input | Cached input | Reasoning | Output | |---|---:|---:|---:|---:| | drafting | 51200 | 30000 | 8000 | 12400 | | latex | 3100 | 1200 | 500 | 980 | ...

若没有任何可计量事件（全部telemetry_unavailable），表格中会输出一行| telemetry_unavailable | - | - | - | - |占位。

七、与最终审计（final_audit）的集成

遥测账本不是可选的"锦上添花"，而是最终审计的必备工件。audit.md 的第 17 项检查明确写道："Usage telemetry 包含实测用量或显式telemetry_unavailable回执；文件字节绝不代表计费 token"。其 Required Outputs 清单也把usage_ledger.jsonl与token_budget_by_stage.md列为必须产物（audit.md）。

在硬门层面，progress_check.py 把usage_ledger.jsonl和token_budget_by_stage.md列为final_audit阶段的必需工件；其_run_final_audit_gate在门禁执行时会把usage_ledger.py与visual_readiness_check.py、publication_surface_check.py、metadata_readiness_check.py一起以--markdown --write实跑一遍，任何非零退出码都会导致GATE FAILED: Final Audit（progress_check.py）。

因此，一个完整的审计收尾命令序列通常这样收场（完整清单见 audit.md）：

python scripts/usage_ledger.py paper_rewriting_output --markdown --write python scripts/progress_check.py paper_rewriting_output --gate final_audit python scripts/progress_check.py paper_rewriting_output --markdown --write

在最终审计全通过之前，progress_check.py --gate final_audit是权威硬门：它会重跑包括 usage-ledger 检查在内的整套校验，并对任何非零退出码判失败（audit.md）。

八、源码级验证行为：测试用例印证

仓库测试对遥测契约的验证集中在 test_readiness_gates.py 的UsageAndVisualTests类：

• test_usage_ledger_accepts_explicit_unavailable_telemetry（L147-L160）：单条telemetry_unavailable事件 + 非空telemetry_note，校验ok=True、状态为UNAVAILABLE——证实"全部不可计量但格式良好"确实通过诚实性检查；
• test_usage_ledger_validates_execution_reuse_receipts（L162-L191）：execution_reuse: hit且带execution_receipt时通过；移除execution_receipt后失败并报requires execution_receipt——证实复用审计约束真实生效。

此外，test_skill_structure.py 把src/skill/references/usage-telemetry.md和src/scripts/usage_ledger.py纳入技能结构校验清单，确保分发技能包中遥测文档与脚本始终齐备。证据链相关的遥测行为也出现在 test_evidence_grounded_review.py：当工具回执的usage.telemetry_status为unavailable时，会被如实披露并计入telemetry_unavailable_count，而不是被当成可计量数据——这与账本的诚实原则一脉相承。

九、最佳实践小结

1. 每条调用/委托阶段追加一行：事件按时间顺序 append，永不覆盖、永不删除历史行，形成完整审计轨迹。
2. 计量有据才填 token：只有宿主/API 暴露了input_tokens、cached_input_tokens、reasoning_tokens、output_tokens才写入；否则一律usage_source: telemetry_unavailable并附telemetry_note。
3. 绝不以字节估 token：文件大小、页面数、字数都不是计费依据，账本只记录真实可观测的用量。
4. 复用必须可审计：execution_reuse: hit|miss必须伴随execution_receipt；昂贵确定性操作的回执由execution_receipt.py哈希绑定管理。
5. 重试有界：同命令同输入快照最多一次初始尝试加一次纠正重试，retry字段如实记录，第三次实质相同尝试应视为阻塞而非进展。
6. 门禁收尾必跑：usage_ledger.py --markdown --write是最终审计的必备一步，其退出码直接参与progress_check.py --gate final_audit的硬门判定。
7. 边界清醒：遥测只是资源记录，UNAVAILABLE状态通过诚实性检查不等于科研完成；任何交付/投稿判定仍需以各就绪维度的真实检查为准。

附：相关文件导航

• 遥测规范文档：usage-telemetry.md（src/skill/references/usage-telemetry.md为同源权威版本）
• 校验/聚合脚本：usage_ledger.py
• 执行效率与复用契约：execution-efficiency.md
• 执行回执工具：execution_receipt.py
• 审计阶段与硬门：audit.md、progress_check.py
• 阶段契约：phase-contracts.md
• 方法路由定位：current-method-routing.json
• 测试印证：test_readiness_gates.py、test_evidence_grounded_review.py

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