feat(dsh): 适配 DSH 0.2.0-rc.1（单线支持）+ v0.24.0
支持线从 ^0.1.7-rc.1 整体前移到 ^0.2.0-rc.1；0.1.7 线（含 npm latest 的 0.1.7-rc.2）停留在 v0.23.0。适配前实测确认这是纯增量，故本版无运行时兼容分支。 必改项（否则装不上/不加载） - 14 条 DSH peer → ^0.2.0-rc.1。实测 caret 跨 minor 不成立：`^0.1.7-rc.1` 展开为 >=0.1.7-rc.1 <0.2.0-0，对 0.2.0-rc.1 判定 false（includePrerelease 也救不了）。判别性验证：把 peer 回退成 ^0.1.7-rc.1 后，在 0.2.0-rc.1 宿主上 `dsh plugin add` 直接拒绝并回滚包树—— "installation rejected: Plugin dsh-better-sidebar@0.24.0 is incompatible with dsh 0.2.0-rc.1: peerDependencies {…^0.1.7-rc.1…}"；恢复 ^0.2.0-rc.1 后安装通过 - 28 个 @deepseek-ai/* devDependencies 精确钉 0.2.0-rc.1（cordis 4.0.4 / cordis-plugin-group 1.0.4 / cordis-plugin-include 1.0.9 不变） - 新增 @deepseek-ai/dsh-util-code-language@0.2.0-rc.1：0.2.0 的 ui-primitives 产物裸 import 它（0.1.7 的产物同样 import，只是旧树里恰好被传递提供）， 不补则所有加载 ui-primitives 的 20 个 spec 在收集期失败 实测证据（写进 docs/plans/2026-09-28-dsh-0.2.0-rc.1-adaptation.md） - 本插件消费的 19 个宿主包零值导出删除（对比 export {} / exports.x=） - 类型面仅 3 处且全为增量：ui-primitives（DisclosureRow/TextShimmer/Tooltip 新增可选 prop、overlay 顶部内距）、dsh-session（新增 ToolCallRecovery）、 dsh-api-remotes（新增 product-analytics remote） - 会话格式仍 v4、SUBAGENT_DESCRIPTOR_VERSION 仍 3、dsh/lib/bin.js 与 dsh-client-modules 运行时逐字节相同、web profile 客户端 inject 列表相同、 ui-primitives 裸 import 集合不变、agent-team 四包类型逐字相同 - 宿主 web profile：新增 desktop-only product-analytics/telemetry（web 上 disabled）；time-context/schedule/ui-schedule（本就 disabled）移入可选 dsh-experimental-schedule-bundle；插件不依赖宿主 schedule 其余同步 - CI 与挂载 lane 钉 @deepseek-ai/dsh@0.2.0-rc.1（scripts/e2e-common.sh 的 DSH_NPX_SPEC/DSH_EXPECT_VERSION、ci.yml），注释记下「0.2.0 首个候选版只挂 next」与「caret 跨 minor 必失效」两条教训 - tests/market-manifest.spec.ts 的 peer 形状断言钉当前基线 tuple - dsh.plugin.json engines.dsh → >=0.2.0-rc.1；SIDEBAR_SERVICE_VERSION → 0.24.0 - README/README_EN、CHANGELOG/CHANGELOG_EN、AGENTS.md（§2 钉版句 + §3 改为 「DSH 版本适配要点」并新增 §3.0 当前基线，0.1.7 内容降为历史分节）、 docs/external-plugin-guide.md 全部同步 验证：pnpm peers check 仅剩上游 better-locale 的 5 条 unmet（非本插件 peer）； typecheck / lint / test（136 文件 1484 通过 9 跳过）/ build 全绿； DSH_CMD='npx -y --package @deepseek-ai/dsh@0.2.0-rc.1 dsh' pnpm test:mount = 7/7； pnpm test:mount:aggregate 通过（聚合双挂载退让）
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.22.0**（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，替换语义不复存在）。
|
||||
> 适用版本：**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.24.0**（peer 下限 `^0.2.0-rc.1`，仅支持 DSH **0.2.0-rc.1+**；0.1.7 线请用 v0.23.0——caret 范围跨 minor 不成立，`^0.1.7-rc.1` 会被 0.2.0 宿主的启动预检静默禁用）。**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)。
|
||||
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
# DSH 0.2.0-rc.1 适配记录（v0.24.0）
|
||||
|
||||
> 状态：已实施。支持线从 `^0.1.7-rc.1` 整体前移到 `^0.2.0-rc.1`（**单线**：0.1.7 用户停在 v0.23.0）。
|
||||
> 上游发布：[dsh-v0.2.0-rc.1](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.1)（npm dist-tag `next`；`latest` 仍是 0.1.7-rc.2）。
|
||||
|
||||
## 0. 结论先行
|
||||
|
||||
**0.2.0-rc.1 对本插件所消费的全部宿主 API 是纯增量**：19 个被用到的宿主包**零值导出删除**，会话格式与子代理描述符版本未动，CLI 与客户端运行时逐字节相同。因此本版**没有为 0.1.7 写任何运行时兼容分支**——唯一必须改的是 peer 下限（否则宿主启动预检会静默禁用整行）。
|
||||
|
||||
## 1. 硬阻塞：caret 跨 minor 不成立
|
||||
|
||||
`packages/boot/app-boot/src/plugin-compatibility.ts`（0.1.7-rc.1 起）遍历 profile 行的 `peerDependencies`，对名字为 `@deepseek-ai/dsh` / `@deepseek-ai/dsh-*` 的条目跑
|
||||
`semver.satisfies(宿主版本, 范围, { includePrerelease: true })`，不满足就 `row.disabled = true`，只在 stderr 留一行 `disabling profile plugin …`。
|
||||
|
||||
实测（semver 7，`includePrerelease: true`）：
|
||||
|
||||
| range | 对 `0.2.0-rc.1` |
|
||||
| --- | --- |
|
||||
| `^0.1.7-rc.1` | **false**（caret 上界展开为 `<0.2.0-0`） |
|
||||
| `^0.2.0-rc.1` | true |
|
||||
| `>=0.1.7-rc.1 <0.3.0` | true（显式比较器不带 `-0` 上界） |
|
||||
| `>=0.1.1-rc.2 <0.2.0` | true（同上，`dsh-whale-report` 正因此仍能加载） |
|
||||
|
||||
**教训**：`AGENTS.md` §3.4 第 12 条(c) 那条「`includePrerelease` 让判定更宽松（`^0.1.6-alpha.2` 也能满足 `0.1.7-rc.1`）」**只在同一 minor 内成立**；跨 minor 时必须同步抬 peer 下限。用户已选择**单线**方案，不做「同时覆盖两条线」的放宽范围。
|
||||
|
||||
## 2. 适配前实测证据（决定了「零运行时改动」）
|
||||
|
||||
| 检查面 | 方法 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 值导出删除 | 对插件 import 的 19 个宿主包，提取 `lib/*.js` 里 `export {…}` / `exports.x=` 的名字集合做差 | **removed = none**；唯一新增 `ui-primitives` 的 `pointerModality` |
|
||||
| 类型面变化 | `lib/types/**` 逐文件 hash + diff | 仅 3 处：`ui-primitives`（`DisclosureRow` / `TextShimmer` / `Tooltip` 新增可选 prop、overlay 顶部内距改用 frame overlay inset）、`dsh-session`（新增 `ToolCallRecovery`；`interruptedTurnClosers` 仍在）、`dsh-api-remotes`（新增 product-analytics remote 行） |
|
||||
| 会话格式 | 查 `SESSION_FORMAT_VERSION` 与 `session-format-*` 迁移包清单 | 仍 **v4**，无 `session-format-v4-to-v5` |
|
||||
| 子代理描述符 | `grep SUBAGENT_DESCRIPTOR_VERSION` | 仍 **3** |
|
||||
| CLI 契约 | `diff dsh/lib/bin.js` | **字节相同**（`dsh plugin` / `dsh web` / 就绪行 / `--version` 全不变） |
|
||||
| 客户端运行时 | `diff dsh-client-modules/lib/index.js`、客户端包 `provide(...)` 名字、web-app 的 `dsh.client.inject` | 全部相同 |
|
||||
| 测试期依赖 | 对比 `ui-primitives` 产物的裸 import 集合 | 相同 → **无需新增 devDependency**（不重演 0.1.7 §3.3 第 12 条） |
|
||||
| agent-team | 四个包的 `lib/types` hash | 逐字相同 |
|
||||
| web profile 组成 | `web-app/cordis.patch.yml` diff | 新增 desktop-only `product-analytics` / `desktop-product-telemetry`（web 上 `disabled`）；`time-context` / `schedule` / `ui-schedule`（本就 `disabled`）移入可选 `dsh-experimental-schedule-bundle`。挂载 lane 的「宿主 tab 恰 1 条（terminal）、browser 缺席」断言不受影响 |
|
||||
|
||||
## 3. 实施内容
|
||||
|
||||
1. `package.json`：14 条 DSH peer → `^0.2.0-rc.1`；27 个 `@deepseek-ai/*` devDependencies 精确钉版 → `0.2.0-rc.1`（`@deepseek-ai/cordis` 4.0.4 / `cordis-plugin-group` 1.0.4 / `cordis-plugin-include` 1.0.9 不变）；`version` → `0.24.0`。
|
||||
2. `dsh.plugin.json`：`engines.dsh` → `>=0.2.0-rc.1`（零读者的元数据，但保持诚实）。
|
||||
3. `scripts/e2e-common.sh`：`DSH_NPX_SPEC` 与 `DSH_EXPECT_VERSION` → `0.2.0-rc.1`。
|
||||
4. `.github/workflows/ci.yml`：`npm install -g @deepseek-ai/dsh@0.2.0-rc.1` + 注释补「0.2.0 首个候选版只挂在 `next` 上」。
|
||||
5. `tests/market-manifest.spec.ts`：peer 形状正则钉当前基线 tuple（`/^\^0\.2\.0-[a-z0-9.]+$/`），并把「caret 跨 minor 必失效」写进注释。
|
||||
6. 文档：`README.md` / `README_EN.md`（支持线横幅、shields 徽章、安装对照表新增 0.2.0 行并保留 0.1.7 行的 v0.23.0 指引、最近更新新增 v0.24.0）、`CHANGELOG.md` / `CHANGELOG_EN.md`（v0.24.0 条目）、`AGENTS.md`（§2 钉版句、§3 改为「DSH 版本适配要点」并新增 §3.0 当前基线 + 0.1.7 历史分节）、`docs/external-plugin-guide.md`（当前版本与 peer 下限）。
|
||||
7. **未改任何 `src/**` 运行时代码**——证据见 §2。
|
||||
|
||||
## 4. 已知残留（非本插件可解）
|
||||
|
||||
- `@huanlin/dsh-plugin-better-locale`（**可选**集成；没有任何源码或测试 import 它，运行时靠 `ctx.get('betterLocale')` 结构化探测）的 peer 钉在 `^0.1.0-rc.8`，其最新 0.4.3 也钉 `^0.1.5-rc.2` → 在 0.2.0 上都会被宿主预检禁用。因此 `pnpm peers check` 会报它的 **5 条 unmet peer**；本插件自身的 14 条 peer 全部满足。属上游未适配 0.2.0。
|
||||
- 本机 pnpm 的 registry 是 `registry.npmmirror.com`，对新预发布滞后（本次实测：镜像上 `@deepseek-ai/dsh-attachment@0.2.0-rc.1` 不存在 → `ERR_PNPM_NO_MATCHING_VERSION`）。安装用一次性覆盖：`pnpm install --registry https://registry.npmjs.org`。
|
||||
- `@deepseek-ai/dsh-experimental-agent-team-web-profile` 仍无 0.1.7 / 0.2.0 发布（停在 0.1.6-alpha.2）→ 本机实例升级时该行保持旧版，运行时兼容性属**未验证**（见 §5）。
|
||||
|
||||
## 5. 本机 3080 实例升级（与仓库适配分开执行）
|
||||
|
||||
升级前的 profile 预检（18 个依赖，按宿主同一套 semver 语义逐个判定）：
|
||||
|
||||
| 依赖 | DSH peer | 0.2.0-rc.1 |
|
||||
| --- | --- | --- |
|
||||
| `dsh-better-sidebar@0.23.0` | `^0.1.7-rc.1` | **会被禁用** → 本版 v0.24.0 修复 |
|
||||
| `dshmarket@1.35.0` | `^0.1.0-rc.7 \|\| ^0.1.1-rc.2`（最新 1.66.3 的 `dsh-settings` peer 仍是 `^0.1.x`） | **会被禁用**（上游未适配，无法绕过） |
|
||||
| `dsh-whale-report@0.5.4` | `>=0.1.1-rc.2 <0.2.0` | 可加载（显式比较器） |
|
||||
| `dsh-notification@0.1.4` | `*` | 可加载 |
|
||||
| `dsh-feishu-notify` / `dsh-flowglass` / `dsh-lan-access` / `dsh-apollo` / `dsh-tauri*` | 无 DSH peer | 不被预检拦（运行时未验证） |
|
||||
| `@deepseek-ai/dsh-experimental-agent-team-profile` | 无 DSH peer | 升级到 0.2.0-rc.1 |
|
||||
| `@deepseek-ai/dsh-experimental-agent-team-web-profile@0.1.6-alpha.2` | 无 DSH peer | 保持旧版（无 0.2.0 发布），运行时未验证 |
|
||||
|
||||
升级步骤（含回滚）见最终交付说明：备份 `~/.dsh/dsh-web.sh` 与 `profiles/web/package.json` → launcher 的 npx 钉版 → `0.2.0-rc.1` → 升 agent-team profile → 装 v0.24.0 tarball → `pm2 restart dsh-web` → 核对路由与 `pm2 logs` 的 `disabling profile plugin` 行。
|
||||
Reference in New Issue
Block a user