dsh-sansheng-liubu/docs/p0/compat.md

471 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# DSH 宿主 × ds-bot 0.3.2 兼容性核查(P0-C)
> 核查性质:**只读**。本次未安装 ds-bot,未修改 profile 的 `package.json` / `cordis.patch.yml` / `pnpm-workspace.yaml`,未执行任何 `dsh plugin add`。
> 核查对象:ds-bot 上游固定 commit `8e0013e077eaeccc137327956e18425e73a5bb8c`,包版本 `0.3.2`。
> 核查时间:2026-11-10(Asia/Shanghai)。宿主为 nightly 通道,结论有时效性。
---
## 1. 版本对照表
| 维度 | 本机宿主实测 | ds-bot 0.3.2 声明 / 期望 | 判定 |
| --- | --- | --- | --- |
| DSH 宿主版本 | **0.2.1-rc.5** | README:`Tested with dsh 0.2.2-rc.1` | ⚠ 比测试基线低 1 个 rc(`peerDeps` 拦不住,见 §4) |
| `@deepseek-ai/cordis` | **4.0.5** | peerDeps `*` | ✅ satisfied(区间为通配,无约束力) |
| `@deepseek-ai/dsh-llm` | **0.2.1-rc.5** | peerDeps `*` | ✅ satisfied |
| `@deepseek-ai/dsh-scope` | **0.2.1-rc.5** | peerDeps `*` | ✅ satisfied |
| `@deepseek-ai/dsh-tools` | **0.2.1-rc.5** | peerDeps `*` | ✅ satisfied |
| `@deepseek-ai/dsh-web` | **0.2.1-rc.5** | peerDeps `*` | ✅ satisfied |
| 上述 5 个 peer 的提供方 | 宿主 `app.asar` 内置(profile 的 `node_modules/@deepseek-ai/` 只有 4 个无关包) | — | ✅ 不会装出第二份 |
| inject 服务(8 个) | 8/8 均存在于宿主 | `inject = [llm, tools, systemPrompt, sessionController, sessions, sessionTitle, workspaceRegistry, connection]` | ✅ 全部 satisfied |
| 被调用的服务方法 | 逐一比对通过(`create` / `list` / `page` / `projections` / `prompt` / `selectModel` / `resolveAgent` / `rename` / `connection.fetch.register`) | — | ✅ 签名与返回形状对齐 |
| client 半边 | `dsh.client.platform = "web"`,走 `window.__ModuleLoader__` | 同 | ✅ |
| `manifestVersion` | 宿主已装插件中 `dsh-better-sidebar` 用 `1`,`dsh-image-gen` 未声明 | ds-bot **未声明** | ✅ 非阻断(与 image-gen 同类) |
| npm 发布状态 | `ds-bot@0.3.2` 已发布,`dist-tags.latest = 0.3.2` | — | ✅ 可走 registry,无需本地 tarball |
| profile 安装状态 | 未安装(dependencies 与 bundles 均无 `ds-bot`) | — | 待安装 |
| profile 尺寸基线 | 36 个 dependencies(5 个 `link:`)、38 条 `dsh.profile.bundles` | — | 已较重,注意增量 |
**一句话结论**:**静态兼容性通过,可以安装**;唯一实质风险是宿主版本比上游自测基线低一个 rc(0.2.1-rc.5 vs 0.2.2-rc.1),而 peerDeps 全是 `*` 不具备任何版本闸门作用,因此真正的把关来自本次的 API 面逐项比对(已做,见 §4)。
---
## 2. 核查方法与证据链
### 2.1 环境与限制
| 项 | 值 |
| --- | --- |
| 工作目录 | `C:\Users\qyh15\三省六部` |
| 宿主安装目录 | `C:\Users\qyh15\AppData\Local\Programs\DeepSeek Harness\` |
| 宿主 `app.asar` | `...\resources\app.asar`,**182,766,714 字节,18,234 个条目** |
| profile | `C:\Users\qyh15\.dsh\profiles\desktop\` |
| node | v24.21.0(需 `export PATH="/c/Users/qyh15/.dsh/dsh-runtimes/dsh-primary-runtime/dependencies/node/bin:$PATH"`) |
| 网络 | git 的 https 远程与 `curl` 均不可用(pipe/schannel 错误),**只能用 node 内置 `fetch`** |
| 安全网 | profile 的 `.npmrc` 被 CC Safety Net 拦截(`Rule: secret.basename.npmrc`),未读取、未绕过;本报告不依赖该文件 |
### 2.2 取证工具(均落在 `.scratch/p0/`,未纳入提交)
| 脚本 / 产物 | 用途 |
| --- | --- |
| `asar-read.cjs` | 解析 asar pickle header(`uint32 headerPickleSize @4`、`headerStringSize @8`,`baseOffset = 8 + headerPickleSize`),按路径解出条目 |
| `asar-grep.cjs` | 一次读入 index,按**路径正则**筛文件并在进程内按**文本正则** grep,输出 `路径:行号:内容` |
| `npm-fetch.mjs` | 用 node `fetch` 打 npm registry |
| `host-package.json` | 从 asar 解出的宿主 `package.json` 原始 17,168 字节 |
| `asar-index.txt` / `core-pkgs.txt` / `host-services.txt` | asar 条目清单 / 307 个 `@deepseek-ai/*` 包名 / 宿主 88 个 cordis 服务名 |
| `api-session-controller.js`、`session-title.js`、`client-connection.index.js` | 从 asar 解出的相关服务源码(3,368 / 652 / — 行) |
关键命令形态:
```bash
node asar-read.cjs "<...>/resources/app.asar" "dsh/package.json"
node asar-grep.cjs "<...>/resources/app.asar" "<路径正则>" "<文本正则>"
node npm-fetch.mjs https://registry.npmjs.org/ds-bot
```
### 2.3 重要限制:asar 内没有任何 `.d.ts`
对 18,234 个条目按 `\.d\.ts$` 计数为 **0**。因此"类型层面"的对齐无法用 d.ts 佐证,本报告只能用 **JS 实现源码 + 服务声明 + README** 作为等效证据,并在 §5 把结论强度分层标注。
---
## 3. 宿主版本:**0.2.1-rc.5**(双独立证据)
| 证据 | 内容 |
| --- | --- |
| E1:asar 内 `dsh/package.json` | `name = @deepseek-ai/dsh-desktop-runtime`,**`version = 0.2.1-rc.5`**;305 个 dependencies 中全部 `@deepseek-ai/*` 均为 `0.2.1-rc.5`(cordis 例外为 `4.0.5`) |
| E2:`DeepSeek Harness.exe` 的 VersionInfo | `FileVersion = 0.2.1-rc.5`,`ProductVersion = 0.2.1.0`,`ProductName = DeepSeek Harness` |
| E3:asar 顶层结构 | `dsh/` 17,188 条、`node_modules/` 1,019 条、`renderer/` 13、`lib/` 13、`package.json` 1 —— 与 "Electron 外壳 + 内嵌 dsh runtime" 一致 |
### 干扰项(**不要用它们判断版本**)
- 安装目录下的 `version` 文件内容是 `44.7.0` —— 这是 **Electron** 版本,不是应用版本。
- `app-update.yml`:`channel: nightly`,`url: https://download.deepseek.com/dsh-desk/feeds/win-x64/` —— 说明本机走 nightly 通道,后续宿主会自动前进到 0.2.2+,届时需复测(见 §7 R1)。
> 附:`resources/runtime/cli/bin/dsh.cmd --version` 从 git bash 需写全路径调用(`dsh` 无 shell wrapper,直接敲 `dsh` 报 `command not found`)。
---
## 4. peerDependencies 满足性(逐项)
### 4.1 ds-bot 0.3.2 声明的 peerDeps
`package.json`(本地 source 与 npm registry 元数据**完全一致**):
```json
"peerDependencies": {
"@deepseek-ai/cordis": "*",
"@deepseek-ai/dsh-llm": "*",
"@deepseek-ai/dsh-scope": "*",
"@deepseek-ai/dsh-tools": "*",
"@deepseek-ai/dsh-web": "*"
}
```
### 4.2 逐项判定
| peer | 区间 | 本机实际提供 | 满足 |
| --- | --- | --- | --- |
| `@deepseek-ai/cordis` | `*` | 4.0.5(宿主 `dsh/package.json`) | ✅ satisfied |
| `@deepseek-ai/dsh-llm` | `*` | 0.2.1-rc.5 | ✅ satisfied |
| `@deepseek-ai/dsh-scope` | `*` | 0.2.1-rc.5 | ✅ satisfied |
| `@deepseek-ai/dsh-tools` | `*` | 0.2.1-rc.5 | ✅ satisfied |
| `@deepseek-ai/dsh-web` | `*` | 0.2.1-rc.5 | ✅ satisfied |
**全部 satisfied —— 但这个结论几乎没有信息量**:`*` 对任何版本都成立,包括 0.1.x 这种 API 完全不同的版本。真正的兼容性证据只能来自 §5 的服务与方法比对。
### 4.3 这 5 个包从哪来(关键机制)
- `C:\Users\qyh15\.dsh\profiles\desktop\node_modules\@deepseek-ai\` 下**只有 4 个包**:`cosmokit`、`dsh-brand`、`dsh-home-paths`、`schemastery`;`node_modules/.pnpm` 下也没有 `deepseek` 相关目录。
- 即:**这 5 个 peer 由宿主 `app.asar` 提供**,profile 既不必也装不到同名包。
- `C:\Users\qyh15\.dsh\profiles\desktop\pnpm-workspace.yaml`:`packages: ['.']`、`nodeLinker: hoisted`、**`autoInstallPeers: false`**。
> `autoInstallPeers: false` 是当前 profile 的**安全网**:一旦改成 `true`,pnpm 会去 npm 拉这 5 个 peer,而 `@deepseek-ai/dsh-llm` 等在 npm 上的 `latest` 是 `0.0.1-rc.1`(stub)、`cordis` 的 `latest` 是 `4.1.0`——会装出**第二份 cordis 与第二套服务**,比版本漂移严重得多。见 §7 R5。
---
## 5. inject 服务存在性(8/8)
ds-bot `index.js:54`:
```js
export const inject = ['llm', 'tools', 'systemPrompt', 'sessionController',
'sessions', 'sessionTitle', 'workspaceRegistry', 'connection']
```
(同文件 `index.js:53` `export const name = 'ds-bot'`,`index.js:63` `export function apply(ctx, config = {})`)
### 5.1 服务声明定位(路径均在 `app.asar` 内 `dsh/node_modules/` 下)
| # | 服务 | 宿主声明位置 | 存在 |
| --- | --- | --- | --- |
| 1 | `llm` | `@deepseek-ai/dsh-llm/lib/index.js:1816` | ✅ |
| 2 | `tools` | `@deepseek-ai/dsh-tools/lib/index.js:2798` | ✅ |
| 3 | `systemPrompt` | `@deepseek-ai/dsh-system-prompt/lib/index.js:226` | ✅ |
| 4 | `sessionController` | `@deepseek-ai/dsh-api-session-controller/lib/index.js:2952`(`super(ctx, "sessionController", { namespace: "session" })`) | ✅ |
| 5 | `sessions` | `@deepseek-ai/dsh-session/lib/index.js:1739` | ✅ |
| 6 | `sessionTitle` | `@deepseek-ai/dsh-session-title/lib/index.js:214` | ✅ |
| 7 | `workspaceRegistry` | `@deepseek-ai/dsh-workspace/lib/index.js:376` | ✅ |
| 8 | `connection` | `@deepseek-ai/dsh-client-connection/lib/index.js:710`(`HostConnectionService`,注释原文 "Host Connection service") | ✅ |
宿主服务全集共 **88 个**(清单见 `.scratch/p0/host-services.txt`),包括 `agentPresets` `agents` `approval` `attachments` `compaction` `goals` `jobs` `schedule` `skills` `tokenMeter` `shellEnv` `agentTeams` `workflowEngine` 等。
### 5.2 软依赖也全部命中
ds-bot 除 8 个硬依赖外,还用 `ctx.inject([...])` 挂可选能力,全部存在:
| 位置 | 软依赖 | 宿主 |
| --- | --- | --- |
| `capabilities.js:320` | `inject: ['skills']` | ✅ |
| `schedules.js:97` | `ctx.inject(['schedule'], attach)` | ✅ |
| `steer.js:22` | `ctx.inject(['jobs'], attachJobs)` | ✅ |
| `tools.js:1114` | `ctx.inject(['goals'], attachGoals)` | ✅ |
另有 `ctx.get(...)` 取 `agentPresets` / `agents` / `attachments` / `compaction` / `shellEnv` / `tokenMeter`,均存在。
把 ds-bot 里所有 `ctx.<name>` 与 `ctx.get('<name>')` 做全集差集,**未命中的只有 cordis `Context` 自身成员**(`on/get/inject/effect/fiber/plugin/reflect/logger/origin/complete`)与局部变量 `session`,**没有缺失的业务服务**。
### 5.3 方法级比对(调用点 → 宿主实现)
| ds-bot 调用 | 宿主实现 | 形状 |
| --- | --- | --- |
| `src/host/agents.js:40` `ctx.sessionController.create({ workspaceId })` | `api-session-controller/lib/index.js:3090` `create(request)` | 返回 `{ sessionId, agentPreset? }` ✅ |
| `src/host/usage.js:411` `(await ctx.sessionController.list({}, signal)).items ?? []` | 同文件 `:3061` `async list(_request, signal)` → `{ items: [...] }` | ✅(**注意**:同文件 `:1959` 的 `async list(signal)` 返回裸数组,那是内部 `ApiSessionList` 路径,**不是服务方法**,勿混淆) |
| `src/host/chat-index.js:58`、`src/host/parts.js:1640/1653` `page({...})` | `:3262` `page(request, signal)` | ✅ |
| `src/host/usage.js:361` `projections({ sessionId }, signal)` | `:3281` `async projections(request, signal)` | ✅ |
| `src/host/channel.js:719` `prompt({...})` | `:3218` `async prompt(request, signal)` | ✅ |
| `src/host/delivery.js:11` `resolveAgent(sessionId)` | `:3037` `resolveAgent(sessionId)` | ✅ |
| `src/host/models.js:231` `selectModel({...})` | `:3098` `selectModel(request)` | ✅ |
| `src/host/agents.js:100`、`roster.js:97/412/600` `ctx.sessionTitle.rename(session, title)` | `dsh-session-title/lib/index.js:295` `rename(session, title)`(另 `refresh:319`、`register:358`) | ✅ |
| `src/host/channel.js:754`、`src/host/feed.js:90` `ctx.connection.fetch.register({...})` | `HostConnectionService` 的 `get fetch() { return { register: (route) => this.registerFetchRoute(route) } }` | ✅ |
**结论:8 个 inject 服务全部存在,被调用的方法签名与返回形状逐项对齐,未发现硬性 API 缺失。**
### 5.4 client 半边(前端)
- `client.js` 1,712,874 字节,首行注释 `// Generated from src/client by npm run build`,格式 `window.__ModuleLoader__.load({ id: 'ds-bot', factory: (require) => ... })`。
- 硬 require `@deepseek-ai/dsh-client-ui-primitives`(见 `src/client/dsh-primitives.js`)。
- 该包**在 `app.asar` 里没有磁盘实体**(按路径 grep 0 命中),但宿主自带 client 插件(`dsh-client-locale`、`dsh-client-shortcuts`、`dsh-client-ui-approval` 等)同样 require 它并作为 `0.2.1-rc.5` 依赖 → 它是前端 `__ModuleLoader__` 提供的**虚拟共享模块**,ds-bot 用同一机制即可解析。
- ds-bot 对它做了**特性探测**而非硬假设:`src/client/user-message.js:250` 附近 `canDrawUserMessages = () => typeof ui.projectUserText === 'function'` —— 宿主缺该 API 时会降级,不会崩。
- 另有字符串常量 `VOICE_BUNDLE = "@deepseek-ai/dsh-experimental-voice-input-bundle"`(`src/client/speech.js`),该 bundle 在宿主包列表中存在。
---
## 6. npm registry:**已发布,无需本地 tarball**
`node npm-fetch.mjs https://registry.npmjs.org/ds-bot` → **HTTP 200,81,795 字节**。
| 项 | 值 |
| --- | --- |
| `dist-tags` | `{"latest": "0.3.2"}` |
| 已有版本 | `0.0.0-stage`、`0.1.0`–`0.1.7`、`0.2.0`–`0.2.7`、`0.3.0`、`0.3.1`、`0.3.2` |
| `0.3.2` 发布时间 | **2026-11-09T09:56:14.583Z**(registry `created` 2026-10-10T15:48:38.408Z,`modified` 2026-11-09T09:56:14.958Z) |
| tarball | `https://registry.npmjs.org/ds-bot/-/ds-bot-0.3.2.tgz` |
| integrity | `sha512-M+Wn55IOjy8T54JY6OS3RqOuuaKX72B7lRZ7DK/y2DzkGEXXtNGmf4lqKUSVaY+ecWnByFv/a3uWVW0/Zc/1SA==` |
| shasum | `909d3ee37acd3c3b89163725c040f6840368db53` |
| 体积 | `fileCount 122`,`unpackedSize 3,936,182` |
| registry 元数据中的 `peerDependencies` / `dsh` | 与本地 source **完全一致** |
### 6.1 本地 tarball 与 npm tarball **不是同一份**
`.scratch/p0/dsbot-8e0013e077eaeccc137327956e18425e73a5bb8c.tar.gz`(6,101,133 字节)是 **GitHub commit 归档**:顶层目录 `DS-Bot-<sha>/ds-bot/`,含 `dev/`、`test/`、`package-lock.json`。
npm 包只发 `files` 白名单(`index.js`、`src/host/`、`src/shared/`、`src/office/`、`client.js`、`office.js`、`web-search.js`、`cordis.patch.yml`、`README.md`、`LICENSE`),122 个文件 / 3.9 MB。
→ **优先走 npm registry**;本地 tarball 仅在完全离线时作后备(此时走 `pnpm add file:...` 或 vendor 目录 + `link:`,见附录 A.2)。
### 6.2 exports 面(决定 cordis 能否按子路径挂载)
`package.json`:`"type": "module"`、`"main": "index.js"`、`exports` 键 = `.` / `./client` / `./web-search` / `./package.json`。
对应 `cordis.patch.yml` 里 `name: ds-bot/web-search` 的子路径加载,以及 browser 半边通过 `./client` 发现。**三者在本机均可解析**(`web-search.js`、`client.js`、`index.js` 均在包内)。
---
## 7. profile 变更点(参照已装插件 manifest)
### 7.1 三个 manifest 对照
| 字段 | `dsh-image-gen@0.9.3` | `dsh-better-sidebar@0.28.2` | `ds-bot@0.3.2` |
| --- | --- | --- | --- |
| `dsh.bundle.patch` | `./cordis.patch.yml` | `./cordis.patch.yml` | `./cordis.patch.yml` |
| `dsh.client.platform` | `web` | `web` | `web` |
| `dsh.client.inject` | 8 个 client 包(含 `dsh-client-ui-settings`、`dsh-client-ui-settings-plugins`、`dsh-client-ui-sidebar-right`…) | 5 个 client 包(`dsh-client-locale/ui-slots/ui-conversation/ui-sidebar-right/client-modules`) | **无该数组** |
| `manifestVersion` | 未声明 | `1` | **未声明** |
| `peerDependencies` | — | `^0.2.1-rc.1` / `^4.0.5` 真实区间 | 全部 `*` |
**判定**:`ds-bot` 的 `dsh` 字段结构与 `dsh-image-gen` 同类(有 `bundle.patch` + `client.platform`,无 `manifestVersion`),而 image-gen 在本机正常工作 → **manifest 层不构成阻断**。`client.inject` 缺省表示它自带完整的 client 依赖解析策略(其 `client.js` 是预打包的单文件,由 `__ModuleLoader__` 注入宿主 client 模块),与 better-sidebar 显式声明注入是两种合法风格。
### 7.2 官方安装通道(profile 文件不必手改)
`dsh-better-sidebar/cordis.patch.yml` 头部注释原文(该注释同时是 DSH 插件分发机制的官方说明):
> 安装 CLI 为 `dsh plugin --profile <name> add dsh-better-sidebar@<version>`。该命令 "reconciles `dsh.profile.bundles` against installed packages and, seeing this declaration, appends … to the bundle stack. The profile boot then merges THIS patch … **No profile file edits needed — one command installs and mounts.**"
并且明确警告:
> "If the profile still carries the old manual mount line in its own `cordis.patch.yml`, remove it before switching to the bundle channel to **avoid double-mounting**."
本机 CLI 实测(`--help`,只读):
```
$ "<...>/resources/runtime/cli/bin/dsh.cmd" plugin --help
Usage: dsh plugin [options] [args...]
manage a profile's plugins by forwarding the remaining arguments to pnpm in the
profile directory
Arguments: args pnpm arguments, forwarded verbatim (add <pkg>, remove <pkg>, why <pkg>, ...)
Options: --profile <name> the profile whose plugins to manage (initialized on first use)
```
→ `dsh plugin` = **在 profile 目录里跑 pnpm**,bundle 列表由宿主在 profile 启动时按 `dsh.bundle` 声明对账。
### 7.3 具体变更点
| # | 位置 | 变更 | 是否需要手改 |
| --- | --- | --- | --- |
| 1 | `profiles/desktop/package.json` → `dependencies` | 增加 `"ds-bot": "0.3.2"` | 否,`dsh plugin add` 代劳 |
| 2 | `profiles/desktop/package.json` → `dsh.profile.bundles` | 追加 `"ds-bot"` | 否,启动时对账(当前 38 条,最后一条是 `dsh-sansheng-liubu-workbench`) |
| 3 | `profiles/desktop/cordis.patch.yml` | **不需要 insert**:ds-bot 自带的 patch 已经 `insert: [{id: bot, name: ds-bot}, {id: web-search-auto, name: ds-bot/web-search}]` | 否(手改反而会双挂,见 §7.5) |
| 4 | `node_modules/` | 新增 `ds-bot` 及其 runtime 依赖 | 自动 |
ds-bot 自带 `cordis.patch.yml`(25 行,4 段)的完整语义:
```yaml
- insert:
- id: bot
name: ds-bot
- id: web-search-auto
name: ds-bot/web-search
- id: web
config:
searchProvider: auto
fetchProvider: http
- id: ui-settings-general
disabled: true
```
(第 11–15 行注释警告:**配置覆盖是整段替换**,所以 `fetchProvider` 必须重述;若 profile 层另外指定 `searchProvider: exa|perplexity|deepseek-official`,则本段失效;而单独关掉 `web-search-auto` 会让每次 `web_search` 都失败。)
### 7.4 与本机现有 profile patch 的冲突分析
`profiles/desktop/cordis.patch.yml`(23,489 字节,profile 层,**最后应用**)现有相关条目:
| 行 | 条目 | 内容 |
| --- | --- | --- |
| :27–30 | `ui-settings` | `name: @deepseek-ai/dsh-client-ui-settings`,`config.enabled: false` |
| :31 | `dsh-better-sidebar-plugin-office` | `disabled: true` |
| :35 | `better-sidebar` | `disabled: false` |
| :37–40 | `image-gen` | `disabled: false`,`config.provider: dashscope` |
对 ds-bot 三段覆盖的逐段核对:
| ds-bot 覆盖 | 本机 profile 层是否已有同名 id | 结论 |
| --- | --- | --- |
| `- id: web`(`searchProvider: auto` / `fetchProvider: http`) | **无** `- id: web` 条目 | ✅ 不冲突,会生效(web 的搜索供应商将从宿主默认变为 `auto`) |
| `- id: ui-settings-general`(`disabled: true`) | **无** 该 id(注意 profile 的 `ui-settings` 是**另一个** id:`@deepseek-ai/dsh-client-ui-settings`) | ⚠ 会**新生效**:宿主原生「通用设置」页被关掉,由 DS Bot 的设置壳接管 |
| `- id: web-search-auto`(insert) | 无 | ✅ 不冲突 |
| `- id: bot`(insert) | 无 | ✅ 不冲突 |
关于 `ui-settings-general`:宿主侧它是真实存在的插件包 `@deepseek-ai/dsh-client-ui-settings-general`(asar 内命中,含独立 LICENSE/包目录)。本机**已经**把 `ui-settings`(`dsh-client-ui-settings`)的 `config.enabled` 设为 `false`,方向上与 ds-bot 的做法一致,故**冲突面很小**;但语义要清楚:装 ds-bot 后,**原生设置抽屉的「通用」页会消失**,改由 Bot 的 Settings 对话框渲染。
已装 38 个插件中**没有任何一个**的 `cordis.patch.yml` 引用 `ui-settings-general`(`grep -rl ui-settings-general --include=cordis.patch.yml .` 在 profile `node_modules` 下 0 命中),因此不存在"别的插件往这个设置页挂面板、被 ds-bot 一并关掉"的连带损失。
### 7.5 双挂载陷阱(必须避免)
- 若既用 `dsh plugin add ds-bot`(→ 进 `dsh.profile.bundles`),**又**在 profile 的 `cordis.patch.yml` 手写 `- insert: [{id: bot, name: ds-bot}]`,`bot` 会被实例化两次 → 两套 `web-search` 路由、两个 settings 座位,`connection.fetch.register` 可能触发重复路由注册。
- 正确姿势:**只用一个通道**。本机建议走 bundle 通道(CLI),profile patch 保持不动。
---
## 8. 风险清单与最小补丁
按"是否阻断安装"排序。**无阻断项。**
| # | 级别 | 风险 | 证据 / 说明 | 最小补丁 |
| --- | --- | --- | --- | --- |
| R1 | 中 | **版本漂移**:宿主 0.2.1-rc.5 < ds-bot 自测基线 0.2.2-rc.1(低一个 rc) | `README.md:7` "Tested with dsh `0.2.2-rc.1` (Web and Desktop)";peerDeps 全 `*` 无闸门 | 已用 §5 的服务/方法比对覆盖;残留面是 client 半边(1.7 MB 预打包 JS)对虚拟模块 `dsh-client-ui-primitives` 的运行时假设,只能靠实际启动验证 |
| R2 | 中 | **web 搜索行为改变**:`- id: web` 被覆盖为 `searchProvider: auto` + `fetchProvider: http` | ds-bot patch:16–19;配置覆盖是**整段替换** | 装后若 `web_search` 报错:在 profile patch 里加 `- id: web / config: {searchProvider: <原值>, fetchProvider: <原值>}`(profile 层最后应用,优先于 bundle 层) |
| R3 | 中 | **原生设置页被接管**:`ui-settings-general` 被 disable | ds-bot patch:24–25;宿主包 `@deepseek-ai/dsh-client-ui-settings-general` | profile patch 加 `- id: ui-settings-general / disabled: false`;同时需接受 DS Bot settings shell 与原生壳并存 |
| R4 | 高(人为) | **双挂载**:bundles + 手写 insert 并存 | §7.5 | 只用 CLI;若已手写,删除 profile patch 中的 `bot` insert |
| R5 | 高(人为) | **peer 自动安装**:若把 `autoInstallPeers` 改 true,会装出第二份 cordis / dsh-*(npm 上 `cordis@latest=4.1.0`、`dsh-llm@latest=0.0.1-rc.1` stub) | `pnpm-workspace.yaml: autoInstallPeers: false`;npm dist-tags 实测 | 保持 `autoInstallPeers: false`;`pnpm why @deepseek-ai/cordis` 应只指向宿主 |
| R6 | 中 | **宿主 nightly 自动升级**:升到 0.2.2+ 后 ds-bot 的 API 假设可能变化(也可能变好) | `app-update.yml: channel: nightly` | 升级后复跑本报告 §5 的比对脚本;升级前在插件市场禁用 ds-bot |
| R7 | 低 | **profile 体量**:已 36 deps / 38 bundles,ds-bot 再引入 122 文件 | — | 装后 `du -sh node_modules/ds-bot` 记录增量 |
| R8 | 低 | **网络**:curl/git https 不可用 | 本次 `node fetch` 成功 → registry 可达,pnpm 应可用;若 pnpm 走代理失败,退回本地 tarball(附录 A.2) | — |
| R9 | 低 | **无类型层证据**:asar 内 0 个 `.d.ts` | §2.3 | 结论强度按 JS 源码计;建议装后用 `dsh plugin --profile desktop why ds-bot` + 启动日志核验 |
| R10 | 低 | **web-search 的密钥路径**:`searchProvider: auto` 走"当前会话路由自带的 key",否则无 key 的结果页兜底 | ds-bot patch:6–9、README "Web search" | 若所在会话用第三方 provider,auto 可能取不到 key → 显式配 `deepseek-official` |
### 8.1 需要的最小补丁(若安装后出问题)
按症状对症,改动都发生在 **profile 层**(最后应用,可覆盖 bundle 层),不动 ds-bot 包本身:
| 症状 | 补丁(追加到 `profiles/desktop/cordis.patch.yml`) |
| --- | --- |
| 每次 `web_search` 都失败 | `- id: web-search-auto` / `disabled: true`,**并且**给 `- id: web` 配一个非 `auto` 的 `searchProvider`(两者必须同时做,见 ds-bot patch:13–15 的警告) |
| 设置页消失不可接受 | `- id: ui-settings-general` / `disabled: false` |
| 想整体停用但不卸载 | 在插件市场禁用,或 profile patch 加 `- id: bot` / `disabled: true`(保留 bundles 中的记录) |
---
## 9. 回退方案(禁止批量备份目录)
### 9.1 原则
- **不建备份目录、不复制 `node_modules`、不 `cp -r` profile。**
- 优先用版本控制与包管理器自身的可逆操作。
- 本项目仓库(`C:\Users\qyh15\三省六部`)只跟踪 `docs/p0/*` 这类文档与大文件清单;**profile 不在本仓库内**,因此 profile 侧的回退靠"装之前只留 1 个 `.bak`"。
### 9.2 安装前的唯一允许备份(若决定手改而不是走 CLI)
只有在你**放弃 CLI、选择手工编辑**时,才需要:
```bash
cd /c/Users/qyh15/.dsh/profiles/desktop
cp package.json package.json.bak # 单个文件
cp cordis.patch.yml cordis.patch.yml.bak # 单个文件
```
共 **2 个 `.bak`**,都是单文件、同目录、无目录复制。走 `dsh plugin add` 时**连这两个都不需要**(pnpm 自己维护 `pnpm-lock.yaml`,且 bundles 可随时重算)。
### 9.3 回退步骤(推荐路径:CLI 安装)
```bash
# 1) 卸载包(forward 给 pnpm remove)
"<...>/resources/runtime/cli/bin/dsh.cmd" plugin --profile desktop remove ds-bot
# 2) 重启 DSH Desktop(宿主启动时按已装包重新对账 dsh.profile.bundles,ds-bot 条目自动消失)
# 3) 校验:两处都不应再出现 ds-bot
grep -n "ds-bot" /c/Users/qyh15/.dsh/profiles/desktop/package.json # 期望无输出
grep -n "ds-bot" /c/Users/qyh15/.dsh/profiles/desktop/cordis.patch.yml # 期望无输出
```
### 9.4 回退步骤(手工安装路径)
```bash
cd /c/Users/qyh15/.dsh/profiles/desktop
cp package.json.bak package.json # 覆盖回原样:dependencies + bundles 一起复原
cp cordis.patch.yml.bak cordis.patch.yml # 仅在手工改过 patch 时
# 然后用 profile 自带的 pnpm 重装依赖
pnpm install --frozen-lockfile || pnpm install
```
### 9.5 回退后的验收清单
| 检查 | 期望 |
| --- | --- |
| `package.json` 的 `dsh.profile.bundles` 条数 | 回到 **38** |
| `package.json` 的 `dependencies` 条数 | 回到 **36** |
| `node_modules/ds-bot` | 不存在 |
| 宿主启动日志 | 无 `bot` / `ds-bot` 相关报错 |
| `ui-settings-general` | 设置页恢复(若曾因此消失) |
| `web_search` | 行为回到装前(若曾覆盖 `- id: web`) |
---
## 10. 结论
1. **宿主 DSH = 0.2.1-rc.5**(asar `dsh/package.json` + exe VersionInfo 双证)。
2. **5 个 peerDeps 逐项 satisfied**,但区间全是 `*`,不构成任何版本保障;5 个包由宿主 asar 提供,profile 不应也不需安装,**必须保持 `autoInstallPeers: false`**。
3. **8 个 inject 服务 8/8 存在**,被调用的 9 处方法(`create` / `list` / `page` / `projections` / `prompt` / `selectModel` / `resolveAgent` / `rename` / `connection.fetch.register`)签名与返回形状全部对齐;软依赖 `skills` / `schedule` / `jobs` / `goals` 也齐备。
4. **npm 已发布 `ds-bot@0.3.2`**(latest,2026-11-09T09:56:14Z,integrity 已记录),**无需本地 tarball**;本地 6.1 MB 包是 GitHub 归档,与 npm 包不同源。
5. **推荐安装方式**:`dsh plugin --profile desktop add ds-bot@0.3.2`(一条命令完成依赖 + bundles 对账,**不手改 profile 文件**)。
6. **风险可控**:无阻断项;需人为守住的是 R4(双挂载)与 R5(peer 自动安装),需产品层面确认的是 R2(web 搜索切 `auto`)与 R3(原生设置页被接管)。
7. **回退成本低**:`dsh plugin remove ds-bot` + 重启即可;手工路径最多 2 个单文件 `.bak`,不产生备份目录。
---
## 附录 A:安装命令草案(**本次未执行**)
### A.1 registry 路径(推荐)
```bash
# 版本固定,避免 latest 漂移
"/c/Users/qyh15/AppData/Local/Programs/DeepSeek Harness/resources/runtime/cli/bin/dsh.cmd" \
plugin --profile desktop add ds-bot@0.3.2
# 校验
"/c/.../runtime/cli/bin/dsh.cmd" plugin --profile desktop why ds-bot
grep -n '"ds-bot"' /c/Users/qyh15/.dsh/profiles/desktop/package.json
```
> `dsh.cmd` 只能写全路径调用(git bash 的 `PATH` 里虽有该 bin 目录,但只有 `.cmd` 后缀,直接敲 `dsh` 报 `command not found`)。
### A.2 离线 / 本地 tarball 路径(仅在 registry 不可达时)
```bash
# 方案 1:直接装本地包(含 dev/test,比 npm 包大)
"/c/.../runtime/cli/bin/dsh.cmd" plugin --profile desktop \
add file:/c/Users/qyh15/三省六部/.scratch/p0/dsbot-8e0013e077eaeccc137327956e18425e73a5bb8c.tar.gz
# 方案 2:vendor 目录 + link:(保持可编辑,便于打最小补丁)
# 1. 解包到 C:\Users\qyh15\.dsh\vendor\ds-bot\ (该目录同时含 package.json 与 client.js)
# 2. package.json 的 dependencies 写 "ds-bot": "link:../../ds-bot"
# 3. pnpm install
```
风险:`link:` 会让宿主加载工作副本,改动即生效,但也**绕过了 integrity 校验**;仅在离线应急时使用,并把 commit `8e0013e0` 记录在案。
### A.3 安装后立即验证(建议脚本化)
1. 宿主启动日志无 `bot` 相关 error;
2. 打开 Web GUI(`http://127.0.0.1:8457`),侧边栏出现 DS Bot 座位;
3. 触发一次 `web_search`,确认走 `auto` 未失败;
4. 打开一次会话,确认 `sessionController.create/list` 正常(新建会话、历史列表);
5. 确认原生设置「通用」页状态符合预期(被接管 or 已用补丁恢复)。
---
## 附录 B:证据文件清单(`.scratch/p0/`,未纳入提交)
| 文件 | 来源 |
| --- | --- |
| `host-package.json` | asar `dsh/package.json`(17,168 字节有效 JSON;解出文件尾部有重复拼接,解析时按偏移截断) |
| `asar-index.txt` | asar 18,234 条目清单 |
| `core-pkgs.txt` | 307 个 `@deepseek-ai/*` 包名 |
| `host-services.txt` | 宿主 88 个 cordis 服务名 |
| `api-session-controller.js` | `@deepseek-ai/dsh-api-session-controller/lib/index.js`(3,368 行) |
| `session-title.js` | `@deepseek-ai/dsh-session-title/lib/index.js`(652 行) |
| `client-connection.index.js` | `@deepseek-ai/dsh-client-connection/lib/index.js` |
| `core/*.README.md` | `dsh-llm` / `dsh-tools` / `dsh-web` / `dsh-scope` 的宿主内置 README |
| `asar-read.cjs` / `asar-grep.cjs` / `npm-fetch.mjs` | 取证脚本 |
| `DS-Bot-8e0013e0.../ds-bot/` | 上游固定 commit 解包源码 |
| `dsbot-8e0013e0....tar.gz` | GitHub commit 归档(6,101,133 字节) |