# 效果与复杂度量化

两层数字：**插件路径**全部是本机实测（`node test/benchmark.mjs`，2026-10-27 复测；网络型数字随线路波动，标注区间）；**手工路径**取自 2026-10-18 那次真实安装过程里记录到的耗时/输出，标注为实测的就来自日志或终端计时，标注为估算的按页面对比估算。

复现插件侧数字：

```sh
node test/benchmark.mjs
```

> 复现注意：若本机继承了 `DSH_PROFILE_DIR` / `DSH_PROFILE`（DSH 只为模型 shell 注入这两个变量），安装编排会去哈希真实已装包，把 install 行从约 60 ms 抬到 1–2.5 s；跑之前清空它们。沙箱里默认缓存目录不可写时，另设 `DSH_HOME` 指向可写目录。

## 1. 插件路径实测（决策链，不含 pnpm 真正下载安装）

2026-10-27 三次运行的代表值（网络型行给出三次区间）：

| 任务 | 工具调用 | 耗时 | 网络请求 | 返回给模型的文本 |
|---|---|---|---|---|
| 目录冷加载（npm 载体） | `plugin_search` | 1,471 ms（3 次：1.47–5.58 s） | 2 | 931 B |
| 同名歧义搜索 | `plugin_search` | 19 ms | 0 | 2,028 B |
| 目录命中缓存 | `plugin_search` | 18 ms | 0 | 2,017 B |
| 同名歧义解析 | `plugin_resolve` | 20 ms | 0 | 2,446 B |
| 按 `engines.dsh` 选版本 | `plugin_resolve` | 123 ms（3 次：0.12–0.53 s） | 1 | 241 B |
| 跨 peer 线选版本（跳过 0.28.1 / 0.28.0） | `plugin_resolve` | 123 ms（3 次：0.11–0.26 s） | 1 | 973 B |
| GitHub 源码安装计划 | `plugin_resolve` | 20 ms | 0 | 438 B |
| 安装编排 + 安装后校验 | `plugin_install` | 63 ms*（3 次：0.06–0.11 s） | 1 | 1,314 B |
| 已装插件盘点 | `plugin_status` | 1 ms | 0 | 246 B |
| **合计** | **9 次调用** | **1.86 s**（3 次：1.86–6.57 s，冷加载主导） | **5 次请求** | **10.4 KiB** |

\* 63 ms 只覆盖解析 + 调 `installBundle` + 回读校验；真正 pnpm 安装时间由插件管理器独占（镜像上一次 170 包的安装实测 13.4 s，2026-10-18）。

## 2. 同一件事的手工路径 vs 插件路径

以"装一个名字有歧义的插件 + 一个 GitHub-only 插件"为例（手工侧取自 2026-10-18 会话日志）：

| 环节 | 手工（2026-10-18 会话实测） | 插件（2026-10-27 实测） | 缩减 |
|---|---|---|---|
| 获取插件目录 | GitHub Pages 拉 **8.78 MB**（2026-10-27 实测；2026-10-18 为 6.4 MB）/ 那次 **91.06 s**；模型还要读大量条目 | npm 载体 2 个请求 / **1.5 s**（3 次：1.47–1.62 s，一次网络抖动 5.58 s） | 目录内容不进模型上下文；91 s 属当时线路，本机已不可复现 |
| 同名候选消歧 | 打印约 60 条中英双语条目（约 20 KB）后人工挑 | 1 次调用，2.0 KB，带 owner/星数/npm 名/install 命令 | 输出体积 **约 10×** 更小，决策 1 步 |
| 版本兼容判定 | 手工对着 35 个已发布版本推 semver；中途写错过"哪些 peer 算内核约束"（靠单测才抓出来） | **0.12 s**，自动降级并列出被跳过版本及原因 | 1 次调用，**0 次试错** |
| 安装 | 直连 npmjs **两次 90.1 s 超时**（90,103 ms / 90,145 ms），换镜像后 13.4 s 成功 | 自动走 `pluginRegistryProbe.fastest()`，**13.4 s 一把过** | 省 **约 180 s / 2 次失败** |
| GitHub-only 源码安装 | 下载 2 s + `pnpm install` 113 s + build 9 s + 扩展安装 6.7 s + 构建 ~2 s，外加 5+ 个分步决策与一次装错依赖的返工 | 同一条流水线收进 1 次 `plugin_install`（约 140 s，主要是不可压缩的编译时间） | 决策步骤 **5+ → 1**，失败点内聚 |
| 安装后校验 | 额外 2 次探测：`/ext/bridge-config` HTTP + GUI boot 清单 | 同一调用内回读 loader entry / bundle / client table，**0 次额外调用** | 2 → 0 |
| 读文档 | 2 个 dshbase 页面 ≈ 60 KB 文本（估算） | 目录里一行摘要（< 1 KB） | 约 **60×** 上下文体积 |
| **合计** | **约 45 次工具调用**、**约 20–25 分钟**（含试错与重启折腾）、**3–4 次失败/返工** | **约 6 次调用**、决策链 **约 1.9 s** + 不可压缩安装/编译 ≈ **3 分钟**、**0 次失败** | 调用 **−87%**，时间 **−80% 以上**，失败 **→ 0** |

