开发
查看 Markdown

捕获覆盖声明契约

Hermes 和 Gateway 在新 Content Source 的 metadata 中增加 powercontext_capture_coverage。这个有界声明记录生成受支持投影时实际观察到的容量损失, 不表示完整原始会话。

本文定义 issue #2437 对应的 powercontext.capture-coverage.v1。共享合成用例位于 tests/integration_conformance/capture_coverage_cases.json;Python 和 Rust 使用同一份文件, 不共享运行时,也不引入插件框架。

声明格式

{
  "powercontext_capture_coverage": {
    "schema": "powercontext.capture-coverage.v1",
    "projection": "hermes-turn-text.v1",
    "unit": "user_assistant_text_pair",
    "status": "complete",
    "reasons": []
  }
}

声明恰好包含这五个字段。对象自身不得超过 512 UTF-8 bytes:按不做 ASCII 转义的紧凑 JSON 计算,不包含外层 metadata 键。v1 合法字段值均为固定枚举,因此契约本身保证该上限。 对象键顺序不影响含义;reasons 数组顺序属于契约。其他 metadata 必须保持原样,包括不透明的 prefix extraction 扩展。不得加入正文、路径、message ID 列表、prompt、模型配置或凭证。

字段契约
schema固定为 powercontext.capture-coverage.v1。
projection下表定义的三个 profile 之一。
unit与 profile 精确配对的投影单元。
statuscomplete、partial 或 unknown。
reasons受支持字符串,去重并按字典序升序排列。

支持的 reason 为 character_limit、field_byte_limit、transcript_byte_limit 和 unmeasured_projection。

实际观察到的事实statusreasons
受支持投影可测量,没有额外容量损失。complete空数组。
至少发生一种容量损失。partial所有已观察到的容量损失原因。
无法测量覆盖情况,且没有已知容量损失。unknownunmeasured_projection。
已知损失与不可测量部分同时存在。partial已知损失原因,加上 unmeasured_projection。

partial 必须包含实际容量损失原因,不能仅包含 unmeasured_projection。unknown 不能掩盖已知损失。 metadata 缺失、没有该键、schema 或 profile 不支持、unit 不匹配、字段错误或类型非法、存在额外字段、 reason 重复或乱序、status 与 reasons 矛盾,都解释为 unknown。解释过程不改写已存储 payload。

受支持投影

profileunit投影边界
hermes-turn-text.v1user_assistant_text_pair当前规范化后的 user/assistant 文本对,包含既有角色标签和分隔符。
hermes-precompress-text.v1new_user_assistant_window宿主提供、经现有过滤及重叠去重后,本次待捕获的新 user/assistant 条目窗口。
gateway-turn-text.v1gateway_turn_projection当前受支持的 Chat/Responses 规范投影,从最后一条 user 到 terminal assistant。

Hermes completed turn

覆盖判断使用裁剪前的完整拼接字符串,包含角色标签及分隔符,并沿用 50,000 字符上限。 恰好达到上限为 complete;实际裁剪为 partial/character_limit。这里计算 Python 字符数, 不是 UTF-8 字节数。

正文、原有 source ID 算法、角色选择、secret handling 和队列行为均保持不变。 messages 参数不会把该 profile 扩展成完整工具历史。空文本对不创建 Source。 类似截断 marker 的正文始终只是普通数据。

Hermes pre-compress

宿主提供 evidence_messages 时优先使用它。继续沿用现有 user/assistant 过滤、secret redaction、 fingerprint 和 overlap 处理。投影单元是本次请求捕获的完整新窗口,不是最后能装下的前缀。

现有 30,000 字符上限只接纳完整条目。全部新条目可容纳时为 complete;optional 模式捕获非空前缀 时为 partial/character_limit。第一条就无法容纳时不创建空 Source。required checkpoint 无法容纳完整 窗口时,必须在发送部分 Source 或推进已捕获快照之前拒绝。

Scope 固定、重叠身份和 checkpoint 状态转换保持现有语义。capture 已持久化之后,后续 extraction 失败不否定 checkpoint。

Gateway normalized turn

继续保留既有可见文本、工具调用和工具输出投影。注入的 prepare、opaque reasoning、传输 ID 及不支持 的媒体仍在 profile 之外;排除它们本身不代表该投影 partial。

实际执行现有 8 KiB 字段裁剪时记录 field_byte_limit;按现有 64 KiB transcript 策略实际删除步骤时 记录 transcript_byte_limit。同时发生则同时保留,即使被裁剪的字段后来随步骤一起省略,也不能丢失 已经观察到的事实。UTF-8 边界、正文 JSON、omitted_steps、截断 marker 和终止响应判断保持不变。 coverage 与正文来自同一次投影计算,不二次解析序列化 transcript,也不使用全局状态。

已接受的 Responses 历史条目出现未知 type 时,现有投影会跳过该条目,因此声明为不可测量。 历史消息不恰好包含一个规范条目时也声明为不可测量;正文继续沿用既有的首条目投影。 未知终止响应、仍需客户端执行工具的响应、无法解析的响应继续不生成 transcript,也不创建 Source。 正文中的伪截断 marker 不改变覆盖声明。

Responses 调用还要求 type 为已知调用类型,并且既有投影字段 arguments、input、action、 code、query 或 queries 中存在非 null 载荷。仅因 _call 后缀被接受的类型,例如 apply_patch_call 或未来调用类型,即使包含上述字段也声明为不可测量。已知调用缺少可投影载荷时 同样不可测量;显式空字符串仍可测量。该规则同时适用于历史调用和终止响应中的 hosted 调用。 正文渲染和终止判断保持不变;不可测量调用记录 unmeasured_projection,并保留同时发生的已知容量损失。

