# DSH 0.2.1-alpha.5 适配记录（v0.28.0-alpha.0）

> 状态：本地适配验证完成，未发布。以下结果由主线程执行并确认；未修改 DSH 源码或升级真实用户 profile。

## 1. 已批准范围

- 宿主精确目标：DSH `0.2.1-alpha.5`；插件版本：`0.28.0-alpha.0`。
- 单支持线：13 条 DSH peer 下限为 `^0.2.1-alpha.5`，开发依赖与 CI / 安装脚本钉精确宿主版本；不写旧版运行时兼容层。
- DSH `0.2.0-rc.2` 用户继续使用 npm 已发布的插件 `0.26.1`；`0.27.0` 尚未发布到 npm。`0.2.0-rc.1` 用 `0.24.1`，`0.1.7` 线用 `0.22.1`。
- alpha 发布后使用 `dsh plugin --profile web add dsh-better-sidebar@0.28.0-alpha.0`；`latest` 不是本 alpha 的安装目标。
- 不修改 DSH 源码，不升级真实用户 profile，不发布 npm。

## 2. 两项删除型迁移

### Connection admission

alpha.5 删除 `webRuntime`。插件注入改为 `connection`；所有 `/sidebar` HTTP/WS 路由调用 `ctx.connection.requestRejection(req)`，仅返回 `undefined` 才继续。Host/Origin 与浏览器认证由宿主裁决，不复制 trusted-host 列表或恢复插件自建例外；拒绝应发生在读取请求体或升级之前。

### Runtime invariants

[官方升级指南](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.5/docs/upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants/guide.md) 明确移除 `@deepseek-ai/dsh-invariants`、`ctx.invariants` 与各宿主包的 `/invariant` 子路径，无替代包。不能把不存在的版本钉成 alpha.5，也不保留 rc.2 包混入新支持线。

本插件同步移除 invariant companion、类型、包导出与打包清单。压缩种子回归移除上游 `/invariant` 导入，继续以公开 surface fold、seed validator 和事件结构断言覆盖原行为，不自建 invariant 框架。

## 3. 当前执行目录、labels 与兼容性判定

用户已选择文件 / Git / 终端与新建 sidechat 跟随会话 `working_directory`。live 读 `ctx.workingDirectory.get(session)`；cold 通过 `ctx.sessionQuery.observeSession` 的 `projectionMode: 'all'` 读取当前目录，lease 在 `finally` 释放。linked worktree 仍按 base 目录记账；sidechat seed 尾部 stamp 当前 cwd，避免历史 seed 目录覆盖新线程当前目录。

alpha.5 的 `TerminalBlockLabels` 新增必填 `commandLine(line)`，两个消费者已补，全 21 份词典 key 同步。伴随更新 Cordis `4.0.5`、schemastery `~3.18.5-alpha.2`、group `1.0.5-alpha.2`、include `1.0.10`。稳定 Cordis 同时满足 alpha 宿主与稳定传递 loader 的范围，无需 override；剩余 4 条 peer 警告仅来自可选 better-locale 的旧 DSH 支持线。

[官方兼容性升级指南](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.5/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md) 描述 alpha.3 之后的规则变化：package 自有 `engines.dsh` 存在时独立决定兼容性，否则才读 DSH peers；拒绝记录由 `peers` 更名 `requirements`。本插件不新增 `package.json#engines.dsh`，仍用 13 peers；第三方 `dsh.plugin.json#engines.dsh` 不参与宿主判定。

## 4. 同步面

- 依赖、lockfile、插件版本与 manifest。
- Connection 注入、路由准入、结构化类型及测试夹具。
- CI、e2e 默认/预期宿主版本、两个安装脚本。
- 当前 README、接入指南、宿主契约、开发规则及本次 CHANGELOG 新条目；历史记录不改写。

## 5. 验证矩阵（主线程执行并确认）

| 检查 | 状态 |
| --- | --- |
| 安装 alpha.5 依赖并检查 lockfile 收敛 | 已执行；最终伴随版本见上文 |
| `pnpm peers check` | 仅可选 better-locale 的 4 条旧 DSH peer 警告，无 loader 未定项 |
| 消费宿主包类型面与裸 import 差集 | 已审计 74 个 primitives 消费符号与 27 个宿主包；必填变化为 commandLine；新增裸 import 均由宿主包或平台模块表提供 |
| 会话格式、子代理描述符版本、web profile inject | 主线程实跑常量仍为 4 / 3；surface 与 sidebar-right 的 6 份消费声明逐字节相同；独立 tag 审计确认客户端 roster 只增不减，真实挂载通过 |
| `pnpm typecheck` / `pnpm lint` | 新鲜通过 |
| `pnpm test`（默认 CI 入口） | 219 文件全部通过；2634 passed / 17 skipped，20.29 s，无 unhandled errors |
| `pnpm test --maxWorkers=1` | 219 文件全部通过；2634 passed / 17 skipped（共 2651），96.1 s |
| `pnpm build` / `pnpm check:consumer-types` | 新鲜通过；浏览器 consumer 不泄漏 Node 类型 |
| `pnpm check:engines` | rg 通过；fd 缺失，未执行 fd 检查 |
| `pnpm pack` 与 tarball 内容检查 | 通过：467 项、版本 0.28.0-alpha.0；废弃 invariant / trust-fence 源码、产物与声明均 0 项 |
| 精确 alpha.5 宿主的 `pnpm test:mount` | 最终交付 tarball 重跑 13/13 通过，2.5 min；此前一轮亦为 13/13 |
| 精确 alpha.5 宿主的 `pnpm test:mount:aggregate` | 通过：settings.get 返回 ok:true，未知路由 404，无重复路由 |
| Windows 原生运行验证 | 未执行 |

排查期间默认并发曾出现 watch / GC 相关失败，保留为历史而非当前阻塞；最终默认入口与单 worker 完整重跑均通过。默认入口日志为 `/tmp/bsb-alpha-tests-default-final.log`，单 worker 日志为 `/tmp/bsb-alpha-tests-final.log`。默认目录、同 base live 增量 epoch 与 sidechat seed cwd stamp 真实测试均通过；cold 外进程同 base 更新仍受既有 15 s TTL 约束。

消费类型通过 `/// <reference lib="esnext.disposable" preserve="true" />` 保留 disposal 标准类型引用，浏览器 consumer 验证不引入 Node 类型。

真实挂载必须使用隔离 scratch profile 与精确 `@deepseek-ai/dsh@0.2.1-alpha.5`，不使用会覆盖 `DSH_HOME` 的桌面 shim。网络或安装失败应记录原始失败，不以旧宿主测试替代 alpha.5 证据。