Merge origin/main into feat/wait-banner: resolve floats retirement + openTabInBottomPane

docs/external-plugin-guide.md

@@ -2,12 +2,38 @@
 
 > 面向 **消费插件开发者**：如何让你的插件向 better-sidebar 注册新的侧边栏页面（tab）和文件类型预览器。
 >
-> 适用版本：**v0.4.0+**（`ctx.betterSidebar` 服务）；声明式设置 **v0.4.1+**；text/number 设置行 **v0.11.0+**；badge/生命周期/定向打开/插件设置/版本探测 **v0.12.0+**；select 设置行（`settingSelect`）与外链认领（`urlTarget`）**v0.13.0+**；统一 `@deepseek-ai/cordis` 类型基底 **v0.15.2+**；自由窗口（`floatWindows`）**v0.16.0+**；终端固定（pin）**v0.17.0+**。当前版本 **v0.18.1**（正式版，仅支持 DSH 0.1.2-rc.1+；旧宿主 stable 线为 v0.17.1）。
+> 适用版本：**v0.4.0+**（`ctx.betterSidebar` 服务）；声明式设置 **v0.4.1+**；text/number 设置行 **v0.11.0+**；badge/生命周期/定向打开/插件设置/版本探测 **v0.12.0+**；select 设置行（`settingSelect`）与外链认领（`urlTarget`）**v0.13.0+**；统一 `@deepseek-ai/cordis` 类型基底 **v0.15.2+**；终端固定（pin）**v0.17.0+**。当前版本 **v0.19.0**（正式版，npm `latest`，仅支持 DSH **0.1.5-rc.1+**；**0.1.5-alpha.2 及更早不再支持**——alpha.2 用户请用 v0.19.0-alpha.1，那是它的最后一版；0.1.2-rc.1 稳定线请用 v0.18.x）。**v0.19.0 移除了自绘右侧面板与自由窗口**（见 §0、§11）。
 > 权威代码：`src/client/service.ts`（服务实现）、`src/client/builtins/`（内置 8 tab + 6 viewer 参考实现）、`lib/types/client/service.d.ts`（类型声明）。
 > 仓库开发规则（硬约束 / CI / 发版）见 [AGENTS.md](../AGENTS.md)。
 
 ---
 
+## 0. 承载面：DSH 原生右侧栏 + 插件底部工作台（v0.19.0-alpha.0 起）
+
+从 v0.19.0-alpha.0 起，**右列完全属于 DSH**：你的 tab 渲染在 **DSH 自己的右侧栏**里（`ctx.sidebarRight` / `ctx.sidebarRightTabs`），插件把每个 `TabDescriptor` 注册成原生 tab 类型（`kind = descriptor.id`）+ 一个原生 tab 体。插件自己只保留**底部工作台**（分栏树、终端、会话内持久化）。对你的接入代码**没有影响**——仍然只调用 `ctx.betterSidebar`：
+
+- `registerTab` / `registerFileViewer` 签名不变；
+- `openTab` / `openFile` 默认落到原生右侧栏；新增可选 `OpenTabSeed.target`（`'right'` 默认 / `'bottom'` 落插件的底部工作台）；
+- `updateTab` / `closeTab` / `activateTab` 认识原生 tab id（插件为每个原生 tab 维护一条合成 `SidebarTab` 记录，`tab.meta` / `tab.path` 的写入照旧生效）。
+
+行为差异（写在这里以免踩坑）：
+
+| 事项 | 说明 |
+|---|---|
+| 生命周期回调 | 原生面只有「一次打开」，不区分新建/聚焦，因此只触发 `onOpen`（`onActivate` 仅在插件自己的底部工作台里触发） |
+| 去重 | 原生按 `(kind, 地址)` 去重：有 `createTab` 的类型每次新开一个 tab（terminal / browser / sidechat / diff），其余聚焦已有 tab；`dedupeKey` 的自定义语义不参与原生面 |
+| 布局持久化 | 原生栏的布局**只在内存**（刷新后回到折叠默认），插件自己的底部工作台仍然持久化 |
+| 跨会话打开 | 目标会话的右侧栏 store 未挂载时，打开会排队到该会话上屏后重放 |
+| 内置类型接管 | 插件的 `editor` 类型以 `extension` 优先级认领 `dsh-resource://file/**`（压过内置 `ui-sidebar-documentpreview` 的 `text` 预览——即 `fallback` 带），并接管内置 `files` 页面 kind（`openTab('files')` 打开插件的文件树）；插件卸载/禁用时内置实现自动复位 |
+| 终端上限 | 终端 tab 的数量上限只统计插件自己底部工作台里的终端；原生栏里的终端不计入 |
+| 底部工作台的开合 | 落到底部工作台的打开一律展开它（新建与聚焦都算），因此 `openTab` 的落点永远可见；开合按钮注册在 DSH 会话头的 utilities 槽（`conversation.session.header.utilities`），不在插件自己的宿主里 |
+| 新建标签页列表 | 每个 tab 类型在原生 guide 里占一行：标题取 `title` + 图标取 `icon`（缺图标时宿主补一个方块占位），说明取可选的 `description`——**宿主只在 guide 列出的条目 ≤ 4 条时渲染说明**（上游 `MAX_DESCRIBED_ENTRIES = 4`），更长的列表整列丢掉所有说明；未声明 `description` 的条目渲染成单行「图标 + 标题」（rc.1 起 `description` 回到宿主契约，但**宿主与插件都没有兜底句**，所以插件恢复字段而不恢复旧的通用句）；`hidden: true` 的类型不占行。插件的 `editor` 类型不再单独占行（它认领的文件资源由 `files` 接管页承载同一视图）。**注意默认组合看不到说明**：插件贡献 6 个 guide 条目（文件 / 文件变动 / 任务管理 / 侧边对话 / 终端 / 浏览器），已超过 4 条上限——要让说明出现，需在插件设置页关掉足够多的 tab 类型把 guide 压到 ≤ 4 条 |
+| 新建面板的种子（alpha.2） | 在新会话打开原生新面板时，宿主从已注册的 guide 条目里播种：恰好 1 个条目 → 直接打开那一页；0 或 ≥2 个条目 → 打开指南。`revealIfOpened` 打开的「页面」在**同一 pane 内**强制去重（已在该 pane 就不再新建）；由已有 tab 地址驱动的打开不受该去重影响 |
+| alpha.2 全局面板（不接入） | 插件**不采用** alpha.2 引入的全局主面板模型——根级 keyed `main` 槽（预留 key `conversation`，由 ui-conversation 注册为 `main.conversation`）、根级 `sidebar.panellist` 列表槽（`SidebarPanelMetadata` / `SidebarPanelIconOwnerProps`）、`ctx.layout.selectPanel(MainPanelId|null)` / `beginNavigation()` / `dispose()`、全局标准 prop `usePanelInfo`，以及改根级并新增会话级 `rightbar.session` 子槽的 `rightbar`——这些只作兼容保留，不向其迁移 |
+| 已移除 | 插件自绘右侧面板（含宽度拖拽 / 新会话默认宽度）与**自由窗口**（`features` 里的 `'floatWindows'` 已删除，v0.18.x 及更早版本的消费者请勿再 gate 该能力）；`openByDefault` / `defaultWidthPercent` / `changesDiffFloat` 三个设置项同步删除（旧文档里的键会被忽略） |
+
+---
+
 ## 1. 总览：你能扩展什么
 
 better-sidebar 从 v0.4.0 起把自己改造成一个**注册表服务**：
