从 REA 6.1 升级到 6.2¶

REA 6.2 包含稳定性修复，以及对公共结果和已保存数据契约的更改。该仓库使用 always-bump-minor，包括破坏性发布；次版本号递增并不意味着向后兼容。升级后请刷新缓存的 MCP 工具定义，并使用本指南调整自定义消费者。

MCP 结果与 Evidence¶

产生 Evidence 的工具现在直接在 structuredContent 和 JSON 文本中返回完整的 Evidence 记录。旧的 { result, evidence_id, evidence } 包装器已移除。 对于成功的产生 Evidence 的调用，请更改：

// 6.1
const value = reply.structuredContent.result;
const evidence = reply.structuredContent.evidence;

// 6.2
const evidence = reply.structuredContent;
const value = evidence.normalized_result;
const evidenceId = evidence.evidence_id;

在读取成功字段之前先检查 isError。错误结果的 isError 为 true，并在文本内容块中携带其类型化的 JSON 诊断信息；它们省略了 structuredContent，因此不会违反所宣称的成功输出 schema。

if (reply.isError === true) {
  const text = reply.content.find((part) => part.type === "text");
  if (text === undefined) throw new Error("REA error has no text diagnostic");
  const { error: diagnostic } = JSON.parse(text.text);
  // Handle diagnostic.code, diagnostic.message and diagnostic.details.
}

Lifecycle 和其他非 Evidence 工具仍使用它们自身声明的输出契约。不要假设每个成功的工具都返回 Evidence。请参阅 tools/list 和结果指南。

传输层（transport）的 resource_constraint 错误可能包含保留的 details.reported_limits.evidence_reference。在同一连接上使用 inspect_analysis_view 或 export_evidence_bundle 来消费完整的保留 Evidence。响应预算设置在服务器启动时捕获；要更改它们，请重新创建服务器，并保持客户端的接收预算一致。提高服务器预算不会改变客户端的限制或分析覆盖范围。

每条 Evidence 记录现在都要求 analysis_profile，可以是其观察到的 profile 对象，也可以是 null。该字段参与 Evidence 的身份标识。省略该字段的记录无法通过插入 null 并保留旧 evidence_id 的方式迁移。请保留原始文件，并使用 6.2 重新生成受影响的观察结果；在链接或比较它们时使用新返回的身份。已满足完整规范契约的现有记录仍然可用。

binary_session 结果移除了冗余的顶层 provider 和 providers 别名。请读取 analysis_provider_binding、analysis_provider_candidates 以及每个操作的 capabilities 以进行选择和可用性判断。使用所声明的值，通过 open_binary.provider_id 或 CLI --provider 选择深层 provider。

这些更改建立了完整的结果表示，以及明确的 provider/profile 所有权，而不是接受不完整的生产者记录。请参阅 63bf914 和 #1277。

已保存快照与工件清单¶

分析快照要求每个缓存的查询都具有 workflow_entries 以及对应的、profile 绑定的 Evidence 记录。导入会拒绝不完整的绑定，而不是静默丢弃它们。当重新运行分析时，请保留不兼容的快照并选择新的输出路径，例如：

rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program-6.2.json

在 MCP 中，打开目标时不要使用不兼容的 snapshot_path，运行所需查询，然后通过 close_binary.snapshot_path 保存到新路径。不要伪造缺失的 provider profiles 或查询绑定。请参阅 快照用法。

工件清单节点标识内容字节。路径特定的角色和权限现在归属于每个 occurrence：

使用 artifact_id 将 occurrence 连接到其内容节点；检查所选 occurrence 的角色，而不是为具有相同字节的所有路径选择一个角色。可执行二进制格式可以具有 artifact_kind: "executable"，而其当前的文件系统权限产生 executable: false。具有相同字节的 .js 和 .txt 文件可以共享一个节点并保留不同的角色。重新生成旧清单：仅凭合并的内容节点无法恢复已丢失的逐路径事实。这些更改属于 63bf914 的一部分。

进程捕获与清理失败¶

REA 不再在导入时转换旧版 v3 进程捕获。捕获要求显式的所选/启动可执行文件身份以及 event_journal；缺失数据会被拒绝，而不是在解析期间填充。请保留旧捕获以供历史参考，并在需要进行当前比较时使用 6.2 重新捕获。不要从稍后的文件摘要推断原始启动的二进制文件，也不要根据独立记录的集合臆造事件顺序。显式为空的 journal 在其声明的契约下是有效的；该字段不可省略。请参阅 2a77469。

文件系统效果现在可以在部分快照无法确定创建或删除时报告 status: "unknown" 并附上原因。请更新穷尽式状态读取器，并将观察到的事实与缺失假设分开保留。

已完成的一次性分析可以在提供方清理失败时报告 cleanup_incomplete，而不是静默返回成功。保留其 details.partial_observation 或主要执行诊断信息，检查报告中拥有的资源，并在重试前处理清理问题。成功的分析观测并不能证明清理成功。此行为已在 #1211 中涵盖。该变更还使配置的代理评估 fixture 检查对引用的 Evidence 进行评分；仅靠路由或答案措辞不再能通过受评估的 fixture。

JavaScript 与函数比较¶

JavaScript 返回字段投影要求 presence 取值为 present、absent 或 unknown-coverage。导出形状变更行保留两侧的存在性，property_inventories 报告已检查的属性和覆盖率。未知值与未知存在性是不同的；调用方不得将未知值视为缺失属性。语义对象操作图观测使用 properties.property_path（完整路径段数组或 null），而不是扁平化的属性名。在依赖嵌套变更或存在性事实之前，请重新生成旧的应用分析。参见 475a0f8。

函数比较维度状态为 unchanged、changed 或 unknown。不可达的 truncated 状态和 summary.truncated 计数器已被移除。更新穷举枚举处理和显示逻辑；不可用的事实保持 unknown。参见 5510b27。

历史源符号链接¶

target_state 为 "unreadable" 或 "unknown" 的源图符号链接要求 target: null。内部、外部和缺失的目标保留其实际记录的 target 字符串。外部目标使用观测到的绝对目标；<outside-root> 之类的显示占位符不能作为查找数据。当旧图仅保留占位符时，请重新导入源树，并在自定义读取器中处理可空 target。参见 b7b4333。

保留原始保存的工件，直到其替代品和消费工作流已检查完毕。如果目标、源树或运行时发生变化，新分析可能会建立不同的事实；它不会改写旧捕获所证明的内容。