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；插件对外的全部行为差异以 docs/external-plugin-guide.md 为准；仓库级适配要点（基线、CI 钉版、宿主契约）同步到 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 合入 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：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）。这不是发布失败，别重发。