# 版本升级与资料刷新

## V1 项目的选型建议

对正在使用 V1 的项目，优先核实 V2 能力覆盖、项目阶段和迁移成本。V2 能力满足、项目仍在测试阶段且代价可控时，建议采用 V2。在 V1 项目中使用统一入口提供的只读迁移评估，获取源码清单，再结合真实数据、在途流程和团队计划评估。命令以统一入口的帮助为准；V2 项目引擎不承担 V1 迁移操作。

确认迁移后，按项目形成 AppSpec 设计、数据与流程映射、验收和回滚方案。尚未完成迁移决策时，原项目继续使用其锁定的 V1 引擎；工具链的同代升级与应用跨代迁移分别处理。

## 升级前核对 {#before}

先运行 `pnpm list openxiangda --depth 0` 核对项目实际安装的根包版本，再运行 `pnpm openxiangda context --json` 核对平台绑定和启用能力。取得目标精确版本和变更说明，核对平台能力要求。应用只直接管理 openxiangda 根包，内部物理包组合由该发行确定。

上下文的 `toolchain.packageName` 标明版本来源，当前 `toolchain.version` 是 `openxiangda-devkit-core` 的物理包版本，不能当作 openxiangda 根包版本。根包与 CLI、Devkit、MCP、contracts 等独立版本化，由根包精确依赖组成同一发行；数字不同不代表版本漂移。

协议版本说明数据格式，能力版本说明某项平台契约，校验实现摘要说明实际执行的规则；不能只比较名称里的数字判断是否配套。旧工具读不懂新协议时升级项目根包及 Skill/MCP；平台缺少新能力时由维护者升级或启用平台能力；规则摘要不同则按发布组合核对两端。诊断无法确定哪端落后时，不应无条件升级平台或反复改业务代码。

共享校验使用 `configuration-compatibility/v2` 描述，包含校验实现摘要。切换到这一契约时，平台和项目工具链需按同一发布说明配套升级。随后每次发布在构建前核对实现摘要；不要反复修改业务代码来处理工具版本不配套。

引导式开发使用 workspace-context/v3 与 AppSpec context/v4。升级后按实际业务补齐总纲与关联变更；空模板不能正式测试发布，生产晋级需要原测试版本的验收计划和实际报告。旧候选缺少计划时建立新的测试候选并验收，不自动补写过去的确认或通过记录。普通 dev/check 仍可用于整理和验证尚未完成的项目。

## 更新项目 {#upgrade}

按实际启用的功能核对要求，不把浏览器文案、局部错误提示等更新当成平台升级理由：

| 变化 | 平台条件 | 应用验证 |
| --- | --- | --- |
| ResourceTypes 和 Nest 类型绑定 | 复用现有 Data API；不新增服务端模型协议 | 运行生成与类型检查，确认隐藏字段可缺失及 revision 来源 |
| 浏览器安全诊断、安装错误提示 | 复用现有响应及请求头 | 模拟只读失败、导出失败、网络中断，确认没有重复写入 |
| 原流程提交结果恢复 | 可选 `business-process.original-resolution` 1.0.0 | 原幂等键查询、刷新恢复、授权拒绝，未知不能转换为未提交 |
| 业务角色候选 | 可选 `directory.assignment-candidates` 1.0.0 | 当前动作声明的角色、目标环境、过期/锁定账号、提交再校验 |
| 预检一次汇总 | 已协商的 configuration-compatibility 与共享 validator 摘要一致 | 同时缺能力/密钥/登录提供方时一次报告；成功结果仍按闭合协议校验 |

平台能力声明、共享校验摘要、根包精确依赖及发布说明共同构成兼容依据。版本号大小、某次 Pod Ready 或历史工单“已发布”不能替代当前目标能力读回。未启用新增可选能力的旧应用继续使用原协议；不承诺未经回归验证的任意旧版本组合。

更新项目的精确根包依赖并安装，提交相应锁文件；不要使用 latest、alpha 或范围版本代替明确版本。运行统一 check，处理实际契约变化，再在测试环境验证后晋级。

执行 `pnpm openxiangda skill install --workspace . --force`，通过新版本根包安装 Skill；已有项目使用项目安装模式时会刷新 AGENTS 的平台管理段，并保留管理段外的自定义说明。没有可识别管理段的旧 AGENTS 不会被整份替换；先审阅工具输出的候选内容，再合并需要的规则。

持续运行的 MCP 进程仍可能加载旧代码，升级后重启该连接并重新读取 workspace_context、资料版本和当前契约。全局 Skill 的版本不代表所有项目版本；进入项目后以项目锁定的 CLI 和随包资料为准。

