dsh-db-tool 0.1.8 → 1.2.0

package/docs/dsh/346/217/222/344/273/266/351/227/256/351/242/230/350/247/243/345/206/263/346/226/271/346/241/210-20260928.md

@@ -0,0 +1,166 @@
+# dsh 插件问题解决方案
+
+- **日期**：2026-09-28
+- **目标 profile**：`C:\Users\ASUS\.dsh\profiles\web`（原记录文档中的 `C:\Users\Sjc\...` 为当时的记录口径，本机实际用户目录为 `C:\Users\ASUS`）
+- **原问题记录**：[dsh插件安装问题记录-20260928.md](./dsh插件安装问题记录-20260928.md)（问题现象、完整排查过程与全部 14 项问题清单见该文档）
+- **环境**：Windows 11 + Git Bash；Node v24.19.0；dsh 0.1.7-rc.2；pnpm 12.6.0；内网 registry `http://10.192.2.173:8081/repository/group-npm/`
+
+---
+
+## 一、问题 1 根因官方定论（dsh-db-tool 加载失败）
+
+### 官方语义依据
+
+Node.js 官方文档（[Modules: CommonJS modules — require.resolve.paths(request)](https://nodejs.org/api/modules.html)）明确规定：
+
+> `require.resolve.paths(request)`
+> Returns:
+> - `<string[]> | null`
+>
+> Returns an array containing the paths searched during resolution of `request` or **`null` if the `request` string references a core module, for example `fs` or `node:fs`**, or **if the request is a relative or absolute path identifier**（即以 `/`、`./`、`../` 开头的请求）.
+
+即：**当 request 引用 core module（`fs`、`node:fs` 等）或以 `/`、`./`、`../` 开头的路径时，`resolve.paths` 必然返回 `null`**——这不是边界情况，而是文档写明的正常返回值。
+
+### 缺陷位置
+
+原记录所指缺陷形态（无空值保护的 `resolve.paths` 迭代）在 `@deepseek-ai/dsh-app-boot/lib/index.js` 中有多处。**0.1.7-rc.2 实测现状**：
+
+```js
+// 原始缺陷形态（无保护，for..of 对 null 迭代即抛 TypeError）：
+for (const searchPath of createRequire(parent).resolve.paths(name)) {
+```
+
+- `L1422-1429`（`routeScoped` 内）：**已于 2026-09-25 被打入一份 local hotfix**（fallback 到 `_nodeModulePaths`），语义上已挡住该路径的崩溃，原堆栈中的 `1422:58` 即修复前的这里；
+- **`L1247`（`nativePackageDir`）：与上述缺陷形态逐字相同、无保护，即本次修复对象**；
+- 另有 `L1482`、`L2026`、`L3270` 三处同类无保护调用（属同类隐患，归上游 issue 一并加固，本次不动）。
+
+该形态**无空值保护**（对比同项目 `profile.ts:596` 的同类调用带 `?? []` 兜底）。凡 core module 或相对/绝对路径请求流经此处，对 `null` 做 `for...of` 迭代即抛出。
+
+### 原错误堆栈（摘自原记录文档）
+
+```
+TypeError: createRequire.resolve.paths is not a function or its return value is not iterable
+    at ResolutionRouter.routeScoped (.../dsh-app-boot/lib/index.js:1422:58)
+    at ResolutionRouter.routePath (...:1554)
+    at Module.wrappedFilename [as _resolveFilename] (...:1771)
+```
+
+### 触发链（四层因果摘要）
+
+1. dsh 为实现 profile 感知解析，改写 CJS 的 `Module._resolveFilename`，**每个模块请求**都流经被改写解析路径上的 `resolve.paths` 调用（含本次缺陷行 `L1247`）；
+2. `mongodb@7.6.0` 为**无 `exports` 字段的老式布局**（132 个 js 文件），`selfReferenceName()` 不短路，内部请求全部进入缺陷路径；请求 core module（如 `fs`）时 `resolve.paths` 返回 `null` → 崩溃（`bson@7.3.3` 有 exports，不触发）；
+3. db-tool 的加载链 `dist/guard/index.js:10` 对 mongodb 适配器做了静态导入，**加载插件必然加载 mongodb**；
+4. dsh 启动审计吞掉原始异常，只打印 `failed to import`，无堆栈线索。
+
+---
+
+## 二、三层处置
+
+### ① 宿主最小修复（host-fixer 已执行完成，2026-09-28）
+
+- 位置：`@deepseek-ai/dsh-app-boot/lib/index.js:1247`（`nativePackageDir`）
+- 改法：`createRequire(parent).resolve.paths(name)` 后补 `?? []`（与同项目 `profile.ts:596` 的既有模式一致），一行最小改动，语义与 Node 官方文档的 `null` 返回约定对齐。
+- **与既有 hotfix 的关系**：`L1422-1429` 已存在另一份 local hotfix（fallback `_nodeModulePaths`，2026-09-25 打入），本次未触碰，两者共存。
+- **patch 留档**：`C:\Users\ASUS\.dsh\profiles\web\.backup-20260928\dsh-app-boot@0.1.7-rc.2-resolve-paths-fix.patch`（含修改前后对照与重放说明）。
+- **重放说明**：该文件位于全局 npm 包 `@deepseek-ai/dsh` 内，**dsh 全局升级会覆盖此修改**。每次升级 dsh 后需重放 patch（含 2026-09-25 的 L1422 那份），直至上游根治版本发布。
+- **产品化更新（2026-09-28）**：上述两处宿主修复已并入插件分发流程——其他电脑装好插件后运行 `npm run patch:dsh`（macOS/Linux 用 `patch:dsh:sh`）即可一键修复两处（`patches/dsh-app-boot-route-scoped-hotfix.patch` 含双 hunk；幂等，已打过旧版单处补丁的机器只补缺的那处；git apply 与内建替换双路径产出逐字节一致）。详见 README「Troubleshooting」。
+
+### ② 插件侧 patch：保持不变
+
+- `patches/dsh-db-tool@0.1.8.patch`（3454 字节）：将 `DANGEROUS_OPS` / `READ_OPS` 两个纯数据集合拆入 `dist/adapters/mongodb/ops.js`，使 `guard/index.js` 的静态导入不再牵连 mongodb → 插件激活不再踩中宿主缺陷。
+- 该 patch 解决的是"插件能否激活"；宿主缺陷未根治前，**实际建立 MongoDB 连接仍会加载 mongodb 并触发同一缺陷**。宿主修复（①）落地后两者配合，MongoDB 功能才能完整恢复。
+- 升级 dsh-db-tool 版本时按官方流程重新生成 patch（见下文第四节）。
+
+### ③ 上游根治（issue 草稿另由专人撰写）
+
+- 反馈目标：[deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) 的 `packages/boot/app-boot`。
+- 核心诉求：给 `routeScoped` 中的 `resolve.paths` 调用补空值保护；同一无保护模式在 rc.2 中仍有多处（原记录文档第六节列有 5 处）。
+- 配套建议：`selfReferenceName()` 对无 `exports` 的老式包增加降级处理；启动审计附带原始错误与堆栈。
+
+---
+
+## 三、修复验证标准
+
+宿主修复后依次满足以下三条，问题 1 方可判定关闭：
+
+1. **插件全激活**：dsh web 重启后 **11/11 插件激活**，启动日志无 `failed to import`；
+2. **API 可达**：`GET /dsh-db-tool/api/connections` 返回 **200**；
+3. **真实连接**：实际建立一次 MongoDB 测试连接**成功**（此前插件侧 patch 已达成 1、2 两条，但第 3 条一直失败——此项是宿主修复生效的直接判据）。
+
+---
+
+## 四、pnpm patch 官方升级流程
+
+引用：[pnpm 官方文档 — pnpm patch](https://pnpm.io/cli/patch)。当被 patch 的包需要升级版本时，按以下顺序操作（以 billion-context 从 0.1.147 → 0.1.163、dsh-db-tool 升级为例）：
+
+1. `pnpm patch <pkg>@<新版本>` —— 按新版本重新生成可编辑副本，在新副本上重做补丁修改（新版 dist 若为压缩格式，旧 patch 上下文无法落位，**必须重新生成**）；
+2. 用 `--patch-dir` 输出的目录内容生成/复制新 patch 文件到 `patches/`；
+3. 修改 `pnpm-workspace.yaml` 的 `patchedDependencies`，将声明指向新版本；
+4. **紧接**执行 `pnpm add <pkg>@<新版本>` —— 切换 patch 声明与升级之间**不插入任何其他 pnpm 命令**，否则旧版本退出依赖树的瞬间 patch 声明失配，触发 `ERR_PNPM_UNUSED_PATCH` 直接拒绝整个操作。
+
+> 本机实证见原记录文档问题 3：0.1.147 声明未对齐时，`pnpm add billion-context@0.1.163` 稳定失败；按上述流程操作后通过。
+
+---
+
+## 五、原生模块本地 headers 构建（node-gyp nodedir）
+
+**适用场景**：本机到 `https://nodejs.org` 被网络策略拦截（SSL `wrong version number`），`better-sqlite3`、`cpu-features` 等 node-gyp 原生构建下载 headers 失败时。
+
+依据 node-gyp 官方参数（[npmjs — node-gyp](https://www.npmjs.com/package/node-gyp)）：`--nodedir` 指定本地 node headers 目录；经 npm 配置传递即 `npm_config_nodedir`。本机验证可行的完整命令（沿用原记录文档问题 6 的成功方案，实测 16 秒完成）：
+
+```bash
+npm_config_nodedir=C:/nodedir npm_config_build_from_source=true \
+  PATH="/c/Users/ASUS/AppData/Roaming/npm:$PATH" dsh plugin --profile web add -E <包名>@<版本>
+```
+
+- `C:\nodedir` 内需有完整 headers 与 `node.lib`；
+- `npm_config_build_from_source=true` 强制源码编译（跳过 prebuild 下载）；
+- PATH 前置用于强制 pnpm 12.6.0（规避 12.3.4 的偶发 fail-fast，见原记录文档问题 4）。
+
+---
+
+## 六、dsh-zh-thinking 结论与替代品
+
+**核实结论**：`dsh-zh-thinking@0.1.1` 经三方核查（内网 Nexus group-npm、公网 registry.npmjs.org、npmjs 网页）**全部 404**——该包从未发布或已下架，任何安装方式均不可行。
+
+**功能相近替代品**（均已核实存在于 npm）：
+
+| 包名 | 版本 | 链接 |
+|---|---|---|
+| `dsh-thinking-levels` | 3.4.3 | https://www.npmjs.com/package/dsh-thinking-levels |
+| `@hytime/dsh-thinking-effort` | 0.3.5 | https://www.npmjs.com/package/@hytime/dsh-thinking-effort |
+
+**待用户决策项 ①**：`dsh-zh-thinking` 从插件清单中**移除**，还是**改用**上述替代品之一？
+
+**待用户决策项 ②**：`mcp-cbmem` 的 `serverName` 当前为 `cbm`（工具前缀 `mcp__cbm__*`），与原基线 `cbmem` 不一致。是否改回 `cbmem`？如需修回，只能手工编辑 `cordis.patch.yml` + 重启（且不可使用 dsh-mcp-manager UI 编辑，见原记录文档问题 2 的整块删除风险）。
+
+---
+
+## 七、context7/mcphub MCP 待修复项
+
+- **现象**：`mcp-context7` 与 `mcp-mcphub` 两个 MCP server 当前 `tools: 0`——工具未同步、资源接口拒绝。
+- **修复方式**：通过 MCP 管理器对这两个 server 各执行一次**重启**，即可重新同步工具列表。
+- **兜底路径**（重启无效时）：直接使用 context7.com 公开 llms.txt API，已验证可用，形如：
+
+  ```
+  https://context7.com/<owner>/<repo>/llms.txt?topic=<topic>&tokens=<n>
+  ```
+
+---
+
+## 参考链接
+
+| 资料 | 链接 |
+|---|---|
+| Node.js 官方文档（`resolve.paths` 返回 `null` 语义） | https://nodejs.org/api/modules.html |
+| pnpm 官方文档（patch 升级流程） | https://pnpm.io/cli/patch |
+| node-gyp（`--nodedir` / `npm_config_nodedir`） | https://www.npmjs.com/package/node-gyp |
+| deepseek-harness 上游仓库（`packages/boot/app-boot`） | https://github.com/deepseek-ai/deepseek-harness |
+| dsh-thinking-levels（替代品） | https://www.npmjs.com/package/dsh-thinking-levels |
+| @hytime/dsh-thinking-effort（替代品） | https://www.npmjs.com/package/@hytime/dsh-thinking-effort |
+
+---
+
+> **执行状态（2026-09-28 更新）**：宿主 `L1247` 修复已完成并重启验证——dsh web 正常监听 127.0.0.1:3080；`GET /dsh-db-tool/api/connections` 返回 200（PostgreSQL 连接 c-muh7giif-gzbl 在列）；`POST /dsh-db-tool/api/test-draft`（mongodb://127.0.0.1:27017/test）由 mongodb@7.6.0 驱动真实加载并返回结构化驱动错误（本机无 MongoDB 实例，`ECONNREFUSED` 为预期），不再 500/不再使插件崩溃。
+>
+> **因果边界说明**：主崩溃路径（原始堆栈中的 `routeScoped`，即 L1422 区域）在 2026-09-25 打入既有 hotfix 后即已挡住——hotfix 之后、本次 L1247 加固之前实测该接口已返回结构化错误；本次 L1247 修复属**同型隐患的防御性加固**（`nativePackageDir` 同处解析链上，加固前任何经它的 core-module 请求仍会崩）。原始缺陷完全未修时（两处修复之前）此操作必崩。插件激活数以 dsh web 启动日志为准（stdout 进控制台窗口，无文件日志可直接核对）。上游 issue 草稿见 `docs/上游issue草稿-20260928.md`。

package/docs/install.md

@@ -73,5 +73,6 @@ rm -rf ../gaussdb-pg && cp -r packages/pg ../gaussdb-pg
 ## 常见问题
 
 - **侧边栏没有「数据库」tab**：确认 dsh-better-sidebar >= 0.12 已随 DSH 加载；本地开发模式确认 `--patch ./cordis.patch.yml` 生效。
+- **插件导入失败（punycode / resolve.paths）**：宿主 `dsh-app-boot@0.1.7-rc.2` 已知缺陷，触发条件是插件依赖树含 core-module 同名包（mongodb 链的 `tr46 → punycode` 即元凶）。**0.1.9 起 mongodb 驱动已 bundle 进发布包（`vendor/mongodb-driver.cjs`），本插件依赖树不含 punycode，正常安装不再触发此 bug**——包括无法打补丁的桌面版 app.asar 形态。若错误仍指向其他插件，或需修复宿主自身，在插件目录运行 `npm run patch:dsh`（macOS/Linux 用 `patch:dsh:sh`）一键修复，详见 README「Troubleshooting」。从源码安装（`npm install` 后直接用）时构建链会自动产出 bundle；缺失时可单独跑 `npm run build:mongodb`。
 - **API 全部报错**：host 端 webServer 须注册前缀 `/dsh-db-tool/api`（loopback only）；前端与 host 前缀不一致是最常见的接错方式。
 - **连接测试通过但查询报 UNAUTHORIZED_PROJECT**：当前项目路径未被授权，在「授权」面板为该项目路径授 ro 或 rw。

package/docs//344/270/212/346/270/270issue/350/215/211/347/250/277-20260928.md

@@ -0,0 +1,133 @@
+# 上游 Issue 草稿（2026-09-28）
+
+> 状态：**草稿，未提交**。仅供审阅后人工提交。
+> 作者：issue-drafter（teammate）
+> 环境：Windows 11 · Node v24.19.0 · dsh 0.1.7-rc.1 / rc.2 均复现
+> 素材来源：dsh-db-tool 插件加载失败排查过程（详见 `docs/dsh插件安装问题记录-20260928.md`）
+
+---
+
+## 草稿一：deepseek-harness 宿主缺陷（app-boot 模块解析崩溃）
+
+- 上游仓库：https://github.com/deepseek-ai/deepseek-harness
+- 语言习惯：英文正文 + 中文备注
+- 提交入口：https://github.com/deepseek-ai/deepseek-harness/issues/new
+
+### 建议标题
+
+```
+[app-boot] TypeError: createRequire.resolve.paths is not iterable — legacy packages without `exports` (e.g. mongodb@7.6.0) crash Module._resolveFilename and break plugin loading
+```
+
+### 正文（可整段复制提交）
+
+**Environment**
+
+- OS: Windows 11
+- Node.js: v24.19.0
+- dsh: 0.1.7-rc.1 and 0.1.7-rc.2 (both affected)
+
+**Summary**
+
+Plugin loading fails with `failed to import` and no actionable error whenever a plugin dependency uses a legacy package layout without an `exports` field. Root cause is an unguarded call to `require.resolve.paths()` inside `ResolutionRouter.routeScoped`, which returns `null` for core-module requests per the [official Node.js docs](https://nodejs.org/api/modules.html).
+
+**Crash location**
+
+`@deepseek-ai/dsh-app-boot/lib/index.js` line 1422 (`ResolutionRouter.routeScoped`):
+
+```js
+for (const searchPath of createRequire(parent).resolve.paths(name)) {
+```
+
+`require.resolve.paths(request)` returns **null** for:
+
+- core modules (`fs`, `node:fs`, …)
+- requests beginning with `/`, `./`, or `../`
+
+This line has no null guard, so a core-module request flowing through the rewritten `Module._resolveFilename` throws:
+
+```
+TypeError: createRequire.resolve.paths is not a function or its return value is not iterable
+    at ResolutionRouter.routeScoped (.../dsh-app-boot/lib/index.js:1422:58)
+    at ResolutionRouter.routePath (...:1554)
+    at Module.wrappedFilename [as _resolveFilename] (...:1771)
+```
+
+Note: the sibling call in the same project (`profile.ts:596`) already guards with `?? []` — this line was missed.
+
+**Trigger surface**
+
+- `mongodb@7.6.0` ships a legacy layout with no `exports` field (132 js files). All of its internal requests route through the rewritten `Module._resolveFilename`; the first core-module request crashes.
+- Packages that declare `exports` (e.g. `bson@7.3.3`) do **not** trigger the bug, because modern resolution bypasses this path.
+- Impact: any plugin depending on `mongodb` (in our case `dsh-db-tool`) fails to load (`failed to import`), and MongoDB connectivity is completely unavailable.
+
+**Suggested fix**
+
+```js
+for (const searchPath of createRequire(parent).resolve.paths(name) ?? []) {
+```
+
+We also audited the unmodified rc.2 sources and found **3 more unguarded `resolve.paths()` calls** (bundled `lib/index.js`, approximately lines 1482, 2026, 3270) — recommend hardening all of them in one pass.
+
+**Additional observations (same area, lower severity)**
+
+1. `selfReferenceName()` short-circuits self-reference resolution only for packages that declare an `exports` field. Legacy packages without `exports` fall through to the full routing path; consider adding a fallback for them.
+2. The plugin startup audit only reports `failed to import` (originating from app-boot's `inactiveEntries`), swallowing the original error and stack trace. We could only localize this bug with a "shadow entry bisection" technique (7 probe entries on the same profile, each importing a submodule one by one). Please consider surfacing the original error and adding a debug flag.
+
+> **中文摘要**：`dsh-app-boot` 第 1422 行对 `require.resolve.paths()` 的返回值无空值保护，core 模块请求直接抛 TypeError；无 `exports` 的老式包（mongodb@7.6.0）内部请求全部流经被改写的 `Module._resolveFilename`，导致依赖它的插件（dsh-db-tool）加载失败且 MongoDB 功能不可用。建议修复为 `resolve.paths(name) ?? []`，并加固同类另外 3 处无保护调用（bundled `lib/index.js` 约 L1482/L2026/L3270）。附带两个观察：`selfReferenceName()` 对无 `exports` 包缺少降级处理；插件审计日志吞掉原始错误与堆栈，建议输出原始错误并加调试开关。
+
+---
+
+## 草稿二：@xxxyz/dsh-mcp-manager 配置覆写缺陷（按块误删条目）
+
+- 包：`@xxxyz/dsh-mcp-manager@2.2.7`
+- 语言习惯：中文正文
+- 提交入口：https://github.com/xxxyz/dsh-mcp-manager/issues/new
+
+### 建议标题
+
+```
+配置编辑/删除按「块」而非「条目」粒度处理，同一 `- insert:` 块内的无标记条目被连带删除
+```
+
+### 正文（可整段复制提交）
+
+**环境**
+
+- 包版本：`@xxxyz/dsh-mcp-manager@2.2.7`
+- 平台：Windows 11 · Node v24.19.0 · dsh 0.1.7-rc.2
+
+**摘要**
+
+插件通过 patch 文件向宿主配置追加 `- insert:` 块。经阅读 `lib/index.js` 确认根因：**所有定位与删除操作都以「块」为单位，而不是以「条目」为单位**。同一块内由用户手工添加的、未被插件标记的条目，会在一次编辑或删除操作中被连带删除。
+
+**根因（源码定位，`lib/index.js`）**
+
+| 位置 | 函数 | 行为 |
+|---|---|---|
+| 678–691 行 | `insertBlockRange()` | 匹配到目标 id 后，返回从 `- insert:` 行到下一个顶层 `- ` 行的**整块**范围 |
+| 713–721 行 | `removeEntryAll()` | 将 `insertBlockRange()` 返回的**整块**并入删除集 |
+| 1074–1079 行 | UI「编辑」 | 先删整块再重写 |
+| 1160–1163 行 | UI「删除」 | 先删整块 |
+| 657–677 行 | `markerRanges()` | 插件自身标记的范围同样按整块计算 |
+
+**实际事故还原**
+
+- 事故场景：4 条 MCP 配置位于同一个 `- insert:` 块内，用户在 UI 中编辑/删除其中 1 条，结果 4 条全部丢失。
+- 文件证据：`cordis.patch.yml` 从 82 行被改写为 49 行，最终仅剩 1/4 条 MCP。
+- 免疫尝试失败：给手工条目补上 `# dsh-mcp-manager:server:<id>` 标记注释也**不能**避免连带删除——`markerRanges()`（657–677 行）按整块计算标记范围，块内任何操作仍波及全部条目。
+
+**建议修复**
+
+按「条目」粒度定位（解析条目缩进层级，定位单条 `- name:` 起始范围）替代整块删除；若短期内不便重构，至少在文档与 UI 中明确警示「同一 `- insert:` 块内的多条配置会被一起删除」。
+
+> **中文摘要**：`insertBlockRange()` / `removeEntryAll()` / UI 编辑与删除均按整块处理，同块内无标记（或甚至有标记，`markerRanges()` 同样按块计算）的条目被连带删除，曾导致 4 条 MCP 配置一次操作全丢（cordis.patch.yml 82 行 → 49 行）。建议改为条目级定位删除，或在文档/UI 明确警示。
+
+---
+
+## 附：提交核对清单（提交前人工确认）
+
+- [ ] 草稿一：确认 deepseek-harness 仓库 issue 模板要求（若有模板字段需补填）
+- [ ] 草稿一：复现版本号与堆栈行号以最终提交时的 rc 版本为准
+- [ ] 草稿二：确认 @xxxyz/dsh-mcp-manager 的 issue 入口（仓库地址按 npm 包实际 homepage 核对）
+- [ ] 两份草稿均为独立 issue，不互相引用提交（可在正文 environment 处交叉提及）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-db-tool",
-  "version": "0.1.8",
+  "version": "1.2.0",
   "description": "DSH community plugin: chat-operated multi-database admin tool with sidebar management, project-scoped grants, ro/rw modes and dangerous-operation confirmation",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.build.json && node -e \"const fs=require('fs'); fs.mkdirSync('dist/script',{recursive:true}); fs.copyFileSync('lib/script/worker.cjs','dist/script/worker.cjs'); console.log('build OK')\"",
+    "build": "tsc -p tsconfig.build.json && node -e \"const fs=require('fs'); fs.mkdirSync('dist/script',{recursive:true}); fs.copyFileSync('lib/script/worker.cjs','dist/script/worker.cjs'); console.log('build OK')\" && node scripts/build-mongodb.mjs",
+    "build:mongodb": "node scripts/build-mongodb.mjs",
+    "prepack": "npm run build",
     "build:gaussdb": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-gaussdb.ps1",
     "build:gaussdb:sh": "bash scripts/build-gaussdb.sh",
     "patch:dsh": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/apply-dsh-hotfix.ps1",
@@ -45,8 +47,8 @@
   },
   "dependencies": {
     "better-sqlite3": "^13.0.3",
+    "bson": "^7.2.0",
     "dmdb": "^1.0.52452",
-    "mongodb": "^7.6.0",
     "mysql2": "^3.24.4",
     "oracledb": "^7.0.1",
     "pg": "^8.23.0",
@@ -57,6 +59,8 @@
     "@stryker-mutator/vitest-runner": "^10.0.0",
     "@types/better-sqlite3": "latest",
     "@types/node": "latest",
+    "esbuild": "^0.28.0",
+    "mongodb": "^7.6.0",
     "stryker-cli": "^1.1.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11"
@@ -76,6 +80,7 @@
     "docs",
     "patches",
     "scripts",
+    "vendor/mongodb-driver.cjs",
     "README.md"
   ]
 }

package/patches/dsh-app-boot-route-scoped-hotfix.patch

@@ -1,5 +1,7 @@
-# DSH ResolutionRouter routeScoped hotfix (upstream bug: createRequire(parent).resolve.paths(name)
+# DSH dsh-app-boot resolve.paths hotfix (upstream bug: createRequire(parent).resolve.paths(name)
 # returns null for core-module names like "punycode", breaking hoisted profile installs).
+# Covers BOTH unguarded for..of sites in 0.1.7-rc.2: routeScoped() (@@ -1419) and
+# nativePackageDir() (@@ -1244).
 # Target-Version: 0.1.7-rc.2
 # Apply manually:  git apply -p1 -d <dsh-app-boot package root> <this file>
 # Or one command:  npm run patch:dsh    (scripts/apply-dsh-hotfix.ps1)
@@ -24,3 +26,15 @@ index 8f6041d..89a138e 100644
  			if (!searchPath.startsWith(layer.localPrefix)) break;
  			localSearchPaths.push(searchPath);
  			const candidate = localPackageCandidate(searchPath, name, flavor);
+@@ -1244,7 +1244,10 @@
+ 	return treePrefix + (end < 0 ? rest : rest.slice(0, end));
+ }
+ function nativePackageDir(parent, name) {
+-	for (const searchPath of createRequire(parent).resolve.paths(name)) {
++	/* local hotfix: nativePackageDir: resolve.paths returns null for core-module names
++	   (fs, node:fs, ...); an empty list means no local candidate, matching the
++	   guard in profile.ts:596. */
++	for (const searchPath of createRequire(parent).resolve.paths(name) ?? []) {
+ 		const candidate = join(searchPath, name);
+ 		if (existsSync(join(candidate, "package.json"))) return candidate;
+ 	}

package/scripts/build-mongodb.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * 构建 vendor/mongodb-driver.cjs：把 mongodb 驱动 bundle 成单文件（esbuild JS API）。
+ *
+ * 背景：DSH 宿主 @deepseek-ai/dsh-app-boot（<= 0.1.7-rc.2）在插件安装/加载时对依赖树
+ * 逐包调 `require.resolve.paths(name)` 且未防护 null 返回值（for..of null → TypeError）。
+ * mongodb → mongodb-connection-string-url → whatwg-url → tr46 → punycode 链会让生产依赖树
+ * 出现核心模块同名包 punycode，在未修复宿主上直接炸掉整个插件。bundle 后 punycode/
+ * whatwg-url/tr46/@mongodb-js/saslprep 全部内联进产物，不再出现在依赖树。
+ *
+ * --external:bson 是刻意设计：bson 保留在 dependencies，bundle 内 mongodb re-export 的
+ * ObjectId/Binary 等来自运行时 require('bson')，与测试/插件其他代码 require 的 bson 是
+ * 同一模块实例（instanceof 兼容，避免双份 BSON 类）。其余 externals 为 mongodb 全部
+ * optional peer 依赖（驱动对其本就 try/catch 降级，缺失不影响功能）。
+ *
+ * 每次执行全量重建（esbuild 亚秒级），不做幂等跳过，避免"源升级产物旧"。
+ */
+import { build } from 'esbuild';
+import { mkdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const outfile = path.join(root, 'vendor', 'mongodb-driver.cjs');
+
+/** bson 必须 external（实例一致性，见文件头注释）；其余为 mongodb optional peers */
+const externals = [
+  'bson',
+  'bson-ext',
+  'kerberos',
+  'snappy',
+  'socks',
+  'gcp-metadata',
+  '@aws-sdk/credential-providers',
+  '@mongodb-js/zstd',
+  'mongodb-client-encryption',
+];
+
+const entry = path.join(root, 'node_modules', 'mongodb', 'lib', 'index.js');
+if (!statSync(entry, { throwIfNoEntry: false })) {
+  console.error('[build-mongodb] 未找到 node_modules/mongodb/lib/index.js —— 请先 npm install（mongodb 在 devDependencies，提供 bundle 源）');
+  process.exit(1);
+}
+
+mkdirSync(path.dirname(outfile), { recursive: true });
+await build({
+  entryPoints: [entry],
+  outfile,
+  bundle: true,
+  platform: 'node',
+  format: 'cjs',
+  target: 'node20',
+  external: externals,
+  legalComments: 'none',
+  sourcemap: false,
+  minify: false,
+  logLevel: 'warning',
+});
+
+const size = statSync(outfile).size;
+console.log(`[build-mongodb] wrote vendor/mongodb-driver.cjs (${(size / 1024 / 1024).toFixed(2)} MB)`);
+console.log('[build-mongodb] done');

package/scripts/hotfix-core.d.mts

@@ -6,8 +6,13 @@ export declare const HOTFIX_MARKER: string;
 export declare const BOOT_INDEX_REL: string;
 export declare const BACKUP_SUFFIX: string;
 export declare const ORIGINAL_LINE: string;
+export declare const ORIGINAL_NPD_BLOCK: string;
+export declare const NPD_FIXED_LINE: string;
+export declare const FIXED_NPD_BLOCK: string;
+export declare const HOTFIX_BLOCK: string;
 
 export declare function isApplied(content: string): boolean;
+export declare function isNpdApplied(content: string): boolean;
 export declare function applyToContent(content: string): {
 	ok: boolean;
 	reason?: string;

package/scripts/hotfix-core.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 /**
- * DSH ResolutionRouter hotfix —— 核心逻辑（纯 Node、零依赖、可被测试 import）。
+ * DSH dsh-app-boot resolve.paths hotfix —— 核心逻辑（纯 Node、零依赖、可被测试 import）。
  *
- * 修复的 bug：@deepseek-ai/dsh-app-boot 的 routeScoped() 直接对
- * `createRequire(parent).resolve.paths(name)` 做 for..of，而 Node 对 core-module
- * 同名包（punycode 等）返回 null，导致 hoisted profile 下 npm 安装插件导入失败
- * （TypeError: Cannot read properties of null）。
+ * 修复的 bug：@deepseek-ai/dsh-app-boot@0.1.7-rc.2 对
+ * `createRequire(parent).resolve.paths(name)` 的 for..of 无保护，而 Node 对
+ * core-module 同名包（punycode 等）返回 null，for..of null 直接抛 TypeError，
+ * 导致 hoisted profile 下 npm 安装插件导入失败。rc.2 中共两处同型缺陷：
+ * 1. routeScoped()（L1419 区域）—— 症状直接暴露；
+ * 2. nativePackageDir()（L1246 区域）—— 第二处，症状相同，一并修复。
  *
  * 用法：node scripts/hotfix-core.mjs [--dsh-root <dir>] [--patch-file <file>]
  *           [--force] [--revert] [--dry-run]
@@ -29,8 +31,27 @@ export const BACKUP_SUFFIX = '.bak-hotfix';
 export const ORIGINAL_LINE =
 	'\t\tfor (const searchPath of createRequire(parent).resolve.paths(name)) {';
 
+/** 原始（未打补丁）nativePackageDir 块 —— rc.2 中第二处同型缺陷（函数签名行做锚，保证匹配唯一）。 */
+export const ORIGINAL_NPD_BLOCK = [
+	'function nativePackageDir(parent, name) {',
+	'\tfor (const searchPath of createRequire(parent).resolve.paths(name)) {',
+].join('\n');
+
+/** nativePackageDir 修复后的 for 行（同时是幂等判据：`?? []` 形态全文件唯一）。 */
+export const NPD_FIXED_LINE =
+	'\tfor (const searchPath of createRequire(parent).resolve.paths(name) ?? []) {';
+
+/** nativePackageDir 热修复块 —— 与 patches/*.patch 第二个 hunk 的 + 行逐字节一致。 */
+export const FIXED_NPD_BLOCK = [
+	'function nativePackageDir(parent, name) {',
+	'\t/* local hotfix: nativePackageDir: resolve.paths returns null for core-module names',
+	'\t   (fs, node:fs, ...); an empty list means no local candidate, matching the',
+	'\t   guard in profile.ts:596. */',
+	NPD_FIXED_LINE,
+].join('\n');
+
 /** 热修复代码块 —— 与 patches/dsh-app-boot-route-scoped-hotfix.patch 的 + 行一致。 */
-const HOTFIX_BLOCK = [
+export const HOTFIX_BLOCK = [
 	'\t\t/* local hotfix: resolve.paths returns null for core-module names (e.g. "punycode"),',
 	'\t\t   which made the for..of throw TypeError and broke every hoisted profile install',
 	'\t\t   whose dependency tree requires such an npm package. Fall back to the standard',
@@ -46,28 +67,65 @@ export function isApplied(content) {
 	return content.includes(HOTFIX_MARKER);
 }
 
+/** nativePackageDir 修复是否已在（幂等判据：`?? []` 形态全文件唯一）。 */
+export function isNpdApplied(content) {
+	return content.includes(NPD_FIXED_LINE);
+}
+
+/** 单处修复的三态应用：already（已在）/ applied（本次注入）/ missing（原始行不在）。 */
+function applyOne(content, isDone, original, fixed) {
+	if (isDone(content)) return { content, status: 'already' };
+	if (content.includes(original)) {
+		return { content: content.replace(original, fixed), status: 'applied' };
+	}
+	return { content, status: 'missing' };
+}
+
 /**
- * 在文件内容上应用热修复（幂等：已应用时返回 already-applied）。
+ * 在文件内容上应用全部热修复（幂等）。
+ * 两处缺陷（routeScoped / nativePackageDir）独立判定、独立注入：
+ * - 任一「本次注入」→ ok:true；
+ * - 全部缺失原始行 → target-line-not-found（可能不是目标文件）；
+ * - 其余（全部已在）→ already-applied。
+ * 已打 FIX1 的机器只会补上 FIX2，反之亦然。
  * @returns {{ ok: boolean, reason?: string, content: string }}
  */
 export function applyToContent(content) {
-	if (isApplied(content)) return { ok: false, reason: 'already-applied', content };
-	if (!content.includes(ORIGINAL_LINE)) {
-		return { ok: false, reason: 'target-line-not-found', content };
+	const r1 = applyOne(content, isApplied, ORIGINAL_LINE, HOTFIX_BLOCK);
+	const r2 = applyOne(r1.content, isNpdApplied, ORIGINAL_NPD_BLOCK, FIXED_NPD_BLOCK);
+
+	if (r1.status === 'applied' || r2.status === 'applied') {
+		return { ok: true, content: r2.content };
+	}
+	if (r1.status === 'missing' && r2.status === 'missing') {
+		return { ok: false, reason: 'target-line-not-found', content: r2.content };
 	}
-	return { ok: true, content: content.replace(ORIGINAL_LINE, HOTFIX_BLOCK) };
+	return { ok: false, reason: 'already-applied', content: r2.content };
 }
 
 /**
  * 还原热修复（优先用内建块反替换；调用方在磁盘层面应优先用 .bak-hotfix 备份）。
+ * 注意：内建反替换只认分发版英文注释块；手工打过的非标准块（如中文注释）
+ * 反替换不到，届时请用 .bak-hotfix 备份整体还原。
  * @returns {{ ok: boolean, reason?: string, content: string }}
  */
 export function revertContent(content) {
-	if (!isApplied(content)) return { ok: false, reason: 'not-applied', content };
-	if (!content.includes(HOTFIX_BLOCK)) {
-		return { ok: false, reason: 'hotfix-block-not-found', content };
+	let changed = false;
+	let result = content;
+
+	if (isApplied(result)) {
+		if (!result.includes(HOTFIX_BLOCK)) {
+			return { ok: false, reason: 'hotfix-block-not-found', content };
+		}
+		result = result.replace(HOTFIX_BLOCK, ORIGINAL_LINE);
+		changed = true;
+	}
+	if (result.includes(FIXED_NPD_BLOCK)) {
+		result = result.replace(FIXED_NPD_BLOCK, ORIGINAL_NPD_BLOCK);
+		changed = true;
 	}
-	return { ok: true, content: content.replace(HOTFIX_BLOCK, ORIGINAL_LINE) };
+	if (!changed) return { ok: false, reason: 'not-applied', content };
+	return { ok: true, content: result };
 }
 
 /** 从补丁文本解析注释头声明的目标版本（无则返回 undefined）。 */
@@ -195,9 +253,13 @@ function commonGlobalRoots() {
 export function applyToIndexFile(indexFile, patchFile) {
 	if (isGitApplyable(indexFile, patchFile)) {
 		const bootRoot = path.dirname(path.dirname(indexFile));
-		execFileSync('git', ['apply', '-p1', '--directory', '.', patchFile], {
-			cwd: bootRoot,
-		});
+		// autocrlf=false：阻止 Windows 上 git apply 把整个文件转成 CRLF——
+		// 转换会破坏与内建替换路径的逐字节等价，并使内建 revert 兜底失配。
+		execFileSync(
+			'git',
+			['-c', 'core.autocrlf=false', 'apply', '-p1', '--directory', '.', patchFile],
+			{ cwd: bootRoot },
+		);
 		return 'git-apply';
 	}
 	const content = fs.readFileSync(indexFile, 'utf8');
@@ -211,9 +273,11 @@ function isGitApplyable(indexFile, patchFile) {
 	const bootRoot = path.dirname(path.dirname(indexFile));
 	try {
 		// --directory 只接受相对路径（git 拒绝绝对目标 "invalid path"），故以包根为 cwd。
-		execFileSync('git', ['apply', '--check', '-p1', '--directory', '.', patchFile], {
-			cwd: bootRoot,
-		});
+		execFileSync(
+			'git',
+			['-c', 'core.autocrlf=false', 'apply', '--check', '-p1', '--directory', '.', patchFile],
+			{ cwd: bootRoot },
+		);
 		return true;
 	} catch {
 		return false;
@@ -300,18 +364,28 @@ export function run(argv = process.argv.slice(2)) {
 		return 0;
 	}
 
-	if (isApplied(content)) {
-		console.log('[dsh-hotfix] already applied; nothing to do.');
+	/** 当前内容中尚未修复的缺陷名列表（dry-run 预览与结果汇报共用）。 */
+	function pendingFixes(c) {
+		const pending = [];
+		if (!isApplied(c)) pending.push('routeScoped');
+		if (!isNpdApplied(c)) pending.push('nativePackageDir');
+		return pending;
+	}
+
+	if (isApplied(content) && isNpdApplied(content)) {
+		console.log('[dsh-hotfix] already applied (both fixes); nothing to do.');
 		return 0;
 	}
 	if (dryRun) {
-		console.log(`[dsh-hotfix] dry-run: would apply patch to ${indexFile}.`);
+		console.log(`[dsh-hotfix] dry-run: would fix [${pendingFixes(content).join(', ')}] in ${indexFile}.`);
 		return 0;
 	}
 	const backup = indexFile + BACKUP_SUFFIX;
 	if (!fs.existsSync(backup)) fs.copyFileSync(indexFile, backup);
 	const method = applyToIndexFile(indexFile, patchFile);
-	console.log(`[dsh-hotfix] applied to ${indexFile} (via ${method}; backup at ${backup}).`);
+	console.log(
+		`[dsh-hotfix] fixed [${pendingFixes(content).join(', ')}] in ${indexFile} (via ${method}; backup at ${backup}).`,
+	);
 	return 0;
 }