← 更新日志

文档 · 钉 6.4.0

升级时怎样不弄坏 runbook

从 6.0.0（2026-10-08）到 6.4.0（2026-10-11），几次次版本发行改了 MCP 输入、Evidence 形状和已保存的捕获。 本页是这些破坏性变更的运维清单。日期取自 GitHub 发行的 published_at。rea.run 的教学钉版本是 [email protected]。

always-bump-minor 不是兼容承诺

上游 6.2 迁移指南用一句话写了策略：仓库使用 always-bump-minor，包括破坏性发行。次版本号并不表示旧脚本、旧 Evidence 文件或旧捕获仍然能通过校验。 2026-10-13 时 npm latest 仍是 6.4.0。runbook 里漂浮的 @latest 会在下一次次版本发布时跟上，破坏性变更也一起跟上。

Factory Droid（droid）和 DeepSeek Harness（dsh）只在 main 上，要等到 6.4.0 之后的 npm 发行。不要把它们写进 6.4.0 的 setup 计划。

升级步骤

1. 记下你今天跑的钉版本：MCP args 里的版本，以及全局 CLI 的 npm view rea-agents version。两者可以不同。
2. 读下面表格里你将跨过的每一行。从 6.1 直接跳到 6.4.0，仍然包含 6.2 和 6.3 的合同。
3. 把 Evidence 包、分析快照和进程捕获复制到旁边的目录。不要就地改写。
4. 把客户端指到该钉版本，并批准一份有范围的 setup 计划：

   npx -y [email protected] setup --client codex --dry-run --json
   # 审阅后再：
   npx -y [email protected] setup --client codex --yes --json

5. 重启或重连智能体。上一包缓存的 tools/list schema 是常见的第一处失败。
6. 运行 npx -y [email protected] doctor --json，把 JSON 附在变更单上。
7. 对一个你已经理解的授权目标重跑一次。先比对字段名，再相信仪表板或脚本。
8. 若消费者仍读取 structuredContent.result，改为 normalized_result（6.2）。若仍读取 network.websocket_events，改为 network.websocket_connections（6.4）。WebSocket 字段没有旧别名。

该钉版本的手动 MCP JSON：

{
  "mcpServers": {
    "rea": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp"]
    }
  }
}

运维会碰到的破坏，6.0 至 6.4.0

同一十天里更早的主版本（4.0.0、5.0.0）另有破坏性变更，列在 更新日志。本手册从 MCP 路径和 Evidence 消费者通常开始坏掉的地方写起：6.0。

6.0.0 — MCP 绝对路径

发布于 2026-10-08。MCP 文件系统输入必须是主机绝对路径。包括目标与快照路径、Evidence 包路径、托管代码与固件输入、浏览器与 Electron 启动路径，以及期望的服务器路径。 可选路径仍然可选。形如 open_binary 且路径为 "./app" 的调用，必须改成 /home/analyst/app 或 C:\analysis\app。 CLI 仍接受操作者的相对路径。从相对工作区根拼 MCP 参数的智能体，需要接上 pwd，而不是模型编出来的字符串。

来源：#948、#1004、发行 rea-agents-6.0.0。

6.1.0 — Hopper 调用方

发布于 2026-10-09。若你经 REA 驱动 Hopper 搜索：正则模式是 ECMAScript Unicode 语法，不是 Python re。匹配在可取消的工作线程里跑，截止 5 秒。字面量模式仍做 Unicode 大小写折叠匹配。 set_current_document 已删除。用 open_binary 切换目标。文档参数的范围是当前活动目标。

6.2.0 — Evidence、快照与已保存清单

发布于 2026-10-09。升级消费者之前，先读 6.4.0 标签上的 docs/migration-6.2.md。下面是运维摘录。合同变更见提交 63bf914 与 #1277。

成功载荷

产出 Evidence 的工具把完整 Evidence 记录放进 structuredContent，也放进 JSON 文本。旧的 { result, evidence_id, evidence } 包装没有了。

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

// 6.2 及以后，包括 6.4.0
const evidence = reply.structuredContent;
const value = evidence.normalized_result;
const evidenceId = evidence.evidence_id;

读成功字段之前先看 isError。错误把 isError 设为 true，把类型化诊断放进文本内容块，并省略 structuredContent，这样它们不必匹配成功 schema。 生命周期和其它非 Evidence 工具仍使用自己的输出合同。不要假设每个成功工具都是 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 选择深度提供者。

传输层 resource_constraint 可以带上 details.reported_limits.evidence_reference。在同一连接上用 inspect_analysis_view 或 export_evidence_bundle 消费保留的 Evidence。 响应预算在服务器启动时固定。要改预算就重建服务器。提高服务器预算不会提高客户端的接收上限。

快照与制品角色

快照要求 workflow_entries，并且每个缓存查询都有一条绑定 profile 的 Evidence。导入会拒绝不完整的绑定。保留旧快照，写到新路径，例如：

npx -y [email protected] analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program-6.4.json

在 MCP 中，打开时不要带上不兼容的 snapshot_path，跑完查询后经 close_binary.snapshot_path 保存。不要编造缺失的提供者 profile。

