dsh-agy-swarm 0.1.0 → 0.1.1

package/README.md

@@ -137,12 +137,13 @@ docs/                     配置、参考、开发与变更日志
 
 ```bash
 npm run check                                   # 全量 node --check
-npm test                                        # 离线主套件（含内置 ACP 替身）
+npm test                                        # 离线主套件（含内置 ACP 替身；Windows 沙盒用）
+npm run test:ci                                 # 同一套件的 CI 版，不带 --test-isolation
 npm run test:acp-integration                    # 可选：真实 dsh-agy-acp 端到端
 npm pack --dry-run --json                       # 打包清单预演
 ```
 
-Windows 沙盒环境跑 `node --test` 必须带 `--test-isolation=none`（子进程命名管道在受限令牌下会 `spawn EPERM`）。
+Windows 沙盒环境跑 `node --test` 必须带 `--test-isolation=none`（子进程命名管道在受限令牌下会 `spawn EPERM`）；Linux / macOS 反而不能带（Node 22.13 之前不认该参数，会以 `exit code 9` 失败），CI 因此统一走 `npm run test:ci`。
 
 ## 许可
 

package/client.js

@@ -235,6 +235,20 @@
     return value !== null && typeof value === 'object' && !Array.isArray(value);
   }
 
+  /**
+   * 解包一元 Remote（Remote 直调）调用的宿主响应信封。
+   *
+   * `@deepseek-ai/dsh-api-gateway` 会把一元 Remote 的结果包成 `{ ok: true, value }`；
+   * 插件自带的 `SwarmRemoteServiceFallback`（以及离线单测里的替身）直接返回裸结果。
+   * 两种形态都必须接受，否则带信封的响应会被 `parseSwarmModelsResult` /
+   * `normalizeSwarmSnapshot` 判成非法载荷（典型症状：设置页报
+   * "models must be an array"）。
+   */
+  function unwrapRemoteResult(res) {
+    if (isPlainObject(res) && res.ok === true && 'value' in res && res.value !== undefined) return res.value;
+    return res;
+  }
+
   function safeDecodeSegment(segment) {
     if (typeof segment !== 'string' || segment === '') return null;
     try {
@@ -1307,6 +1321,22 @@
     return String(error);
   }
 
+  /**
+   * 模型目录拉取失败的原因摘要：压成单行并限长，只用于设置页 status 的 tooltip，
+   * 既方便排查（例如宿主流未挂载 / 协议校验失败），又不会把长堆栈塞进 DOM。
+   */
+  function describeModelsError(error) {
+    let text = '';
+    try {
+      text = formatErrorMessage(error);
+    } catch {
+      text = '';
+    }
+    text = String(text || '').replace(/\s+/g, ' ').trim();
+    if (!text) return 'unknown error';
+    return text.length > 240 ? text.slice(0, 237) + '...' : text;
+  }
+
   function makeRemoteFailureFrame(code, message, details) {
     const error = new Error(message);
     error.name = 'RemoteError';
@@ -1469,6 +1499,8 @@
         Array.isArray(props?.models) ? props.models.map(normalizeSwarmModelEntry) : null
       );
       const [modelsStatus, setModelsStatus] = useState('');
+      /** 拉取失败时的可读原因（单行摘要，挂在 status 的 tooltip 上，不阻塞设置页）。 */
+      const [modelsError, setModelsError] = useState('');
       const loadModels = typeof props?.loadModels === 'function' ? props.loadModels : null;
       useEffect(() => {
         if (!loadModels) return undefined;
@@ -1479,10 +1511,12 @@
             if (cancelled || !alive.current) return;
             setDiscoveredModels(Array.isArray(list) ? list.map(normalizeSwarmModelEntry) : []);
             setModelsStatus('');
+            setModelsError('');
           })
-          .catch(() => {
+          .catch((error) => {
             if (cancelled || !alive.current) return;
             setModelsStatus('modelsUnavailable');
+            setModelsError(describeModelsError(error));
           });
         return () => {
           cancelled = true;
@@ -1689,9 +1723,13 @@
           if (!alive.current) return undefined;
           setDiscoveredModels(Array.isArray(list) ? list.map(normalizeSwarmModelEntry) : []);
           setModelsStatus('');
+          setModelsError('');
           return true;
-        } catch {
-          if (alive.current) setModelsStatus('modelsUnavailable');
+        } catch (error) {
+          if (alive.current) {
+            setModelsStatus('modelsUnavailable');
+            setModelsError(describeModelsError(error));
+          }
           return false;
         }
       };
@@ -1754,6 +1792,18 @@
       const manualDraft = Object.prototype.hasOwnProperty.call(drafts, 'manualModelRule')
         ? drafts.manualModelRule
         : '';
+      /**
+       * 模型目录状态行：文字只保留本地化摘要，失败原因放进 `title`（tooltip），
+       * 让用户能一眼看出是「宿主流未挂载」还是「协议校验失败」。
+       */
+      const modelsStatusText = modelsStatus
+        ? t(modelsStatus)
+        : (discoveredModels ? '' : t('modelsLoading'));
+      const modelsStatusProps = {
+        className: 'dsh-swarm-settings-status' + (modelsError ? ' is-error' : ''),
+        'data-role': 'models-status',
+        ...(modelsError ? { title: modelsError, 'data-models-error': modelsError } : {}),
+      };
 
       return h('section', { className: 'dsh-swarm-settings', 'data-settings-id': SWARM_SETTINGS_ID, 'aria-label': t('title') },
         h('h2', null, t('title')),
@@ -1798,8 +1848,7 @@
           h('p', { className: 'dsh-swarm-settings-hint', 'data-role': 'whitelist-hint' },
             whitelistMode ? t('whitelistHintOn') : t('whitelistHintOff')),
           h('div', { className: 'dsh-swarm-settings-row' },
-            h('p', { className: 'dsh-swarm-settings-status', 'data-role': 'models-status' },
-              modelsStatus ? t(modelsStatus) : (discoveredModels ? '' : t('modelsLoading'))),
+            h('p', modelsStatusProps, modelsStatusText),
             h('button', {
               type: 'button',
               className: 'dsh-swarm-settings-chip',
@@ -2165,7 +2214,8 @@
         if (!api || typeof api.getSwarmSnapshot !== 'function') {
           throw new Error('Host 端 dsh-swarm.getSwarmSnapshot 服务未就绪');
         }
-        const response = await api.getSwarmSnapshot({ sessionId });
+        // 宿主 api-gateway 会包 `{ ok: true, value }` 信封，先解包再做归一化。
+        const response = unwrapRemoteResult(await api.getSwarmSnapshot({ sessionId }));
         if (isPlainObject(response) && response.ok === false) {
           throw new Error(formatErrorMessage(response.error || response));
         }
@@ -3407,7 +3457,8 @@
           if (!api || typeof api.getSwarmModels !== 'function') {
             throw new Error('Host 端 dsh-swarm.getSwarmModels 服务未就绪');
           }
-          const response = await api.getSwarmModels({ probeAgy: false });
+          // 同 fetchSnapshotOnce：真实宿主的响应带 `{ ok: true, value }` 信封。
+          const response = unwrapRemoteResult(await api.getSwarmModels({ probeAgy: false }));
           if (isPlainObject(response) && response.ok === false) {
             throw new Error(formatErrorMessage(response.error || response));
           }
@@ -3545,6 +3596,8 @@
     parseSwarmResourceUri: parseSwarmAddress,
     parseSwarmRequest,
     normalizeSwarmSnapshot,
+    unwrapRemoteResult,
+    describeModelsError,
     tokenizeSwarmText,
     isLongSwarmMessage,
     getCollapsedPreviewText,

package/docs/changelog.md

@@ -1,12 +1,33 @@
 # 变更日志
 
-## 未发布
+## [0.1.1] - 2026-11-15
+
+### 修复 · 设置页「未能读取宿主模型列表」
+
+- 真实宿主 `@deepseek-ai/dsh-api-gateway` 的一元 Remote 调用在**成功**时返回 `{ ok: true, value: <payload> }` 信封（失败时 `{ ok: false, error }`）。此前设置页把整封响应当载荷直接交给 `parseSwarmModelsResult`，`Array.isArray(response.models)` 恒为假，于是永远报「未能读取宿主模型列表」并且只留下一句 `models must be an array` 的内部错误。
+- 新增 `unwrapRemoteResult(res)`：`isPlainObject(res) && res.ok === true && 'value' in res && res.value !== undefined` 时取 `res.value`，否则原样透传（插件自带的 `SwarmRemoteServiceFallback` 与离线单测替身返回裸结果，必须同样可用）。`loadSwarmModels` 与 `fetchSnapshotOnce` 统一先解包再交给校验 / 归一化函数。
+- 设置页仍拉取失败时保留简化可读的错误摘要（`modelsError`）：状态行文字维持本地化提示，真实原因（截断为单行 240 字内）挂在 `title` 与 `data-models-error` 上，便于区分「宿主流未挂载」与「协议校验失败」；拉取成功或重试成功即清空。
+- 新增回归：注入真实 `{ ok: true, value: { models: [...] } }` 信封给 `api.getSwarmModels`，设置页 `loadModels()` 必须解包返回全量模型；同时覆盖「裸结果透传」「失败信封不被误解包」与错误 tooltip 的出现 / 清空。
+
+### 修复 · Host 依赖加载脱节（`MODULE_NOT_FOUND` 退回 Fallback）
+
+- 桌面 Profile 里 `require('@deepseek-ai/dsh-typert-protocol')` / `dsh-tools` / `dsh-scope` / `dsh-llm` / `dsh-session` 全部 `MODULE_NOT_FOUND`：这些包只在 `<resourcesPath>/app.asar/dsh/node_modules` 里，插件目录解析不到，于是 `index.js` 静默退回手写 Fallback（工具定义、fork 种子、中继消息、Typert 远程服务全部降级）。
+- `runtime.js` 的宿主锚点升级：除环境变量与 `require.main` / `process.argv[1]` 外，新增 `<resourcesPath>/app.asar/{dsh,lib}` 锚点，并把入口文件所在目录的若干层祖先一并当锚点，覆盖桌面版 / CLI / 便携包布局，仍然零硬编码安装路径。
+- 新增 `runtime.requireHostModule(specifier)`：先普通 `require`（依赖被提升到 profile 的布局），失败则 `resolveHostModule` 定位宿主 `app.asar` 入口再 `require(entry)`；`ERR_REQUIRE_ESM`、asar 读取失败等一律返回 `null`（结果含失败一并缓存），调用方继续走兜底，**绝不因为可选依赖缺失而崩溃**。`index.js` 的 `tryRequire` 改为委托它；`loadSchemastery` 复用同一条链路。
+- `mountSwarmRemoteService` 加固：真实 `typertProto.Remote` 装饰器失败时退回手写 `remote-methods` 描述符；`new SwarmRemoteService(ctx)` 抛错（宿主 Cordis / Typert 契约漂移）时退回 `SwarmRemoteServiceFallback`；描述符定义失败也不再影响服务本身。
+- 纯 Node 离线单测零依赖兜底 100% 保留：无 `resourcesPath`、无 `@deepseek-ai/*` 时所有解析都返回 `null`，全部用例仍跑在兜底实现上。
+
+### 修复 · GitHub Actions 在 Node 22 报 `exit code 9`
+
+- `npm test` 里的 `--test-isolation=none` 是为 Windows 沙盒（命名管道 `spawn EPERM`）准备的；Linux/macOS 并不需要，而 Node 22.13 之前的版本不认这个参数，会以 `exit code 9`（Invalid Argument）直接失败。
+- `package.json` 新增 `"test:ci"`（不带 `--test-isolation`），保留 `"test"` 兼容 Windows 沙盒；`ci.yml` 与 `publish.yml` 的测试步改调 `npm run test:ci`。
+- Matrix 的 `22` 改为 `22.19`，对齐 `engines.node` 的 `^22.19.0`，避免 setup-node 拉到 22.13 以下的小版本。
 
 ### 修复 · 严格白名单空名单的权限反转
 
 - 新增持久化开关 `strictAllowlist`（默认 `false`）：白名单激活条件改为「`strictAllowlist === true` 或 `allowedModels` 非空」。此前「严格模式下取消最后一个勾选」会写入 `allowedModels: []`，被误判成「未启用白名单 → 全部放行」，权限方向反转；现在空名单一律**全禁**，报错明确提示「已启用严格白名单模式但允许列表为空」。
-- 设置页开关改为先写 `strictAllowlist` 再写 `allowedModels`（关闭时相反），任一步保存失败即回滚开关并显示保存失败，绝不停留在未落盘的开关状态。
-- 新增 4 项回归：取消最后一个勾选、移除最后一个白名单胶囊、空目录开启严格模式、保存失败不误显示。
+- 设置页开关与白名单写入路径均改为先持久化 `strictAllowlist` 再更新 `allowedModels`（包括 legacy 仅非空名单激活时清空最后一项，也会先钉住 `strictAllowlist: true`；关闭时先写 `strictAllowlist: false` 再清空），任一步保存失败即回滚到已持久化快照并显示保存失败，绝不停留在未落盘的开关状态。
+- 新增 5 项设置页回归（含取消最后一个勾选、移除最后一个白名单胶囊、空目录开启严格模式、legacy 仅非空名单清空、保存失败不误显示）以及对应 Host / 协议回归。
 
 ### 新增 · 可视化模型派发权限
 

package/docs/development.md

@@ -5,12 +5,14 @@
 - Node `^22.19.0 || >=24.0.0`
 - DSH 宿主（`engines.dsh: >=0.2.2-rc.1`）
 - Windows 沙盒下跑 `node --test` **必须**带 `--test-isolation=none`：受限令牌下子进程命名管道会 `spawn EPERM`
+- 反之 Linux / macOS（CI）不需要该参数，且 Node 22.13 之前不认它（`exit code 9`），所以 CI 统一用 `npm run test:ci`
 
 ## 本地检查
 
 ```bash
 npm run check    # node --check 全量源码
-npm test         # 离线主套件
+npm test         # 离线主套件（Windows 沙盒：含 --test-isolation=none）
+npm run test:ci  # 同上但不带 --test-isolation，供 Linux / macOS CI 使用
 npm pack --dry-run --json
 ```
 
@@ -55,8 +57,8 @@ test/                      主套件、开源友好度套件、可选集成套
 
 `.github/workflows/publish.yml` 是 `workflow_dispatch` 触发，带 `dry_run` 布尔输入：
 
-1. `actions/checkout@v4` → `actions/setup-node@v4`（Node 22，registry `https://registry.npmjs.org`）；
-2. `npm run check` + `npm pack --dry-run` 作为门禁；
+1. `actions/checkout@v4` → `actions/setup-node@v4`（Node 22.19，对齐 `engines.node`，registry `https://registry.npmjs.org`）；
+2. `npm run check` + `npm run test:ci` + `npm pack --dry-run` 作为门禁；
 3. 正式发布走 `npm publish --provenance --access public`。
 
 包内容由 `package.json#files` 白名单控制，`test/` 与 `.github/` 不进入 tarball。

package/index.js

@@ -860,12 +860,24 @@ function fenceAroundText(text) {
   return `${fence}text\n${text}\n${fence}`;
 }
 
+/**
+ * Host dependency loader with a zero-dependency fallback.
+ *
+ * Desktop DSH bundles every `@deepseek-ai/*` runtime package inside its
+ * Electron archive, so a plain `require` from the plugin directory raises
+ * MODULE_NOT_FOUND and the plugin silently degraded to its hand-written
+ * fallbacks. `runtime.requireHostModule` first tries the plain `require`
+ * (profile-hoisted layouts), then resolves the specifier against host entry
+ * anchors (the desktop runtime's own node_modules, CLI layouts, ...) and
+ * requires that entry by path. The archive layout knowledge lives only in
+ * `runtime.js`; nothing here spawns a process or reads the archive directly.
+ *
+ * Missing / ESM-only / unreadable modules still return `null`, so every
+ * caller keeps its fallback and the pure-Node offline suite stays
+ * dependency-free — no host package is ever required for the plugin to boot.
+ */
 function tryRequire(specifier) {
-  try {
-    return require(specifier);
-  } catch {
-    return null;
-  }
+  return runtime.requireHostModule(specifier);
 }
 
 /**
@@ -4718,58 +4730,68 @@ function mountSwarmRemoteService(ctx, controller) {
 
   const attachRemotePrototypeMarkers = (Proto) => {
     if (typertProto && typeof typertProto.Remote === 'function') {
-      let initGet;
-      typertProto.Remote(Proto.getSwarmSnapshot, {
-        name: 'getSwarmSnapshot',
-        private: false,
-        static: false,
-        addInitializer(fn) {
-          initGet = fn;
-        },
-      });
-      let initWatch;
-      const streamDec = typertProto.Remote({ mode: 'stream' });
-      streamDec(Proto.watchSwarm, {
-        name: 'watchSwarm',
-        private: false,
-        static: false,
-        addInitializer(fn) {
-          initWatch = fn;
-        },
-      });
-      let initModels;
-      typertProto.Remote(Proto.getSwarmModels, {
-        name: 'getSwarmModels',
-        private: false,
-        static: false,
-        addInitializer(fn) {
-          initModels = fn;
-        },
-      });
-      return { initGet, initWatch, initModels };
+      // 宿主协议的装饰器会做名称 / 上下文字段校验；版本漂移时退回手写描述符，
+      // 绝不能因为一个可选元数据步骤让整个 Swarm 服务挂不上。
+      try {
+        let initGet;
+        typertProto.Remote(Proto.getSwarmSnapshot, {
+          name: 'getSwarmSnapshot',
+          private: false,
+          static: false,
+          addInitializer(fn) {
+            initGet = fn;
+          },
+        });
+        let initWatch;
+        const streamDec = typertProto.Remote({ mode: 'stream' });
+        streamDec(Proto.watchSwarm, {
+          name: 'watchSwarm',
+          private: false,
+          static: false,
+          addInitializer(fn) {
+            initWatch = fn;
+          },
+        });
+        let initModels;
+        typertProto.Remote(Proto.getSwarmModels, {
+          name: 'getSwarmModels',
+          private: false,
+          static: false,
+          addInitializer(fn) {
+            initModels = fn;
+          },
+        });
+        return { initGet, initWatch, initModels };
+      } catch {
+        // fall through to the hand-written descriptor below
+      }
     }
 
-    Object.defineProperty(Proto, REMOTE_METHOD_DESCRIPTOR_KEY, {
-      configurable: true,
-      value: Object.freeze({
-        version: 1,
-        methods: Object.freeze([
-          Object.freeze({
-            method: 'getSwarmSnapshot',
-            invocation: Object.freeze({ kind: 'direct' }),
-          }),
-          Object.freeze({
-            method: 'watchSwarm',
-            mode: 'stream',
-            invocation: Object.freeze({ kind: 'direct' }),
-          }),
-          Object.freeze({
-            method: 'getSwarmModels',
-            invocation: Object.freeze({ kind: 'direct' }),
-          }),
-        ]),
-      }),
-    });
+    try {
+      Object.defineProperty(Proto, REMOTE_METHOD_DESCRIPTOR_KEY, {
+        configurable: true,
+        value: Object.freeze({
+          version: 1,
+          methods: Object.freeze([
+            Object.freeze({
+              method: 'getSwarmSnapshot',
+              invocation: Object.freeze({ kind: 'direct' }),
+            }),
+            Object.freeze({
+              method: 'watchSwarm',
+              mode: 'stream',
+              invocation: Object.freeze({ kind: 'direct' }),
+            }),
+            Object.freeze({
+              method: 'getSwarmModels',
+              invocation: Object.freeze({ kind: 'direct' }),
+            }),
+          ]),
+        }),
+      });
+    } catch {
+      // 原型不可扩展 / 已有不可重定义描述符：服务本身依旧可用，放弃元数据声明。
+    }
     return null;
   };
 
@@ -4805,7 +4827,12 @@ function mountSwarmRemoteService(ctx, controller) {
       initializers.initWatch?.call(protoProxy);
       initializers.initModels?.call(protoProxy);
     }
-    return new SwarmRemoteService(ctx);
+    try {
+      return new SwarmRemoteService(ctx);
+    } catch {
+      // 宿主 Cordis / Typert 契约漂移（例如 TypertRemoteService 构造签名变化）时
+      // 退回插件自带实现：degrade gracefully，绝不让 apply 直接抛错。
+    }
   }
 
   class SwarmRemoteServiceFallback {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-agy-swarm",
   "displayName": "Swarm Collaboration Cluster",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Multi-agent collaboration cluster for DeepSeek Harness: shared #seq message board, doorbell-based wakeups, zero-token sleeping, hot model switching, live feed/topology panel, and an optional Antigravity ACP teammate backend.",
   "license": "MIT",
   "author": "higekibaka",
@@ -118,6 +118,7 @@
   "icon": "./icon.svg",
   "scripts": {
     "test": "node --test --test-isolation=none test/swarm.test.mjs test/swarm-agy-acp.test.mjs test/swarm-open-source.test.mjs",
+    "test:ci": "node --test test/swarm.test.mjs test/swarm-agy-acp.test.mjs test/swarm-open-source.test.mjs",
     "test:acp-integration": "node --test --test-isolation=none test/agy-acp-integration.test.mjs",
     "check": "node --check index.js && node --check client.js && node --check runtime.js && node --check src/protocol.js && node --check src/board-store.js && node --check src/prompts.js && node --check src/redaction.js && node --check src/mcp-bridge-server.js && node --check src/mcp-stdio-entry.js"
   }

package/runtime.js

@@ -3,17 +3,19 @@
 /**
  * 宿主依赖加载器（零依赖兜底）。
  *
- * DSH 桌面版把 @deepseek-ai/schemastery 之类运行时依赖放在 app.asar 内，
- * 桌面插件目录之外 require 解析不到。这里按可选扩展 dsh-agy-acp 的
- * `runtime.js` 思路，用宿主入口作为解析锚点；插件自己绝不硬依赖该包：
+ * DSH 桌面版把 @deepseek-ai/* 运行时依赖打进 app.asar，插件目录之外 require
+ * 解析不到；CLI / 便携包布局又各不相同。这里按可选扩展 dsh-agy-acp 的
+ * `runtime.js` 思路，用「宿主入口」当解析锚点，而不是硬编码任何安装路径：
  *
- *   1) DSH_SWARM_HOST_MODULES 指向的目录（离线单测用）；
- *   2) require.main.filename（宿主主进程入口）；
- *   3) process.argv[1]；
- *   4) 插件自身目录（宿主把依赖提升到 profile 时的兜底）。
+ *   1) DSH_SWARM_HOST_MODULES 指向的目录（离线单测注入用）；
+ *   2) require.main / process.mainModule（宿主主进程入口）及其祖先目录；
+ *   3) process.argv[1] 及其祖先目录；
+ *   4) <resourcesPath>/app.asar/{dsh,lib} —— Electron 桌面版的真实依赖树
+ *      （@deepseek-ai/* 全部在 app.asar/dsh/node_modules 下）；
+ *   5) 插件自身目录（宿主把依赖提升到 profile 时的兜底）。
  *
- * 与 agy-acp 不同的是：这里找不到时返回 null，由调用方切到手写的
- * Standard Schema 兜底，保证插件在纯 Node 离线单测里也能正常挂载。
+ * 解析失败一律返回 null，由调用方切到手写兜底实现：纯 Node 离线单测因此
+ * 零依赖也能完整跑通，且这条路径绝不抛错。
  */
 
 const path = require('node:path');
@@ -21,25 +23,75 @@ const { createRequire } = require('node:module');
 
 const HOST_MODULES_ENV = 'DSH_SWARM_HOST_MODULES';
 
+/** 把某个入口文件所在目录（及其若干层祖先）加成锚点，覆盖各种宿主布局。 */
+function ancestorAnchors(entry, depth = 6) {
+  const anchors = [];
+  if (typeof entry !== 'string' || !entry) return anchors;
+  let dir;
+  try {
+    dir = path.dirname(path.resolve(entry));
+  } catch {
+    return anchors;
+  }
+  for (let i = 0; i < depth && dir; i += 1) {
+    anchors.push(path.join(dir, 'package.json'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return anchors;
+}
+
+/** Electron 桌面版：app.asar 内部的依赖树锚点（非 Electron 返回空）。 */
+function electronAnchors() {
+  const roots = [];
+  const resources = process.resourcesPath;
+  if (typeof resources === 'string' && resources) {
+    try {
+      roots.push(path.resolve(resources));
+    } catch {
+      // ignore
+    }
+  }
+  const anchors = [];
+  for (const root of roots) {
+    // dsh/ 是 @deepseek-ai/dsh-desktop-runtime，其 node_modules 才是完整依赖树；
+    // 根目录的 node_modules 只有桌面壳自己用到的一小部分包。
+    anchors.push(path.join(root, 'app.asar', 'dsh', 'package.json'));
+    anchors.push(path.join(root, 'app.asar', 'package.json'));
+    anchors.push(path.join(root, 'app.asar', 'lib', 'main.js'));
+    anchors.push(path.join(root, 'app', 'package.json'));
+    anchors.push(path.join(root, 'package.json'));
+  }
+  return anchors;
+}
+
 function hostAnchors() {
   const anchors = [];
   const root = process.env[HOST_MODULES_ENV];
   if (typeof root === 'string' && root.trim()) {
     anchors.push(path.join(root.trim(), 'anchor.cjs'));
   }
-  try {
-    const main = require.main && require.main.filename;
-    if (typeof main === 'string' && main) anchors.push(main);
-  } catch {
-    // ignore
+  const mainModule = (() => {
+    try {
+      return require.main && require.main.filename;
+    } catch {
+      return null;
+    }
+  })();
+  const main = typeof mainModule === 'string' && mainModule ? mainModule : process.mainModule && process.mainModule.filename;
+  if (typeof main === 'string' && main) anchors.push(...ancestorAnchors(main), main);
+  if (typeof process.argv[1] === 'string' && process.argv[1]) {
+    anchors.push(...ancestorAnchors(process.argv[1]), process.argv[1]);
   }
-  if (typeof process.argv[1] === 'string' && process.argv[1]) anchors.push(process.argv[1]);
+  anchors.push(...electronAnchors());
   anchors.push(path.join(__dirname, 'index.js'));
   return [...new Set(anchors)];
 }
 
 /** 从宿主锚点解析模块入口，全部失败返回 null（绝不抛错）。 */
 function resolveHostModule(specifier) {
+  if (typeof specifier !== 'string' || !specifier) return null;
   for (const anchor of hostAnchors()) {
     try {
       return createRequire(anchor).resolve(specifier);
@@ -54,6 +106,40 @@ function resolveHostModule(specifier) {
   }
 }
 
+/** specifier -> module | null 的加载结果缓存（含失败结果，避免重复解析）。 */
+const hostModuleCache = new Map();
+
+function loadHostModule(specifier) {
+  // 1) 普通 require：宿主把依赖提升到 profile / 与插件同层时的最快路径。
+  try {
+    return require(specifier);
+  } catch {
+    // 落到宿主入口锚点
+  }
+  // 2) 按宿主 app.asar 入口解析，再以入口路径加载。
+  const entry = resolveHostModule(specifier);
+  if (!entry) return null;
+  try {
+    return require(entry);
+  } catch {
+    // ERR_REQUIRE_ESM（旧版 Node 的纯 ESM 宿主模块）、asar 读失败、包自检失败
+    // 等一律视为不可用：调用方会自动退回手写兜底实现，绝不因此崩溃。
+    return null;
+  }
+}
+
+/**
+ * 惰性加载宿主模块：先普通 require，失败再走 app.asar 锚点。
+ * 解析或加载失败返回 null，调用方据此退回零依赖兜底。
+ */
+function requireHostModule(specifier) {
+  if (typeof specifier !== 'string' || !specifier) return null;
+  if (hostModuleCache.has(specifier)) return hostModuleCache.get(specifier);
+  const loaded = loadHostModule(specifier);
+  hostModuleCache.set(specifier, loaded);
+  return loaded;
+}
+
 let schemasteryModule;
 let schemasteryResolved = false;
 
@@ -63,20 +149,7 @@ let schemasteryResolved = false;
  */
 function loadSchemastery() {
   if (schemasteryResolved) return schemasteryModule;
-  const entry = resolveHostModule('@deepseek-ai/schemastery');
-  if (!entry) {
-    schemasteryResolved = true;
-    schemasteryModule = null;
-    return null;
-  }
-  let loaded;
-  try {
-    loaded = require(entry);
-  } catch {
-    schemasteryResolved = true;
-    schemasteryModule = null;
-    return null;
-  }
+  const loaded = requireHostModule('@deepseek-ai/schemastery');
   const z = loaded && typeof loaded.object === 'function' ? loaded : loaded?.default;
   schemasteryModule = z && typeof z.object === 'function' ? z : null;
   schemasteryResolved = true;
@@ -87,12 +160,16 @@ function loadSchemastery() {
 function resetHostModuleCache() {
   schemasteryModule = undefined;
   schemasteryResolved = false;
+  hostModuleCache.clear();
 }
 
 module.exports = {
   HOST_MODULES_ENV,
+  ancestorAnchors,
+  electronAnchors,
   hostAnchors,
   resolveHostModule,
+  requireHostModule,
   loadSchemastery,
   resetHostModuleCache,
 };