apes-sidebar/docs/plans/2026-09-10-dsh-0.1.5-rc.1-adaptation.md

# DSH 0.1.5-rc.1 适配（v0.19.0 正式版基线）

日期：2026-09-10　分支：`feat/dsh-0.1.5-rc.1`

## 背景

DSH `dsh-v0.1.5-alpha.2..dsh-v0.1.5-rc.1`（上游 commit `183f08e9c`，npm 发布 2026-09-10T03:12Z）的 delta 很小：373 个变更文件，绝大多数是各包 `package.json` 版本号、原生右侧栏预览 UI 打磨与测试快照。触及本插件的只有一处契约回归——`SidebarRightGuideEntry.description` 回来了。本计划记录该 delta、插件对它的取舍、以及 v0.19.0 正式版的基线决策。上一版（alpha.2）的适配记录见 [2026-09-09-dsh-0.1.5-alpha.2-adaptation.md](./2026-09-09-dsh-0.1.5-alpha.2-adaptation.md)；插件对外的全部行为差异以 [docs/external-plugin-guide.md](../external-plugin-guide.md) 为准；仓库级适配要点（基线、CI 钉版、宿主契约）同步到 [AGENTS.md](../AGENTS.md) §2/§3。

## 上游 delta（alpha.2 → rc.1，影响本插件的三项）

| # | 上游变更 | 对插件的影响 |
|---|---|---|
| 1 | `SidebarRightGuideEntry.description?: () => string` 回归（可选）：原生指南**只在列出条目 ≤ 4 条时**渲染它（上游 `MAX_DESCRIBED_ENTRIES = 4`），更长的列表整列丢弃说明；没有 `icon` 的条目改由宿主补方块占位 | 恢复 `TabDescriptor.description`（六个内置类型声明它，`guideDesc*` 词条一并回来）；**不恢复**旧的通用兜底句 `nativeGuideDesc`——宿主自己没有兜底，通用句在所有页面上长得一样、纯噪音；未声明该字段的 descriptor 就不发 `description` 字段 |
| 2 | 内置 `files` 类型重新声明指南说明，且改用彩色的 `FileTypeIcon kind="folder"` 作指南字形 | 仅背景信息：`files` 页面 kind 由插件接管，该行现在随插件渲染（`editor` descriptor 的图标与说明） |
| 3 | `@deepseek-ai/dsh-client-ui-primitives@0.1.5-rc.1` **仍不声明 `dependencies`**，而其 bundle 继续裸 import `anser` / `shiki` / `@shikijs/langs/*` / `mdast-util-*` / `micromark-*` / `katex` | 上一版提升进 devDependencies 的那组第三方包**不得回退**（回退即 vitest 一加载 primitives 就 `Cannot find package 'anser'`）；`ui-primitives` 的导出面未变，只有 CodeBlock 渲染变化 |

**明确未变**（不必再核）：

- 全局主面板模型——根级 keyed `main` 槽、`sidebar.panellist`、`ctx.layout.selectPanel` / `beginNavigation`、根级 `rightbar` + `rightbar.session`；插件仍不接入。
- 文件地址语法——`packages/util/workspace-path` 只动了 `package.json` 的版本号。
- 原生 tab 体宿主契约——`dsh-client-ui-dockkit` 的 `.paneBody` 仍是「有确定高度的块级滚动容器」，只加了两行 z-index。
- core / agent / session / subagent 宿主 API——仅版本号变化。

## 决策

- **插件版本 0.19.0（无 prerelease 后缀）**：`release.yml` 按「版本号是否含 `-`」自动选 dist-tag，因此本版发 npm **`latest`**；npm 的 `alpha` 标签保持指向 `0.19.0-alpha.1`（上游 rc.1 自己的 GitHub Release 仍标 pre-release，与本插件的通道无关）。
- **基线 = DSH 0.1.5-rc.1+ only**：peer 下限 `^0.1.5-rc.1`、manifest `engines.dsh >=0.1.5-rc.1`、CI 钉 `@deepseek-ai/dsh@0.1.5-rc.1`。DSH **0.1.5-alpha.2 用户留在 v0.19.0-alpha.1**，DSH **0.1.2-rc.1 用户留在 v0.18.1**。
- **恢复 `description`，不恢复通用兜底句**：宿主渲染第二行时读 descriptor 自己的说明；`nativeGuideDesc` 兜底句不再存在——没写说明的条目就是单行「图标 + 标题」。
- **接受 ≤4 渲染规则，不做额外工程**：插件默认贡献 6 个 guide 条目 > 4，说明在默认组合下不渲染（见下节）。不为此裁剪内置类型、不改条目数、不把关键信息只放进说明里。
- **升级本地 3080 实例**到 DSH 0.1.5-rc.1 + 插件 0.19.0，作为真机观察点。

## ≤4 渲染规则的后果（重要）