用 artifact_id 把出现位置连到内容节点。相同字节可以共用一个节点，同时保留不同的路径角色。合并后的内容节点恢复不了当初没存下来的按路径事实。旧清单需要重新生成。

其它 6.2 消费者破坏

• 进程捕获。导入时不再转换旧版 v3（2a77469）。捕获需要明确的选定／启动可执行身份和 event_journal。空日志有效；省略字段无效。旧捕获留作历史，需要当前对比时重新捕获。不要用后来的摘要编造启动身份，也不要从分开的日志编造事件顺序。
• 文件系统效果在无法判定创建或删除时，可以报告 status: "unknown" 并给出原因。未知不是「不存在」。
• 清理。一次性分析在提供者清理失败时，可以报告 cleanup_incomplete，而不是静默成功（#1211）。保留 details.partial_observation 或主要诊断。观察成功不能证明清理成功。
• JavaScript 投影要求 presence 为 present、absent 或 unknown-coverage。未知的值与未知的存在性是两回事。对象操作使用 properties.property_path（路径段或 null），不是压扁的名字。
• 函数对比使用 unchanged、changed 或 unknown。truncated 状态和 summary.truncated 计数器已删除。
• 符号链接在 target_state 为 unreadable 或 unknown 时要求 target: null。外部目标保留观察到的绝对路径。像 <outside-root> 这样的显示占位符不能当查找数据。这些图需要重新导入。

6.3.0 — 捕获的生产者记账

发布于 2026-10-09。缺少当前生产者记账或事务身份的历史捕获会被拒绝；缺少无障碍或存储维度的网页差异也会被拒绝 （3283a45）。 保留原始捕获，用当前生产者重新捕获。对比消费者必须包含每一个维度。不要为了让差异还能画出来而补一条没观察到的记录。

同一发行里，若你存储这些对象，下面几条同样可见：

• JSON 形状路径使用带类型的属性段和数组元素段。WebMCP 的 input_schema_shape 改为 input_schema 与 input_schema_sha256。
• 文件系统摘要省略项要求 system_code。预算与已改文件的省略用 null。不可用文件的省略保留操作系统错误码。
• 提供者分析输出必须显式给出过去用默认值修补的元数据。不支持的可空侧面是 null，不是省略。
• JavaScript 语义图存储 Evidence 上下文 ID 与位置，结果需要内联的 evidence_contexts 表。
• source map URL 位于由 declared_url_sha256 选定的目标观察上。doctor 的 skill 身份不再发出 installed_catalog_digest；改用 identity.skill.state。
• JavaScript 应用分析里从未递增的 truncated_scopes 统计已删除。

6.4.0 — WebSocket 结果与已存储的图

发布于 2026-10-11。2026-10-13 核对时的 npm latest。发行：rea-agents-6.4.0。

WebSocket 字段改名

读 network.websocket_connections。不要读 network.websocket_events。没有旧别名 （db4e360）。 每条连接含 request_id、url 和 events。大小未知时 payload_bytes 可以是 null。先改仪表板，再把缺字段说成捕获失败。

已存储的 Evidence 与图

• 已保存的引用图。排除项需要匹配的 pattern，并区分 project-ignored 与 default-ignored。缺少该来源的图要重新导入（6585293）。
• 制品图的边。子制品 ID 与路径来自由 occurrence_id 选定的出现位置，不是边字段 child_artifact_id／logical_path。更早的清单 Evidence 不再符合新承诺（#1493）。
• 语义图 schema。节点和关系不再包含 identifier_strategy，关系 ID 也不再对其做哈希。更早的 Evidence 不再通过校验（#1474）。
• 语义身份。从父图选择 ID。事件名读 event_name，端点读 endpoint，字面量读 properties.value。新分析对过长或保留的名字使用基于摘要的 ID。先前存储的图保留原 ID，仍是有效的工作流输入（#1427 及相关）。
• 使用自定义规范化的捕获对比必须用 literal-replacements-v1 重新捕获两侧。无版本的旧模式捕获仍可读，但不能与新模式捕获对比。没有模式的捕获不受影响（#1456）。
• 终端捕获用 columns × (rows + scrollback) 把初始缓冲区和调整后的缓冲区限制在 1,000,000 个单元格内。过大的场景在启动前被拒绝。

库作者，不是 MCP JSON

进程内的直接资源 API 现在要调用方持有的 ArtifactResourceScope（清单、提取、JavaScript 分析、引用导入、网页导出）。对 readJavaScriptArtifactFiles，scope 是第三个参数，中止信号是第四个。 这些操作的 CLI 与 MCP 输入没有变。若你只通过 stdio 调用工具，不要往工具参数里加 scope 对象。

可选的智能体验证报告接受 schema 版本 4。该报告的生产 CLI 与 MCP 合同没有变。

相关

• 更新日志，3.2.0 至 6.4.0
• 安装，钉在 6.4.0
• 6.4.0 客户端矩阵
• 6.4.0 运维指南（ADB、JEB、compact schema）
• JEB，自备许可
• Android ADB 设备通道