dsh-db-tool 1.3.0 → 1.3.1

package/docs/dsh/346/217/222/344/273/266/345/256/211/350/243/205/351/227/256/351/242/230/350/256/260/345/275/225-20260928.md

@@ -1,309 +0,0 @@
-# dsh 插件安装/更新问题记录
-
-- **记录时间**：2026-09-28
-- **任务范围**：按 `G:\CLI\DSH插件包.txt` 的 12 个插件清单，对 dsh web profile 执行安装/更新
-- **目标 profile**：`C:\Users\Sjc\.dsh\profiles\web`
-- **环境**：Windows 11 + Git Bash；Node v24.19.0；dsh 起始版本 0.1.7-rc.1（任务中途升级至 0.1.7-rc.2）；pnpm 双版本共存（`G:\Env\nodejs\pnpm` 12.3.4 / `C:\Users\Sjc\AppData\Roaming\npm\pnpm` 12.6.0）；内网 registry `http://10.192.2.173:8081/repository/group-npm/`
-
-## 一、最终结果
-
-| 项目 | 结果 |
-|---|---|
-| 版本达标 | **11/11**（清单第 12 个 `dsh-zh-thinking` 确认从未发布，跳过） |
-| 服务状态 | dsh web 正常运行（PID 83020，监听 127.0.0.1:3080），11 个插件全部激活 |
-| 附带修复 | ① 依赖残缺态恢复；② 3 条被覆写丢失的 MCP 配置恢复 + 拆块加固；③ dsh-db-tool 加载修复 |
-| 遗留 | MongoDB 连接功能不可用（需上游修复宿主缺陷）；`dsh-zh-thinking` 来源待确认 |
-
----
-
-## 二、问题清单（按严重度）
-
-| # | 问题 | 严重度 | 状态 |
-|---|---|---|---|
-| 1 | dsh-db-tool 插件加载失败（宿主 loader 缺陷） | 高 | 已修复（插件侧绕过）+ 上游待修 |
-| 2 | MCP 配置被 mcp-manager 覆写丢失 3 条 | 高 | 已恢复 + 已加固 |
-| 3 | `ERR_PNPM_UNUSED_PATCH` 阻断所有升级操作 | 高 | 已解决 |
-| 4 | pnpm 崩溃 exit 3221226505 遗留依赖残缺态 | 中 | 已恢复（崩溃本身不可复现） |
-| 5 | dsh-zh-thinking 不存在于任何 registry | 中 | 待确认 |
-| 6 | better-sqlite3 构建失败（nodejs.org 被拦） | 中 | 已解决 |
-| 7 | skill-explorer 宿主版本门槛不满足 | 中 | 已豁免（rc.2 后自然满足） |
-| 8 | 诊断探针插件被 dsh 拒绝加载 | 低 | 已知规避 |
-| 9 | mcp-intellij 未拉起 | 低 | 外部依赖（IDEA 未运行） |
-| 10 | Git Bash 的 http_proxy 拦截本机 curl | 低 | 已知规避 |
-| 11 | 清单记载的 rtk 路径错误 | 低 | 已澄清 |
-| 12 | cordis.patch.yml 注释过期 | 低 | 已标注 |
-| 13 | cpu-features 原生构建失败（既有问题） | 低 | 不阻塞 |
-| 14 | GitHub 直装包 specifier 为浮动引用 | 低 | 已知风险 |
-
----
-
-## 三、问题详情
-
-### 问题 1：dsh-db-tool 插件加载失败【高】
-
-**现象**
-
-插件安装成功、版本正确（0.1.8），但启动日志始终出现：
-
-```
-dsh: warning: 1 entry did not activate
-db-tool (dsh-db-tool): failed to import
-```
-
-宿主 0.1.7-rc.1 与升级后的 0.1.7-rc.2 均复现；纯 Node 环境下导入该插件完全正常。
-
-**根因（四层因果）**
-
-1. **宿主缺陷**：dsh 为实现 profile 感知解析，用 `node-addon-require-builtin` 深入 Node 内部模块并改写 CJS 的 `Module._resolveFilename`。每个请求都会经过 `dsh-app-boot/lib/index.js:1422`：
-
-   ```js
-   for (const searchPath of createRequire(parent).resolve.paths(name)) {
-   ```
-
-   该行**无空值保护**（对比同类调用 `profile.ts:596` 有 `?? []`），在特定请求上抛：
-
-   ```
-   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)
-   ```
-
-2. **为何是 mongodb 触发**：dsh 的 `selfReferenceName()` 只在包声明了 `exports` 字段时才短路解析。`mongodb@7.6.0` 是**无 exports 的老式布局**（132 个 js 文件），内部请求全部经过缺陷循环；而 `bson@7.3.3` 有 exports，不触发。纯 Node 下穷举 mongodb（132 文件 × 8 种子路径请求）的 `resolve.paths` 调用：**零异常**，证明包本身无问题。
-
-3. **为何是 db-tool 撞上**：其加载链 `dist/index.js → manager.js → guard/index.js:10 静态导入 ../adapters/mongodb/index.js → 顶层 import 'mongodb'`。即**加载插件必然加载 mongodb**——而 db-tool 的适配器本设计为惰性加载（`adapters/index.js` 中 8 个驱动全是 `() => import(...)`），是 guard 为取两个常量做的静态导入破坏了惰性。
-
-4. **为何看不到线索**：dsh 启动审计把加载异常吞掉，只打印 `failed to import`（源头 `app-boot` 的 `inactiveEntries`）。
-
-**定位方法**：影子入口二分法——在同一 profile 挂 7 个探针入口（分别导入 db-tool 的各子模块），一次实验即锁定：不碰 mongodb 的 `store`/`adapters` 成功，`guard`/`manager`/`http`/`script` 全部失败。
-
-**修复（插件侧绕过，三处最小改动）**
-
-1. 新增 `dist/adapters/mongodb/ops.js`：把 `DANGEROUS_OPS`、`READ_OPS` 两个纯数据集合拆出；
-2. `dist/guard/index.js` 改为从 `ops.js` 导入这两个常量；
-3. `dist/adapters/mongodb/index.js` 改为从 `ops.js` 转发导出（对外接口不变）。
-
-**固化**：pnpm patch 官方机制 —— `patches/dsh-db-tool@0.1.8.patch`（3454 字节）+ `pnpm-workspace.yaml` 的 `patchedDependencies`，重装后自动应用。
-
-**验证**：纯 Node 导入成功且不再加载 mongodb → 实例启动 11/11 激活 → 生产服务重启后 `GET /dsh-db-tool/api/connections` 返回 **200**（修复前 404，响应体 `{"ok":true,"data":[]}`）。
-
-**遗留**：真正建立 MongoDB 连接时仍会加载 mongodb 包、仍会踩中同一缺陷，**MongoDB 连接功能暂不可用**（其余 6 种数据库正常）。彻底修复需上游给 1422 行加空值保护（建议反馈上游）。
-
----
-
-### 问题 2：MCP 配置被 mcp-manager 覆写丢失【高】
-
-**现象**
-
-`cordis.patch.yml` 在 2026-09-28 08:51（dsh web 运行期间）被从约 82 行改写为 49 行：原本 4 条 MCP 挂载只剩 `mcp-cbmem` 一条，`mcp-intellij`（IDEA）、`mcp-laya`、`mcp-mcphub` 三条丢失；且 `mcp-cbmem` 的 `serverName` 被从 `cbmem` 改成 `cbm`。
-
-**根因（读 `@xxxyz/dsh-mcp-manager@2.2.7/lib/index.js` 确认）**
-
-- 该插件按"块"而非"条目"处理：`insertBlockRange()`（678-691 行）一旦在某 `- insert:` 块内匹配到目标 id，返回范围就是**从 `- insert:` 到下一个顶层 `- ` 的整块**；
-- `removeEntryAll()`（713-721 行）把整块并入删除集；UI 的"编辑"（1074-1079 行）与"删除"（1160-1163 行）都会先删整块再（或不）追加；
-- 因此**同块内的无标记条目会被连带删除**——4 条 MCP 同处一个 insert 块，误操作一次即全丢；
-- 给手工条目补 `# dsh-mcp-manager:server:<id>` 标记也**不能免疫**（`markerRanges()` 657-677 行同样按整块计算）。
-
-这与历史记录中的同类事故（`G:\CLI\github-项目安装核查报告.md` 第 507-509 行）完全吻合。
-
-**处置**
-
-1. 恢复：按历史原文补回丢失的 3 条（`mcp-intellij` / `mcp-laya` / `mcp-mcphub`），`dsh --profile web --dump-config` 验证 4 条全部加载；
-2. **加固**：把 4 条 MCP 拆成 **4 个独立 `- insert:` 块**，把"误删一条导致全部丢失"降级为"只丢一条"；
-3. 备份：`.backup-20260928/cordis.patch.yml.before-mcp-restore`（恢复前）、`cordis.patch.yml.before-split`（拆块前）。
-
-**遗留与建议**
-
-- ⚠️ **不要在 dsh-mcp-manager 的 UI 里"编辑/删除"任何 MCP 条目**（新增/启用/禁用/重启是安全的）；
-- `mcp-cbmem` 的 serverName 仍为 `cbm`（工具前缀 `mcp__cbm__*`，原基线 `cbmem`）；恢复时未改回以避免二次风险，如需修回只能手工改文件 + 重启。
-
----
-
-### 问题 3：`ERR_PNPM_UNUSED_PATCH` 阻断升级【高】
-
-**现象**：`pnpm add billion-context@0.1.163` 稳定失败：
-
-```
-Error: ERR_PNPM_UNUSED_PATCH
-  × adding a new package
-  ╰─▶ The following patches were not used: billion-context@0.1.147
-```
-
-**根因**：`pnpm-workspace.yaml` 的 `patchedDependencies` 声明了 `billion-context@0.1.147: patches/billion-context@0.1.147.patch`。一旦执行升级命令、0.1.147 退出依赖树，该 patch 立即"未被使用"，pnpm 直接拒绝整个操作。**这不是崩溃、不是网络问题，而是版本的确定性阻塞**——换任何 pnpm 版本都会失败。
-
-**处置**：为 0.1.163 重新生成 patch（新版 dist 是压缩格式，旧 patch 上下文无法落位，必须重新生成）→ 复制 patch 文件 → 修改 `pnpm-workspace.yaml` 的 `patchedDependencies` 指向 0.1.163 → **紧接**执行升级 add（切换与升级之间不插入其他 pnpm 命令，最小化不一致窗口）。
-
-**说明**：该 patch 修复的不是安装问题，而是 billion-context 的隧道 DNS 校验：本机内网 DNS 不解析外网域名，导致其内置 deepseek 路由被 403 拒绝。补丁让 DNS 解析失败时对回环客户端放行（非回环仍拒绝，SSRF 防护不变）。
-
-**验证**：patch 文件 sha256 与 lock 记录一致；`node_modules/billion-context/dist/index.js` 中 `ctx.clientLoopback` 出现 3 次（原 2 + 补丁 1）；`catch{` 后紧跟补丁注释与 `if(ctx.clientLoopback)return{ok:true}`。
-
----
-
-### 问题 4：pnpm 崩溃 exit 3221226505 遗留依赖残缺态【中】
-
-**现象**：2026-09-28 08:12 一次 `pnpm add "billion-context@0.1.163"` 以 Windows 崩溃码 **3221226505（0xC0000409，fail-fast）** 退出，日志 76 字节无输出；其后 node_modules 残缺，任何 `dsh plugin` 命令都在 reconcile 阶段报 `cannot resolve profile bundle` 并异常退出。
-
-**诊断实验**：临时目录 × {pnpm 12.3.4, 12.6.0} × {小包, billion-context} × {共享 store, 干净 store} 全矩阵 —— **全部 exit 0，崩溃不可复现**；同期生产日志（08:41）显示同一命令已变为稳定的 `exit 1`（即 ERR_PNPM_UNUSED_PATCH），说明崩溃是一次偶发的 Windows fail-fast，非确定性缺陷。
-
-**规避**：所有 dsh/pnpm 命令统一用 PATH 前置强制走 pnpm 12.6.0：
-
-```bash
-PATH="/c/Users/Sjc/AppData/Roaming/npm:$PATH" dsh plugin --profile web <args>
-```
-
-（dsh 从 PATH 解析 pnpm，`operations.js:271` 有 `options.command ?? 'pnpm'`；已验证前置生效。）
-
-**遗留**：崩溃根因未定位（无输出、不可复现），升级 pnpm 属合理规避但无直接证据证明根治。
-
----
-
-### 问题 5：dsh-zh-thinking 不存在于任何 registry【中】
-
-**现象**：清单记载 `dsh-zh-thinking@0.1.1` 且给出 npm 链接，但三方核实全部 404：
-
-| 来源 | 结果 |
-|---|---|
-| 内网 Nexus（group-npm） | 404 |
-| 公网 registry.npmjs.org | 404（`{"error":"Not found"}`） |
-| npmjs 网页 | 本机 TLS 不可达（环境问题，非包问题） |
-
-**结论**：该包从未发布或已下架/改名。**待你确认来源**。另有相似包 `@hytime/dsh-thinking-effort@0.3.5`（用途不同），如需请告知。
-
----
-
-### 问题 6：better-sqlite3 构建失败【中】
-
-**现象**：安装 `dsh-db-tool@0.1.8` 时其依赖 `better-sqlite3@^13.0.3` 的 `node-gyp rebuild` 失败 —— 需要从 `https://nodejs.org` 下载 node headers，本机网络返回 SSL `wrong version number`（被代理/防火墙拦截）。经测试 CCProxy（`http://10.192.2.117:8085`）**只放行 github.com，不放行 nodejs.org**（HTTP 000）。
-
-**处置（方案 2 成功，仅 16 秒）**：使用本机已有的 node headers 强制源码编译：
-
-```bash
-npm_config_nodedir=C:/nodedir npm_config_build_from_source=true \
-  PATH="/c/Users/Sjc/AppData/Roaming/npm:$PATH" dsh plugin --profile web add -E dsh-db-tool@0.1.8
-```
-
-`C:\nodedir` 内已有完整 headers 与 node.lib；node-gyp 找到 VS2022 与 Python 3.13.15，编译通过。
-
-**验证**：`require('better-sqlite3')` 加载成功、SQL 往返 `{"x":42}` 通过。注：该版本 binding.gyp 为 `type:'none'`（prebuildify 设计），运行时加载包内 `prebuilds/win32-x64.node`，无 build/Release 产物属正常。
-
----
-
-### 问题 7：skill-explorer 宿主版本门槛不满足【中】
-
-**现象**：`@linxin666/dsh-client-ui-skill-explorer@0.4.3` 声明 `dsh.engines.dsh = ">=0.1.7-rc.2"`，而当时宿主为 0.1.7-rc.1，被兼容性预检拒绝。
-
-**处置**：按 dsh 官方机制授予精确版本豁免：
-
-```bash
-dsh plugin --profile web allow-version '@linxin666/dsh-client-ui-skill-explorer@0.4.3' \
-  --dsh-version 0.1.7-rc.1 --accept-risk
-```
-
-记录持久化在 `compatibility.json`：`{"@linxin666/dsh-client-ui-skill-explorer@0.4.3": ["0.1.7-rc.1"]}`。功能实测正常。
-
-**后续**：宿主升级到 rc.2 后门槛自然满足、**不再需要豁免**；旧豁免记录保留无副作用（未撤销以避免无谓变更）。
-
----
-
-### 问题 8：诊断探针插件被 dsh 拒绝加载【低】
-
-**现象**：凡是在插件顶层或 `apply()` 内**包装 `Module._resolveFilename` 或 `Module.prototype.require`** 的探针插件，自身都会 `failed to import`；甚至顶层 `import Module from 'node:module'` 也可能触发。普通探针（只做动态 import、读文件）正常。
-
-**解释**：dsh 对模块加载链有自我保护/一致性校验，包装会破坏其内部假设。
-
-**规避**：诊断时改用"影子入口二分法"（只做静态导入、不包装加载器）或"层外探针 + 延迟执行"。
-
----
-
-### 问题 9：mcp-intellij 未拉起【低】
-
-**现象**：服务启动期 IDEA MCP 反复 11 轮 `io.ktor.client.plugins.sse.SSEClientException: Connection refused`，之后放弃；`curl 127.0.0.1:64342` 返回 000。
-
-**原因**：IDE 未运行（其 MCP Server 未监听 64342），非配置问题（stdio 拉起命令被反复执行、Java 进程反复启停可证）。**启动 IDEA 后即可用。**
-
----
-
-### 问题 10：Git Bash 的 http_proxy 拦截本机 curl【低】
-
-**现象**：在本机探测 `http://127.0.0.1:3080` 等地址时，Git Bash 环境的小写 `http_proxy=http://10.192.2.117:8085` 会拦截请求，返回统一 403，导致误判"端口无监听"。
-
-**规避**：本机探测一律加 `--noproxy '*'`：
-
-```bash
-curl -s --noproxy '*' -o /dev/null -w "%{http_code}" http://127.0.0.1:3080/
-```
-
----
-
-### 问题 11：清单记载的 rtk 路径错误【低】
-
-清单写 `~/.local/bin/rtk.exe`，实际路径为 `G:\CLI\Rtk\rtk.exe`（PATH 可用）。`dsh-pwsh-rtk-rewrite` 按 `RTK_BIN || 'rtk'` 解析，**功能不受影响**，仅文档偏差。
-
----
-
-### 问题 12：cordis.patch.yml 注释过期【低】
-
-文件第 30-37 行的 billion-context 注释仍称补丁文件为 `billion-context@0.1.147.patch`，而实际引用的已是 0.1.163。旧 patch 文件已保留（未删除）但不再被引用。建议后续手工更新注释。
-
----
-
-### 问题 13：cpu-features 原生构建失败【低】
-
-`dsh-pwsh-rtk-rewrite` 与 `dsh-db-tool` 两次安装中均出现 `cpu-features`（`ssh2` 的可选依赖）原生构建失败（同问题 6 的 nodejs.org 拦截），但 pnpm 容忍、主操作成功。**既有问题，非本次引入，不阻塞。**
-
----
-
-### 问题 14：GitHub 直装包 specifier 为浮动引用【低】
-
-`dsh-ssh-tunnel` 的依赖 specifier 为 `github:thirsty5034/dsh-ssh-tunnel#main`（跟随 main）。当前 lockfile 已锁死 commit `c88da56b...`（与远端 main 一致），但**非 frozen 安装可能漂移**。`dsh-restart-fab` 则锁定 commit `99cd34aa...`（与远端最新一致，无漂移风险）。
-
----
-
-## 四、避坑与操作建议
-
-1. **改插件版本前，先对齐 patch 声明**：`pnpm-workspace.yaml` 的 `patchedDependencies` 必须与实际依赖树匹配，否则一律 `ERR_PNPM_UNUSED_PATCH`。
-2. **不要用 dsh-mcp-manager 的 UI 编辑/删除 MCP 条目**（会把整块删掉）；手工编辑 `cordis.patch.yml` 更安全（现已拆成 4 块进一步降低影响面）。
-3. **安装/升级前先停 dsh web**（Windows 文件占用会导致 EPERM/EBUSY）；升级后必须重启服务才生效。
-4. **统一用 pnpm 12.6.0**：`PATH="/c/Users/Sjc/AppData/Roaming/npm:$PATH" dsh plugin ...`（规避 12.3.4 的偶发 fail-fast）。
-5. **构建原生模块时用本地 headers**：`npm_config_nodedir=C:/nodedir npm_config_build_from_source=true`（本机到 nodejs.org 被拦）。
-6. **本机 HTTP 探测加 `--noproxy '*'`**（Git Bash 的 http_proxy 会拦截回环请求）。
-7. **改配置前先备份**：本次全程滚动快照在 `.dsh\profiles\web\.backup-20260928\`。
-8. 兼容性被拒时用官方豁免（`dsh plugin --profile web allow-version <pkg>@<ver> --dsh-version <ver> --accept-risk`），并记录豁免清单。
-
----
-
-## 五、关键路径索引
-
-| 用途 | 路径 |
-|---|---|
-| 改造前基线快照 | `C:\Users\Sjc\.dsh\profiles\web\.backup-20260928\snapshot-0\` |
-| 最终快照（含修复） | `…\.backup-20260928\snapshot-final2\` |
-| db-tool 修复说明 | `…\.backup-20260928\db-tool-修复说明.md` |
-| MCP 恢复前备份 | `…\.backup-20260928\cordis.patch.yml.before-mcp-restore` |
-| MCP 拆块前备份 | `…\.backup-20260928\cordis.patch.yml.before-split` |
-| billion-context patch | `…\patches\billion-context@0.1.163.patch` |
-| db-tool patch | `…\patches\dsh-db-tool@0.1.8.patch` |
-| 宿主缺陷代码位置 | `…\@deepseek-ai\dsh\node_modules\@deepseek-ai\dsh-app-boot\lib\index.js:1422` |
-
-**回滚方式**：用目标快照覆盖 `package.json` / `pnpm-workspace.yaml` / `pnpm-lock.yaml` / `cordis.patch.yml`（+ `patches/`），再执行 `dsh plugin --profile web install`。
-
----
-
-## 六、待办与上游反馈建议
-
-> 解决方案详见 [dsh插件问题解决方案-20260928.md](./dsh插件问题解决方案-20260928.md)。
-
-**待你决策**
-
-1. `dsh-zh-thinking` 的来源（清单给了 npm 链接但三方 404）；
-2. MongoDB 连接功能是否接受"暂不可用"（等上游修复），或要求我尝试给宿主 app-boot 打补丁（改动全局 npm 包，dsh 升级会被覆盖）。
-
-**建议反馈上游（deepseek-harness）**
-
-1. `dsh-app-boot` 的 `routeScoped` 中 `createRequire(parent).resolve.paths(name)` 缺空值保护（对比 `profile.ts:596` 有 `?? []`），建议统一加固；同一模式在 rc.2 中仍有 5 处无保护；
-2. `selfReferenceName()` 对无 `exports` 字段的老式包会走完整路由路径，建议增加降级处理；
-3. 启动审计对插件加载异常只输出 `failed to import`，建议附带原始错误与堆栈（可加调试开关）。
-
-**建议反馈 `@xxxyz/dsh-mcp-manager`**
-
-`insertBlockRange` / `removeEntryAll` 的"整块删除"语义会把同块内非目标条目一并删除，建议改为按条目粒度定位（配合缩进解析），或在文档中明确警示。

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

@@ -1,166 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# dsh-db-tool 安装指南
-
-dsh-db-tool 是 DSH（DeepSeek Harness）插件：侧边栏管理数据库连接与授权，聊天内经 DatabaseManager 工具操作 8 种数据库（MySQL、PostgreSQL、GaussDB、SQLite、Redis、MongoDB、Oracle、达梦）。
-
-## 一键安装（发布模式）
-
-```powershell
-dsh plugin --profile web add "dsh-db-tool@github:<user>/dsh-db-tool"
-```
-
-把 `<user>` 换成实际发布仓库的 GitHub 用户名/组织。安装后侧边栏出现「数据库」tab，即装即用。
-
-> GaussDB 支持依赖 `vendor/gaussdb-pg` 产物（见下文）；不使用 GaussDB 时可不构建，其余 7 库开箱即用。
-
-## 本地开发模式
-
-在仓库根目录执行：
-
-```powershell
-pnpm dsh web --patch ./cordis.patch.yml
-```
-
-`cordis.patch.yml` 会向 DSH 的 cordis 配置注入 `id: db-tool` 的插件条目，指向本仓库入口；改动 `client/client.js` 后重启该命令生效。
-
-## GaussDB vendor 构建
-
-官方 [openGauss-connector-nodejs](https://gitcode.com/opengauss/openGauss-connector-nodejs) 未发布 npm，需从源码构建（详见 `scripts/build-gaussdb.sh` 头注释）：
-
-```bash
-bash scripts/build-gaussdb.sh            # 幂等：已有产物则跳过
-bash scripts/build-gaussdb.sh --force    # 强制重新拉取并构建
-npm run build:gaussdb                    # 等价入口
-```
-
-脚本失败（网络等）时可手动执行同样步骤：
-
-```bash
-git clone https://gitcode.com/opengauss/openGauss-connector-nodejs vendor/gaussdb-src
-cd vendor/gaussdb-src && npm install && npm run build
-rm -rf ../gaussdb-pg && cp -r packages/pg ../gaussdb-pg
-# 保留 vendor/gaussdb-pg/package.json 与 dist/
-```
-
-产物为 `vendor/gaussdb-pg`（CJS，结构同 `pg`：`{ Pool, Client, ... }`）。
-
-> **Node 版本要求**：≥ 22.12。构建脚本会补装 `p-limit@7`（纯 ESM，源码 package.json 未声明），依赖 Node 原生 require(esm)；更旧 Node 加载 GaussDB 驱动会抛 `ERR_REQUIRE_ESM`（其余 7 库不受影响）。
-
-## oracledb approve-scripts
-
-`oracledb` 安装时需要运行安装脚本编译/下载二进制。仓库 `package.json` 已配置白名单：
-
-```jsonc
-"allowScripts": { "oracledb@7.0.1": true }
-```
-
-若你的 npm/pnpm 版本提示 approve-scripts 拦截，按提示批准 `oracledb` 即可；已配置白名单的环境无需额外操作。
-
-## 真机测试
-
-单测（vitest）不依赖真实数据库；要跑真机冒烟，设置以下环境变量后执行 `npm test`（或对应集成脚本）：
-
-| 环境变量 | 示例 |
-|---|---|
-| `DBT_TEST_MYSQL_URL` | `mysql://user:pass@127.0.0.1:3306/test` |
-| `DBT_TEST_PG_URL` | `postgres://user:pass@127.0.0.1:5432/test` |
-| `DBT_TEST_REDIS_URL` | `redis://127.0.0.1:6379/0` |
-| `DBT_TEST_MONGO_URL` | `mongodb://127.0.0.1:27017/test` |
-| `DBT_TEST_ORACLE_CONNECT` | Oracle 连接串/ezconnect 描述 |
-| `DBT_TEST_DM_CONNECT` | 达梦连接串 |
-
-未设置对应变量时该库的真机用例自动跳过。
-
-## 常见问题
-
-- **侧边栏没有「数据库」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。