上游只在 guide 列出的条目 **≤ 4 条**时渲染 `description`（`MAX_DESCRIBED_ENTRIES = 4`），更长的列表整列丢掉所有说明——注意是「整列丢弃」，不是截断到前四条。插件默认贡献 6 条 guide 条目（文件 / 文件变动 / 任务管理 / 侧边对话 / 终端 / 浏览器），**因此在默认组合下，插件与内置类型的说明都不会出现**，六条仍是「图标 + 标题」。

说明只在读者于插件设置页关掉足够多的 tab 类型、把 guide 压到 ≤ 4 条时才出现（逐类型开关；关掉 `editor` 会同时移除接管出去的「文件」行）。这是上游行为而非插件缺陷：插件恢复字段是为了让「关到 ≤ 4 条」的读者拿到真实说明，而不是为了在默认组合里显示什么。指南 §0 与 §4.1 都写明了这条规则，消费插件不应把关键信息只放在 `description` 里。

## 改动清单（子系统级）

| 子系统 | 文件 | 变更 |
|---|---|---|
| 基线 | `package.json` | 版本 → `0.19.0`（无后缀）；dsh-* peer 全部 `^0.1.5-rc.1`；devDeps 同步钉 `0.1.5-rc.1`；`dsh-client-locale` 跟随基线到 `0.1.5-rc.1`（该包已回到与 DSH 同 tuple 发版，§3-9 的落后例外保持消除） |
| 基线 | `pnpm-lock.yaml` | 锁文件对齐 rc.1 |
| 基线 | `dsh.plugin.json` | `version` → `0.19.0`；`engines.dsh` → `>=0.1.5-rc.1` |
| 基线 | `.github/workflows/ci.yml` | mount lane 钉 `@deepseek-ai/dsh@0.1.5-rc.1`（rc.1 在 npm 上同时是 `latest` 与 `next`） |
| 基线 | `package.json` | 上一版提升的第三方 devDependencies（anser / shiki / `@shikijs/langs` / `mdast-util-*` / `micromark-*` / katex）保留不回退——`ui-primitives@0.1.5-rc.1` 仍无 `dependencies` |
| Tab 契约 | `src/client/service.ts` | `TabDescriptor` 恢复可选 `description`；`SIDEBAR_SERVICE_VERSION` 跟随插件版本（`0.19.0`） |
| Tab 契约 | `src/client/builtins/tabs.tsx` | 六个内置类型（editor / git / subagent / sidechat / terminal / browser）重新声明 `description` |
| Tab 契约 | `src/client/native/index.ts` | guide 条目在 descriptor 声明了说明时带上 `description`；未声明就不发该字段（不补通用句） |
| 词典 | `src/client/locales.ts` + 19 份 `locales-*.ts` | 恢复 6 个 `guideDesc*` 词条（zh / en / ja 与其余第三方语言） |
| 测试 | `tests/builtins.spec.ts` | 指南断言从「仅 `title`」改回「`title` + `description`」 |
| 测试 | `tests/native-surface.spec.ts` | 断言 guide 条目携带 `description`；`editor` 类型仍不单独占行、接管行承载其图标与说明 |
| 文档 | `docs/external-plugin-guide.md` | 顶部基线行（v0.19.0 / DSH 0.1.5-rc.1+ / 两个钉版旧版本）、§0 「新建标签页列表」行、§4.1 恢复 `description` 字段与 ≤4 规则 |
| 文档 | `docs/plans/2026-09-09-dsh-0.1.5-alpha.2-adaptation.md` | 加一行前向链接（该版删掉的 `description` 在 rc.1 回归） |
| 文档 | `docs/plans/2026-09-10-dsh-0.1.5-rc.1-adaptation.md` | 本计划 |
| 文档 | `AGENTS.md` | §2 CI 基线戳、§3 标题与基线 prose、§3 第 9/10 条（devDeps 不回退 / `description` 回归） |
| 文档 | `README.md` / `README_EN.md` | 顶部与安装节的「支持的 DSH 版本」徽章、安装节正式版说明、新增 `### v0.19.0` 更新段落 |

## 验证

- **本工作流（文档）未执行任何门禁或真机验证**，只做了与工作树现状的交叉核对：`package.json` 为 `0.19.0`（dsh-* peer 与 devDep 均 `0.1.5-rc.1`）、`dsh.plugin.json` 的 `engines.dsh` 为 `>=0.1.5-rc.1`、`.github/workflows/ci.yml` 钉 `@deepseek-ai/dsh@0.1.5-rc.1`、`SIDEBAR_SERVICE_VERSION` 为 `0.19.0`、`src/client/builtins/tabs.tsx` 六个类型与 `src/client/native/index.ts` 的 guide 条目（含 `files` 接管行）重新带上 `description`、`src/client/locales*.ts` 恢复 6 个 `guideDesc*` 键。
- 仓库**没有守护指南文档章节的测试**——`tests/builtins.spec.ts` / `tests/native-surface.spec.ts` 守护的是 guide 行的形态，不是文档文本，因此文档改动没有对应的测试命令可跑。
- **待补（由主代理在实施完成后回填，本文件不预填未经执行的结论）**：门禁数字（`pnpm typecheck` / `pnpm lint` / `pnpm vitest run --exclude '**/*.e2e.ts'` / `pnpm peers check`）、`scripts/e2e-mount.sh` 真机挂载车道的通过数，以及本地 3080 实例（DSH 0.1.5-rc.1 + 插件 0.19.0）上的实测结果——默认组合下 6 条 guide 行仍是「图标 + 标题」、关掉 tab 类型至 ≤ 4 条后说明出现、以及 `pageerror` / 控制台状况。