> 口径说明：手工的 91 s / 90 s×2 / 13.4 s / 113 s / 6.7 s 都是本机日志或计时器实测（2026-10-18）；45 次调用与 20–25 分钟是按那次会话记录统计的近似值；60 KB 的文档体积为估算。插件侧网络型数字于 2026-10-27 复测，随线路波动。

## 3. 复杂度从哪来、被收进哪里

手工路径要求模型（或人）当场掌握 9 类领域知识，每一类都可能单独出错：

1. 目录从哪来、结构是什么、同名如何区分
2. npm registry 文档结构、怎么拿全部版本与 peer
3. semver 的 `includePrerelease` 语义与 caret 跨 minor 的陷阱
4. 哪些 `@deepseek-ai/*` peer 才算内核版本约束（cordis/schemastery 不算），以及宿主"有 `engines.dsh` 就只看它"的规则
5. 区域网络：npmjs 慢、要选镜像、要与安装器的 registry 参数对上
6. `dsh plugin` 安装路径 / generation 安装语义 / 何时 restart-required
7. GitHub-only 仓库不提交 `lib/`，必须先构建再 `link:` 注册
8. 安装后如何判断真的生效（loader entry、bundle、client boot 表）
9. 哪些失败是"等一下重试"、哪些是"永远装不上"

这些现在被固化在约 **2,060 行**代码里（下表五类合计约 1,800 行）：

| 文件 | 行数 | 承担的知识 |
|---|---|---|
| `logic/semver.js` | 227 | 第 3 条：版本比较 + range 求值（含 `-0` 上界语义） |
| `logic/catalog.js` | 281 | 第 1 条：目录获取/缓存/检索/歧义检测 |
| `logic/resolve.js` | 417 | 第 2、4、7 条前半：registry 读版本、宿主预检对齐、GitHub spec 解析 |
| `logic/install.js` | 421 | 第 6、7、8 条：安装编排、源码构建、安装后校验 |
| `logic/api.js` + `host/register.js` | 459 | 工具面、输出格式、可热加载边界 |

并有 **35 条离线单测 + 10 条宿主无关 harness 检查**（`npm test`，共 45 项，含"同名歧义不得猜""跳过不兼容版本""兼容判定与宿主预检一致""已加载插件不得假装热换"这类回归）。也就是说：同样的判断，从"每次会话重新推一遍、推错就重来"变成"写一次、测住、以后每次 1 次调用"。

## 4. 插件不能压缩的部分（诚实边界）

- **pnpm 下载与编译时间**是物理成本：镜像安装仍要 ~13 s，源码构建仍要 ~2 分钟。插件省的是决策、试错、验证与上下文，不是 CPU/带宽。
- **替换已加载插件**仍要重启宿主（`restart-required`）：这是 loader 模块缓存 + 打包宿主没有 Node 内部 loader 的硬边界，插件如实报出来，不伪装成功；**新增 bundle** 则以插件管理器的应用结果为准（就地应用不报 restart-required，带 client 半时提示刷新 GUI）。
- **同名歧义**仍需要一次人类/上层的选择（`owner=`），插件故意不猜。
- 目录是社区维护的第三方列表，插件只保证"按声明来源装对版本"，不做安全审计。