## 整理旧模板测试 {#tests}

旧模板的测试与源码预算属于项目自有文件，升级包不会静默删除。若新增页面或合理重构触发样例限制，先提交当前源码，检查 `apps/web/test/contracts.test.ts`、`apps/web/scripts/check.mjs` 和 `apps/server/test/smoke.test.ts`：把项目实际业务断言保留，仅移除固定初始页数、样例文件名、普通业务词和总行数限制；Web 的 check 保留 `tsc -p tsconfig.json --noEmit`，后端可用 `tsx --test` 自动发现用例。

旧 `apps/web/e2e/` 中的通用模拟平台夹具及 `*.e2e.html` 不代表本应用验收。确认没有项目用例依赖后，可连同 Vite 中对应的预热入口整理；保留项目自行编写的用例与配置。使用实际业务记录重建验收覆盖，并执行完整 check；不要把整理样例当成修复真实契约、类型或权限错误的方法。

## 失败与回退 {#rollback}

保留失败指针和变更差异。资料缺失或摘要不符时重新安装该精确版本，不能复制其他版本的文档掩盖问题。应用版本回滚、依赖降级和数据/迁移恢复分别处理；降级 npm 包不等于撤回已经发生的业务写入。

平台能力不足时交由平台维护者升级，不通过删除字段、改生成契约或退回 1.x 接口绕过。开发者无需执行工具链 npm 发包或平台数据库迁移。

## 从 1.x 迁移业务到 2.0 {#business-migration}

迁移按用户任务验收，不能只以“字段已搬过来、CRUD 页面能打开”为完成。1.x 继续使用独立维护工具；在原业务尚未完成切换时保留它的入口、数据和恢复路径，不让 V2 编译器兼容或发布 V1 工作区。

先在 AppSpec 的当前迁移变更中保存下列矩阵，引用原资料/页面/流程的精确来源及现行版本；Schema、Head、部署状态仍从原平台读取，不复制为另一份权威。已有确认可引用，不重新编造用户确认。

| 核对维度 | 必须记录 | 完成证据 |
| --- | --- | --- |
| 用户任务与入口 | 谁、何时、从哪个入口完成什么；原入口与新入口映射 | 对应角色走通完整任务，结果读回 |
| 页面与设备 | 列表、详情、编辑、自定义报表及必要设备范围 | 真实平台入口交互；未要求移动的管理页面不额外扩范围 |
| 角色与数据范围 | 角色并集、组织/部门/本人范围、字段读写与越权拒绝 | 至少允许和拒绝各一条；超管不能代验普通角色 |
| 模型与历史数据 | 原字段含义、精度、空值、子表、关系、状态及历史记录归属 | 原样本与新结果逐项对照；原ID映射和不可迁移项明确 |
| 流程与状态分支 | 发起、办理、转交、退回、撤回、补正、抄送及终态 | 必要正常/异常分支、实际办理人、待办和业务状态一致 |
| 文件与附件 | fileId、记录绑定、原存储位置、下载权限、引用关系 | 历史样本可授权读取；不能按当前存储默认值猜归属 |
| 后台与外部集成 | 事件、Timer、通知、外部订单/账务等效果及原键 | 原操作回执、外部读回、失败和未知结果恢复路径 |
| 并发和恢复 | 重复提交、版本冲突、网络丢响应、处理中退出 | 沿原键查询和恢复；无重复副作用、不丢已确认结果 |
| 发布与切换 | TEST版本、验收人、停写/流量切换、旧系统职责、回退边界 | TEST成功版本原样晋级，关键数据与任务再读回 |
| 测试收尾 | 新测试记录来源、允许清理的域、保留证据和未知效果 | 原owner核对并清理；不支持的域标为未回收，历史数据不批量删除 |

每一行绑定验收用例ID、来源、目标TEST版本/包摘要、实际角色、结果和证据。使用“通过、失败、未覆盖、不适用（附原因）”区分状态，不能把未实现分支写成通过。临时脚本或模拟接口只证明其覆盖的行为；真实角色、原文件与外部效果另行验收。

建议先选代表任务覆盖公共边界，再批量迁移相同能力；无需为每条流程重复平台完整数据库/队列矩阵。存在未知外部写入时，先按原请求键与业务编号读回，不切换身份、换键重发或回放整个流程。数据库/外部业务效果已提交后，回滚代码不等于撤销效果；按原恢复方案处理。

迁移方案和实施记录属于应用项目，通用规则从本专题引用。最后按[验收](./testing.md)和[交付](./delivery.md)关闭原TEST版本；不能用新构建替换已验收候选。