### 回填（主代理实测）

- **门禁**：`pnpm typecheck` / `pnpm lint` / `pnpm check:consumer-types` 全绿；`pnpm vitest run --exclude '**/*.e2e.ts'` = **124 files / 1296 passed / 9 skipped**；`pnpm peers check` = No peer dependency issues found（rc.1 未新增失配的传递 peer，因此没有再提升任何 devDep）。
- **挂载冒烟**（`DSH_CMD` 指向 npm 安装的 0.1.5-rc.1，`scripts/e2e-mount.sh`）：**7 passed**，含 tab 体填充断言与新增的 ≤4 条描述断言。
- **≤4 断言的真实形态**：默认 6 条下永远拿不到说明文本，所以该用例先用插件自己的 `settings.get` / `settings.update` 把启用集合压到 3 个类型（files / sidechat / browser），断言 `files` 胶囊文本含英文说明片段 `workspace tree`，并断言被禁用的三个条目离开 guide。
  - **踩坑（已修）**：恢复设置时最初只把原始 `tabsEnabled`（scratch profile 里是 `{}`）原样发回——而该路由的 patch 是**逐键合并**，空对象清不掉刚写下的三个 `false`，于是同车道的 `perf.e2e.ts` 扫 guide 时找不到 `git` 条目而失败。改为对本次动过的每个键显式恢复（原值缺省即 `true`）后全绿；这条经验对任何"临时改设置再恢复"的 e2e 都适用。
- **真机 3080**（DSH 0.1.5-rc.1 + 插件 0.19.0）：guide 六行胶囊均为「图标 + 标题」、**无说明**（6 > 4，符合上游规则）；胶囊高度 56px（上游把 `min-height` 从 alpha.2 的 48px 调到 56px）；文件树点击 `AGENTS.md` → tab 标题 `AGENTS.md` + CodeMirror 挂载；sidechat 宿主盒 962px == `.paneBody` 962px（fillGap 0），composer 底边距 8px；底部工作台与 `[data-dsh-center-col]` 左右边完全重合（gap 0）；`pageerror` 0；控制台仅第三方 `dsh-tauri-worktree` 的 `/api/dsh-worktree/attach` 500（alpha.2 期同样存在，与本次无关）。rc.1 真机的 `[data-slot]` 清单与 alpha.2 完全一致（`main` / `main.conversation` / `rightbar` / `rightbar.session`），印证"全局面板模型未变"。

## 不做

- 不为 ≤4 渲染规则裁剪内置 tab 类型、调整条目数或改写图标。
- 不恢复 `nativeGuideDesc` 通用兜底句。
- 不接入 alpha.2 的全局面板（`main` 槽 / `sidebar.panellist` / `ctx.layout` / `usePanelInfo` / 根级 `rightbar`）——沿用上一版结论，rc.1 上这些面同样只是兼容保留。
- 不回退提升进 devDependencies 的第三方包。
- 不改 DSH 源码（仓库硬约束 §1）。

## 落地

- [#613](https://github.com/omdsh-dev/DSH-better-sidebar/pull/613) 合入 `main`（merge commit `754974a`）；main 的 `package.json` 为 `0.19.0`、`engines.dsh` 为 `>=0.1.5-rc.1`。PR 的 `ci` / `ci-windows` / `plugin-mount` 三个 check 全绿。
- 发布 [v0.19.0](https://github.com/omdsh-dev/DSH-better-sidebar/releases/tag/v0.19.0)：`release.yml` 通过全门禁后经 npm Trusted Publishing 发布到 **`latest`**（带 provenance）；实测 dist-tags：`latest = 0.19.0`、`alpha = 0.19.0-alpha.1`（不变）、`beta` 不变。
- 产物核对：`lib/index.js` 与本地已验证构建**逐字节一致**，且与 `v0.19.0-alpha.1` 的同名文件同哈希（宿主侧代码在这两版之间确实没动）；`lib/client.js` 仅差已知的打包非确定性；发布包的 client bundle 内含恢复后的说明文案。
- **npm 传播延迟仍是 ~4–5 分钟**：06:49:10 工作流报 `Published package dsh-better-sidebar@0.19.0`，06:53:53 dist-tags 才可见 `latest = 0.19.0`（版本元数据与 tarball 依次到达，期间 `npm view` / tarball 会 404）。这不是发布失败，别重发。