# v1.0 安装、升级、回退与验收

## 已验收运行矩阵

GitHub 预发布候选在以下组合上验收：

| 组件 | 版本或约束 |
| --- | --- |
| Node.js | `24.15.0`；包声明支持 `^22.19.0 || >=24.0.0` |
| npm | `11.12.1`，本仓库的规范构建工具 |
| Corepack | `0.34.6`，用于独立 DSH 验收 profile |
| pnpm（DSH 验收 profile） | `11.24.0`；本插件构建不要求 pnpm |
| DSH | 固定 `0.1.1-rc.2` |
| Cordis | 精确固定 `4.0.1` |

使用 `npm ci` 按 `package-lock.json` 重建依赖。不要用未锁定的 DSH `latest` 作为生产基线。

## DSH RC 风险豁免

DSH `0.1.1-rc.2` 是发布候选而非稳定版，其配置、插件加载和工具协议仍可能变化。v1.0 本地候选只对上表组合给出兼容性证据；升级 DSH 前必须在独立 profile 和输出目录副本上重跑真实端到端验收。

接受该风险的前提是：固定 DSH 版本、保留上一版插件包和 profile 备份、完整备份 `outputDir`，并能按下文回退。若组织不能接受 RC 依赖，应继续使用已验证的旧版本，不部署此候选。

## 从 tgz 安装

1. 获取发布附件 `dsh-teacher-preset-1.0.0.tgz` 和 `SHA256SUMS.txt`。
2. 在安装前计算 tgz 的 SHA-256，并与 `SHA256SUMS.txt` 逐字核对。
3. 建立独立 DSH profile，固定安装 `@deepseek-ai/dsh@0.1.1-rc.2`。
4. 通过 DSH 的本地文件插件方式添加 tgz 或其解包目录。
5. 在独立 `outputDir` 中启动 DSH，确认 22 个插件工具可见，并用合成数据执行“迁移 → 上下文 → 单元包 → 评价诊断 → 关联下一课包”闭环。公开附件不包含 DSH Pilot；项目维护者如另有完整受审 Pilot runtime/profile，可按其内部手册另行执行控制器验收。

源码构建使用：

```text
npm ci
npm test
npm pack --dry-run
```

## 从 v0.4 升级到 v1.0

1. 停止使用目标输出目录的 DSH 实例。
2. 复制整个 v0.4 `outputDir` 作为只读备份，并记录原插件版本。
3. 在独立 profile 安装 v1.0 候选，保持 `outputDir` 指向副本进行演练。
4. 调用 `teacher_migrate_workspace`；它只读取并索引旧 Markdown，不移动或改写材料。
5. 核对 `legacy-materials.json` 的数量和 SHA-256，并抽查原文件字节不变。
6. 演练通过后再对正式目录执行同样步骤。

JSON 更新使用 `.next` / `.previous` sidecar 恢复；单元包使用 staging 和 transaction journal。启动时会完成有完整日志的中断事务。没有日志的 staging 不会自动删除，以免静默丢失内容。

## 回退

1. 停止 DSH，保存当前日志和失败现场。
2. 切回先前固定的插件包和 DSH profile；不要覆盖原备份。
3. v0.4 会忽略 `.teacher-workspace`，原 Markdown 仍可继续使用。
4. 如果 v1 期间修改了旧材料，使用 `.backups` 或升级前的完整副本恢复所需版本。
5. 在独立目录验证旧版的保存、读取和恢复后，再恢复日常使用。

不要通过删除 `.teacher-workspace` 来“修复”异常；这会丢失上下文、单元包和评价链路。应先导出现场并定位具体损坏记录。

## 卸载

先从 DSH profile 移除插件配置或本地插件引用，再重启并确认工具不再注册。卸载默认保留 `outputDir`，因此可以重新安装或离线导出。只有数据负责人按 `DATA-LIFECYCLE.md` 完成备份、范围确认和批准后，才删除具体输出目录。

## 发布候选验收

发布候选至少满足：

- 干净构建后的旧版兼容套件、v1 集成套件和发布契约全部通过。
- `npm audit --omit=dev` 为 0 个已知生产漏洞。
- `npm pack --dry-run` 只包含允许发布的源码产物、模板和文档。
- tgz 能在空目录安装并成功导入插件入口。
- v0.4 fixture 迁移前后 SHA-256 一致。
- 真实 DSH 依次完成迁移、上下文保存、单元包创建、评价记录和带来源关联的下一课单元包。
- 包内 SBOM、NOTICE、SECURITY、数据生命周期和本手册可读取。

本地验收不等于机构隐私、课堂使用、真实模型数据处理或代码签名审批。GitHub `v1.0.0` 预发布已由项目所有者单独授权；npm registry 发布仍需维护者账号登录和 2FA。

内部发布构建器默认只生成 `INTERNAL_PACKAGE_AND_CONTROLLER_VERIFIED`。只有显式传入机器可读的 DSH 验收证据，且 `scripts/verify-dsh-acceptance.mjs` 确认其中的 tgz SHA-256、源码修订、DSH/Cordis 版本、22 个工具清单、完整合成闭环和磁盘检查都与本次构建一致时，manifest 才能晋级为 `LOCAL_DSH_RC_VERIFIED`。通过验证的证据位于内部 bundle ZIP 根部，并以独立 `DSH-ACCEPTANCE.json` 公开附件分发；它不放入 tgz，避免制品哈希自引用。