# 固定包生命周期与稳定发布计划

> 计划日期：2026-08-27

这份计划只处理当前 `v0.1.0` Public Preview 的两个剩余发布门禁：固定安装包的升级、卸载、重装与 fallback 验证，以及可追溯的旧版 baseline 和稳定版判定。

## 目标与边界

- 只使用独立的 `gitchain-test` profile 做破坏性验证。
- 保留用户当前 `desktop` profile，不覆盖本地 link、workspace 或用户配置。
- 所有安装都使用固定 tarball，并记录 SHA-512、DSH Desktop 版本、Windows 版本、profile 和测试时间。
- 旧版先做本地、明确标记的 `0.1.0-preview.1` baseline；它用于验证安装器的版本迁移，不作为已经公开发布过的历史 Release。
- 不把“目录 Issue 已创建”误认为运行时验收；目录收录、运行时验证和稳定 Release 是三个独立结果。

## 研究结论

DSH 官方 CLI 文档说明：`dsh plugin --profile <name> <pnpm args...>` 在 profile 目录执行插件管理；成功的 add/remove/update 会更新 profile manifest 与 bundle 列表，Bundle 变更必须重启 profile 才会进入运行时。相近的社区插件发布实践要求在 disposable profile 中安装固定 tarball、核对校验值、检查 composed config，再执行移除和重新安装。本轮通过 DSH Desktop profile API 重启，并在直接调用 pnpm 时手动核对/同步 `dsh.profile.bundles`，因为底层 pnpm 本身不会执行 DSH CLI 的 bundle reconcile。

## 阶段计划

### Phase 0：冻结基线

- [x] 确认工作区干净、`main` 与 `origin/main` 一致（本轮验收文档补齐后复核）。
- [x] 从当前 `v0.1.0` 代码线构建 `v0.1.0` tarball，保存 SHA-512：`sha512-Lu3QHIwgqCXB6/CRo9vaxOQd8BqIJSzN2rX1Hr3Os1FqIhXs8Q+ZCRK7HEThkVxH2T7gJZFj1sMFnsEfcx711w==`。
- [x] 记录 `gitchain-test` 初始 manifest、bundle 顺序、DSH Desktop `2.0.2.0` 和安装包来源。
- [x] 创建本地 `0.1.0-preview.1` baseline tarball，并标记为 test-only。

验收：两个包均可被 profile 安装，manifest 中插件和 bundle 各只出现一次。

### Phase 1：旧版安装与升级

- [x] 在 `gitchain-test` 安装旧版 baseline。
- [x] 重启 DSH Desktop，确认插件入口、完整图和 Host 查询正常。
- [x] 按 DSH 规则移除旧版，再安装固定 `v0.1.0` tarball。
- [x] 重启 DSH Desktop，确认只有一个入口、没有重复 bundle、完整图/first-parent/详情/Diff 正常。
- [x] 核对升级前后 profile manifest、lockfile、bundle 顺序和包 SHA-512；实际安装版本为 `0.1.0`。

验收：旧版 → `v0.1.0` 后只有一个 `dsh-git-chain`，核心 UI 和 Host 查询均通过。

### Phase 2：卸载与重装

- [x] 记录卸载前 profile manifest 和运行时入口。
- [x] 执行 `gitchain-test` 的插件移除操作。
- [x] 重启 DSH Desktop，确认 profile 不再引用插件 bundle；已打开的历史标签显示不可用占位，关闭该标签后入口消失。
- [x] 重新安装同一份固定 `v0.1.0` tarball。
- [x] 重启 DSH Desktop，确认入口恢复且核心功能通过。

验收：移除后无残留入口、残留 bundle 或错误请求；重装后恢复且无重复入口。

### Phase 3：fallback 与错误恢复

- [x] 从固定包解包出的 `lib/client.js` 运行 Chromium fallback smoke，确认无 better-sidebar 时 chip/overlay 可用。
- [x] 通过 GraphPanel/Host 自动化测试验证无 workspace、非 Git 仓库、Host 不可用和非法输入的稳定错误状态。
- [x] 确认 fallback 不显示堆栈、不泄露 profile 私有配置，并且可重试/关闭。
- [x] 记录 smoke 截图和结果；无法在 DSH Desktop 直接制造的场景明确标记为自动化 harness 证据，不冒充真实 Desktop 证据。

验收：固定包 fallback 通过，错误状态可读、可恢复，公开文档只声明实际覆盖的场景。

### Phase 4：稳定版决策

- [x] 所有 Phase 0–3 的执行项通过，且 typecheck、55 项测试、构建、package check 和固定包 Chromium smoke 为绿色。
- [x] 更新 `docs/COMPATIBILITY.md`、双语 README、CHANGELOG 和 Release notes。
- [x] 创建与当前主线一致的不可变稳定 patch tag `v0.1.1`，不移动已有的 `v0.1.0` Public Preview tag。
- [x] 追加与稳定 tag 一致的固定 tarball 与 SHA-512 Release 附件。
- [x] 稳定 Release 发布前复核没有未声明的兼容性限制，并将 README/CHANGELOG/Release notes 版本号统一。
- [x] 社区 Issue #218 继续保持事实状态，不把 stable Release 当作社区审核结果。

稳定 Release：<https://github.com/ShinonomeAya/dsh-git-chain/releases/tag/v0.1.1>

## 可追溯证据格式

每一步至少记录：

| 字段 | 内容 |
| --- | --- |
| DSH | Desktop 版本 |
| OS | Windows 版本 |
| Profile | `gitchain-test` |
| Package | 版本、文件名、SHA-512 |
| Action | install / start / restart / upgrade / remove / reinstall / fallback |
| Result | PASS / FAIL / PARTIAL |
| Evidence | manifest、命令输出、截图或 Smoke 结果 |

## 风险与回滚

- 如果升级后出现重复入口：停止继续发布，移除测试 profile 中的插件并恢复固定 `v0.1.0` 安装。
- 如果卸载后 profile 无法启动：只修复 `gitchain-test`，不手动改 `desktop`；保留 profile manifest 作为诊断证据。
- 如果固定包与当前源码不一致：以 SHA-512 为准，重新构建并丢弃旧候选包。
- 如果 fallback 只能在 harness 中验证：稳定版说明中保留该边界，不把它写成已通过真实 Desktop 的场景。

## 稳定版 Definition of Done

只有以下条件全部满足，才允许发布稳定 patch（`v0.1.1`；已有 `v0.1.0` Public Preview tag 保持不可变）：

1. 固定包旧版 → 当前版升级通过。
2. 固定包卸载后入口和 bundle 残留清零，重装后恢复。
3. fallback 和错误恢复证据可复核，且不泄露内部信息。
4. 自动化门禁与 GitHub Actions 绿色。
5. README、兼容性矩阵、CHANGELOG、稳定 Release 附件和社区提交字段一致。