PaperSpine5 使用遥测（Usage Telemetry）实战指南：JSONL 记账、诚实计量与最终审计集成

AI 技能AI 写作人工智能深度研究AI 应用【免费下载链接】PaperSpinePaperSpine5 — local-first, evidence-bound paper research, writing, figures, review and delivery. Download: https://wubing2023.github.io/PaperSpine/v5/项目地址https://gitcode.com/gh_mirrors/pa/PaperSpine点击查看免费下载导读本文以 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采用JSONLJSON Lines格式每一行一个独立、完整的 JSON 对象对应一次模型调用或一个被委托的阶段执行。追加写入append意味着历史事件不会被覆盖天然形成可回放的审计轨迹。从 usage_ledger.py 的源码常量可以还原完整的字段契约2.1 必填字段每个事件都必须出现REQUIRED_FIELDS (timestamp, stage, role, model, reasoning_effort, usage_source, gate_result, retry)字段含义说明timestamp事件时间戳推荐 ISO 8601 格式如2026-08-22T12:00:00Zstage流水线阶段如research、planning、drafting、latex、word、final_audit等role角色如sota-mapper、renderer、reviewer-method等对应委托阶段或调用角色model实际模型标识宿主管理时可写host-managedreasoning_effort推理强度无法获知时写unknownusage_source用量来源三选一api、host、telemetry_unavailable见第三节gate_result关卡结果如pass用于把用量与阶段门禁结果关联retry重试序号整数0表示首次尝试校验逻辑usage_ledger.py要求这些字段必须存在且非空字符串否则该行记为 findingmissing field。2.2 可选计量字段宿主暴露 token 时记录TOKEN_FIELDS (input_tokens, cached_input_tokens, reasoning_tokens, output_tokens)字段含义input_tokens输入 token 数cached_input_tokens缓存命中cached输入 token 数reasoning_tokens推理reasoningtoken 数output_tokens输出 token 数只有宿主真实暴露这些数值时才写入。校验器要求它们必须是非负整数否则记为must be a non-negative integer for measured usageusage_ledger.py。2.3 可审计字段宿主可用时补充记录当宿主提供以下信息时一并写入它们让未变化重试与昂贵操作复用变得可审计elapsed_ms耗时毫秒数非负整数execution_reuse取值hit命中复用、miss未命中、not_applicable不适用execution_receipt执行回执路径如execution_receipts/pdf-render.jsonfailure_category失败分类如输入、依赖、环境、瞬时供应商、权限、契约、科研阻塞等input_hashesSkill/输入工件的哈希列表或对象用于把事件绑定到具体输入快照output_artifacts输出工件路径列表如[sota_gap_map.md]、[visual_audit/pages]。值得注意的交叉校验当execution_reuse为hit或miss时execution_receipt必须同时存在usage_ledger.pyfailure_category若出现则必须非空input_hashes必须是 list 或 dictoutput_artifacts必须是 listusage_ledger.py。三、usage_source 三态与不可用的诚实处理usage_source只有三个合法取值这在源码中直接定义为集合USAGE_SOURCES {api, host, telemetry_unavailable}取值语义api用量来自 API 层暴露的 usage 对象host用量来自宿主host暴露的用量信息telemetry_unavailable宿主未返回任何 usage 对象无法计量核心规则绝不允许根据文件字节数估算计费 token。如果宿主没有返回用量对象就把usage_source记为telemetry_unavailable并在telemetry_note中写清原因如host returned no usage object同时省略全部 token 计数字段。这样既保留了执行回执的完整性又不假装它是账单。校验器对telemetry_unavailable事件有一条专门的强制约束telemetry_unavailable必须附带非空的telemetry_note否则记 findingusage_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返回okTrue且状态为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 pdftoppmexact-version-or-path \ --input paper_rewriting_output/final_paper/paper.pdf \ --output paper_rewriting_output/visual_audit/pages退出码语义源码见 execution_receipt.py0/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.pydist/claude/skills/paper-spine/scripts/usage_ledger.py等分发目录下存在字节级一致的副本已用 diff 确认IDENTICAL。6.1 命令行参数参数作用默认值output_dir位置参数输出目录脚本在该目录下查找usage_ledger.jsonl并写出聚合报告paper_rewriting_output--markdown打印 Markdown 格式报告关闭默认仍打印 Markdown见 6.3--json以 JSON 打印完整UsageResult含 totals、by_stage、findings关闭--write把聚合报告写入output_dir/token_budget_by_stage.md关闭6.2 状态语义PASS / UNAVAILABLE / FAIL脚本逐行解析 JSONL按utf-8-sig读取以兼容 BOM对每一行执行字段契约校验最终汇总出三种状态usage_ledger.pyPASS账本存在、所有事件格式良好、无任何 findingUNAVAILABLE账本所有事件都是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 Auditprogress_check.py。因此一个完整的审计收尾命令序列通常这样收场完整清单见 audit.mdpython 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_telemetryL147-L160单条telemetry_unavailable事件 非空telemetry_note校验okTrue、状态为UNAVAILABLE——证实全部不可计量但格式良好确实通过诚实性检查test_usage_ledger_validates_execution_reuse_receiptsL162-L191execution_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而不是被当成可计量数据——这与账本的诚实原则一脉相承。九、最佳实践小结每条调用/委托阶段追加一行事件按时间顺序 append永不覆盖、永不删除历史行形成完整审计轨迹。计量有据才填 token只有宿主/API 暴露了input_tokens、cached_input_tokens、reasoning_tokens、output_tokens才写入否则一律usage_source: telemetry_unavailable并附telemetry_note。绝不以字节估 token文件大小、页面数、字数都不是计费依据账本只记录真实可观测的用量。复用必须可审计execution_reuse: hit|miss必须伴随execution_receipt昂贵确定性操作的回执由execution_receipt.py哈希绑定管理。重试有界同命令同输入快照最多一次初始尝试加一次纠正重试retry字段如实记录第三次实质相同尝试应视为阻塞而非进展。门禁收尾必跑usage_ledger.py --markdown --write是最终审计的必备一步其退出码直接参与progress_check.py --gate final_audit的硬门判定。边界清醒遥测只是资源记录UNAVAILABLE状态通过诚实性检查不等于科研完成任何交付/投稿判定仍需以各就绪维度的真实检查为准。附相关文件导航遥测规范文档usage-telemetry.mdsrc/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 应用【免费下载链接】PaperSpinePaperSpine5 — local-first, evidence-bound paper research, writing, figures, review and delivery. Download: https://wubing2023.github.io/PaperSpine/v5/项目地址https://gitcode.com/gh_mirrors/pa/PaperSpine点击查看免费下载相关推荐Substrate 遥测计量Telemetry Meter用 OTLP Tee 按服务精确测量 Spans 与 Datapoints 流量Substrate 遥测计量Telemetry Meter用 OTLP Tee 按服务精确测量 Spans 与 Datapoints 流量 导读 Subs人工智能AI AgentAgent 沙箱云原生容器运行时零信任Visual Studio Code 扩展遥测Telemetry指南vscode/extension-telemetry 模块、用户知情权与最佳实践Visual Studio Code 扩展遥测Telemetry指南vscode/extension telemetry 模块、用户知情权与最佳实践 V文档教程Daft 使用统计遥测Telemetry机制详解数据采集范围、退出方式与源码实现Daft 使用统计遥测Telemetry机制详解数据采集范围、退出方式与源码实现 Daft 作为面向 AI 与多模态工作负载的高性能数据引擎在 docs大数据数据分析数据工程AI 应用上一篇如何轻松实现Windows和Office永久激活KMS智能激活终极指南下一篇告别连接烦恼1分钟搞定Windows苹果USB驱动安装创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考