从 1.2 升级到 1.4
本指南以已发布的
1.2.0为升级基线,直接迁移至1.4.0发布目标;最新公开稳定版本以 GitHub Release、npm 与 PyPI 为准。未独立发布的1.3.0全部修复已纳入,不要求安装中间版本。只有同版本 Release、npm/PyPI 制品与最终资格证据确认后,才按正式版本切换。源码和工程 CI 不等于公开发布、生产效果或 Provider 认证;完整变更见双语发布说明。
升级前
停止正在使用旧版本的 CLI、SDK 和 Worker,备份配置、Session、RunState、Checkpoint 与业务文件。全部 CoreMind npm 包、Python SDK、bundled Worker 同步更新为 1.4.0,避免新旧进程并发写入同一状态目录。保留 Node.js ≥ 22.19、Python ≥ 3.10 和 Git 工具的 Git ≥ 2.36 要求。
Config 版本和 Protocol 主版本的既有边界保留:Config v2 继续兼容,deferred 仍须显式 Config v3,Protocol v1 继续支持。Protocol v2 新增任务/会话 DTO 与能力,使用新功能须匹配完整 Schema 指纹。ToolPolicy 构造选项新增可选 protectedPaths 保护条目,authorize() 的 identity 新增可选 signal?: AbortSignal,既有调用保持兼容。SDK 和 Worker 仍须匹配,不能因某项修复未改 wire shape 就混用不同版本。1.2 以前版本先按1.0→1.2 指南核对既有迁移要求。
检查行为变化
文件与框架状态
普通业务工具不能写框架管理的持久状态,三档权限和显式 allow 都不能覆盖该保护。把业务输出放在合法业务路径;恢复、清理和状态维护仍交给宿主维护接口。现存文件有多个硬链接时,普通工具写入会拒绝,读取仍按原权限;需要修改时由宿主明确处理链接关系。保留合法工作区文件的审批与 Checkpoint 流程;此保护不隔离任意宿主代码。
Workflow 输出与取消
同一 Agent 连续运行时,模型仍可使用同一 Session 历史;prompt/call 的步骤输出、saveAs、后续插值和 transcript 只取本步骤新增 assistant 文本。例如前两步分别产生 A、B,第二步结果应为 B。若业务解析依赖历史回答被重复拼入结果,需调整解析与断言。
parallel 首次失败或暂停会取消同组其他步骤并等待收尾,保留首个错误;Run 结束后不再准入新模型调用。全成功仍按声明顺序聚合。取消不撤销已经开始的工具操作,继续按收据核对副作用。
Python v1 工具 Schema
@client.tool 自动 Schema 解析 from __future__ import annotations 及字符串形式的 int、str、bool 和已有容器注解。无法解析的前向引用须提供显式 parameters;原显式 Schema 保持兼容,复杂 typing 不超出既有支持范围。
Node 侧仍先按既有规则转换再校验,例如 int 参数的字符串 '5' 可转为整数 5;转换后仍未通过 Schema 的参数才在 callable 执行前拒绝。不要将修复理解为严格拒绝所有原始类型差异。
Diff grader
preserveExisting: false 仅关闭旧脏内容保护,不能绕过 allowedPaths、forbiddenPaths、requiredPaths 或 maxChangedFiles。变化集包含基线与终态的状态或内容变化;状态和内容均未变化的既有脏文件不计,原 untracked 文件删除计入变化。原 stage/unstage 计数和默认 true 保护保持。检查原评测是否依赖被遗漏的变化,按业务允许范围修正用例,而不是移除约束。
Protocol v2 启动失败
已接受 Run 的 Runtime 初始化失败会保留共享分类的稳定错误码、对应终态与安全消息,可用 query/events 查询。消费端应按实际错误合同处理,不再假定全部是 agent_failed。未知 unclassified_error 保守暂停且要求人工审计;暂停并不自动证明可安全 resume。该启动错误修复本身不新增错误字段,也不公开凭据或原始堆栈;新增任务管理的身份与子码见下文。
Web 工具收尾
web-fetch/web-search 的非 2xx 或正文读取失败会先等待正文取消/释放的清理尝试结束,再结算本地网络活动;清理失败不覆盖原 HTTP/读取错误。保留正常结果、取消、权限与网络策略,web-fetch 的 2 MiB 上限不变;不向 web-search 增加新的大小合同。
readline 与 doctor
readline /exit、!exit 现在先请求取消活动 Run 并等待收尾,与 TUI 一致。若管道希望等待已开始的普通回答自然完成,应使用原 EOF 路径;空闲、审批和 MCP 登录等待的既有行为保持。退出不会自动回滚已开始工具副作用。
doctor <配置文件> 复用所选 Provider 的既有凭据策略,合法匿名/Header-only 自定义端点不要求无关 API key;带 baseUrl 的内置同名入口也按自定义端点处理。显式缺失凭据仍失败,原生内置鉴权要求不变。无配置时保留通用体检;诊断不加载项目脚本、不发 Provider 请求,不证明凭据有效或真实连通。
安全策略的支持表和已交付能力说明已校正;支持政策、0.3.1 重大安全问题例外和私密披露方式没有扩大,见安全策略。
新增的持久任务与跨语言边界
任务定义、状态与迁移
TaskSession 在唯一 Node Runtime 内新增持久任务阶段,任务 checkpoint、可选 document/entry 和下一阶段使用同一原子提交记录;旧 Session/Run/Workspace 数据不迁移为任务。start 只保存初始状态,每次 resume 执行一个阶段;消费端须处理 ready、paused、sleeping、completed、cancelled。完成或取消后再次恢复只返回终态,并发写入拒绝而不隐式排队。
更改定义、Schema、处理器、闭包或依赖行为时,由可信宿主显式提升定义 version;需要升级已有任务时提供 migrate(previous, signal),仅返回 { phase, checkpoint }。同版本漂移、降级、缺少或无效迁移均拒绝;迁移失败保留原事实,成功状态先原子提交再执行下一阶段。配置、审批、工具能力或凭据路由变化还须更新 authorityVersion,不能用状态迁移授予新权限。处理器从阶段顶部重新进入,内存、计时器与 JavaScript 栈不会恢复。
持久等待与宿主 alarm
阶段可返回绝对 UTC 毫秒 sleepUntil,持久保存 sleepId;宿主以 nextWake() 从当前时钟重算等待,用稳定 wakeId 与准确 sleepId 调用 wake,再显式 resume。唤醒只保存 ready,不自动执行下一阶段;进程若在 wake 落盘后退出,宿主启动时还须查询并恢复已知 ready 任务,仅扫描 nextWake 不够。过早、重复、过期或终态通知按结果处理,不重绑旧键或复活任务。
等待不扩大原 Run、工具、阶段或 Worker 超时。宿主负责启动进程和投递 alarm,框架没有新增后台分布式调度器。取消不回滚外部操作;关闭空闲会话不取消已持久保存的等待。
稳定键调用与副作用核对
一个阶段选择 context.run 或 context.runCalls,使用同一个受治理 Run。executeTool(key, tool, args) 的键绑定任务、阶段、定义版本、阶段 Run、参数、工具及权限身份;重开仅在原事实证明安全时复用已提交结果。不同键按既有顺序串行 await,不能改变参数、增删或调换旧键来绕过恢复。session.calls(taskId) 提供调用与结果记录;结果和任务提交仍受既有大小上限约束。
Run 效果或结果已落盘但阶段未提交时,恢复核对原 Run/key/result,不盲目再做工具。未知效果保持暂停核对,不能更换 key 或新建 Run 重发;裸 JavaScript、随机值、时间和未受治理 I/O 不受调用账本保护。这不承诺外部 exactly-once。写入确认失败不证明回滚,应保留目录、关闭重开,再查任务与原 Run 事实。
会话分支、fork 与路径身份
ChatSession 新增树查询、命名分支、持久选择及消息节点 fork;继续对话只读取所选历史,原消息仍保留。fork 使用新会话身份,不复制旧 Run、控制回执或执行授权。导航须满足持久化、空闲与原 writer 条件;树包含完整消息,宿主仍须实施访问授权,绑定 sessionId 不构成多租户认证。
同一物理工作目录通过 Windows 长短名或目录链接重开时,核对目录与公开文件身份后沿用 v4 原存储,不搬移历史;不同物理目录或复制文件不能据此恢复为同一会话。别名发布或写入确认失败可能留下已提交事实,先核对原状态,不盲目再次 fork 或删除来源。
TS、Python 与 Worker 一起升级
使用匹配的 1.4.0 SDK 和 bundled Worker,通过 Protocol v2 完整 Schema 指纹与 durableTasks/sessionBranches 独立能力协商。旧 Protocol v1 保持既有行为;旧 Worker 显式不支持新能力,不能静默降级。TS 和同步/异步 Python 共用原 Node Runtime、任务/Run/会话事实与错误身份,不新增 Python 运行时、事实库或调度器。
任务定义由可信 Node 宿主通过 runStdioWorker 注册;默认 Worker 没有任务注册表,Python 只传定义 ID 和 JSON,不传 callable、源码、任意模块路径或凭据。宿主代码加载信任与工具权限分别控制,可信处理器不是沙箱。任务子码位于 details.taskCode,请求的 operation/action/sessionId/taskId 继续核对,取消或 RPC 错误不等于业务效果已回滚。
重试与依赖风险
请求 ID 或长数字中的状态码子串不再触发暂态重试,未知错误保留原分类与人工审计。将底层运行库依赖族整体升级至 1.5.0,并核对实际 npm 安装图使用 Undici 8.12.3 和 minimatch 11.0.3。这两个版本超出 #359 登记的九条公告影响范围。独立开发依赖风险保留原审计范围与 2026-11-14 到期日,见安全策略。
底层运行库 1.5.0 的工具参数校验可按 Schema 转换输入,例如将数字字符串转为数字。升级时用业务输入核对审批、执行和恢复记录使用同一组有效参数,并确认无效参数仍被拒绝。
依赖目录升级可能改变部分 Provider 的默认模型。需要固定模型行为时,在配置中显式设置 provider.model。
验证与回滚
先在备份副本验证业务文件写入与状态保护、同 Agent 输出、并行失败/暂停收尾、Python 自动/显式 Schema、Diff 变化集、v2 错误持久查询、Web 失败清理、显式退出与 EOF,以及 doctor 凭据策略。使用框架已有测试与业务评测,不把一次成功当成完整发布资格。
在备份副本中补验任务 A→持久等待→进程重启→准确唤醒→复用原 Run/key/result→阶段 B 的完整链路,并比较 TS 与同步/异步 Python 的状态、身份、错误和取消;同时检查会话选择/fork、未知能力/旧 Worker 拒绝、权限及写入故障。普通 close/reopen 不代替真实进程退出验收,离线夹具不代替外部服务认证。
正式发布须使用绑定 1.4.0 最终 main、Runtime/Worker 与准确制品的严格 Provider、双平台工程/稳定性/覆盖率/真实 PTY 和公开回装证据。旧版本认证不可复用;本地受控夹具不认证外部 Provider/OAuth/MCP 互通。
需要回滚时停止新进程,将程序、SDK 与 Worker 一起恢复到已发布 1.2.0,并恢复升级前配置和持久状态备份。旧 SDK 不理解新任务 sleep/wakes、调用账本和会话持久选择;必须一起保全并恢复任务、Session、Run 与 Workspace/Checkpoint 事实,不能让旧 SDK 单独 resume 新任务 Run,也不能编辑事实或关闭校验来兼容。不要让旧程序继续写入无法理解的新事实,也不要并发启动两版本写同一状态。人工核对外部效果后再决定补偿或重试;恢复本地文件不撤销外部操作,已发布同版本制品不得覆盖。