chore(release): cut v0.21.1 as the stable adapter for DSH 0.1.7-rc.1
The rc.1 adapter first went out as 0.21.0-rc.1, but DSH 0.1.7-rc.1 is upstream's release batch, so the plugin that targets it must not sit on a prerelease channel. Re-cut it as v0.21.1: the version is now free of `-`, so release.yml publishes it under npm's `latest` instead of `alpha`. Version literals only — package.json, dsh.plugin.json and SIDEBAR_SERVICE_VERSION (tests/service.spec.ts still pins the last two together). No code change: the peer floor stays ^0.1.7-rc.1 and the support line stays "DSH 0.1.7-rc.1 and later". Docs follow the channel move: README/README_EN/guide drop the "alpha channel" framing, the install command becomes @latest, and every older DSH line now gets an explicitly pinned command in the version table (@0.19.1 and so on) because `latest` no longer covers them. The rc.1 design record keeps its history and gains a §8 for the re-cut.
This commit is contained in:
Menghuan1918
@@ -2,7 +2,7 @@
|
||||
|
||||
> 面向 **消费插件开发者**：如何让你的插件向 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+**。当前版本 **v0.21.0-rc.1**（npm dist-tag `alpha`；`latest` 仍是 **v0.19.1**，peer 下限 `^0.1.7-rc.1`，仅支持 DSH **0.1.7-rc.1+**）。**v0.19.0 移除了自绘右侧面板与自由窗口**（见 §0、§11）；**自 v0.20.0 开发线起**（**注意：0.20.0 从未发布到 npm，这些变更全部落在 v0.21.0-rc.1**）插件**移除了自带的终端**（宿主 0.1.6 的 `ui-sidebar-terminal` 取代，见 §4.4）、**移除了终端固定（pin）**，并在 0.1.7 上**把浏览器视图与只读文件预览整体让给宿主**（`ui-sidebar-browser` / `ui-sidebar-documentpreview`，见 §4.4、§5.4）、**收敛了外链接管**（见 §4.1）、**重写了设置接入面**（`SettingsForms`，见 §8.2）、**给文件树加了实时刷新**（见 §10）；同时**删除了轮尾产物行接管**（DSH 0.1.6 把 `conversation.chat.turnTail` 从 chain 改成只能追加的 list，替换语义不复存在）。
|
||||
> 适用版本：**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+**。当前版本 **v0.21.1**（npm dist-tag `latest`，peer 下限 `^0.1.7-rc.1`，仅支持 DSH **0.1.7-rc.1+**）。**v0.19.0 移除了自绘右侧面板与自由窗口**（见 §0、§11）；**自 v0.20.0 开发线起**（**注意：0.20.0 从未发布到 npm，这些变更全部落在 v0.21.1**）插件**移除了自带的终端**（宿主 0.1.6 的 `ui-sidebar-terminal` 取代，见 §4.4）、**移除了终端固定（pin）**，并在 0.1.7 上**把浏览器视图与只读文件预览整体让给宿主**（`ui-sidebar-browser` / `ui-sidebar-documentpreview`，见 §4.4、§5.4）、**收敛了外链接管**（见 §4.1）、**重写了设置接入面**（`SettingsForms`，见 §8.2）、**给文件树加了实时刷新**（见 §10）；同时**删除了轮尾产物行接管**（DSH 0.1.6 把 `conversation.chat.turnTail` 从 chain 改成只能追加的 list，替换语义不复存在）。
|
||||
> 权威代码：`src/client/service.ts`（服务实现）、`src/client/builtins/`（内置 5 tab + 3 viewer 参考实现）、`lib/types/client/service.d.ts`（类型声明）。
|
||||
> 仓库开发规则（硬约束 / CI / 发版）见 [AGENTS.md](../AGENTS.md)。
|
||||
|
||||
@@ -25,8 +25,8 @@
|
||||
| 布局持久化 | 原生栏的布局**只在内存**（刷新后回到折叠默认），插件自己的底部工作台仍然持久化 |
|
||||
| 跨会话打开 | 目标会话的右侧栏 store 未挂载时，打开会排队到该会话上屏后重放 |
|
||||
| 内置类型接管 | 插件的 `editor` 类型以 `extension` 优先级认领 `dsh-resource://file/**`（压过内置 `ui-sidebar-documentpreview` 的 `text` 预览——即 `fallback` 带），并接管内置 `files` 页面 kind（`openTab('files')` 打开插件的文件树）；插件卸载/禁用时内置实现自动复位。**但认领是有选择的**：宿主自己的文档预览已经覆盖的格式（表格 / PDF / 图片 / Office，清单见 §5.4）由 `editor.canOpen` 主动**拒绝**，地址交回内置 `text` 档 |
|
||||
| 文件树实时刷新（v0.21.0-rc.1+） | 插件接管了内置 `files` 页，所以宿主自己的按目录 watch 覆盖不到这棵树——插件自带一条 `/sidebar/ws/fs-watch` socket：客户端上报**已展开**的目录集，宿主侧按目录 `fs.watch`（150ms 去抖、每连接上限 64 个句柄），变动后只让那一层缓存失效并重列；目录折叠即退订。路径仍走 `fs.tree` 同一道 workspace fence |
|
||||
| 链接接管（v0.21.0-rc.1+） | DOM 层只接管**有类型通过 `urlTarget` 声明认领**的外链（Ctrl/Cmd/Shift/Alt 点击一律放行）；一个都没认领到时**不阻止默认行为**，交回宿主。见 §4.1 的 `urlTarget` |
|
||||
| 文件树实时刷新（v0.21.1+） | 插件接管了内置 `files` 页，所以宿主自己的按目录 watch 覆盖不到这棵树——插件自带一条 `/sidebar/ws/fs-watch` socket：客户端上报**已展开**的目录集，宿主侧按目录 `fs.watch`（150ms 去抖、每连接上限 64 个句柄），变动后只让那一层缓存失效并重列；目录折叠即退订。路径仍走 `fs.tree` 同一道 workspace fence |
|
||||
| 链接接管（v0.21.1+） | DOM 层只接管**有类型通过 `urlTarget` 声明认领**的外链（Ctrl/Cmd/Shift/Alt 点击一律放行）；一个都没认领到时**不阻止默认行为**，交回宿主。见 §4.1 的 `urlTarget` |
|
||||
| path 种子的去向（v0.19.2+） | `path` seed 的含义**跟随类型**：只有 `editor`（唯一认领 `dsh-resource://file/**` 的类型）把 path 转成资源地址打开（文件落在编辑器）；**其余类型保留页面型打开**，path 随导航 params 落到合成记录的 `tab.path` 供组件消费——组件型 tab 的 path seed 不会被改道到文件编辑器（v0.19.0/0.19.1 上一切 path seed 都被改道，组件从未挂载，#632） |
|
||||
| 终端（已交还宿主） | 插件**不再提供任何终端**：宿主 0.1.6 起自带 `ui-sidebar-terminal`（kind `terminal`），插件侧 PTY 栈与 `terminal_*` 工具整体删除。这里不再有「插件终端数量上限」这类语义 |
|
||||
| 底部工作台的开合 | 落到底部工作台的打开一律展开它（新建与聚焦都算），因此 `openTab` 的落点永远可见；开合按钮注册在 DSH 会话头的 utilities 槽（`conversation.session.header.utilities`），不在插件自己的宿主里 |
|
||||
@@ -226,7 +226,7 @@ interface TabDescriptor {
|
||||
*
|
||||
* **没被认领的链接一律放行**（插件不 preventDefault）：DSH 0.1.7 起正文链接的
|
||||
* 去向由宿主的用户设置 `linkOpening` 决定（进侧栏还是新标签页），插件自绘
|
||||
* markdown 里则走 `<a>` 自己的默认行为。**v0.21.0-rc.1 起那三个「按协议分流」
|
||||
* markdown 里则走 `<a>` 自己的默认行为。**v0.21.1 起那三个「按协议分流」
|
||||
* 的旧设置项已删除**（旧文档里的键会被忽略），本插件不再有任何接管总闸——
|
||||
* 认领与否完全由你的 urlTarget 决定；Ctrl/Cmd/Shift/Alt 点击永远绕过接管。
|
||||
* 认领成功但目标类型在打开那一刻已不可用（插件卸载 / 被设置关闭）时，点击
|
||||
@@ -415,7 +415,7 @@ ctx.effect(() => {
|
||||
|
||||
你的 `id` 不可与上述重复，否则 `registerTab` 抛 `"tab type \"X\" already registered"`。
|
||||
|
||||
**自 v0.20.0 开发线起删除的类型（迁移提示；0.20.0 从未发布，变更落在 v0.21.0-rc.1）**：
|
||||
**自 v0.20.0 开发线起删除的类型（迁移提示；0.20.0 从未发布，变更落在 v0.21.1）**：
|
||||
|
||||
| 原 id | 现状 | 你该怎么做 |
|
||||
|---|---|---|
|
||||
@@ -506,7 +506,7 @@ interface FileViewerProps {
|
||||
>
|
||||
> `xlsx xls csv tsv fods pdf png jpg jpeg gif webp svg bmp ico doc docx ppt pptx`
|
||||
>
|
||||
> **这份清单现在是「宿主渲染器实际覆盖的集合」，不多不少**：`v0.21.0-rc.1` 收回了 9 个宿主其实**没有渲染器**的扩展名（`xlsb` / `xlt` / `xltx` / `xltm` / `ots` / `dot` / `dotx` / `avif` / `ods`——前两个落在宿主的 `document/unviewable.ts`「已知二进制、无渲染器」表里，其余落回 text 兜底后按二进制判定失败，一律只有「暂不支持预览」），它们重新由插件的 `code` catch-all 认领并落到下载面板。`fods` 保留让出：宿主会用纯文本显示那段扁平 XML，比下载面板有用。`tests/native-surface.spec.ts` 双向钉住这条边界（宿主能渲染的必须拒绝、宿主不能渲染的必须认领）。
|
||||
> **这份清单现在是「宿主渲染器实际覆盖的集合」，不多不少**：`v0.21.1` 收回了 9 个宿主其实**没有渲染器**的扩展名（`xlsb` / `xlt` / `xltx` / `xltm` / `ots` / `dot` / `dotx` / `avif` / `ods`——前两个落在宿主的 `document/unviewable.ts`「已知二进制、无渲染器」表里，其余落回 text 兜底后按二进制判定失败，一律只有「暂不支持预览」），它们重新由插件的 `code` catch-all 认领并落到下载面板。`fods` 保留让出：宿主会用纯文本显示那段扁平 XML，比下载面板有用。`tests/native-surface.spec.ts` 双向钉住这条边界（宿主能渲染的必须拒绝、宿主不能渲染的必须认领）。
|
||||
>
|
||||
> 后果：**你注册这些扩展名的 viewer 仍然合法（注册表不冻结 id，`matchFileViewer` 也会命中），但通过聊天 / 文件树 / 编辑器的正常文件打开路径拿不到它们**——那是宿主的文档预览。要在这些格式上做文章，只能自己在页面里渲染（或像 [Office 预览插件](https://github.com/HuanLinOTO/dsh-plugin-better-sidebar-plugin-office) 那样在宿主接管前的旧版本上生效）。**可用的是 md/markdown / html/htm 与 code catch-all 三类**（外加任何不在上表里的扩展名）。未知二进制（`.zip` / `.wasm`）仍走 code 认领 → `fs.read` 判 binary → head 重匹配无 sniffer → 编辑器渲染下载面板，功能不回归。
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
> 基线标签：`dsh-v0.1.6-alpha.2`（`ddefc45fbc`）→ `dsh-v0.1.7-alpha.1`（`c36a83ff6b`），相隔 **1299 个 commit / 4754 个文件变更**。
|
||||
> 本文记录**为什么这么改**与**改完的证据**；规则性结论沉淀在仓库根 `AGENTS.md` §3。
|
||||
>
|
||||
> ⚠️ **后续**：`v0.21.0-alpha.1` **从未发布到 npm**——这条开发线随后又适配到 **0.1.7-rc.1**，peer 下限收到 `^0.1.7-rc.1`，整个 0.21 线的变更一并随 **v0.21.0-rc.1** 出货。本文保留为 alpha.1 阶段的原始记录（结论仍然有效），最新状态见 [2026-09-23-dsh-0.1.7-rc.1-adaptation.md](2026-09-23-dsh-0.1.7-rc.1-adaptation.md)。
|
||||
> ⚠️ **后续**：`v0.21.0-alpha.1` **从未发布到 npm**——这条开发线随后又适配到 **0.1.7-rc.1**，peer 下限收到 `^0.1.7-rc.1`，整个 0.21 线的变更一并随 **v0.21.1** 出货。本文保留为 alpha.1 阶段的原始记录（结论仍然有效），最新状态见 [2026-09-23-dsh-0.1.7-rc.1-adaptation.md](2026-09-23-dsh-0.1.7-rc.1-adaptation.md)。
|
||||
|
||||
## 1. 怎么做的（方法与边界）
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# DSH 0.1.7-rc.1 适配记录
|
||||
|
||||
> 适配对象：`dsh-better-sidebar` v0.21.0-alpha.1（支持 DSH 0.1.7-alpha.1）→ **v0.21.0-rc.1（仅支持 DSH 0.1.7-rc.1+）**。
|
||||
> 适配对象：`dsh-better-sidebar` v0.21.0-alpha.1（支持 DSH 0.1.7-alpha.1）→ **v0.21.1 正式版（仅支持 DSH 0.1.7-rc.1+）**（中途曾在 `alpha` 通道切过一版 `0.21.0-rc.1`，见 §8）。
|
||||
> 基线标签：`dsh-v0.1.7-alpha.1`（`c36a83ff6b`）→ `dsh-v0.1.7-rc.1`（`46a7f68b09`），相隔 **318 个 commit / 1361 个文件变更**（中间还跨过一个没适配的 `0.1.7-alpha.2`）。
|
||||
> 本文记录**为什么这么改**与**改完的证据**；规则性结论沉淀在仓库根 `AGENTS.md` §3（新增 §3.4 第 12 条）。上一阶段见 [2026-09-22-dsh-0.1.7-alpha.1-adaptation.md](2026-09-22-dsh-0.1.7-alpha.1-adaptation.md)。
|
||||
|
||||
@@ -104,3 +104,12 @@ peerDependencies {"@deepseek-ai/dsh-client-runtime":"^0.0.1-rc.1"}. …
|
||||
- **未按同一份实践文档把 `jobs` 路由重构成 `ctx.sessionProjections` 单元**：那是行为等价重构，超出本轮范围。
|
||||
- **`src/client/conversation-draft.ts` 的锚点缺陷未动**：它只认 `[data-slot="conversation"]`（`center-column.ts` 已经是 `main.conversation` 优先的双臂选择器）。经核对这是 **0.1.7-alpha.1 起就存在**的既有缺陷、不是 rc.1 引入，且与本轮变更不同源；记在这里待单独处理。
|
||||
- **未重跑真机 Plugins 页的图标/文案断言**：那条路径（`readPluginMeta` + `ui-plugin-manager` 渲染）在本轮逐字未变，且上一轮已真机验证过；本轮的真机证据集中在「升级后插件仍挂载、无错误、跑的是新产物、设置 volatile 提交仍成立」。
|
||||
|
||||
## 8. 正式版 v0.21.1
|
||||
|
||||
rc.1 适配完成后先切过一版 `0.21.0-rc.1`（含 `-` → 只进 npm `alpha` 通道，GitHub Release 标为 Pre-release）。但 **DSH 0.1.7-rc.1 本身就是上游的正式发布批次**，适配它的插件版本不该停留在预发布通道上，因此重切 **`v0.21.1`**（不含 `-` → npm dist-tag `latest`）：
|
||||
|
||||
- 版本号只改字面量：`package.json` / `dsh.plugin.json` / `SIDEBAR_SERVICE_VERSION`；**代码零改动**（`tests/service.spec.ts` 仍然守着 `SIDEBAR_SERVICE_VERSION === pkg.version`）。
|
||||
- peer 下限仍是 `^0.1.7-rc.1`（不变），支持线仍是 **DSH 0.1.7-rc.1 及之后的 0.1.7 线**。
|
||||
- npm `latest` **从 `0.19.1` 前移到 `0.21.1`**；`0.21.0-rc.1` 继续留在 `alpha` 通道上作为历史版本，未撤回。
|
||||
- 因此 README 与 Release 的「按 DSH 版本选插件版本」对照表里，**旧 DSH 一律改成精确钉版**（`dsh plugin --profile web add dsh-better-sidebar@0.19.1` 之类）——`@latest` 从此只服务 0.1.7-rc.1+ 这条线。
|
||||
|
||||
Reference in New Issue
Block a user