Codewhale Runtime Receipts 解读：基于 Rust 运行时持久化记录的可审计收据导出设计

Codewhale Runtime Receipts 解读基于 Rust 运行时持久化记录的可审计收据导出设计【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhaledocs/RECEIPTS.mdRuntime Receipts是 Codewhale 终端编码代理项目中关于只读运行时收据receipt导出的协议设计说明它规划了一套让本地监督方在不抓取终端屏幕文本的前提下审计单次已完成的 turn对话轮次的方案并已经落地了其中代码评审收据review receipt这一 pre-push 交接产物。读完本文你将理解收据需要覆盖哪些运行时记录、为什么它被刻意设计成本地只读、无副作用、不含思维链原文以及评审收据的字段语义、命令用法与逐层落地路径——所有内容均与仓库源码中的持久化结构与 CLI 实现一一对应。为什么需要运行时收据在一次 Codewhale 会话thread中一个 turn 从模型调用、工具执行到审批决策会产生大量持久化记录。若要由本地监督方审计某一 turn 做了什么传统做法是去解析终端 transcript屏显文本这种方式脆弱且无法反映结构化事实。docs/RECEIPTS.md提出的目标是让本地监督方在不做终端屏幕抓取的前提下审计一个已完成的 turn。收据应当汇总 Codewhale 运行时Runtime本身已经拥有的持久化记录主要包括线程元数据thread metadataturn 状态turn statusturn 内的条目turn items事件序列血缘event sequence lineage可用时的用量统计usage审批决策approval decisions副作用边界side-effect boundaries换句话说收据不是新造的审计数据而是把运行时已经持久化的事实以确定性、可校验的形式重新编排后输出。Non-Goals收据刻意不做什么以下约束是协议的一部分任何实现都不应越过这些边界。收据不是安全认证safety certification、provider 兼容性认证或托管证明hosted attestation。生成收据的过程不得调用 provider、执行工具、写记忆memory、写项目文件、变更运行时状态或暴露 API 密钥。收据默认不得导出原始思维链chain-of-thought或私有推理内容。当需要表达推理保管reasoning custody状态时应当使用稳定的 item id、计数、哈希或显式unavailable字段而不是原始隐藏内容。这些Non-Goals直接决定了后文的 Schema 设计与 Builder Rules收据必须可以被安全地生成与共享因为它不是一份证明任何事的可信凭证而是一份事实摘要。候选交互面CLI 与本地 Runtime API文档给出了两类候选的本地导出入口codewhale receipt export --thread thread_id --turn turn_id --format json GET /v1/threads/{thread_id}/turns/{turn_id}/receipt文档明确指出两个交互面都应共享既有的 Runtime API 鉴权边界且只允许读取已持久化的运行时记录与只追加append-only的事件。这一点在仓库中可以找到对应的鉴权模型佐证docs/RUNTIME_API.md 描述了 Runtime token 的读取顺序--auth-token其次CODEWHALE_RUNTIME_TOKEN、DEEPSEEK_RUNTIME_TOKEN并约定--insecure-no-auth仅可用于 loopback 场景非 loopback 绑定前必须配置 token防止密钥泄露。从源码结构看crates/protocol/src/runtime/mod.rs 定义了RuntimeEventEnvelope含schema_version、seq、event、kind、thread_id、turn_id、item_id、timestamp、payload事件以单调递增的seq追加落盘——这正是收据append-only 事件假设的底层支撑。需要注意receipt export命令与 HTTP receipt 端点在当前仓库中尚属协议草案protocol note非已实现端点。已实现的收据能力是下一节的 review receipt。Review Receipts已经落地的 pre-push 交接收据codewhale review的收据能力在仓库中已经实现。它解决的具体痛点是本地评审diff review与真正把变更推到远端之间需要一份可离线交接的审计产物——记录评审了哪个 diff、评审结论是什么但不推送、不打 tag、不创建 PR也不声称替代维护者评审。写收据codewhale review --write-receiptcodewhale review --write-receipt会把被评审 diff 的本地 JSON 收据写入 Codewhale 状态目录下的review-receipts/除非用--receipt-path path指定自定义路径。它的数据来源路径在源码中可查write_review_receipt调用codewhale_config::ensure_state_dir(review-receipts)并落盘 pretty JSON见 crates/tui/src/tools/review.rs这印证了文档所述state directoryreview-receipts/的默认位置。当前收据包含以下字段crates/tui/src/tools/review.rs 的结构体定义与文档一致字段语义diff_fingerprint被评审 diff 的 SHA-256 指纹provider/model实际路由所用的评审 provider 与模型checks_run关联到收据上的本地检查项空数组表示未附加检查已附加的检查必须上报通过状态findings结构化评审输出中的 issue/suggestion 计数及 issue 位置unresolved_risk由未解决 findings 保守推导出的风险摘要review_content_sha256评审文本的 SHA-256收据刻意不包含原始 diff 正文。因此文档给出明确操作指引变更 diff 后必须重新执行codewhale review --write-receipt在 PR 交接中复用旧收据前应先比对diff_fingerprint。源码侧的build_review_receiptcrates/tui/src/tools/review.rs正是通过diff_fingerprint(diff)与sha256_hex(review_content)计算这两个指纹diff 变了指纹自然失效。校验收据codewhale review --check-receiptcodewhale review --check-receipt是本地 pre-push 门槛检查它不调用模型只做本地比对用--receipt-path path指定收据或自动寻找与当前 diff 指纹匹配的最新本地收据当出现以下任一情况时以非零退出码失败当前 diff 与收据指纹不再匹配收据 schema 版本不受支持收据带有未解决风险unresolved risk附加的检查项未通过。参数校验逻辑在 crates/tui/src/lib.rs--receipt-path必须配合--write-receipt或--check-receipt使用且二者互斥。校验实现validate_review_receipt_for_diffcrates/tui/src/tools/review.rs依次核对 schema 版本、diff 指纹、unresolved_risk.unresolved与checks_run中是否有未通过项——与文档列出的四类失败条件一一对应。无匹配收据时会提示先运行--write-receipt或显式传入--receipt-path。结合--json标志run_review_receipt_check还会输出结构化的校验结果passed、diff_fingerprint、receipt_fingerprint、unresolved、risk_level便于接入 CI。当前数据来源收据构建器所需的持久化记录一次完整 turn 的收据必须建立在运行时已经持久化的四类记录之上。文档列出的记录与源码一一对应全部定义在 crates/tui/src/runtime_threads.rsThreadRecordL631model、workspace、mode、shell/trust/auto-approve 标志、title、任务关联task_id、以及最新 turn 元数据latest_turn_id等。TurnRecordL709turn 状态RuntimeTurnStatus、输入摘要、时间戳、时长、usage、错误、steer 计数steer_count与 item id 列表item_ids还记录了路由后的有效 provider/model 与计费模式等。TurnItemRecordL892条目类型TurnItemKind、生命周期状态TurnItemLifecycleStatus如 Queued/InProgress/Completed/Failed/Interrupted/Canceled、摘要、可选 detail、元数据、产物引用artifact_refs与条目时间戳。RuntimeEventRecordL913thread id、turn id、item id、事件名、JSON payload、时间戳以及每个运行时存储内单调递增的seq值。关键原则并非每个收据字段在今天都能从这些记录中填满。如果某 provider 或存储没有持久化某个值收据应当如实输出available: false或unavailable绝不能从 UI 文本去反推推断。这保证了收据的可审计性——任何猜测出来的数字都会破坏审计价值。草拟 Schema 形态文档给出了一份完整 JSON 示例收据基于版本化 schemaschema_id承载线程配置、turn 时间线、工具调用血缘、用量证据、事件序列边界、审批与副作用边界以及声明上限{ schema_id: codewhale.conformance-receipt/v0, thread: { id: thr_..., model: deepseek-v4-pro, mode: agent, auto_approve: false, trust_mode: false, allow_shell: false }, turn: { id: turn_..., status: completed, started_at: 2026-06-02T01:00:00Z, ended_at: 2026-06-02T01:00:12Z, duration_ms: 12000 }, reasoning_custody: { raw_reasoning_exported: false, available: false, reason: reasoning blocks are not persisted as receipt-ready records }, tool_lineage: { tool_call_count: 1, tool_result_count: 1, unmatched_tool_call_ids: [], unmatched_tool_result_ids: [] }, usage_evidence: { available: true, usage: { prompt_tokens: 123, completion_tokens: 45 }, provider_cache_breakdown_available: false }, source_event_lineage: { first_seq: 10, last_seq: 42, event_count: 33, missing_event_ranges: [] }, side_effect_boundary: { approval_required_count: 1, approval_allowed_count: 0, approval_denied_count: 1, command_execution_count: 0, file_change_count: 0, sandbox_denied_count: 0 }, claim_ceiling: [ local_receipt_only, not_safety_certification, not_provider_compatibility_certification ] }对这份 schema 可以做如下理解thread/turn两段把被审计对象钉死哪个线程、哪种模式与审批姿态、哪一次 turn、起止与耗时——对应ThreadRecord与TurnRecord中可直接读取的字段。reasoning_custody用available: false显式表达思维块未按可生成收据的记录持久化而不是输出推理原文。tool_lineage记录工具调用/结果计数并要求列出找不到配对的 idunmatched_tool_call_ids/unmatched_tool_result_ids用于暴露工具血缘不完整的 turn。source_event_lineage以first_seq/last_seq/event_count/missing_event_ranges表达事件序列的边界与缺口——这与 crates/protocol/src/runtime/mod.rs 中事件信封携带单调seq的设计相呼应。side_effect_boundary汇总审批require/allow/deny、命令执行、文件变更与沙箱拒绝的计数直接回答这次 turn 到底触碰了多少外部副作用。claim_ceiling把收据的声明上限显式写进文档本身防止下游把收据误当作安全或兼容性认证。Builder Rules确定性与保守性收据构建器builder应当具备两条核心品质确定性与保守性。文档给出 7 条规则按 id 加载 thread 与 turn随后拒绝任何thread_id不匹配的数据。只加载该 turn 引用到的 item id。读取该 thread 的事件记录并按turn_id过滤。用first_seq、last_seq及检测到的缺口保留事件序列边界。仅依据类型化记录或已知事件名统计审批、命令、文件、沙箱与工具事件。不可用的证据要显式标记为不可用而不是从自由文本摘要中推导。除非后续 schema 引入独立的脱敏redaction策略否则不输出既有 item 摘要之外的原始工具输出。这些规则本质上都在服务同一目标让收据成为一份可重复生成、可逐项核对的审计物。规则 5 的意义在于计数必须来自类型化记录或白名单事件名避免解析自由文本产生误报规则 6 与Current Data Sources一节中的available: false原则一脉相承。增量实施路径文档建议按风险递增的顺序逐步落地先确立本协议说明敲定字段名与 Non-Goals增加协议结构体protocol structs并为 completed、failed、approval-denied 三种 turn 状态准备 JSON 快照 fixtures在ThreadRecord、TurnRecord、TurnItemRecord、RuntimeEventRecord之上实现一个纯函数式 builder无副作用暴露本地 Runtime API 端点增加 CLI 导出命令与可选的校验模式。从仓库现状看这条路径的1 一部分 2/3已经在review receipt分支上得到验证字段名与边界modepre_push_review、targetworking-tree已在 crates/tui/src/tools/review.rs 附近的测试中固化builderbuild_review_receipt、落盘write_review_receipt、查找latest_review_receipt_for_diff、校验validate_review_receipt_for_diff与 CLI 接线均已实现并带有测试覆盖。未来的turn 级 receipt export可以复用同一套指纹、schema 版本与仅读取持久化事实的约束。小结Runtime Receipts 的核心理念可以概括为一句话只汇总运行时已经拥有的持久化事实显式承认缺失绝不推断或捏造。对使用者而言今天的可直接落地能力是codewhale review --write-receipt/--check-receipt构成的 pre-push 收据闭环——用 SHA-256 diff 指纹把评审过哪个 diff、结论如何钉死成一份可离线比对的 JSON 文件对协议演进而言docs/RECEIPTS.md为未来的 turn 级只读导出提供了 schema 草案、builder 规则与 5 步实施路径任何实现都必须遵守本地只读、无副作用、不导出思维链原文的边界。若要在自己的流水线中接入评审收据建议从对照diff_fingerprint的--check-receipt门槛开始并将非零退出码作为 push 前的强制门禁。【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考