@@ -155,7 +181,15 @@ interface TabDescriptor {
   id: string
   /** 标题（i18n 友好：传字符串或返回字符串的函数） */
   title: string | (() => string)
-  /** 图标：ReactNode 或 (size: number) => ReactNode */
+  /**
+   * 一行说明，渲染在标题下方（DSH 原生右侧栏的新建标签页 / guide 列表）。
+   * **宿主只在 guide 列出的条目 ≤ 4 条时渲染它**（上游 `MAX_DESCRIBED_ENTRIES = 4`），
+   * 更长的列表整列丢掉所有说明——也就是说这是一行「锦上添花」，别把关键信息只放这里。
+   * 不声明就不发 `description` 字段：宿主没有兜底句，插件也不补（通用句在所有页面上
+   * 长得一样，纯噪音），条目就渲染成单行「图标 + 标题」。函数形式在渲染时求值，跟随语言。
+   */
+  description?: string | (() => string)
+  /** 图标：ReactNode 或 (size: number) => ReactNode（不声明时宿主补一个方块占位） */
   icon?: ReactNode | ((size: number) => ReactNode)
   /** + 菜单排序（升序）；默认 100。内置：editor=10, git=20, subagent=30, sidechat=35, terminal=40, browser=50 */
   order?: number
@@ -362,7 +396,7 @@ ctx.effect(() => {
 | id | order | single | hidden | 用途 |
 |---|---|---|---|---|
 | `editor` | 10 | 否（按 path 去重） | 否 | 唯一「文件窗口」（编辑/预览 + 资源管理）。chrome 恒合并形态：路径输入框 + 编辑器控件 + 可开关内嵌文件树（全局搜索 `fs.search`；状态存 `tab.meta.treeOpen/treeWidth`）。`editorExplorer`：关（默认）= 按 path 新开，无路径窗口 = 纯资源管理器；开 = 树点击/Enter 经 `updateTab` 原地切换（id/meta 不变），无路径窗口 = 带 chrome 空窗口。树右键「在新 Tab 中打开」「在侧边打开」（pane 右侧 split）。新会话 seed 空文件窗口（`title:'Files'`）；旧 `explorer` tab 经 `sanitizeState` 迁移 |
-| `git` | 20 | 是 | 是（本轮文件操作数） | 「文件变动」统一 tab（id 保留 `git` 以兼容持久化布局）：**Git 视角**（原 Git 面板：staged/unstaged / 提交 / 历史 / worktree·子仓库选择）+ **本轮文件视角**（原 file-trace：模型读/写/编辑实时折叠，按文件分组、类型筛选）；会话事件经插件自有宿主路由 `changes.ops` 供给（live 日志优先、冷会话回放持久化记录，`afterSeq` 增量），badge 读 tab 轮询写入的同步缓存。两视角共用底部可拖拽预览面板（`tab.meta.lens/previewH` 持久化），diff 渲染统一走 `src/client/diff/`（`DiffRows`/`DiffFiles`：mod 配对 + 行内高亮 + 语法着色 + 上下文折叠）；Git 目标可展开为独立 diff tab——落点由二级设置 `changesDiffFloat` 决定（默认**自由浮窗**居中弹出，可选面板下半 split），设置项见 tab descriptor 的 `settings.toggles` select |
+| `git` | 20 | 是 | 是（本轮文件操作数） | 「文件变动」统一 tab（id 保留 `git` 以兼容持久化布局）：**Git 视角**（原 Git 面板：staged/unstaged / 提交 / 历史 / worktree·子仓库选择）+ **本轮文件视角**（原 file-trace：模型读/写/编辑实时折叠，按文件分组、类型筛选）；会话事件经插件自有宿主路由 `changes.ops` 供给（live 日志优先、冷会话回放持久化记录，`afterSeq` 增量），badge 读 tab 轮询写入的同步缓存。两视角共用底部可拖拽预览面板（`tab.meta.lens/previewH` 持久化），diff 渲染统一走 `src/client/diff/`（`DiffRows`/`DiffFiles`：mod 配对 + 行内高亮 + 语法着色 + 上下文折叠）；Git 目标可展开为独立 diff tab（落进工作台的 diff 分栏） |
 | `subagent` | 30 | 是 | 否 | 子代理拓扑 |
 | `sidechat` | 35 | 否（`sidechat:<uuid>`，按 `meta.threadId` 去重） | 否 | 侧边对话（每对话一 Tab）：打开即建空线程（首条消息赢得标签并同步标题）；线程 = 插件自建子会话（种子继承父会话上下文，进行中回合以 `interrupted` 闭合；种子带合法 `subagent/descriptor`，SubagentView 按 `Side: ` 前缀过滤），`origin:'subagent'` 隐藏于主列表；走 `/sidebar/api/sidechat.*` 路由；头部菜单切换/重开（`parkSidechatReopen` + 确定性 id），关 Tab 释放 live agent；重开经 `collectOwnEvents` 回源到种子边界；「保存为新会话」= `session.fork`（`this` 敏感）。[设计文档](plans/2026-08-20-sidechat-tab-design.md) |
 | `terminal` | 40 | 否（`terminal:<n>`） | 否 | 终端。v0.17.0+ 右键「固定到工作区/全局」：跨会话不消失，TabBar 内联虚拟 Tab（`pinned:<homeSessionId>:<tabId>`），就地按 home scope 连 PTY；global 全会话可见、workspace 仅同 cwd；`tab.pin = { scope, homeCwd? }` 随会话持久化，渲染期解析（`collectPinnedTabs` → `createPinnedVirtualTab` → `injectPinnedIntoTree`） |
@@ -584,10 +618,10 @@ interface BetterSidebarService {
   // ── v0.12.0+ ──────────────────────────────────────────────────────────
   /** 插件版本（如 '0.17.1'；与 package.json 同步，测试守护） */
   readonly version: string
-  /** 单调能力清单（只增不删）：'badge' | 'tabLifecycle' | 'updateTab' |
-   *  'openFile' | 'targetedOpen' | 'stateSubscription' | 'tabMeta' |
-   *  'pluginSettings' | 'urlTarget' | 'settingSelect' | 'floatWindows'
-   *  ——用 `features.includes('xxx')` 按能力 gate。 */
+  /** 能力清单（只增不删，唯一例外：v0.19.0 删除了 'floatWindows'）：
+   *  'badge' | 'tabLifecycle' | 'updateTab' | 'openFile' | 'targetedOpen' |
+   *  'stateSubscription' | 'tabMeta' | 'pluginSettings' | 'urlTarget' |
+   *  'settingSelect' ——用 `features.includes('xxx')` 按能力 gate。 */
   readonly features: readonly string[]
   /** 当前快照：激活 sessionId + 其状态（面板几何/打开的 tabs/展开集）+ prefs。
    *  session 未激活时 state/sessionId 为 undefined。 */
@@ -730,20 +764,18 @@ ctx.effect(() =>
 | **i18n 跟随** | 文案跟随 DSH `ctx.locale`（词典在 `betterSidebar` 命名空间；Host-backed `locale.preference` 优先于浏览器语言并实时切换；缺失回退浏览器）。消费插件**不要**依赖内部 `t()`——标题传字符串或 `() => string` |
 | **第三语言覆盖（ja 等）** | 可选 peer `@huanlin/dsh-plugin-better-locale`（optional）提供 ja/ko 覆盖，**借用 DSH 英文槽位**（仅 DSH=en 时生效，zh 下惰性）。经 `ctx.get('betterLocale')` 注入 `t()`；未安装整段 no-op |
 | **懒加载 chunk** | 重依赖（xterm/CodeMirror）在独立 bundle（`lib/client-<name>.js`），经 `/sidebar/bundle` 按需下发；factory 赋到 `globalThis.__dshChunks__[<name>]`，由 `src/client/chunk-loader.ts` 物化，**不经** `__ModuleLoader__`。对消费插件透明 |
-| **聊天文件打开漏斗（alpha 宿主）** | 聊天里一切文件打开（工具行 / 产物行 / 正文提及 / 行内代码路径）汇入 `ctx.remote.session.openWorkspacePath`（Typert remote 命名空间，cordis 服务 key `remote.session`，方法为 **accessor 属性**、异步挂载）。better-sidebar 的「聊天区文件在侧边栏打开」即在 `ctx.inject(['remote.session'], …)` 内以 defineProperty 遮蔽该方法（`src/client/openpath-intercept.ts`）。你的插件若要观测/旁路聊天文件打开，走同一服务；不要假设 pre-alpha 的 `ctx.workspaces.openPath` 存在（alpha 的 `IWorkspaces` 已无此方法） |
+| **聊天文件打开漏斗（0.1.5 宿主）** | 聊天里一切文件打开（工具行 / 产物行 / 正文提及 / 行内代码路径）统一走 DSH 原生右侧栏的 `ctx.sidebarRight.openResource(fileAddressFor(sessionId, cwd, path))`（`packages/client/ui-chat/src/client/apply.ts` 是唯一调用点）；`remote.session.openWorkspacePath` 在 0.1.5 客户端**已无调用者**，better-sidebar 的 openpath 拦截随之删除。你的插件若要观测/旁路聊天文件打开，注册原生 tab 类型认领 `dsh-resource://file/**`（见 [AGENTS.md §3](AGENTS.md) 第 10 条）；不要假设 `ctx.workspaces.openPath`（已删除）或旧 `remote.session` 漏斗存在 |
+| **原生 tab 体的高度契约** | 你的 tab 组件被挂在**全高列 flex 宿主**里：native 适配层给每个 tab 体（含 orphaned 回退）包一层 `height:100%` 的 `sidebar.module.css` `.nativeTabHost`（带 `data-dsh-native-tab-host`）——根用 `flex: 1` / `height: 100%` 并加 `min-height: 0` 填满面板。宿主的面板体 `.paneBody`（`dsh-client-ui-dockkit`）是**有确定高度的块级滚动容器，不是 flex 容器**，因此只靠外层 flex 容器支撑的根会塌成内容高度（sidechat 的输入框就贴不到面板底）；DSH 自己的 tab 体（`ui-sidebar-documentpreview` 的文档预览、`ui-sidebar-files` 的 FilesBody）正是因此在根上声明 `height: 100%` |
 
 ---
 
-## 11. 自由窗口（v0.16.0，`features` 含 `'floatWindows'`）
+## 11. 自由窗口（v0.16.0 – v0.18.x，**v0.19.0 已移除**）
 
-任意 tab（含你注册的）可拖出侧边栏成为悬浮**自由窗口**——对你的组件基本透明，只需知道以下语义：
+自由窗口（tab 拖出侧边栏成为可移动/缩放的悬浮窗，`SidebarState.floats`、`floatTab`/`dockFloat`/`raiseFloat`、`features` 里的 `'floatWindows'`、右键「移动到自由窗口」、`src/client/FreeWindow.tsx`）在 **v0.19.0-alpha.0 整体删除**：右列交给 DSH 原生右侧栏后，插件只剩底部工作台，浮窗既没有语义归属也没有可用手势（拖出目标区域现在是原生栏的属地）。
 
-- **拖出**：tab 拖到主会话区域（conversation 列）松开即浮动（`floatTab`：移入 `SidebarState.floats`，默认 390×780 按视口钳制居中，清空 pane 折叠）。检测在 `Sidebar.tsx`（`body[data-dsh-tab-dragging]` 门控）；窄视口禁用。右键「移动到自由窗口」始终可用。
-- **窗口操作**（`src/client/FreeWindow.tsx`，`[data-dsh-panel-host]` 内、z-42）：头部拖动移动；拖到 pane（`[data-dsh-pane]`）松开**停靠**（`dockFloat`）；右下角缩放（最小 320×200）；点击置顶（层叠 = `floats` 数组序）；X = `closeTab`（触发 `onClose`、释放终端）。
-- **持久化**：`floats` 随会话进 localStorage（`dsh-sidebar:v1:<sessionId>`）；`sanitizeState` 宽容校验（非法条目单独丢弃、几何钳入视口、diff/ephemeral 不持久化）。
-- **服务语义**：`openTab` 聚焦命中浮动 tab = 置顶窗口（不重复开）；`closeTab`/`activateTab` 关窗/置顶并触发回调；agent 终端 reconcile 移除已消失的浮动窗口。**浮窗内你的组件 `visible` 恒 true**。
-- **稳定寻址面**：`[data-dsh-float-window]` / `[data-dsh-float-id]` / `[data-dsh-pane]` / `[data-dsh-float-dock-over]` / `[class*='floatDropHint']`；全令牌驱动，头部 `-webkit-app-region: no-drag`。
-- **⚠️ portal 事件劫持陷阱**：拖拽表面子树含 portal 覆盖层时（如你的组件在 tab 头部区域渲染弹层），portal 后代合成事件**沿 React 树冒泡**回 `onPointerDown`，会被误判为拖拽开始（吞点击 + 抢 pointer，菜单/X 失灵；jsdom 不走此路径，只有 e2e 能抓）。拖拽起点必须带**同源守卫**：`event.currentTarget.contains(event.target)` 为假或目标在 `button` 内时直接返回（回归：`tests/free-window.spec.tsx` portaled-menu 用例）。
+- 升级到 v0.19.x 后请**不要**再 gate `features.includes('floatWindows')`，也不要引用 `floatTab` 等符号（类型声明里已不存在）；
+- 旧文档里持久化的 `floats` 字段会被 `sanitizeState` 直接忽略，会话不会因此加载失败；
+- 需要「同一个 tab 在别处看」的场景，改用原生栏打开（`openTab` 默认落点）或底部工作台分栏（`OpenTabSeed.target: 'bottom'`）。
 
 ---
 
@@ -756,7 +788,7 @@ ctx.effect(() =>
 - **面板表面**：右/底面板背景 = `var(--dsw-alias-bg-layer-1)`。**绝不消费 `--dsw-specific-sidebar-fill`**（宿主左导航专属，皮肤按左导航语义覆盖它，面板消费会失去填充）。换面板表面 = 覆写 `--dsw-alias-bg-layer-1`。
 - **终端/编辑器表面**：`effectiveTokenValue` 读 `--dsw-alias-bg-base`——`transparent` 与 alpha < 0.9 的半透明值回退不透明底色（文字不叠背景画，issue #90）；≥ 0.9 放行。
 - **根锚点**：宿主 div 带 `data-dsh-better-sidebar`（append 到 body）；其内**面板宿主层** `[data-dsh-panel-host]`（`fixed; inset:0; z-25; pointer-events:none; overflow:hidden+clip`，v0.13.1+），面板/开关簇 absolute 定位，免疫中间层 transform 劫持；页面级 transform 触发 `data-dsh-panel-host-degraded` 降级。`overflow` 级联是**契约**（`hidden` 兜底 + `clip` 收尾，`tests/panel-host-css.spec.ts` 守护）：`hidden` 盒子仍是滚动容器，脚本滚动或浏览器 scroll-into-view 修正（焦点移入视口外区域、嵌套 iframe/工作台加载时抢焦点、面板滑出动画中 focus() 落点）会沿最近可滚祖先滚走整层——面板与开关簇集体偏离视口角（computed left/right 仍"正确"，偏移藏在盒子自身 scroll offset 里）；`clip` 裁剪语义相同但不产生滚动盒，任何路径都滚不动这层。皮肤作用域覆盖限定在 `[data-dsh-better-sidebar]` 内。
-- **布局变量**（`<html>` 上，面板打开时有效）：`--dsh-sidebar-width` / `--dsh-sidebar-height`。右面板宽度 = AppFrame 的 `padding-right` 预留（新版 `#root [data-dsh-frame]` / rc.8 `#root > [data-slot="root"] > div` 双锚点），AppFrame border box 保持完整桌面视口宽度（Harness 以此判定桌面/窄屏布局，避免插件面板展开误入窄屏）；AppFrame 的 details 拖拽手柄按同一变量向左平移贴合列边缘。底部面板仍走 centerCol `margin-bottom`；centerCol 锚点 = **JS 标注**（禁止 `nth-child`）：侧栏 shell 的定位器给测得的 centerCol 节点打 `[data-dsh-center-col]` 标签（`Sidebar.tsx` locate，节点更换/HMR 时随 ref 迁移），`layout.css` 用 `#root [data-dsh-center-col]` 选中（`drag-layout.e2e.ts` 断言恰一节点且为 `[data-slot="conversation"]` 的父级；frame 宽度与桌面 Session Log 由 `desktop-layout.e2e.ts` 断言）。
+- **布局变量**（`<html>` 上，面板打开时有效）：`--dsh-sidebar-width` / `--dsh-sidebar-height`。右面板宽度 = AppFrame 的 `padding-right` 预留（新版 `#root [data-dsh-frame]` / rc.8 `#root > [data-slot="root"] > div` 双锚点），AppFrame border box 保持完整桌面视口宽度（Harness 以此判定桌面/窄屏布局，避免插件面板展开误入窄屏）；AppFrame 的 details 拖拽手柄按同一变量向左平移贴合列边缘。底部面板仍走 centerCol `margin-bottom`；centerCol 锚点 = **JS 标注**（禁止 `nth-child`）：侧栏 shell 的定位器给测得的 centerCol 节点打 `[data-dsh-center-col]` 标签（`Sidebar.tsx` locate，节点更换/HMR 时随 ref 迁移），`layout.css` 用 `#root [data-dsh-center-col]` 选中（`drag-layout.e2e.ts` 断言恰一节点且为对话槽宿主的父级——alpha.2 起 shell 把 `#root [data-slot="main.conversation"]` 解析进列并跳过 `display: contents` 祖先（`center-column.ts` 的 `CENTER_COLUMN_SELECTOR` 同时认 `main.conversation` 与 alpha.1 的 `conversation`），定位器从槽宿主向上取第一个非 `contents` 的祖先；frame 宽度与桌面 Session Log 由 `desktop-layout.e2e.ts` 断言）。
 - **桌面信号与标题栏**（v0.14.1+ 四方案模型 `SidebarPrefs.titleBarScheme`，唯一决策点 `src/client/titlebar-strip.ts` 纯函数）：
   - 壳信号（只读，不自动触发修改）：URL `dsh-desktop-mode` / `dsh-desktop-platform` / 可选 `dsh-desktop-titlebar-inset`（0–120 clamp）。
   - **strip 取值链**：⓪ `web` 方案强制 0；① `navigator.windowControlsOverlay` 真实几何（`wco.ts` 订阅 `geometrychange`，**为 0 也权威**，`visible=false` 幽灵 API 视为缺失）；② URL inset；③ 壳预设 `stripFor`（仅 `preset`）；④ 手动 `titleBarStripPx`（仅 `custom`）；⑤ 0。驱动 `body[data-dsh-title-bar-compat]` + `--dsh-title-bar-strip`。
@@ -861,8 +893,9 @@ better-sidebar 的内置 tab 和 viewer 就是参考实现（"吃狗粮"），
 
 - **`src/client/builtins/`**：7 个内置 tab（tabs.tsx）+ 6 个内置 viewer（viewers.tsx）的注册代码 + 聚合与 disposer 生命周期（index.ts）；Office 预览见 plugins-viewers.ts
 - **`src/client/service.ts`**：`BetterSidebarService` 接口 + `createBetterSidebarService` 工厂实现（含匹配算法、dedupe、createTab、启用态 gating）
-- **`src/client/Sidebar.tsx`**：`TabContent` 分发（查 `getTab` → 调 descriptor.component；未注册 → `<OrphanedTab/>`）、`+` 菜单构建（order 排序 + available disabled + 禁用过滤）、自由窗口拖拽检测
-- **`src/client/FreeWindow.tsx`**：自由窗口（移动/停靠/缩放/置顶，§11）
+- **`src/client/Sidebar.tsx`**：底部工作台外壳 + `TabContent` 分发（查 `getTab` → 调 descriptor.component；未注册 → `<OrphanedTab/>`）、`+` 菜单构建（order 排序 + available disabled + 禁用过滤）
+- **`src/client/native/`**：原生右侧栏接入（tab 类型注册、合成 `SidebarTab` 适配、资源地址、跨会话打开排队）
+- **`src/client/sidebar/bottom-toggle.tsx`**：底部工作台开合按钮（注册进 DSH 会话头 utilities 槽）
 - **`src/client/SideCardSection.tsx`**：声明式设置页（注册表驱动清单 + 嵌套设置行 + 开关持久化）
 - **`src/client/api.ts`**：`/sidebar` API 的封装（复制其 fetch 模式到你的插件）
 - **`src/client/plugins-tabs.ts`** / **`plugins-viewers.ts`**：推荐插件目录（「添加插件」弹窗数据源；加一条数据即上架，`tests/plugin-list.spec.ts` 守护）

docs/plans/2026-09-09-dsh-0.1.5-alpha.2-adaptation.md

@@ -0,0 +1,88 @@
+# DSH 0.1.5-alpha.2 适配（v0.19.0-alpha.1 基线）
+
+日期：2026-09-09　分支：`feat/dsh-0.1.5-alpha.2`
+
+## 背景
+
+DSH `dsh-v0.1.5-alpha.1..dsh-v0.1.5-alpha.2` 的宿主契约里有一批会实际波及本插件的变更。本计划记录哪些值得处理、哪些只做兼容、以及每一处的子系统级落点。插件对外的全部行为差异以 [docs/external-plugin-guide.md](../external-plugin-guide.md) 为准；仓库级适配要点（基线、CI 钉版、宿主契约）同步到 [AGENTS.md](../AGENTS.md) §3。
+
+## 上游 delta（alpha.1 → alpha.2，影响本插件的六项）
+
+| # | 上游变更 | 对插件的影响 |
+|---|---|---|
+| 1 | `SidebarRightGuideEntry` 去掉 `description` 字段；指南条目变为「图标 + 标题」胶囊 | 删除 `TabDescriptor.description` 与 6 个 `guideDesc*` 词典键（连同 `nativeGuideDesc` 兜底句——不再有第二行说明） |
+| 2 | 新增**全局面板**：根级 keyed `main` 槽（预留 key `conversation`，由 ui-conversation 注册为 `main.conversation`）、根级 `sidebar.panellist` 列表槽（`SidebarPanelMetadata` / `SidebarPanelIconOwnerProps`）、`ctx.layout.selectPanel(MainPanelId|null)` / `beginNavigation()` / `dispose()`、全局标准 prop `usePanelInfo`；`rightbar` 改根级并新增会话级 `rightbar.session` 子槽 | 插件**不接入**（兼容 only） |
+| 3 | 原生 tab 体宿主 `.paneBody`（`dsh-client-ui-dockkit`）是**有确定高度的块级滚动容器**，不是 flex 容器；DSH 自己的 tab 体（`ui-sidebar-documentpreview` 的文档预览、`ui-sidebar-files` 的 FilesBody）在根上声明 `height: 100%` | 原生适配层给每个 tab 体包一层 `height: 100%` 的列 flex 宿主（`sidebar.module.css` `.nativeTabHost`，带 `data-dsh-native-tab-host`），修复 sidechat 输入框贴不到面板底的根塌陷 |
+| 4 | 文件地址语法：`fileAddressFor` 一律返回 session 作用域地址（绝对路径保留前导 `/`）；`parseFileAddress` 前缀解析并去 `?`/`#`；`absoluteFileAddress` 仍在 | 镜像 alpha.2 语法（插件自实现于 `src/client/resource-address.ts`——客户端 bundle 纯度门禁禁 value-import 未列名的 `@deepseek-ai/*`，不能直接引 DSH 工具包） |
+| 5 | `ui-sidebar-textpreview` 被 `ui-sidebar-documentpreview` 取代（同 `text` kind、`fallback` 带、`dsh-resource://file/**` 模式） | 插件 `editor` 仍以 `extension` 优先级认领 `dsh-resource://file/**`，压过其 `text` 的 `fallback` 带 |
+| 6 | 基线升到 0.1.5-alpha.2（peer 下限 / manifest / CI 钉版） | 插件基线 = alpha.2 only；alpha.1 用户留在 v0.19.0-alpha.0 |
+
+> 后续（2026-09-10）：`SidebarRightGuideEntry.description` 在 DSH 0.1.5-rc.1 回归（可选，且宿主只在 guide 列出的条目 ≤ 4 条时渲染），插件已在 **v0.19.0** 恢复该字段——见 [2026-09-10-dsh-0.1.5-rc.1-adaptation.md](./2026-09-10-dsh-0.1.5-rc.1-adaptation.md)。
+
+## 决策
+
+- **基线 = alpha.2 only**：peer 下限 `^0.1.5-alpha.2`、manifest `>=0.1.5-alpha.2`、CI 钉 `@deepseek-ai/dsh@0.1.5-alpha.2`；不再对 alpha.1 做运行时兼容。
+- **全局面板：兼容 only，不接入**——不迁移到 `main` 槽 / `sidebar.panellist` / `ctx.layout` / `usePanelInfo` / 根级 `rightbar`，仅保证在 alpha.2 宿主上不破坏。
+- **删除 `TabDescriptor.description`**：宿主不再渲染第二行，字段留着只会在类型上撒谎；同步删 6 个 `guideDesc*` 与 `nativeGuideDesc` 兜底句。
+- **修复 tab 体填充**：native 适配层为每个 tab 体（含 orphaned 回退）包 `height:100%` 列 flex 宿主 `.nativeTabHost`；tab 组件根遵循 `flex:1` / `height:100%` + `min-height:0` 契约。
+- **镜像 alpha.2 地址语法**：`fileAddressFor` 不再产生 `absolute` 作用域（但仍解析旧地址与第三方地址），`parseFileAddress` 前缀解析并去 `?`/`#`。
+- **中心列锚点跟随 alpha.2**：`center-column.ts` 的 `CENTER_COLUMN_SELECTOR` 改为 `#root [data-slot="main.conversation"], #root [data-slot="conversation"]`，`resolveCenterColumn` 从对话槽宿主向上跳过 `display: contents` 祖先取真实列；alpha.1 的 `[data-slot="conversation"]` 依旧认可。
+
+## 改动清单（子系统级）
+
+| 子系统 | 文件 | 变更 |
+|---|---|---|
+| 基线 | `package.json` | 版本 → `0.19.0-alpha.1`；dsh-* peer 全部 `^0.1.5-alpha.2`；devDeps 同步钉 `0.1.5-alpha.2` |
+| 基线 | `pnpm-lock.yaml` | 锁文件对齐 alpha.2 |
+| 基线 | `dsh.plugin.json` | `version` → `0.19.0-alpha.1`；`engines.dsh` → `>=0.1.5-alpha.2` |
+| 基线 | `.github/workflows/ci.yml` | mount lane 钉 `@deepseek-ai/dsh@0.1.5-alpha.2` |
+| 基线 | `package.json` | 按 §3-9 补提 `dsh-session-persistence`（`pnpm peers check` 唯一新失配项） |
+| 基线 | `package.json` | **上游打包缺陷**：`@deepseek-ai/dsh-client-ui-primitives@0.1.5-alpha.2` 的 manifest 不再声明任何 `dependencies`（alpha.1 声明了 19 个），但其 `lib/*.js` 仍裸 import `anser` / `shiki` / `@shikijs/langs/*` / `mdast-util-*` / `micromark-*` / `katex`。宿主自身由预构建前端 bundle 满足，独立安装的消费方（本仓库的 dev/test 树）必须自备，故把 alpha.1 声明的同一组版本提升进 devDependencies（`@shikijs/langs`、`@types/mdast`、`anser`、`katex`、`mdast-util-from-markdown/gfm/math`、`micromark-core-commonmark/extension-gfm/extension-math/factory-space/util-character/util-classify-character/util-sanitize-uri/util-symbol/util-types`、`shiki`；`clsx` 已在 dependencies） |
+| 基线/文档 | `AGENTS.md` | §2/§3 基线戳、§10 补 alpha.2 行为差异（本 workstream 回填） |
+| Tab 契约 | `src/client/service.ts` | `TabDescriptor` 删除 `description` 字段；`SIDEBAR_SERVICE_VERSION` → `0.19.0-alpha.1` |
+| Tab 契约 | `src/client/builtins/tabs.tsx` | 6 个内置 tab 删除 `description` 行 |
+| Tab 契约 | `src/client/native/index.ts` | native 注册的 guide 条目去掉 `description`（删 `descriptionOf` 与通用兜底）；`guide` 条目只剩 `order`/`title`/`icon` |
+| 词典 | `src/client/locales.ts` + 各 `locales-*.ts` | 删除 `nativeGuideDesc` + 6 个 `guideDesc*` 词条（zh/en + 全部第三方语言） |
+| Tab 高度 | `src/client/native/tab-adapter.tsx` | `NativeTabBody` 把 live 组件与 orphaned 回退都包进 `css.nativeTabHost`（带 `data-dsh-native-tab-host`） |
+| Tab 高度 | `src/client/sidebar.module.css` | 新增 `.nativeTabHost`（`display:flex; flex-direction:column; height:100%; min-height:0`） |
+| 地址语法 | `src/client/resource-address.ts` | 重写为镜像 alpha.2 文件地址语法（`fileAddressFor` 不再产 `absolute` 作用域、`parseFileAddress` 前缀去 `?`/`#`、保留 `absolute` 解析） |
+| 中心列锚点 | `src/client/center-column.ts` | `CENTER_COLUMN_SELECTOR` 加 `main.conversation`；新增 `columnOfSlotHost` 跳过 `display: contents` 祖先 |
+| 中心列锚点 | `src/client/sidebar/use-center-column.ts` | 宿主查找逻辑对齐 alpha.2 |
+| 中心列锚点 | `src/client/layout.css` | 选择器/注释同步 `main.conversation` 与 `display: contents` 跳过 |
+| 测试 | `tests/builtins.spec.ts` | 指南断言从 `description` 改成 `title`（图标+标题胶囊） |
+| 测试 | `tests/native-surface.spec.ts` | 注册/guide 断言去 `description`；断言 guide 条目不再携带 `description` |
+| 测试 | `tests/center-column-locator.spec.ts` | 覆盖 `main.conversation` 解析与 `display: contents` 跳过 |
+| 测试 | `tests/resource-address.spec.ts` | 覆盖 alpha.2 地址语法 |
+| 测试 | `tests/e2e/mount.e2e.ts` | guide 页断言跟随胶囊形态；新增 tab 体填充断言（可见 tab 的 `[data-dsh-native-tab-host]` 盒高 == 其带盒祖先高 ±2px，且 sidechat composer 底边距面板底 ≤12px） |
+| 文档 | `docs/external-plugin-guide.md` | §0 行为差异表、§4.1 删 `description`、§10 加 tab 体高度契约、§12 中心列锚点、`ui-sidebar-documentpreview` |
+| 文档 | `docs/plans/2026-09-09-dsh-0.1.5-alpha.2-adaptation.md` | 本计划 |
+
+## 已知差距
+
+- **side-chat 线程仍只携带 `subagent/descriptor`，不携带 alpha.2 的 `subagent/catalog`**：DSH 自己的直接子代理发现现在优先读 `catalog`，而我们沿用的 `subagents.listDescendants`（`src/subagent-live-route.ts`）与转录种子的 `type: 'subagent/descriptor'`（`src/sidechat-routes.ts`）路径不变。catalog 只作为新增读面出现，不构成对现有路径的破坏，本期不跟进。
+
+## 验证
+
+- **门禁**（本分支 HEAD）：`pnpm typecheck` / `pnpm lint` / `pnpm check:consumer-types` 全绿；`pnpm vitest run --exclude '**/*.e2e.ts'` = 124 files / 1295 passed / 9 skipped；`pnpm peers check` = No peer dependency issues found。
+- **真机挂载冒烟**（`DSH_CMD` 指向 npm 安装的 DSH 0.1.5-alpha.2，`scripts/e2e-mount.sh`）：7 passed。新增的 tab 体填充断言（可见 tab 的 `[data-dsh-native-tab-host]` 盒高 == 其带盒祖先 ±2px，sidechat composer 底边距面板底 ≤12px）是这次修复的回归守护——它在修复前失败（`gap -862px`，因为断言最初漏跳过 `display: contents` 槽宿主）。
+- **真机 3080（web profile 升到 alpha.2 + 插件 0.19.0-alpha.1）**：
+  - 原生 guide 六行均为 48px「图标+标题」胶囊，无第二行：文件 / 文件变动 / 任务管理 / 侧边对话(beta) / 终端 / 浏览器。
+  - 文件树点击 `AGENTS.md` → tab 标题 `AGENTS.md` + CodeMirror 挂载（`editor` 接管成立）。
+  - **sidechat 输入框贴底**：原生右侧栏 `hostHeight 962 == paneBodyHeight 962`（fillGap 0），composer 底边距面板底 8px（即它自己的 margin）；底部工作台同样 8px。
+  - 底部工作台中心列锚点：`[data-dsh-bottom-panel]` 与 `[data-dsh-center-col]` 左右边完全重合（gap 0）——证明 `main.conversation` + 跳过 `display: contents` 的解析在真机成立；真机 `[data-slot]` 清单同时确认 `main` / `main.conversation` / `rightbar.session` 已存在、旧 `conversation` 槽已消失。
+  - `pageerror` 0 条；控制台仅 `POST /api/dsh-worktree/attach` 500（第三方 dsh-tauri-worktree 插件，与本次改动无关）。
+  - 未覆盖：**聊天里的文件链接点击**——当前可见会话没有可解析的文件提及（内联 `code` 是纯文本，不是链接），该漏斗（`ctx.sidebarRight.openResource(fileAddressFor(...))`）由挂载车道与 `tests/resource-address.spec.ts` 覆盖，本实例未实测。
+- 仓库没有守护指南文档章节的测试；`tests/builtins.spec.ts` / `tests/native-surface.spec.ts` 守护的是 guide 行形态而非文档文本。
+- 早期本分支相关测试曾整体收集失败：`@deepseek-ai/dsh-client-ui-primitives@0.1.5-alpha.2` 在模块加载时裸 `import 'anser'`，而该包 manifest 已不再声明依赖。补齐 devDependencies 后恢复（见改动清单）。
+
+## 不做
+
+- 不接入 alpha.2 全局面板（`main` 槽 / `sidebar.panellist` / `ctx.layout` / `usePanelInfo` / 根级 `rightbar`）。
+- 不引入 `subagent/catalog` 读取面。
+- 不改 DSH 源码（仓库硬约束 §1）。
+
+## 落地
+
+- #603 → #604 → #605 → #609 依序合入 `main`（各自 retarget 到 main 后以 merge commit 合并）；main 的 `package.json` 为 `0.19.0-alpha.1`、`engines.dsh` 为 `>=0.1.5-alpha.2`。main 的 CI 首轮 `ci-windows` 因既有的 pty/git 5s 超时抖动失败，重跑后三 job 全绿。
+- 发布 [v0.19.0-alpha.1](https://github.com/omdsh-dev/DSH-better-sidebar/releases/tag/v0.19.0-alpha.1)：`release.yml` 通过全门禁后经 npm Trusted Publishing 发布，npm `alpha` dist-tag → `0.19.0-alpha.1`（带 provenance）。发布产物核对：`lib/index.js` 与本地已验证构建逐字节一致；`lib/client.js` 仅差打包非确定性（已知）；`package.json` 仅少 dev-only 字段（`packageManager` / `prepare` / `prepublishOnly`，npm 发布时剥离）。
+- 注意：新版本在 registry 上可见有约 5 分钟传播延迟（版本元数据先到、tarball 后到），期间 `npm view`/tarball 可能 404——不是发布失败。

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

@@ -0,0 +1,86 @@
+# 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）。这不是发布失败，别重发。