Responses 历史输出仅在受支持的 function、custom、computer 或 shell 输出类型中存在非 null 的 output 时可测量;空字符串仍可测量。MCP 审批响应和未知 *_call_output 类型即使包含 output,也记录 unmeasured_projection,因为其他载荷字段没有进入投影。受支持类型缺失 output 或其值为 null 时同样不可测量。正文渲染和终止判断保持不变。

Chat 工具调用的 function name、arguments 均为字符串,且 type 为 function 或缺省时,才视为 可测量;缺省 type 沿用既有 legacy 格式。其他调用类型或无法投影的 function 字段记录 unmeasured_projection,不改变正文渲染。存在已知容量损失时仍为 partial,同时保留损失和不可测量原因。

身份、重放与升级

新捕获必须同时提交正文和声明。同版本相同重试保持 source ID、正文、声明及其他 metadata 一致, 不新增 journal position。coverage 不参与 source ID 算法。SourceRepository 继续执行完整 payload 冲突检查。

Hermes pre-compress 发送前不冻结声明,而是按当前窗口临时计算 coverage reasons。发送成功、或结果 不确定(无法证明未写入)时,才按当前 provider Scope/stream 内的 Source 身份固定该 reasons;被 Server 明确拒绝(除 408/409 外的 4xx)时不固定,下一次尝试按当时窗口重新计算。一旦固定,若应答丢失,宿主 随后提供更短或更长的窗口,只要捕获前缀的身份相同,重放就使用首次声明。当前窗口能否满足 required checkpoint 仍独立判断;重放成功不会把历史 partial 声明改成 complete。

该进程内映射只为每个尝试过的身份保存固定 reason 元组,不缓存正文。内存随当前 Scope/stream 内的 不同尝试身份数增长,初始化、Scope 切换及 stream reset/rewind 时清空。它不是持久化恢复日志:provider 重启后,不会自动协调不同大小的宿主窗口与先前声明。正文及其他 metadata 的真实冲突始终保留。

仅在 Hermes capture 操作中,409 可以触发最多一次 legacy 重试:使用相同 Scope、source ID、正文及 其他 metadata,只移除本次新增 coverage 键。只有 Server 接受完全相同的 legacy payload,重试才算 成功。再次失败保留原冲突;首次 401、403 和传输失败不触发该路径。普通 turn 的失败诊断和 required checkpoint 的失败行为仍由各自边界负责。

legacy 重放成功后,旧 Source 仍然没有声明,解释为 unknown。不回填历史、不换 ID、不增加网络查询, 也不修改通用 HTTP client 的重试策略。Gateway 继续沿用 409 first-write-wins,不能因为重复提交就声称 新声明已经持久化。

持久化、证据与信任

现有 Content Source adapter 和 TextEvidence 投影保留 metadata。重新打开 SQLite 后,通过现有 SourceRepository 完整读回可以取得原始声明及其他 metadata。现有 HTTP get_source 对 Content Source 只暴露正文和身份,不返回 metadata;本功能不增加 HTTP 响应字段。E2E 通过真实 Server 进程重启验证 HTTP 正文和身份,再通过现有 repository 读回验证完整 metadata。

capture coverage、EvidenceManifest.incomplete、隐私 admission 的 coverage.complete、 authority/verification 和 root independence 是不同事实。caller 提供的声明不证明来源,也不授予 权限。Core 不根据该键改变 generation eligibility、authority、trust policy、Memory 内容或召回。

声明始终是不可信证据数据,不转换成系统指令。它保存在 Source metadata、进入提取输入,并不承诺 经过模型摘要后还能确定性传播到 Memory 或 PreparedContext。本功能不提升任何宿主的生命周期能力。

输入成本与验证

同一声明可能同时出现在证据内容和 provenance 中。应测量完整输入,不能把声明对象的字节上限当成 模型输入预算。

共享 fixture 的 budget_sample 使用 hermes-turn-text.v1、内置 coding 提取指令、注入的 recording extractor,不配置自定义 input renderer,estimator 为 character:weighted、版本 1:

测量项无声明有声明增量
声明对象紧凑 UTF-8 bytes0147147
序列化 AtomicMemoryExtractionInput UTF-8 bytes608968360
指令 + 换行 + 序列化输入的 estimated tokens1,2381,32890

这些是合成输入的测量结果,不是真实模型 token 用量。指令、渲染方式、estimator 和输入内容都会影响 总量。完整输入预算检查保持有效:单 Source 超限时拒绝且不消费 cursor;多 Source 窗口超限时继续沿用 现有持久化缩窗及重试行为。两条路径都不能丢弃声明或放宽预算。

验证命令:

uv run pytest tests/integration_conformance tests/integrations/test_hermes_provider.py -q
uv run pytest tests/e2e/test_capture_coverage.py -q
cargo test --manifest-path gateway/Cargo.toml -p pc-gateway-core
cargo clippy --manifest-path gateway/Cargo.toml -p pc-gateway-core --all-targets -- -D warnings

E2E 覆盖真实本地 HTTP、独立 Server 进程及 SQLite、精确重放、冲突、Scope 隔离、TextEvidence 和 AtomicMemoryEvidence。模型生成使用 recording extractor;直接调用 Hermes provider 验证的是 adapter 行为,不代表完成原生 Hermes 宿主验收。Gateway 捕获通过 executor 和受控协作者验证。

On this page