从 0.2 升级到 0.3

本指南面向从 0.2.0-rc.1 迁移或评估 0.3.0 的用户。0.3.0 已通过 GitHub Release、npm 与 PyPI 正式发布；安装时仍应核对所选渠道的目标版本。

升级前

1. 提交或备份业务工程，记录当前 Node、Python、配置、Session 目录和包版本。
2. 停止正在运行的 CLI、Worker 和 SDK 进程。
3. 备份 sessions/、.coremind/ 与业务系统副作用收据；密钥只保留在环境变量中。
4. 如果业务代码直接依赖底层模型、消息或工具类型，先切换到 CoreMind 公开类型。

安装与自检

源码方式在仓库根目录执行：

npm ci
npm run build:python-worker
npm run check

应用升级时必须把 8 个 npm 包作为同一版本族升级；Python SDK 必须整体升级 wheel，不要把新版 Python 客户端与旧 Worker 混用。升级后执行：

coremind --version
coremind doctor coremind.yaml
coremind check coremind.yaml --profile strict

兼容与新增合同

• Config 仍为 schema v2，Protocol 请求仍为 v1，既有权限模式、通用终态和 CLI 退出码保留。
• RunResult.operation 与 RunResult.snapshot 成为权威运行证据。JSON 消费方应容忍新增字段；手工构造 TypeScript RunResult 的测试夹具需补齐快照。
• Python SDK 初始化时要求随包 Worker 声明 runSnapshot；版本混用会返回 protocol_capability_missing。
• Session 首次迁移前创建 .v3.backup，迁移使用版本化仓库并最后切换稳定公开路径。无法无损迁移时保留原文件并失败关闭。
• 大工具输出进入工作区 .coremind/artifacts/，模型只接收有界预览与相对引用。疑似凭据不会写入 Artifact。
• TUI 新增 /artifacts 与 /context，/status 增加恢复、压缩、产物和评测状态。
• 生命周期扩展只有四个事件，必须显式声明信任、能力和授权；它不是操作系统沙箱。
• Provider 认证升级为七项真实检查，旧五项证据不再表示当前认证。

验证

至少完成同一个业务 Case 的 CLI、TypeScript 与 Python 运行，并比对 snapshot.runId、operation、outcome、metrics 和 trace。涉及写入时还要验证审批、Checkpoint、Diff、Restore、Session 恢复和 abort。

回滚

1. 停止所有新版本进程，保留 RunState、Trace、Artifact 和外部副作用收据作为审计证据。
2. 确认没有存活 writer 后再处理锁；不要直接删除活动锁。
3. 使用 .v3.backup 恢复旧 Session，切回完整 0.2.0-rc.1 npm 包族与 Python wheel。
4. 不要只回滚一个内部包；不要自动重放结果不确定的外部副作用。

分批细节见 Runtime Adapter、Session 与恢复、Context 与 Artifact。