@omdp/dsh-connector 0.3.2 → 0.3.4

package/README.md

@@ -1,12 +1,36 @@
 # @omdp/dsh-connector
 
-**MCP 服务器 + 用户 Skills + 魔搭市场浏览三合一设置页**（`v0.3.0`）。适合需要在 DSH 里频繁增删改 MCP server / skills、又不想手改 `cordis.patch.yml` 的用户。
+**MCP 服务器 + 用户 Skills + 魔搭市场浏览三合一设置页**（`v0.3.4`）。适合需要在 DSH 里频繁增删改 MCP server / skills、又不想手改 `cordis.patch.yml` 的用户。
 
 ## Requirements
 
 - DeepSeek Harness 带 `web` profile GUI（`npx @deepseek-ai/dsh web`）
 - Node.js `^22.19` 或 `>=24`
-- `@deepseek-ai/cordis` `4.0.1` / `4.0.2`（已实测版本；插件无 peer 声明，唯一 DSH 硬依赖是 `ctx.webServer`）
+- `@deepseek-ai/schemastery` `3.18.1` / `3.18.2` / `3.18.4`（peer 枚举，供工具过滤的 Config 声明用；无则过滤静默全放行）
+- 已实测 DSH **0.1.5-rc.1**（源码级核查，2026-09-10）、**0.1.5-rc.2** 与 **0.1.6-alpha.1**（源码级 + 运行时冒烟：`/connector/api/*` 正常服务、设置页渲染，2026-09-15，见 `docs/plugin-compatibility.md`）、**0.1.7-rc.1**（0.3.3 适配：修掉 import 期崩溃 + 迁移到 settings 托管配置，2026-09-24）
+- **`@deepseek-ai/dsh` peer 声明 `0.1.7-rc.1`**（0.3.4 起，逐版本枚举；规范见 `AGENTS.md` 规范 3）
+
+## 兼容性门禁（0.3.4 起声明）
+
+0.3.4 起本插件在 `peerDependencies` 里**显式声明支持的 DSH 版本**：
+
+```json
+"peerDependencies": {
+  "@deepseek-ai/dsh": "0.1.7-rc.1"
+}
+```
+
+这条声明由 DSH 自己的 **`evaluatePluginCompatibility()`**（`dsh-app-boot` 的公开导出，是一个 Inspector 可查的正式机制、不是本插件自造的约定）在**安装时**与**每次启动时**校验，语义是「声明版本 = 我实测过的版本」：
+
+| 运行中的 DSH | 行为 |
+|---|---|
+| **`0.1.7-rc.1`**（本次实测） | ✅ `evaluatePluginCompatibility()` 返回 `undefined` ⇒ 正常加载，与 0.3.3 行为一致 |
+| **`0.1.7` 及更新的、未实测版本** | ⛔ 门禁拦下：启动时**整个 bundle 被跳过**（stderr 打 `skipping profile bundle "@omdp/dsh-connector"`），安装时该行被置灰 |
+| **`≤0.1.6` 及 `0.1.7-alpha.x`** | ➖ **不受影响**：那些版本里**根本没有这个门禁**（经解包 npm tarball 逐版核对，`0.1.5-rc.2`/`0.1.5-rc.3`/`0.1.6-alpha.1`/`0.1.6-alpha.2`/`0.1.7-alpha.1`/`0.1.7-alpha.2` 的 `dsh-app-boot` 里 `evaluatePluginCompatibility` 出现 **0 次**，只有 `0.1.7-rc.1` 出现 4 次），旧运行时读到这条 peer 只是「不认识的声明」，照常加载 |
+
+**为什么故意只写 `0.1.7-rc.1`（而不是写老版本）**：老版本运行时压根不执行这个检查，写进去纯属装饰、无法被验证；而**未实测的新版本必须被拦住**——这正是 `AGENTS.md` 规范 3 的要求（`peerDependencies` 只精确枚举实测过的版本，禁止开放范围，未核查的版本宁可报 unmet peer 也不得预先放行）。门禁被触发时是**优雅跳过**（插件不加载、DSH 照常启动），符合本插件「硬保证 = DSH 不会因插件崩溃」的抗崩溃设计。
+
+> 升级 DSH 后若设置页突然看不到 Connector 标签，先看启动日志有没有 `skipping profile bundle`——那就是门禁在提醒你「该插件尚未针对这个 DSH 版本做兼容核查」，核查通过后把该版本追加进上面的枚举并同步更新 `docs/plugin-compatibility.md`。
 
 ## Overview
 
@@ -14,7 +38,7 @@
 合并到 DSH Web UI 的同一个设置页（设置页标签：**Connector**）。
 
 - **MCP**：读取/编辑 `profiles/web/cordis.patch.yml` 中的 `mcp-*` 块（结构化表单）。保存后**重启 `dsh` 生效**。
