@omdp/dsh-connector 0.3.2 → 0.3.3

package/README.md

@@ -1,12 +1,13 @@
 # @omdp/dsh-connector
 
-**MCP 服务器 + 用户 Skills + 魔搭市场浏览三合一设置页**（`v0.3.0`）。适合需要在 DSH 里频繁增删改 MCP server / skills、又不想手改 `cordis.patch.yml` 的用户。
+**MCP 服务器 + 用户 Skills + 魔搭市场浏览三合一设置页**（`v0.3.3`）。适合需要在 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）
 
 ## Overview
 
@@ -14,7 +15,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 官方托管 / 已认证）
@@ -144,7 +145,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 +164,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 +182,7 @@ 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 一致 |
 | 保存 MCP 被拒（HTTP 400） | 配置不合法（transport/serverName/command/url 校验失败），按提示修正——插件不会写入坏配置 |
 | MCP server 保存后不生效 | 需**重启 dsh**（`dsh-mcp-client` 静态加载） |
 | `/connector/api/*` 404 | client/host 边界异常：确认插件 host 半边已加载（重启），浏览器强刷缓存 |
@@ -228,9 +229,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+ 不再直接读写该文件（DSH 已改为 profile 条目托管） |
 | HTTP `/connector/api/*` | 本机监听 | 与 DSH GUI 同源，无额外鉴权 |
 | 魔搭 `modelscope.cn/openapi/v1` | **只读外部** | 市场浏览代理（匿名）；结果仅存进程内存（30 分钟 TTL），**不写文件、不落盘** |
 | 环境变量 | 只读引用 | 只读 `process.env.*`，不持久化 |
@@ -241,10 +242,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 +287,19 @@ 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()`）。历史：
+DSH `0.1.0-rc.8`（2026-08-20）；0.2.0 市场功能以 `node --check` + 真实 HTTP 集成测试通过（11 项：
+skills/mcp 列表与详情、证书/Hosted 标识、安装命令、记录来源回写、更新判定），未改动 DSH 实例。
+
+## 变更记录
+
+- **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,57 @@ 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）
+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
+}
 // 公开名 `mcp__<server>__<raw>` 反解回 (server, raw)：注意 serverName 本身可含
 // 下划线，所以按 `mcp__` 前缀 + __ 分段取“第一段”为 server，余下 join 回 raw。
 function splitPublicName(publicName) {
@@ -540,8 +582,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 +973,37 @@ 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
+      ctx.effect(() => () => { _filterRef = 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 +1015,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 +1026,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')
@@ -1058,14 +1123,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 +1157,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.3",
   "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,6 @@
     "jsdom": "^24.1.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/schemastery": "3.18.1 || 3.18.2"
+    "@deepseek-ai/schemastery": "3.18.1 || 3.18.2 || 3.18.4"
   }
 }