claw-code G004 事件与报告契约指南Lane 事件、报告 Schema v1 与能力协商的机器可信互操作规范【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code导读本文是 claw-code 仓库中 ROADMAP Phase 2「G004 events/reports」契约的完整解读围绕 docs/g004-events-reports-contract.md 展开并结合 lane_events.rs、report_schema.rs 与 ROADMAP.md 的源码与验收标准讲清 lane 事件流、报告 Schema v1、批准令牌链与能力协商四类互操作契约的字段语义、最小消费规则与验证方式。读完本文你将掌握如何按规范消费结构化 Lane 事件而不再依赖解析终端文本如何理解规范报告的 canonical payload 与派生 projection 之间的关系以及如何在混合版本消费者环境中做安全、可审计的降级与授权。一、G004 是什么一份给契约消费者的互操作指南G004 是 claw-code 在 Stream 2G004-events-reports团队运行期间文档捕获于 2026-05-14沉淀的契约指引。它的定位非常明确它不是 task 5 的实现映射而是 lane-event、report-schema、approval-token、capability-negotiation 四条 lane 落地后消费者应当依赖的互操作契约说明。其价值在于把机器可信任作为第一原则下游消费者如 clawhip、监控与看板应当消费结构化事件与报告而不是从终端文本pane text里猜测状态。全仓库的证据链如下契约需求源头ROADMAP.md Phase 2 §4.5–§4.7会话事件排序与终态调和、事件来源标注、会话身份完整性、§4.25–§4.26消费者能力协商、自描述报告 Schema、§4.32确定性投影/脱敏可复现、§4.34下游一致性测试契约、§4.37–§4.40策略拦截交接、所有者批准令牌、一次性使用与回放防护、委托链可追溯。实现与所有者锚点lane_events.rs、report_schema.rs两者经 lib.rs 导出。验证证据g004-events-reports-verification-map.md。下表是原文档给出的来源真相锚点可直接作为查阅索引契约族Roadmap 锚点当前实现 / 所有者锚点消费者指引Canonical lane eventsROADMAP.mdPhase 2 §4、§4.5、§4.6、§4.7rust/crates/runtime/src/lane_events.rsLaneEventName、LaneEventStatus、LaneEventMetadata、终态调和辅助函数消费event、status、emittedAt、metadata字段作为规范状态流存在结构化事件时不要从终端文本推断 lane 状态。Report schema v1 and projectionsROADMAP.md§4.25–§4.34Stream 2 report-schema lane / fixtures把报告视为带版本号的规范载荷 派生投影。投影只有在具备显式来源兼容降级、脱敏策略、截断、源缺失时才能省略或变换字段。Policy-blocked handoff and approval-token chainROADMAP.md§4.37–§4.39Stream 2 approval-token lane把策略拦截与所有者批准视为类型化工件而非散文。只有当批准令牌匹配 actor、策略、动作、repo/branch/commit 范围、过期时间与一次性使用状态时才执行例外。Capability negotiationROADMAP.md§4.25、§4.26、§4.32、§4.34Report-schema/projection fixtures 与一致性用例消费者在依赖精简载荷之前必须先声明其支持的 Schema 版本、可选字段族、投影视图、脱敏语义与降级处理方式。二、Lane 事件契约第一块机器可信表面Lane 事件流是 Stream 2 第一块机器可信任的表面。契约要求消费者在读取LaneEvent载荷时遵守以下不变量。2.1 事件名称event类型化事件名LaneEventName在 lane_events.rs 中定义序列化到线上时使用#[serde(rename ...)]声明的点分名称。测试 canonical_lane_event_names_serialize_to_expected_wire_values 逐一断言了每个变体到 wire value 的映射。当前完整集合按族划分如下族事件名wire value语义核心 lane 生命周期lane.started、lane.ready、lane.blocked、lane.red、lane.green、lane.finished、lane.failedlane 启动、就绪、阻塞、红/绿状态、完成与失败提示投递lane.prompt_misdelivery提示被投递到错误的会话/lane源码额外保留的族提交与合并流lane.commit.created、lane.pr.opened、lane.merge.ready、lane.merged提交创建、PR 打开、合并就绪与合并完成分支健康branch.stale_against_main、branch.workspace_mismatch分支落后于 main、会话工作区与当前工作区不一致调和reconciliationlane.reconciled、lane.superseded、lane.closed终态不确定被调和、事件被取代、lane 关闭发布溯源ship provenanceship.prepared、ship.commits_selected、ship.merged、ship.pushed_main发布准备、提交选择、合并与推送 main对应 ROADMAP §4.44.52.2 状态status自动化应优先使用的归一化状态LaneEventStatus使用#[serde(rename_all snake_case)]序列化running、ready、blocked、red、green、completed、failed、reconciled、merged、superseded、closed。契约明确status是事件的归一化状态消费者做自动化时应优先于自由文本detail。detail仅供人工阅读与排障绝不能作为机器判定依据。2.3 元数据metadata排序、去重、溯源与归属LaneEventMetadatalane_events.rs承载以下字段对应契约的四条不变量排序与去重钩子sequ64 单调递增序号、timestamp_ms事件观测/创建时间、event_fingerprint终态事件指纹。消费者应使用终态调和输出而不是对矛盾的终态爆发做重复上报。来源判定provenance区分事件是 live lane 真相、测试流量、健康检查/回放输出还是传输层证据。EventProvenance枚举在 lane_events.rs 中定义为live_lane、test、healthcheck、replay、transport五种配套的is_test_event/is_live_lane_event过滤函数与filter_by_provenance、filter_by_environment、filter_by_confidence可帮助消费者直接按来源与信任级别裁剪事件流lane_events.rs。environment_label如 production/staging/dev、emitter_identity如 clawd、plugin-name、operator-id、confidence_levelhigh/medium/low/unknown进一步细化信任语义。会话与归属绑定session_identitySessionIdentitytitle、workspace、purpose未知字段须带显式placeholder_reason并支持reconcile_enriched在后续信息到达时补齐、ownershipLaneOwnershipowner、workflow_scope、watcher_action。WatcherAction取act/observe/ignore三值——watcher 不得对observe或ignore归属的事件采取行动。nudge_id用于周期性提示的去重配套NudgeTracking、classify_nudge区分new/retry/stale_duplicate。终态指纹event_fingerprint由 compute_event_fingerprint 对{event, status, data}做 SHA-256 派生并取前 16 个十六进制字符8 字节得到。关键行为载荷变化必须刷新指纹。测试 convenience_terminal_events_attach_and_refresh_fingerprints 与 tool_style_finished_events_dedupe_after_payload_is_added 验证了这一点——这正是契约中消费者应使用终态调和输出而不是对矛盾终态爆发重复上报的底层依据。2.4 终态调和把矛盾的事件爆发收敛为一个规范结局reconcile_terminal_events 实现了 ROADMAP §4.5「会话事件排序 终态调和」的验收要求处理四类情况乱序事件按metadata.seq单调排序保证确定性重复终态相同指纹的终态事件去重仅当events_materially_differ事件类型、status、failure_class、data 任一不同见 lane_events.rs时用较新载荷覆盖传输层死亡终态事件之后出现lane.reconciledprovenance 为transport时将终态包装为lane.reconciled/statusreconcileddetail 标注Session terminal state uncertain: transport died after terminal event——把未知显式类型化而不是静默改写历史completed - idle - error - completed噪声收敛为唯一可行动的终态。is_terminal_eventlane_events.rs与classify_event_terminalitylane_events.rs定义了终态分类finished/failed/merged/superseded/closed为 Terminalreconciled为 Uncertainty其余为 Advisory。dedupe_terminal_eventslane_events.rs按指纹只保留每个终态首次出现。提交流还有dedupe_superseded_commit_eventslane_events.rs以data.canonicalCommit回退到commit为键丢弃带supersededBy的旧提交事件只保留最新一次lane.commit.created。2.5 最小消费规则如果存在结构化事件pane 文本只是辅助证据。对带有匹配会话/工作流归属的高置信类型化事件pane 抓取pane scraping不得覆盖它。从源码看这一规则的高置信由confidence_level与provenance共同支撑测试流量provenancetest/healthcheck/replay会被is_test_event直接识别从而避免污染生产 lane 状态对应 ROADMAP §4.6 验收clawhip 无需启发式文本匹配即可忽略或降权测试 ping。三、报告 Schema v1 契约规范事实记录 可选投影一份 Stream 2 报告应被视为规范事实记录canonical fact record并附带可选投影。即使消费者只收到降级视图也必须保留下述语义。3.1 核心结构身份、断言、负证据与字段增量报告相关类型集中在 report_schema.rsSchema 版本常量为claw.report.v1REPORT_SCHEMA_V1。CanonicalReportV1report_schema.rs包含部分字段契约语义身份schema_version、identity.report_id、identity.content_hash每个报告载荷声明 Schema 版本与稳定报告身份/内容哈希对全保真 canonical 载荷断言claims[]ReportClaimkindobserved_fact/inference/hypothesis/recommendation、confidencehigh/medium/low/unknown、evidence引用、sensitivitypublic/internal/operator_only/secret。断言必须带证据类标签、置信度与来源引用负证据negative_evidence[]NegativeEvidencestatus区分not_observed_in_checked_scope与unknown_not_checked并携带checked_surfaces、query、window。负证据是一等公民not observed、checked and absent、redacted是三种不同状态字段增量field_deltas[]FieldDeltafield、statechanged/unchanged/cleared/carried_forward、previous_hash/current_hash、attribution——命名字段、前后值/状态、归属以及增量来自源内容、投影、降级还是脱敏策略3.2 自描述 Schema 注册表report_schema_v1_registryreport_schema.rs返回一个自描述注册表满足 ROADMAP §4.26「自描述报告 Schema 表面」声明兼容性规则additive fields are compatible; missing required fields are breaking并列出字段清单含identity.report_id、identity.content_hash、claims[].kind、claims[].confidence、claims[].evidence、negative_evidence[]、field_deltas[]、projection.provenance.redactions[]每个字段标注required与所属field_family。测试 report_schema_registry_is_self_describing 断言了注册表的自描述性。3.3 规范化与内容哈希canonicalize_report 强制schema_version、按id/field排序claims/negative_evidence/field_deltas保证确定性序列化并在report_id为空时自动生成report-{content_hash}report_content_hashreport_schema.rs对排除身份字段后的载荷做stable_json_hash键排序的规范化 JSON SHA-256 前 8 字节见 report_schema.rs。3.4 投影与脱敏来源provenanceproject_report 按ConsumerCapabilities生成ReportProjectionV1仅当消费者声明支持某field_familyclaims/negative_evidence/field_deltas时才携带该族否则记入omitted_field_families对sensitivity超过消费者max_sensitivity的断言执行脱敏Secret级整体省略并记录RedactionProvenancefield_path、reason、policy_id、original_hash其余超限断言将text替换为redacted并清空evidence同样记录来源downgraded标志在不支持 Schema / 省略字段族 / 发生脱敏任一情况为真投影携带ProjectionProvenancepolicy_idclaw.report.projection.v1、source_schema_version、source_report_id、source_content_hash、consumer其projection_id由stable_json_hash({view, provenance, payload})确定性生成。这正是契约的投影规则投影必须把血统lineage追溯回 canonical report id/内容哈希并命名投影视图、能力集、Schema 版本、脱敏策略与确定性渲染输入。测试 projections_are_deterministic_and_record_redaction_provenance 验证了两次同参数投影完全相等、来源哈希一致、脱敏记录完整capability_negotiation_omits_unsupported_field_families 验证了未声明字段族被省略并记录。3.5 最小消费规则把 canonical 身份与投影元数据一起存储。只有当两份投影的 canonical 内容哈希或声明的投影输入不同时才能把它们之间的差异当作状态变化进行比较。换句话说缺失字段本身不能作为底层事实不存在的证据——一个没有脱敏/降级/源缺失原因的缺失字段不足以让自动化消费者下结论。这与NegativeEvidence把检查过且不存在与未检查/未知区分开的设计一脉相承。3.6 Fixture 佐证rust/crates/runtime/tests/fixtures/report_schema_v1/README.md说明in-code fixturereport_schema.rs::tests::fixture_report覆盖 fact/hypothesis/confidence 标签、带检查面与查询窗口的负证据、字段级增量归属、canonical 报告 id 内容哈希、确定性投影/脱敏来源以及消费者能力协商与降级投影由cargo test -p runtime report_schema -- --nocapture验证。注意该 fixture 目前是代码内确定性 fixture报告发射尚未接入 CLI/状态表面见下文的集成风险。四、批准令牌与策略拦截契约例外必须是可执行工件策略拦截的动作与所有者批准的例外属于同一个结构化事件/报告族对应 ROADMAP §4.37–§4.40当前由 worker-2 单独 lane 负责worker-1 未改动策略拦截命名类型化原因如main_push_forbidden、release_requires_owner、策略来源、actor 范围、被拦截动作、安全回退路径如 create branch、open PR、request owner approval。这使策略拒绝从死胡同聊天文本变成机器可行动的交接§4.37 验收。批准令牌命名批准者身份、策略例外、动作、repository/worktree/branch/commit 范围、过期时间、允许使用次数§4.38。对应源码侧的LaneCommitProvenancecommit、branch、worktree、canonicalCommit、supersededBy、lineage展示了同类范围 溯源结构在提交事件中的实践。令牌消费记录消耗令牌的确切动作与范围回放、范围扩大、过期令牌、撤销令牌都应浮出类型化策略错误§4.39 一次性使用与回放防护。委托可追溯性当另一个 worker/lane 执行被批准动作时委托链保持附着执行者必须能够证明哪个批准工件授权了该例外§4.40区分直接自用与委托执行审计可回答谁批准、谁请求、谁实际使用。最小消费规则散文式的 approved 不是可执行批准。必须要求结构化令牌并在继续之前验证它未被消费且范围精确匹配该动作。五、能力协商与一致性混合版本消费者如何共存Stream 2 rollout 期间必然出现混合版本消费者。契约要求生产者和消费者协商而非静默丢字段消费者声明支持的报告 Schema 版本、字段族、投影视图、脱敏状态、降级语义以及 fixture/conformance 套件版本。源码侧的ConsumerCapabilitiesreport_schema.rs正是这个声明的数据结构consumer、schema_versionsBTreeSet、field_familiesBTreeSet空集即全支持、max_sensitivity。生产者行为保留一份 canonical 全保真报告仅在携带downgraded_for_compatibility元数据源码中即ProjectionProvenance.downgraded与omitted_field_families/redactions时发射降级投影。确定性投影输入Schema 版本、消费者能力集、投影策略版本claw.report.projection.v1、脱敏策略版本、canonical 内容哈希——这些共同决定投影是否可复现、何时允许比较。一致性区分消费者一致性测试应区分语法接受与语义正确尤其对redactedvsmissing、过期 vs 当前投影、负证据、批准令牌回放状态对应 §4.34 下游消费者一致性测试契约。最小消费规则旧消费者可以接受降级投影但必须把降级呈现为能力限制而不是把被省略字段当作 canonical 缺失。六、验证与质量门用测试证明契约成立g004-events-reports-verification-map.md 给出了 worker-1 的验证证据与 leader 集成验证计划可在rust/目录下复跑# 聚焦契约测试 cargo test -p runtime lane_events -- --nocapture # PASS46 个 lane-event 测试 cargo test -p runtime report_schema -- --nocapture # PASS4 个 report-schema 测试 cargo test -p tools lane_event_schema_serializes_to_canonical_names -- --nocapture # PASS1 个工具契约测试 # runtime 质量门 cargo check -p runtime cargo clippy -p runtime --all-targets -- -D warnings # task 4 关闭批后 PASS cargo test -p runtime -- --nocapture # PASS531 个单元测试 12 个集成测试 doc-testslane 事件侧LaneEventName/LaneEventStatus的 wire value 由 21 组序列化用例锁定指纹确定性、终端去重、调和排序、传输死亡不确定性、阻塞/失败复用LaneEventBlockerfailureClassdetail 可选BlockedSubphaseblocked.trust_prompt、blocked.prompt_delivery、blocked.plugin_init、blocked.mcp_handshake、blocked.branch_freshness、blocked.test_hang、blocked.report_pending等均有测试覆盖。报告侧report_schema.rs内嵌 4 个测试自描述注册表、canonical 标签、确定性投影/脱敏来源、能力协商省略字段族。工具侧rust/crates/tools/src/lib.rs的AgentOutput.lane_events承载事件向量write_agent_manifest在写 manifest 前调用dedupe_superseded_commit_eventspersist_agent_terminal_state在终态时追加lane.finished/lane.failed事件maybe_commit_provenance生成lane.commit.created事件——测试 lane_event_schema_serializes_to_canonical_names 锁定其契约。注意终态指纹变化会有意影响finished/failed/superseded/merged/closed 事件的metadata.event_fingerprint。集成风险提示来自验证地图均以仓库现状为准runtime/src/lib.rs导出块共享合并 worker-2 的 approval-token 工作时应检查导出冲突tools/src/lib.rs将 lane 事件序列化进 agent manifest指纹语义变更会影响工具侧report_schema.rs目前只定义可复用契约与代码内确定性 fixture尚未把报告发射接入 CLI/状态表面ROADMAP §4.38–§4.40 的批准令牌是独立 lane不要把 worker-1 的报告 Schema 当成批准工件全 workspace 检查可能包含无关的慢速/provider 依赖测试本 stream 已验证的本地门限是 runtime 上述定向工具测试。七、文档维护规则让契约与代码永不脱钩原文档以四条规则收尾这里原样保留其约束力ROADMAP Phase 2 是产品需求源本文件是契约阅读指南两者分工明确需求变更先改 ROADMAP。Rust 类型名与事件名必须与 lane_events.rs 对齐公开事件名或元数据语义变化时在同一变更中同步更新本文档。报告 Schema 示例/fixtures 与本文档对齐schema lane 落地后fixture 更新必须说明有意的 Schema 或投影变更。worker lane 不得变更.omx/ultragoalUltragoal 检查点由 leader 独占从任务结果消费提交与验证证据。这也与验证地图的Ownership boundaries一致lane 事件/事件身份/终态调和归lane_events.rs报告 Schema/投影/脱敏/能力协商归report_schema.rspinpoint 关闭批横跨 compact/file_ops/policy_engine/sandbox/integration 测试面回归 harness 与文档对齐由 worker-3/4 协作完成。结语G004 契约的核心思想可以浓缩为一句话把发生了什么、为什么、谁授权从自由文本提升为带版本、带来源、可验证、可调和的结构化工件。无论你是实现 lane 事件的 producer还是消费事件的 clawhip/看板还是执行策略例外的 operator都可以在这份契约与 lane_events.rs、report_schema.rs 的源码中找到精确的字段语义、最小消费规则与可复跑的验证命令——这正是 ROADMAP Phase 2 中机器可信任互操作的落地形态。【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 1:55:04 · 阅读 1.2k claw-code G004 事件与报告契约指南：Lane 事件、报告 Schema v1 与能力协商的机器可信互操作规范
claw-code G004 事件与报告契约指南Lane 事件、报告 Schema v1 与能力协商的机器可信互操作规范【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code导读本文是 claw-code 仓库中 ROADMAP Phase 2「G004 events/reports」契约的完整解读围绕 docs/g004-events-reports-contract.md 展开并结合 lane_events.rs、report_schema.rs 与 ROADMAP.md 的源码与验收标准讲清 lane 事件流、报告 Schema v1、批准令牌链与能力协商四类互操作契约的字段语义、最小消费规则与验证方式。读完本文你将掌握如何按规范消费结构化 Lane 事件而不再依赖解析终端文本如何理解规范报告的 canonical payload 与派生 projection 之间的关系以及如何在混合版本消费者环境中做安全、可审计的降级与授权。一、G004 是什么一份给契约消费者的互操作指南G004 是 claw-code 在 Stream 2G004-events-reports团队运行期间文档捕获于 2026-05-14沉淀的契约指引。它的定位非常明确它不是 task 5 的实现映射而是 lane-event、report-schema、approval-token、capability-negotiation 四条 lane 落地后消费者应当依赖的互操作契约说明。其价值在于把机器可信任作为第一原则下游消费者如 clawhip、监控与看板应当消费结构化事件与报告而不是从终端文本pane text里猜测状态。全仓库的证据链如下契约需求源头ROADMAP.md Phase 2 §4.5–§4.7会话事件排序与终态调和、事件来源标注、会话身份完整性、§4.25–§4.26消费者能力协商、自描述报告 Schema、§4.32确定性投影/脱敏可复现、§4.34下游一致性测试契约、§4.37–§4.40策略拦截交接、所有者批准令牌、一次性使用与回放防护、委托链可追溯。实现与所有者锚点lane_events.rs、report_schema.rs两者经 lib.rs 导出。验证证据g004-events-reports-verification-map.md。下表是原文档给出的来源真相锚点可直接作为查阅索引契约族Roadmap 锚点当前实现 / 所有者锚点消费者指引Canonical lane eventsROADMAP.mdPhase 2 §4、§4.5、§4.6、§4.7rust/crates/runtime/src/lane_events.rsLaneEventName、LaneEventStatus、LaneEventMetadata、终态调和辅助函数消费event、status、emittedAt、metadata字段作为规范状态流存在结构化事件时不要从终端文本推断 lane 状态。Report schema v1 and projectionsROADMAP.md§4.25–§4.34Stream 2 report-schema lane / fixtures把报告视为带版本号的规范载荷 派生投影。投影只有在具备显式来源兼容降级、脱敏策略、截断、源缺失时才能省略或变换字段。Policy-blocked handoff and approval-token chainROADMAP.md§4.37–§4.39Stream 2 approval-token lane把策略拦截与所有者批准视为类型化工件而非散文。只有当批准令牌匹配 actor、策略、动作、repo/branch/commit 范围、过期时间与一次性使用状态时才执行例外。Capability negotiationROADMAP.md§4.25、§4.26、§4.32、§4.34Report-schema/projection fixtures 与一致性用例消费者在依赖精简载荷之前必须先声明其支持的 Schema 版本、可选字段族、投影视图、脱敏语义与降级处理方式。二、Lane 事件契约第一块机器可信表面Lane 事件流是 Stream 2 第一块机器可信任的表面。契约要求消费者在读取LaneEvent载荷时遵守以下不变量。2.1 事件名称event类型化事件名LaneEventName在 lane_events.rs 中定义序列化到线上时使用#[serde(rename ...)]声明的点分名称。测试 canonical_lane_event_names_serialize_to_expected_wire_values 逐一断言了每个变体到 wire value 的映射。当前完整集合按族划分如下族事件名wire value语义核心 lane 生命周期lane.started、lane.ready、lane.blocked、lane.red、lane.green、lane.finished、lane.failedlane 启动、就绪、阻塞、红/绿状态、完成与失败提示投递lane.prompt_misdelivery提示被投递到错误的会话/lane源码额外保留的族提交与合并流lane.commit.created、lane.pr.opened、lane.merge.ready、lane.merged提交创建、PR 打开、合并就绪与合并完成分支健康branch.stale_against_main、branch.workspace_mismatch分支落后于 main、会话工作区与当前工作区不一致调和reconciliationlane.reconciled、lane.superseded、lane.closed终态不确定被调和、事件被取代、lane 关闭发布溯源ship provenanceship.prepared、ship.commits_selected、ship.merged、ship.pushed_main发布准备、提交选择、合并与推送 main对应 ROADMAP §4.44.52.2 状态status自动化应优先使用的归一化状态LaneEventStatus使用#[serde(rename_all snake_case)]序列化running、ready、blocked、red、green、completed、failed、reconciled、merged、superseded、closed。契约明确status是事件的归一化状态消费者做自动化时应优先于自由文本detail。detail仅供人工阅读与排障绝不能作为机器判定依据。2.3 元数据metadata排序、去重、溯源与归属LaneEventMetadatalane_events.rs承载以下字段对应契约的四条不变量排序与去重钩子sequ64 单调递增序号、timestamp_ms事件观测/创建时间、event_fingerprint终态事件指纹。消费者应使用终态调和输出而不是对矛盾的终态爆发做重复上报。来源判定provenance区分事件是 live lane 真相、测试流量、健康检查/回放输出还是传输层证据。EventProvenance枚举在 lane_events.rs 中定义为live_lane、test、healthcheck、replay、transport五种配套的is_test_event/is_live_lane_event过滤函数与filter_by_provenance、filter_by_environment、filter_by_confidence可帮助消费者直接按来源与信任级别裁剪事件流lane_events.rs。environment_label如 production/staging/dev、emitter_identity如 clawd、plugin-name、operator-id、confidence_levelhigh/medium/low/unknown进一步细化信任语义。会话与归属绑定session_identitySessionIdentitytitle、workspace、purpose未知字段须带显式placeholder_reason并支持reconcile_enriched在后续信息到达时补齐、ownershipLaneOwnershipowner、workflow_scope、watcher_action。WatcherAction取act/observe/ignore三值——watcher 不得对observe或ignore归属的事件采取行动。nudge_id用于周期性提示的去重配套NudgeTracking、classify_nudge区分new/retry/stale_duplicate。终态指纹event_fingerprint由 compute_event_fingerprint 对{event, status, data}做 SHA-256 派生并取前 16 个十六进制字符8 字节得到。关键行为载荷变化必须刷新指纹。测试 convenience_terminal_events_attach_and_refresh_fingerprints 与 tool_style_finished_events_dedupe_after_payload_is_added 验证了这一点——这正是契约中消费者应使用终态调和输出而不是对矛盾终态爆发重复上报的底层依据。2.4 终态调和把矛盾的事件爆发收敛为一个规范结局reconcile_terminal_events 实现了 ROADMAP §4.5「会话事件排序 终态调和」的验收要求处理四类情况乱序事件按metadata.seq单调排序保证确定性重复终态相同指纹的终态事件去重仅当events_materially_differ事件类型、status、failure_class、data 任一不同见 lane_events.rs时用较新载荷覆盖传输层死亡终态事件之后出现lane.reconciledprovenance 为transport时将终态包装为lane.reconciled/statusreconcileddetail 标注Session terminal state uncertain: transport died after terminal event——把未知显式类型化而不是静默改写历史completed - idle - error - completed噪声收敛为唯一可行动的终态。is_terminal_eventlane_events.rs与classify_event_terminalitylane_events.rs定义了终态分类finished/failed/merged/superseded/closed为 Terminalreconciled为 Uncertainty其余为 Advisory。dedupe_terminal_eventslane_events.rs按指纹只保留每个终态首次出现。提交流还有dedupe_superseded_commit_eventslane_events.rs以data.canonicalCommit回退到commit为键丢弃带supersededBy的旧提交事件只保留最新一次lane.commit.created。2.5 最小消费规则如果存在结构化事件pane 文本只是辅助证据。对带有匹配会话/工作流归属的高置信类型化事件pane 抓取pane scraping不得覆盖它。从源码看这一规则的高置信由confidence_level与provenance共同支撑测试流量provenancetest/healthcheck/replay会被is_test_event直接识别从而避免污染生产 lane 状态对应 ROADMAP §4.6 验收clawhip 无需启发式文本匹配即可忽略或降权测试 ping。三、报告 Schema v1 契约规范事实记录 可选投影一份 Stream 2 报告应被视为规范事实记录canonical fact record并附带可选投影。即使消费者只收到降级视图也必须保留下述语义。3.1 核心结构身份、断言、负证据与字段增量报告相关类型集中在 report_schema.rsSchema 版本常量为claw.report.v1REPORT_SCHEMA_V1。CanonicalReportV1report_schema.rs包含部分字段契约语义身份schema_version、identity.report_id、identity.content_hash每个报告载荷声明 Schema 版本与稳定报告身份/内容哈希对全保真 canonical 载荷断言claims[]ReportClaimkindobserved_fact/inference/hypothesis/recommendation、confidencehigh/medium/low/unknown、evidence引用、sensitivitypublic/internal/operator_only/secret。断言必须带证据类标签、置信度与来源引用负证据negative_evidence[]NegativeEvidencestatus区分not_observed_in_checked_scope与unknown_not_checked并携带checked_surfaces、query、window。负证据是一等公民not observed、checked and absent、redacted是三种不同状态字段增量field_deltas[]FieldDeltafield、statechanged/unchanged/cleared/carried_forward、previous_hash/current_hash、attribution——命名字段、前后值/状态、归属以及增量来自源内容、投影、降级还是脱敏策略3.2 自描述 Schema 注册表report_schema_v1_registryreport_schema.rs返回一个自描述注册表满足 ROADMAP §4.26「自描述报告 Schema 表面」声明兼容性规则additive fields are compatible; missing required fields are breaking并列出字段清单含identity.report_id、identity.content_hash、claims[].kind、claims[].confidence、claims[].evidence、negative_evidence[]、field_deltas[]、projection.provenance.redactions[]每个字段标注required与所属field_family。测试 report_schema_registry_is_self_describing 断言了注册表的自描述性。3.3 规范化与内容哈希canonicalize_report 强制schema_version、按id/field排序claims/negative_evidence/field_deltas保证确定性序列化并在report_id为空时自动生成report-{content_hash}report_content_hashreport_schema.rs对排除身份字段后的载荷做stable_json_hash键排序的规范化 JSON SHA-256 前 8 字节见 report_schema.rs。3.4 投影与脱敏来源provenanceproject_report 按ConsumerCapabilities生成ReportProjectionV1仅当消费者声明支持某field_familyclaims/negative_evidence/field_deltas时才携带该族否则记入omitted_field_families对sensitivity超过消费者max_sensitivity的断言执行脱敏Secret级整体省略并记录RedactionProvenancefield_path、reason、policy_id、original_hash其余超限断言将text替换为redacted并清空evidence同样记录来源downgraded标志在不支持 Schema / 省略字段族 / 发生脱敏任一情况为真投影携带ProjectionProvenancepolicy_idclaw.report.projection.v1、source_schema_version、source_report_id、source_content_hash、consumer其projection_id由stable_json_hash({view, provenance, payload})确定性生成。这正是契约的投影规则投影必须把血统lineage追溯回 canonical report id/内容哈希并命名投影视图、能力集、Schema 版本、脱敏策略与确定性渲染输入。测试 projections_are_deterministic_and_record_redaction_provenance 验证了两次同参数投影完全相等、来源哈希一致、脱敏记录完整capability_negotiation_omits_unsupported_field_families 验证了未声明字段族被省略并记录。3.5 最小消费规则把 canonical 身份与投影元数据一起存储。只有当两份投影的 canonical 内容哈希或声明的投影输入不同时才能把它们之间的差异当作状态变化进行比较。换句话说缺失字段本身不能作为底层事实不存在的证据——一个没有脱敏/降级/源缺失原因的缺失字段不足以让自动化消费者下结论。这与NegativeEvidence把检查过且不存在与未检查/未知区分开的设计一脉相承。3.6 Fixture 佐证rust/crates/runtime/tests/fixtures/report_schema_v1/README.md说明in-code fixturereport_schema.rs::tests::fixture_report覆盖 fact/hypothesis/confidence 标签、带检查面与查询窗口的负证据、字段级增量归属、canonical 报告 id 内容哈希、确定性投影/脱敏来源以及消费者能力协商与降级投影由cargo test -p runtime report_schema -- --nocapture验证。注意该 fixture 目前是代码内确定性 fixture报告发射尚未接入 CLI/状态表面见下文的集成风险。四、批准令牌与策略拦截契约例外必须是可执行工件策略拦截的动作与所有者批准的例外属于同一个结构化事件/报告族对应 ROADMAP §4.37–§4.40当前由 worker-2 单独 lane 负责worker-1 未改动策略拦截命名类型化原因如main_push_forbidden、release_requires_owner、策略来源、actor 范围、被拦截动作、安全回退路径如 create branch、open PR、request owner approval。这使策略拒绝从死胡同聊天文本变成机器可行动的交接§4.37 验收。批准令牌命名批准者身份、策略例外、动作、repository/worktree/branch/commit 范围、过期时间、允许使用次数§4.38。对应源码侧的LaneCommitProvenancecommit、branch、worktree、canonicalCommit、supersededBy、lineage展示了同类范围 溯源结构在提交事件中的实践。令牌消费记录消耗令牌的确切动作与范围回放、范围扩大、过期令牌、撤销令牌都应浮出类型化策略错误§4.39 一次性使用与回放防护。委托可追溯性当另一个 worker/lane 执行被批准动作时委托链保持附着执行者必须能够证明哪个批准工件授权了该例外§4.40区分直接自用与委托执行审计可回答谁批准、谁请求、谁实际使用。最小消费规则散文式的 approved 不是可执行批准。必须要求结构化令牌并在继续之前验证它未被消费且范围精确匹配该动作。五、能力协商与一致性混合版本消费者如何共存Stream 2 rollout 期间必然出现混合版本消费者。契约要求生产者和消费者协商而非静默丢字段消费者声明支持的报告 Schema 版本、字段族、投影视图、脱敏状态、降级语义以及 fixture/conformance 套件版本。源码侧的ConsumerCapabilitiesreport_schema.rs正是这个声明的数据结构consumer、schema_versionsBTreeSet、field_familiesBTreeSet空集即全支持、max_sensitivity。生产者行为保留一份 canonical 全保真报告仅在携带downgraded_for_compatibility元数据源码中即ProjectionProvenance.downgraded与omitted_field_families/redactions时发射降级投影。确定性投影输入Schema 版本、消费者能力集、投影策略版本claw.report.projection.v1、脱敏策略版本、canonical 内容哈希——这些共同决定投影是否可复现、何时允许比较。一致性区分消费者一致性测试应区分语法接受与语义正确尤其对redactedvsmissing、过期 vs 当前投影、负证据、批准令牌回放状态对应 §4.34 下游消费者一致性测试契约。最小消费规则旧消费者可以接受降级投影但必须把降级呈现为能力限制而不是把被省略字段当作 canonical 缺失。六、验证与质量门用测试证明契约成立g004-events-reports-verification-map.md 给出了 worker-1 的验证证据与 leader 集成验证计划可在rust/目录下复跑# 聚焦契约测试 cargo test -p runtime lane_events -- --nocapture # PASS46 个 lane-event 测试 cargo test -p runtime report_schema -- --nocapture # PASS4 个 report-schema 测试 cargo test -p tools lane_event_schema_serializes_to_canonical_names -- --nocapture # PASS1 个工具契约测试 # runtime 质量门 cargo check -p runtime cargo clippy -p runtime --all-targets -- -D warnings # task 4 关闭批后 PASS cargo test -p runtime -- --nocapture # PASS531 个单元测试 12 个集成测试 doc-testslane 事件侧LaneEventName/LaneEventStatus的 wire value 由 21 组序列化用例锁定指纹确定性、终端去重、调和排序、传输死亡不确定性、阻塞/失败复用LaneEventBlockerfailureClassdetail 可选BlockedSubphaseblocked.trust_prompt、blocked.prompt_delivery、blocked.plugin_init、blocked.mcp_handshake、blocked.branch_freshness、blocked.test_hang、blocked.report_pending等均有测试覆盖。报告侧report_schema.rs内嵌 4 个测试自描述注册表、canonical 标签、确定性投影/脱敏来源、能力协商省略字段族。工具侧rust/crates/tools/src/lib.rs的AgentOutput.lane_events承载事件向量write_agent_manifest在写 manifest 前调用dedupe_superseded_commit_eventspersist_agent_terminal_state在终态时追加lane.finished/lane.failed事件maybe_commit_provenance生成lane.commit.created事件——测试 lane_event_schema_serializes_to_canonical_names 锁定其契约。注意终态指纹变化会有意影响finished/failed/superseded/merged/closed 事件的metadata.event_fingerprint。集成风险提示来自验证地图均以仓库现状为准runtime/src/lib.rs导出块共享合并 worker-2 的 approval-token 工作时应检查导出冲突tools/src/lib.rs将 lane 事件序列化进 agent manifest指纹语义变更会影响工具侧report_schema.rs目前只定义可复用契约与代码内确定性 fixture尚未把报告发射接入 CLI/状态表面ROADMAP §4.38–§4.40 的批准令牌是独立 lane不要把 worker-1 的报告 Schema 当成批准工件全 workspace 检查可能包含无关的慢速/provider 依赖测试本 stream 已验证的本地门限是 runtime 上述定向工具测试。七、文档维护规则让契约与代码永不脱钩原文档以四条规则收尾这里原样保留其约束力ROADMAP Phase 2 是产品需求源本文件是契约阅读指南两者分工明确需求变更先改 ROADMAP。Rust 类型名与事件名必须与 lane_events.rs 对齐公开事件名或元数据语义变化时在同一变更中同步更新本文档。报告 Schema 示例/fixtures 与本文档对齐schema lane 落地后fixture 更新必须说明有意的 Schema 或投影变更。worker lane 不得变更.omx/ultragoalUltragoal 检查点由 leader 独占从任务结果消费提交与验证证据。这也与验证地图的Ownership boundaries一致lane 事件/事件身份/终态调和归lane_events.rs报告 Schema/投影/脱敏/能力协商归report_schema.rspinpoint 关闭批横跨 compact/file_ops/policy_engine/sandbox/integration 测试面回归 harness 与文档对齐由 worker-3/4 协作完成。结语G004 契约的核心思想可以浓缩为一句话把发生了什么、为什么、谁授权从自由文本提升为带版本、带来源、可验证、可调和的结构化工件。无论你是实现 lane 事件的 producer还是消费事件的 clawhip/看板还是执行策略例外的 operator都可以在这份契约与 lane_events.rs、report_schema.rs 的源码中找到精确的字段语义、最小消费规则与可复跑的验证命令——这正是 ROADMAP Phase 2 中机器可信任互操作的落地形态。【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考