-- **工具过滤（0.3.0 新增）**：每台 MCP server 卡片下可勾选放行的工具（`mcp__<server>__<raw>` 公开名按 `__` 切分回 raw 名）。规则存 `settings.yaml` 的 `connector.toolFilters`（`{<serverName>: {allow: [...]}}`），**无配置 = 全量放行**；保存后新会话即生效、无需重启。生效三件套：`systemPrompt.tools(provider)` 隐藏 schema + `ctx.tools.guard` 执行期硬拦截（做法参照 `hyqhyq3/dsh-mcp-manager`）。典型场景：tinyfish 这类 15 个工具只留 `search`/`fetch_content` 两个免费工具。
+- **工具过滤（0.3.0 新增）**：每台 MCP server 卡片下可勾选放行的工具（`mcp__<server>__<raw>` 公开名按 `__` 切分回 raw 名）。规则存本插件自己的配置（0.1.7+ 为 profile 条目 `connector` 行的 `config.toolFilters`；rc.x 为 `settings.yaml` 的 `connector.toolFilters`，双后端自动判别），**无配置 = 全量放行**；保存后新会话即生效、无需重启。生效三件套：`systemPrompt.tools(provider)` 隐藏 schema + `ctx.tools.guard` 执行期硬拦截（做法参照 `hyqhyq3/dsh-mcp-manager`）。典型场景：tinyfish 这类 15 个工具只留 `search`/`fetch_content` 两个免费工具。
 - **Skills**：列出/查看/编辑/删除 `~/.dsh/skills` 下的 `SKILL.md`。保存**即时生效**（filesystem provider 自动重新发现）。
 - **市场探索（0.2.0 新增）**：只读浏览魔搭社区 [Skills 中心](https://modelscope.cn/skills) 与 [MCP 广场](https://modelscope.cn/mcp)（匿名 OpenAPI，无需密钥）。
   - 列表/详情：名称、作者、分类、下载/浏览数、认证标识（Hosted 官方托管 / 已认证）
@@ -81,7 +105,7 @@ pnpm install --lockfile-only --offline   # 按 link 依赖重写 lockfile
 
 ```jsonc
 "dependencies": {
-  "@omdp/dsh-connector": "^0.3.0"
+  "@omdp/dsh-connector": "^0.3.4"
 }
 ```
 
@@ -144,7 +168,7 @@ pnpm remove @omdp/dsh-connector
    - 列出当前 `cordis.patch.yml` 里的 `mcp-*` 服务器
    - 「编辑」改名称/传输/URL/命令/参数/Header；「删除」移除；「＋ 添加」新建
    - 每台 server 卡片下有**工具过滤**多选（chips）：勾选即放行，未勾选的工具模型不可见、调用被拒；「清除」回到全量放行
-   - 保存后提示**重启 dsh** 才会真正加载新的 MCP server（工具过滤规则除外：存 settings，**新会话即生效**）
+   - 保存后提示**重启 dsh** 才会真正加载新的 MCP server（工具过滤规则除外：存**本插件的 profile 条目配置**，**新会话即生效**）
 2. **Skills** 区：
    - 列出 `~/.dsh/skills` 下的用户技能
    - 「编辑」改 frontmatter 与正文；「删除」移除目录；「＋ 新建」创建
@@ -163,7 +187,7 @@ pnpm remove @omdp/dsh-connector
 | 设置页 | client half 注册 `settings.section` 槽位（"Connector" 页签；client factory 须 `exports.inject = ['slots']`，否则 fiber 在 slots 就绪前跑 apply 会静默丢注册） |
 | 跨边界调用 | client 用 `fetch('/connector/api/...')`，host 用 `ctx.webServer.register` 接收（安装包走 HTTP） |
 | MCP 持久化 | 文本块级提取并替换 `cordis.patch.yml` 中含 `mcp-` 的 insert 块，**保留 `!!js` 表达式与 env 块原样**（preserve 桶） |
-| 工具过滤 | 规则存 settings `connector` 命名空间（`toolFilters`）；`systemPrompt.tools(provider)` 滤 schema + `tools.guard` 硬拦截；`dsh-mcp-client` Config 封闭，规则**不能**写进 mcp 行 config |
+| 工具过滤 | 规则存本插件 profile 条目（`connector` 行）的 `config.toolFilters`，经 `Config` 的 `.volatile()` 字段由 DSH settings 服务托管（0.1.7+）；`systemPrompt.tools(provider)` 滤 schema + `tools.guard` 硬拦截；`dsh-mcp-client` Config 封闭，规则**不能**写进 mcp 行 config |
 | Skill 持久化 | 直接读写 `~/.dsh/skills/<name>/SKILL.md` |
 
 ## 已知限制
@@ -181,7 +205,9 @@ pnpm remove @omdp/dsh-connector
 | 问题 | 原因 / 解决 |
 |---|---|
 | 设置页看不到 Connector 标签 | bundle 未挂载：确认 `dsh.profile.bundles` 含 `@omdp/dsh-connector`，重启 dsh；仍无则检查 client.js 尾部 `exports.inject = ['slots']` 是否在（缺了会静默丢注册） |
-| 工具过滤不生效（模型仍能看到/调用） | 过滤规则只对**新会话**生效（当前会话的 schema 已下发）；确认 settings.yaml 有 `connector.toolFilters` 且 serverName 拼写与 patch 一致 |
+| 工具过滤不生效（模型仍能看到/调用） | 过滤规则只对**新会话**生效（当前会话的 schema 已下发）；确认规则落盘位置正确——0.1.7+ 看 profile 条目 `connector` 的 `config.toolFilters`，rc.x 看 `~/.dsh/settings.yaml` 的 `connector.toolFilters`；再确认 serverName 拼写与 patch 一致 |
+| 升级 0.1.7 后勾好的工具过滤变回全量放行 | 0.1.7 的配置迁移会静默漏掉未声明 volatile `Config` 的段，规则被留在 `~/.dsh/settings.yaml.imported` 里；0.3.4 的 `ensureLegacyFiltersMigration()` 会在首次请求时自动搬回（日志 `migrated toolFilters from settings.yaml.imported`）。**不要删 `settings.yaml.imported`**——它是遗留配置的唯一副本。若仍未恢复，用 `PUT /connector/api/mcp/filters` 手写一次即可 |
+| 升级 DSH 后设置页整页丢失 Connector 标签、`/connector/api/*` 全 404 | 先查启动日志有无 `skipping profile bundle "@omdp/dsh-connector"`——这是 0.1.7 起的**兼容性门禁**拦下了尚未核查的 DSH 版本（见「## 兼容性门禁」）。核查通过后把该版本追加进 `peerDependencies["@deepseek-ai/dsh"]` 枚举 |
 | 保存 MCP 被拒（HTTP 400） | 配置不合法（transport/serverName/command/url 校验失败），按提示修正——插件不会写入坏配置 |
 | MCP server 保存后不生效 | 需**重启 dsh**（`dsh-mcp-client` 静态加载） |
 | `/connector/api/*` 404 | client/host 边界异常：确认插件 host 半边已加载（重启），浏览器强刷缓存 |
@@ -228,9 +254,9 @@ MIT License。安全问题请通过 GitHub Issues 私密报告（https://github.
 
 | 数据 | 访问方式 | 说明 |
 |---|---|---|
-| `profiles/web/cordis.patch.yml` | **读写** | MCP 块的结构化编辑（保留 `!!js`/env 原样） |
+| `profiles/web/cordis.patch.yml` | **读写** | MCP 块的结构化编辑（保留 `!!js`/env 原样）；0.1.7+ 工具过滤规则也由 DSH settings 服务写回本行 `config.toolFilters` |
 | `~/.dsh/skills/**/SKILL.md` | **读写** | 用户技能文件的查看/编辑/删除/新建；「记录来源」会写 `source`/`sourceUpdated` frontmatter |
-| `~/.dsh/settings.yaml` 等 | 只读 | 不主动读写 |
+| `~/.dsh/settings.yaml` 等 | rc.x 经 settings 服务读；0.1.7+ **只读** `settings.yaml.imported` 做一次性救援 | 0.1.7+ 不再直接读写活动配置（DSH 已改为 profile 条目托管）；`.imported` 是遗留配置唯一副本，**永不删除** |
 | HTTP `/connector/api/*` | 本机监听 | 与 DSH GUI 同源，无额外鉴权 |
 | 魔搭 `modelscope.cn/openapi/v1` | **只读外部** | 市场浏览代理（匿名）；结果仅存进程内存（30 分钟 TTL），**不写文件、不落盘** |
 | 环境变量 | 只读引用 | 只读 `process.env.*`，不持久化 |
@@ -241,10 +267,44 @@ MIT License。安全问题请通过 GitHub Issues 私密报告（https://github.
 
 本插件采用**抗崩溃架构**，DSH 更新时不会导致 DSH 崩溃（硬保证）。
 
-- **纯静态依赖**：只 `import node:*` + `yaml`（唯一第三方依赖，版本 `^2.9.0`），**零 `@deepseek-ai/*` 依赖**（`@deepseek-ai/schemastery` 仅 peer 声明，供工具过滤的 settings schema 用，无则过滤静默全放行）。
+- **纯静态依赖**：只 `import node:*` + `yaml`（`^2.9.0`）；`jsdom`（`^24.1.3`）**只在魔搭 WAF 挑战求解时动态 `import()`**，不在模块顶层加载（见下方 0.1.7 说明）。`@deepseek-ai/schemastery` 仅 peer 声明（供工具过滤的 Config 声明用），且用 `typeof field.volatile === 'function'` 守卫，具备则走 0.1.7+ 托管配置。
 - **唯一的 DSH 硬依赖**：`ctx.webServer`（`inject: ['webServer']`），用于注册 `/connector/api/*` HTTP 路由。
 - **失败隔离**：webServer 不可用/变化时插件**干净失败不加载**，DSH 照常运行；内部多处 try/catch 防御。
 
+### 为什么 jsdom 必须懒加载（0.3.3 修复）
+
+0.3.2 在模块顶层 `import { JSDOM, VirtualConsole } from 'jsdom'`，这会在插件 import 期就拉起
+`jsdom → whatwg-url → tr46` 依赖图，而 `tr46/index.js` 第 3 行是 `require("punycode/")`。
+DSH `0.1.7-rc.1` 的解析路由（`dsh-app-boot` `ResolutionRouter.routeScoped`）对 `punycode/`
+这种**带子路径的内置模块名**会先切出裸名 `punycode`，再用
+`createRequire(...).resolve.paths("punycode")` 求查找路径 —— Node 对裸内置模块名返回
+`null`，而该处循环没有兜底，直接抛：
+
+```
+TypeError: createRequire.resolve.paths is not a function or its return value is not iterable
+    at ResolutionRouter.routeScoped (…/dsh-app-boot/lib/index.js:1414:58)
+```
+
+后果不是"市场功能不可用"，而是**整个插件的 import 失败**：fiber 建不起来，设置页那行永远停在
+「已安装，重启后生效」，`/connector/api/*` 全部 404（重启也不会好，因为抛错是确定性的）。
+修复即把 jsdom 挪进 `loadJsdom()`，只在真正要解 WAF 挑战时才 `await import('jsdom')`，
+失败范围收敛到该功能本身。
+
+> ⚠️ **诚实说明：这是缓解，不是根治。** DSH 的解析拦截（`PluginPackages` 安装的
+> `installRuntimeInterception`）在**进程生命周期内常驻**（只在 `ctx.effect` 清理时 `dispose()`），
+> 所以懒加载只是把同一个 `TypeError` **推迟到首次解 WAF 挑战时**，并非消除：
+>
+> | | 0.3.2（顶层静态 import） | 0.3.3（懒加载） |
+> |---|---|---|
+> | 插件 import | ❌ 崩溃 ⇒ 设置页死的、全部路由 404 | ✅ 干净 |
+> | 设置页 / MCP / Skills / 工具过滤 | ❌ 全废 | ✅ 恢复 |
+> | 魔搭市场浏览（走 WAF 解） | ❌（插件都没起来） | ⚠️ 首次解挑战仍会抛，但被 `marketError` 包成 **502 + 明确 message**，不挂起 |
+> | 爆炸半径 | 整个插件 | 单个功能分支 |
+>
+> 实测该 WAF 挑战当前**未下发**（`PUT /api/v1/dolphin/mcpServers` 返回 HTTP 200、116103 字节、
+> 无 `acw_sc__v2`/`aliyunwaf`），故该路径处于休眠。**根治仍应由 DSH 在 `dsh-app-boot` 的该循环
+> 补 `?? []` 兜底**（同文件 `packageDirFromAnchor` 是有兜底的，新增 `routeScoped` 时漏了）。
+
 | 场景 | 崩溃？ |
 |---|---|
 | DSH 小更新/补丁 | ✅ 不会崩 |
@@ -252,6 +312,40 @@ MIT License。安全问题请通过 GitHub Issues 私密报告（https://github.
 | yaml 版本 | ✅ 独立 npm 包，不受 DSH 更新影响 |
 | 魔搭市场不可达 | ✅ 市场接口报 502，本地 MCP/skill 管理不受影响 |
 
-**最后验证**：DSH `0.1.0-rc.8`（2026-08-20）；0.2.0 市场功能以 `node --check` +
-真实 HTTP 集成测试通过（11 项：skills/mcp 列表与详情、证书/Hosted 标识、安装命令、
-记录来源回写、更新判定），未改动 DSH 实例。当前 npm 版本 `0.3.0`。
+**最后验证**：DSH `0.1.7-rc.1`（2026-09-24，本轮修复：模块 import 期零抛错，`node --check` + 实际
+`import()` 冒烟通过；工具过滤读写改用 0.1.7 的 `Config`+`.volatile()`+`settings.replace()`；
+0.3.4 追加 `@deepseek-ai/dsh` peer 声明并用 DSH 真实 `evaluatePluginCompatibility()` 验证门禁行为、
+追加遗留 `toolFilters` 一次性救援）。历史：
+DSH `0.1.0-rc.8`（2026-08-20）；0.2.0 市场功能以 `node --check` + 真实 HTTP 集成测试通过（11 项：
+skills/mcp 列表与详情、证书/Hosted 标识、安装命令、记录来源回写、更新判定），未改动 DSH 实例。
+
+## 变更记录
+
+- **0.3.4**（2026-09-24）：**声明 DSH 版本支持 + 修复工具过滤被静默清空**。
+  1. **`@deepseek-ai/dsh` peer 声明 `0.1.7-rc.1`**（逐版本枚举，语义见上方「## 兼容性门禁」）。
+     用 DSH 真实的 `evaluatePluginCompatibility()` 逐一验证：`0.1.7-rc.1` → 正常加载；
+     `0.1.7-alpha.2` / `0.1.6-alpha.1` / `0.1.5-rc.3` / `0.1.8-rc.1` → 被门禁拦下（前者是老运行时
+     无门禁、后者是未实测的新版本，均符合规范 3）。
+  2. **修复工具过滤丢失（根因：DSH 0.1.7 的配置迁移是「全有或全无」）** —— 0.1.7 首次启动会把
+     `<DSH_HOME>/settings.yaml` 改名为 `settings.yaml.imported` 并逐段导入 profile 条目；该导入
+     对**没有 volatile `Config` 声明的段**会**静默跳过**（只往 stderr 打一行 `settings: section …
+     was not imported`）。本插件 0.3.3 才刚引入 `Config`，所以用户机器上 `connector.toolFilters`
+     被落在 `settings.yaml.imported` 里没搬过来 ⇒ 过滤规则读成空 ⇒ **全量放行**（表现为
+     「设置页里勾的过滤没了」）。
+     修复：新增 `ensureLegacyFiltersMigration()`，在**路由处理前**（`apply()` 期间 `settings.replace()`
+     不可用，因为该条目 fiber 尚未进入 ACTIVE 状态）检查一次——若活的 `config.toolFilters` 为空、
+     而 `settings.yaml.imported` 里还留着 `connector.toolFilters`，就把它写回本插件的 profile 条目
+     并打一行 `migrated toolFilters from settings.yaml.imported`。失败时复位重试标记，下一次请求再试。
+     一次性且幂等：已有非空过滤规则时**不覆盖用户当前设置**。
+  3. `settings.yaml.imported` **只读、绝不删除**——它是遗留配置的唯一副本（0.1.7 迁移后就地改名，
+     原始 `settings.yaml` 已不存在；DSH 内置导入器见到 `.imported` 不会再跑）。
+
+- **0.3.3**（2026-09-24）：**适配 DSH 0.1.7-rc.1**。
+  1. **修复 import 期崩溃**：`jsdom` 由顶层静态 import 改为按需 `await import()`（原因见上方
+     「为什么 jsdom 必须懒加载」）——0.3.2 在 0.1.7 上整个插件 import 失败、设置页永远显示
+     「已安装，重启后生效」、API 全 404。
+  2. **工具过滤迁到 0.1.7 托管配置**：导出 `Config = z.object({ toolFilters: <dict>.volatile() })`，
+     读取走注入的 `config.toolFilters` 活 Ref、写入走 `settings.replace(entryId, …)`；同时对
+     0.1.5/0.1.6 rc.x 保留老的 `settings.register/get/update` 后端（`typeof volatile === 'function'`
+     守卫自动分流），**新旧两代均可用**。
+  3. 补 `@deepseek-ai/schemastery` peer 枚举 `3.18.4`（0.1.7 自带版本）。

package/index.js

@@ -26,8 +26,16 @@ import { spawnSync } from 'node:child_process'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
-import { JSDOM, VirtualConsole } from 'jsdom'
 import z from '@deepseek-ai/schemastery'
+// NOTE: `jsdom` is deliberately NOT imported at module scope. A static import
+// pulls in jsdom -> whatwg-url -> tr46, and tr46/index.js:3 does
+// `require("punycode/")`. Under DSH 0.1.7's ResolutionRouter that subpath form
+// resolves `createRequire(...).resolve.paths("punycode")` to null, which the
+// router iterates without a guard (dsh-app-boot/lib/index.js:1414) and throws
+// `TypeError: createRequire.resolve.paths is not a function or its return value
+// is not iterable` — killing this whole plugin's import (fiber never created,
+// UI shows "已安装，重启后生效"). Only the ModelScope WAF challenge needs jsdom,
+// so it is loaded lazily there and the failure is local to that feature.
 
 const API_PREFIX = '/connector/api'
 const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
@@ -41,12 +49,14 @@ const TRANSPORTS = new Set(['stdio', 'streamable-http'])
 // patch file itself (NUL, control chars). Tab/newline are already rejected by
 // the single-token rules; this catches the rest defensively.
 const CONTROL_CHARS = /[\x00-\x1f\x7f]/
+// 0.1.7 移除了 settings.register/get/update；`settings` 服务本身仍需存在（本插件的
+// Config 条目才会进入组合树并被托管），且老版本（0.1.5/0.1.6 rc.x）仍走它的
+// register/get/update 老 API，所以 inject 保留。
 export const inject = ['webServer', 'settings']
 
 // ── MCP 工具过滤（tool-filter, 0.3.0 新增）────────────────────────────
 // dsh-mcp-client 的 Config schema 是封闭的：未知键会拒收并导致下次启动失败，
-// 所以过滤规则不能写进 mcp-* 行的 config，只能放在 connector 自己的 settings
-// namespace（settings.yaml `connector:` 节）里：
+// 所以过滤规则不能写进 mcp-* 行的 config，只能放在 connector 自己的配置里：
 //   connector:
 //     toolFilters:
 //       <serverName>:
@@ -56,25 +66,107 @@ export const inject = ['webServer', 'settings']
 //   1. systemPrompt.tools(provider) —— 提示词里的 schema 列表先过滤，模型看不到被滤掉的工具；
 //   2. ctx.tools.guard —— 执行期硬拦截（guard 返回 reason 即拒收），补 provider 漏网；
 //   3. UI 多选框 —— 见 client.js ServerForm 的工具过滤区 + GET /api/mcp/tools/:serverName。
-// 无配置 = 全量放行（零回归）；guard 是同步函数，读的是 apply 时缓存 + watch 刷新的快照。
+// 无配置 = 全量放行（零回归）；guard 是同步函数，每次调用现读最新值。
+//
+// 配置后端是双版本的（同 dsh-key-fallback 的做法）：
+//   · 0.1.7+：DSH 用 settings 服务托管插件配置 —— 本插件导出带 `.volatile()` 的
+//     `Config`，apply(ctx, config) 拿到的 config.toolFilters 是一个活 Ref，读写走
+//     `settings.replace(entryId, ...)`；
+//   · 0.1.5/0.1.6（rc.x）：无 `.volatile()`，`Config` 退化为 undefined，改用老的
+//     `settings.register(ns, schema)` + `settings.get(ns)` + `settings.update(ns, ...)`。
+// 两条路都在 apply 时判别一次，之后读写自动分流；都没有时静默全放行。
+// Profile entry id of this plugin (the `id:` in the bundle's cordis.patch.yml,
+// which the user's own profile patch keeps unless they override the row). The
+// settings service addresses config by entry id, not by settings namespace.
 const CONNECTOR_SETTINGS_NS = 'connector'
+const CONNECTOR_ENTRY_ID = 'connector'
 const ToolFilterSchema = z.object({
   toolFilters: z.dict(z.object({ allow: z.array(String).default([]) })).default({}),
 })
-function readToolFilters(ctx) {
+// DSH 0.1.7+ hands a `.volatile()` field to apply() as a live Ref; 0.1.6 and older
+// lack `volatile`, so Config degrades to undefined and the legacy path is used.
+const _toolFiltersField = z.dict(z.object({ allow: z.array(String).default([]) })).default({})
+export const Config = (typeof _toolFiltersField.volatile === 'function')
+  ? z.object({ toolFilters: _toolFiltersField.volatile() })
+  : undefined
+// 后端状态：二选一（0.1.7+ 用 _filterRef；rc.x 用 _legacyScope/_legacySvc），都用空表示全放行。
+let _filterRef = null     // 0.1.7+: config.toolFilters 这个活 Ref
+let _legacyScope = null   // rc.x: settings.register(...) 返回的 scope
+let _legacySvc = null     // rc.x: settings 服务（读用 get，写用 update）
+let _settingsSvc = null   // 0.1.7+: ctx.settings（迁移写回用，见 ensureLegacyFiltersMigration）
+let _migrationAttempted = false
+function readToolFilters() {
   try {
-    const settings = ctx.get('settings')
-    const value = settings ? settings.get(CONNECTOR_SETTINGS_NS) : undefined
-    const filters = value && typeof value === 'object' ? value.toolFilters : undefined
-    if (!filters || typeof filters !== 'object' || Array.isArray(filters)) return {}
-    const out = {}
-    for (const [server, rule] of Object.entries(filters)) {
-      const allow = rule && Array.isArray(rule.allow) ? rule.allow.filter((t) => typeof t === 'string' && t.length > 0) : []
-      out[server] = { allow }
+    // 优先 0.1.7+ 的活 Ref（.get() 每次返回最新值）
+    if (_filterRef) {
+      const value = _filterRef.get()
+      return normalizeToolFilters(value)
+    }
+    // rc.x：老的 settings.get(ns) —— 每次现读，外部编辑同样立即生效
+    if (_legacySvc && typeof _legacySvc.get === 'function') {
+      const value = _legacySvc.get(CONNECTOR_SETTINGS_NS)
+      return normalizeToolFilters(value && value.toolFilters)
     }
-    return out
+    return {}
   } catch { return {} }
 }
+function normalizeToolFilters(filters) {
+  if (!filters || typeof filters !== 'object' || Array.isArray(filters)) return {}
+  const out = {}
+  for (const [server, rule] of Object.entries(filters)) {
+    const allow = rule && Array.isArray(rule.allow) ? rule.allow.filter((t) => typeof t === 'string' && t.length > 0) : []
+    out[server] = { allow }
+  }
+  return out
+}
+
+/* ── 0.1.7 迁移遗留救援 ──────────────────────────────────────────────────────
+ * DSH 0.1.7 启动时把 <home>/settings.yaml 改名为 settings.yaml.imported，再把每个
+ * section 当作对应 entry 的 config override 调 settings.update(ns, values) 写回。
+ * 而 update() 走 write()，要求该 entry 的 Config 含 volatile 字段，否则抛
+ * 「Config field ... is not volatile」，只打一条 warn 就跳过——配置静默留在
+ * .imported 里，插件再也看不到它（UI 显示「未配置 = 全量放行」，用户以为改动被吞）。
+ *
+ * 本插件 0.3.2 及更早没有 volatile 的 toolFilters，升级 0.1.7 时用户的过滤规则
+ * 就是这样丢的。0.3.3 补上了 volatile Config（写入通道已通），但已经丢过一次的
+ * 数据不会自己回来，所以这里做一次性救援：把滞留在 .imported 的 connector 节
+ * 搬进 profile entry 的 config（即 cordis.patch.yml 的 connector 行）。
+ *
+ * 时序：settings.replace() 要求该 entry 的 fiber 处于 ACTIVE(2)——apply() 期间
+ * 还没到，所以这里只在惰性调用（首次读 filters 的路由）里跑，绝不放进 apply()。
+ * 语义：只搬一次；本插件已有配置时不动（避免覆盖用户后来的修改）；失败不抛错
+ * （GET 必须可用），留给下一次请求重试。
+ */
+async function ensureLegacyFiltersMigration() {
+  if (_migrationAttempted) return
+  _migrationAttempted = true
+  try {
+    if (!_filterRef || !_settingsSvc || typeof _settingsSvc.replace !== 'function') return
+    // 已有配置 → 用户在新后端上配过了，不要覆盖。
+    const existing = normalizeToolFilters(_filterRef.get())
+    if (Object.keys(existing).length > 0) return
+    // 读遗留文档：不存在 = 全新安装或已被内置导入器处理过，无事可做。
+    let text
+    try {
+      text = await readFile(join(resolveHome(), 'settings.yaml.imported'), 'utf8')
+    } catch {
+      return
+    }
+    let doc
+    try { doc = parseYaml(text) } catch { return }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return
+    const block = doc[CONNECTOR_SETTINGS_NS]
+    const migrated = normalizeToolFilters(block && block.toolFilters)
+    if (Object.keys(migrated).length === 0) return
+    await _settingsSvc.replace(CONNECTOR_ENTRY_ID, { toolFilters: migrated })
+    console.info('[dsh-connector] migrated toolFilters from settings.yaml.imported:', Object.keys(migrated).join(', '))
+  } catch (error) {
+    // 写失败（entry 尚未 ACTIVE、revision 冲突等）：清标记让下一次请求重试，
+    // 否则一次过早的调用会永久放弃救援。
+    _migrationAttempted = false
+    console.warn('[dsh-connector] toolFilters migration skipped:', error?.message ?? error)
+  }
+}
 // 公开名 `mcp__<server>__<raw>` 反解回 (server, raw)：注意 serverName 本身可含
 // 下划线，所以按 `mcp__` 前缀 + __ 分段取“第一段”为 server，余下 join 回 raw。
 function splitPublicName(publicName) {
@@ -540,8 +632,17 @@ let wafCookie = null // { value, at }
 // Solve the acw_sc__v2 cookie by executing the challenge page in jsdom. The
 // challenge HTML arrives as the body of the WAF-blocked request itself (the
 // SPA shell on /mcp is NOT a challenge page and yields no cookie).
+// jsdom is imported lazily on purpose — see the note next to the import list.
+let _jsdom = null
+async function loadJsdom() {
+  if (_jsdom) return _jsdom
+  const mod = await import('jsdom')
+  _jsdom = mod.default && mod.default.JSDOM ? mod.default : mod
+  return _jsdom
+}
 async function solveWafFromChallenge(html) {
   if (wafCookie && Date.now() - wafCookie.at < WAF_TTL) return wafCookie.value
+  const { JSDOM, VirtualConsole } = await loadJsdom()
   const vc = new VirtualConsole()
   vc.on('jsdomError', () => {}) // jsdom navigation is not implemented — that is expected here
   const dom = new JSDOM(html, {
@@ -922,23 +1023,38 @@ async function readBody(req) {
   }
 }
 
-export function apply(ctx) {
-  // ── 工具过滤三件套之 (0)：settings namespace 注册 + 快照缓存 ──
-  // settings 经声明式 inject 依赖保证就绪（见上方 export const inject），
-  // 这里同步拿服务；万一缺失不炸，过滤保持全放行（零回归）。
+export function apply(ctx, config) {
+  // ── 工具过滤三件套之 (0)：判定配置后端 + 快照缓存 ──
+  // 0.1.7+：config.toolFilters 是 volatile Ref（.get() 每次返回最新值，编辑热生效）。
+  // rc.x：无 volatile，退回老的 settings.register/get/update（0.3.0 的原始实现）。
+  // 两者皆无 → 恒 {} 全放行（零回归）。
   // 注：cordis 的 ctx.inject(deps, cb) 回调按 (ctx, config) 调用，不是服务展开，
   // 不能拿回调参数当 service 用 —— 0.3.0 曾因此 register 从未落地。
-  const settings = ctx.get('settings')
-  let toolFilters = {}
-  const refreshFilters = () => { toolFilters = readToolFilters(ctx) }
-  if (settings) {
-    try {
-      const scope = settings.register(CONNECTOR_SETTINGS_NS, ToolFilterSchema, { base: { toolFilters: {} } })
-      refreshFilters()
-      ctx.effect(() => scope.watch(() => refreshFilters()), 'connector: watch tool filters')
-    } catch (error) {
-      console.error('[dsh-connector] register tool filter settings failed:', error?.message ?? error)
+  const currentFilters = () => {
+    try { return readToolFilters() } catch { return {} }
+  }
+  try {
+    const field = config && config.toolFilters
+    if (field && typeof field.get === 'function') {
+      _filterRef = field
+      _settingsSvc = ctx.get('settings') || null
+      ctx.effect(() => () => { _filterRef = null; _settingsSvc = null }, 'connector: release tool filter ref')
+    } else {
+      // ── rc.x 老后端：注册 settings namespace（本插件自己的两段式配置）──
+      const settings = ctx.get('settings')
+      if (settings && typeof settings.register === 'function') {
+        const scope = settings.register(CONNECTOR_SETTINGS_NS, ToolFilterSchema, { base: { toolFilters: {} } })
+        _legacySvc = settings
+        _legacyScope = scope
+        ctx.effect(() => () => { _legacySvc = null; _legacyScope = null }, 'connector: release legacy tool filter scope')
+        // scope 存在时用它的 watch 做热刷新（0.3.0 的行为）；读仍走 settings.get。
+        if (scope && typeof scope.watch === 'function') {
+          ctx.effect(() => scope.watch(() => {}), 'connector: watch tool filters')
+        }
+      }
     }
+  } catch (error) {
+    console.error('[dsh-connector] tool filter config unavailable:', error?.message ?? error)
   }
 
   // ── 三件套之 (1)：prompt 层过滤 —— assemble waterfall 真替换 ──
@@ -950,7 +1066,7 @@ export function apply(ctx) {
     ctx.on('system-prompt/assemble', async (_assembly, _context, next) => {
       const assembled = await next()
       if (!assembled || !Array.isArray(assembled.tools)) return assembled
-      const kept = assembled.tools.filter((t) => isToolAllowed(toolFilters, t && t.name))
+      const kept = assembled.tools.filter((t) => isToolAllowed(currentFilters(), t && t.name))
       if (kept.length === assembled.tools.length) return assembled
       return { ...assembled, tools: kept }
     }, { global: true })
@@ -961,7 +1077,7 @@ export function apply(ctx) {
     if (tools && typeof tools.guard === 'function') {
       ctx.effect(() => tools.guard((exec) => {
         if (!exec || typeof exec.name !== 'string') return undefined
-        if (isToolAllowed(toolFilters, exec.name)) return undefined
+        if (isToolAllowed(currentFilters(), exec.name)) return undefined
         const split = splitPublicName(exec.name)
         return `connector: 工具 ${exec.name} 已被过滤（server "${split ? split.server : '?'}” 的 allow 列表未包含它）`
       }), 'connector: mcp tool filter guard')
@@ -974,6 +1090,11 @@ export function apply(ctx) {
     try {
       if (!path.startsWith(API_PREFIX)) { res.writeHead(404); res.end(); return }
 
+      // 首次请求时救援 0.1.7 迁移遗留的 toolFilters（见 ensureLegacyFiltersMigration）。
+      // 放在这里而不是 apply()：settings.replace() 要求本 entry 已 ACTIVE。
+      // 成功后 _migrationAttempted 短路，后续请求零开销。
+      await ensureLegacyFiltersMigration()
+
       // GET /api/mcp — list server entries (with preserve buckets)
       if (req.method === 'GET' && path === API_PREFIX + '/mcp') {
         let text
@@ -1058,14 +1179,14 @@ export function apply(ctx) {
         } catch (error) {
           return json(res, 500, { error: String(error?.message ?? error).slice(0, 200) })
         }
-        const filters = readToolFilters(ctx)
+        const filters = readToolFilters()
         const rule = filters[serverName]
         return json(res, 200, { server: serverName, tools: names.sort(), allow: rule ? rule.allow : [] })
       }
 
       // GET /api/mcp/filters — 全部 server 的过滤规则（UI 批量展示用）
       if (req.method === 'GET' && path === API_PREFIX + '/mcp/filters') {
-        return json(res, 200, { filters: readToolFilters(ctx) })
+        return json(res, 200, { filters: readToolFilters() })
       }
 
       // PUT /api/mcp/filters — 保存过滤规则 → settings.yaml `connector:` 节
@@ -1092,13 +1213,24 @@ export function apply(ctx) {
         }
         try {
           const settings = ctx.get('settings')
-          if (!settings) return json(res, 503, { error: 'settings service unavailable' })
-          await settings.update(CONNECTOR_SETTINGS_NS, { toolFilters: clean })
+          if (_filterRef) {
+            // 0.1.7+：settings 服务托管配置。replace() 先清空本 entry 的全部 volatile
+            // 字段再写入本节：toolFilters 是唯一 volatile 字段，所以等价于「整节覆盖」，
+            // 空 allow 的 server 已被上面清掉。
+            if (!settings || typeof settings.replace !== 'function') {
+              return json(res, 503, { error: 'settings service unavailable (DSH 0.1.7+ required to persist tool filters)' })
+            }
+            await settings.replace(CONNECTOR_ENTRY_ID, { toolFilters: clean })
+          } else if (_legacySvc && typeof _legacySvc.update === 'function') {
+            // rc.x：老的命名空间写入（settings.yaml `connector:` 节）
+            await _legacySvc.update(CONNECTOR_SETTINGS_NS, { toolFilters: clean })
+          } else {
+            return json(res, 503, { error: 'settings service unavailable; cannot persist tool filters' })
+          }
         } catch (error) {
           return json(res, 500, { error: String(error?.message ?? error).slice(0, 300) })
         }
-        refreshFilters()
-        return json(res, 200, { ok: true, filters: readToolFilters(ctx) })
+        return json(res, 200, { ok: true, filters: readToolFilters() })
       }
 
       // GET /api/skills — list

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omdp/dsh-connector",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Unified DeepSeek Harness connector: edit MCP servers (cordis.patch.yml), user skills (~/.dsh/skills) and browse the ModelScope MCP/Skills marketplaces from one Web UI settings page.",
   "type": "module",
   "main": "index.js",
@@ -46,6 +46,7 @@
     "jsdom": "^24.1.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/schemastery": "3.18.1 || 3.18.2"
+    "@deepseek-ai/dsh": "0.1.7-rc.1",
+    "@deepseek-ai/schemastery": "3.18.1 || 3.18.2 || 3.18.4"
   }
 }