dsh-escalation-review 0.2.0

package/lib/config-schema.js

@@ -0,0 +1,162 @@
+/**
+ * config-schema.js —— 插件配置的 schemastery schema（即宿主侧的 `export const Config`）。
+ *
+ * 为什么字段要标 `.volatile()`：0.1.7 的 `SettingsForms.describe()` 用 `volatileForm(schema)` 过滤，
+ * **没有任何 volatile 字段的条目会被整个跳过**（设置页里什么都不显示）。放置规则：
+ * list / inner / dict-key 的子节点不能标 volatile（否则 `validateVolatilePlacement` 抛错）。
+ *
+ * 为什么布尔/数组以**文本字段**暴露：0.1.7 的字段辅助只有 `settingsTextField` / `settingsNumberField`，
+ * 且 `SettingsValueField` 内部是单行 input；文本值由 lib/index.js 的 `sanitize()` 解析成规范值。
+ */
+const dual = (zh, en) => ({ zh, en })
+
+/** 卡片里的表单 schema（字段名 = 配置键名）。 */
+export function buildSchema(z) {
+  const shape = {
+    mode: z
+      .union([z.const('observe'), z.const('enforce')])
+      .default('enforce')
+      .description(
+        dual(
+          '观察：只评审记录，照旧弹窗问你；自动批准：评审 allow 直接放行、deny 直接拒绝。⚠️ 只在「介入越界审批」开关打开后才有意义（开关关闭时插件完全零介入）。本项是调试项，配置页默认不显示。',
+          'observe: review and log only; enforce: auto-approve on pass. Only meaningful while the "Take over escalations" switch is on (off = no intervention at all). A debugging field, hidden on the config page by default.',
+        ),
+      ),
+    selftestModule: z.string().default('').hidden().description(dual('可选：附加自测模块的绝对路径', 'Optional absolute path to an additional self-test module')),
+    selfTest: z
+      .boolean()
+      .default(false)
+      .description(
+        dual(
+          '打开后，第一次越界会用一批「伪造的待审动作」跑一遍策略自检（绝不执行工具，约 9 次模型调用）',
+          'Run the fabricated-action policy self-test once (no tool is ever executed)',
+        ),
+      ),
+    allowedHosts: z
+      .array(z.string())
+      .default([])
+      .description(
+        dual(
+          '低风险主机白名单：命中这些主机的常规网络操作按 low 放行（把凭据/隐私发往外部仍按 high 拒绝）',
+          'Hosts treated as low risk for ordinary network access',
+        ),
+      ),
+    policyExtra: z
+      .string()
+      .default('')
+      .description(dual('追加到评审策略末尾的自定义规则（自然语言，随便写）', 'Extra policy text appended to the reviewer prompt')),
+    provider: z
+      .string()
+      .default('')
+      .description(dual('reviewer 使用的 provider；留空则跟随当前会话', 'Reviewer provider; empty = follow the session')),
+    model: z
+      .string()
+      .default('')
+      .description(dual('reviewer 使用的 model；留空则跟随当前会话（可指定更便宜快的模型）', 'Reviewer model; empty = follow the session')),
+    reasoningEffort: z
+      .string()
+      .default('')
+      .description(
+        dual(
+          '评审调用的思考强度；留空＝跟随当前会话/模型默认。可选：off / minimal / low / medium / high / xhigh / max（模型支持哪些档位由该模型决定）',
+          'Reasoning effort for the reviewer call; empty = follow the session/model default (off/minimal/low/medium/high/xhigh/max)',
+        ),
+      ),
+    timeoutMs: z
+      .number()
+      .min(1000)
+      .max(300000)
+      .step(1000)
+      .default(45000)
+      .description(dual('单次评审超时（毫秒）；超时按「评审失败」处理', 'Review timeout in ms; a timeout counts as review failure')),
+    attemptTimeoutMs: z
+      .number()
+      .default(30000)
+      .description(dual('单次请求超时（毫秒）；超时后按 retryDelayMs 重试', 'Per-request timeout (ms); a timeout is retried after retryDelayMs')),
+    minAttemptMs: z
+      .number()
+      .default(2000)
+      .description(dual('最小重试预算（毫秒）：扣掉等待后剩余预算低于此值就不再重试', 'Minimum budget for another attempt (ms): skip the retry when the remaining budget after the delay is below this')),
+    retryDelayMs: z
+      .number()
+      .default(5000)
+      .description(dual('重试间隔（毫秒）；生产评审与策略自检共用', 'Retry delay (ms); shared by reviews and the policy self-test')),
+    probeRunner: z
+      .string()
+      .default('inproc')
+      .description(dual('只读探针执行方式：inproc=进程内（默认，不 spawn 进程）| shell=沙箱内只读命令', 'Probe runner: inproc (default, no spawn) | shell (read-only command inside the sandbox)')),
+    failMode: z
+      .union([z.const('deny'), z.const('ask')])
+      .default('deny')
+      .description(dual('评审失败/超时怎么办：deny 直接拒绝（fail-closed）；ask 交回人工', 'On review failure: deny (fail-closed) or ask the user')),
+    denyMode: z
+      .union([z.const('deny'), z.const('ask')])
+      .default('deny')
+      .description(dual('评审判定为拒绝怎么办：deny 直接拒绝；ask 交回人工', 'On a deny verdict: refuse outright or ask the user')),
+    selfTestText: z
+      .string()
+      .default('')
+      .description(
+        dual(
+          '策略自检：填 true 会在第一次越界后用一批「伪造动作」跑一遍评审策略（绝不执行工具）；留空表示不改动',
+          'Policy self-test: "true" runs the fabricated-action self-test once; blank leaves it unchanged',
+        ),
+      ),
+    allowedHostsText: z
+      .string()
+      .default('')
+      .description(
+        dual(
+          '低风险主机白名单（逗号或换行分隔）。填了就以它为准；留空表示沿用文件配置里的 allowedHosts',
+          'Comma-separated low-risk host allowlist; blank keeps the file configuration',
+        ),
+      ),
+    logPath: z
+      .string()
+      .default('')
+      .hidden()
+      .description(dual('评审日志路径；留空用 $DSH_HOME/escalation-review.log', 'Review log path')),
+    historyLimit: z.number().min(1).default(12).hidden().description(dual('喂给 reviewer 的「用户指令」上限条数', 'Retained-instruction budget')),
+    transcriptLimit: z.number().min(1).default(40).hidden().description(dual('喂给 reviewer 的 transcript 事件上限', 'Transcript budget')),
+    textLimit: z.number().min(100).default(900).hidden().description(dual('单条证据文本的截断长度', 'Per-item text limit')),
+    // 介入开关：enabled 是规范化布尔（供 YAML / host config 层用，不进 UI）；
+    // enabledText 是配置页的文本形态（'true'/'false'），由 sanitize() 解析成 enabled。
+    // ⚠️ 这两个键必须**同时**出现在 schema 与 EDITABLE 里：设置层写入会对每个路径做
+    //    isVolatilePath 校验，schema 里没有的键必然被拒（"Config field … is not volatile"），
+    //    表现为"开关选了但存不下去"。
+    enabled: z.boolean().default(false).hidden().description(dual('是否接管沙箱越界审批（规范化布尔）', 'Take over sandbox-escalation approvals (normalized boolean)')),
+    enabledText: z.string().default('false').description(dual('介入开关（配置页文本形态：true/false）', 'Take-over switch (form text: true/false)')),
+    devMode: z.string().default('').description(dual('开发者模式：显示调试项（运行模式 / 策略自检）', 'Developer mode: show debugging fields')),
+  }
+
+  // ⚠️ 0.1.7 的 SettingsForms 只把 **`meta.volatile`** 的字段投影成可编辑表单：
+  //   volatileForm(schema)：`meta.volatile` 直接整棵通过；否则逐字段过滤，非 volatile 的一律丢掉；
+  //   一个都没有 → 整个条目被跳过 → 设置页里什么都不显示（这就是"没有设置界面"的原因）。
+  // 放置规则：list/inner/dict-key 的子节点不能标 volatile（会抛 "volatile fields require a fixed
+  // object path…"），所以只标这几个顶层字段。
+  //
+  // 设置页（Plugins 页里的配置页）由**客户端半边**渲染，用的官方控件是
+  // `SettingsFormModel` + `settingsTextField` / `settingsNumberField`（只有文本与数字两种）。
+  // 因此布尔/数组以**文本字段**暴露，由 lib/index.js 的 sanitize() 解析成规范值。
+  const EDITABLE = [
+    'enabledText',
+    'devMode',
+    'mode',
+    'selfTestText',
+    'allowedHostsText',
+    'policyExtra',
+    'provider',
+    'model',
+    'reasoningEffort',
+    'timeoutMs',
+    'failMode',
+    'denyMode',
+  'probeRunner',
+  'attemptTimeoutMs',
+  'retryDelayMs',
+  'minAttemptMs',
+  ]
+  for (const key of EDITABLE) shape[key] = shape[key].volatile()
+
+  return z.object(shape)
+}

package/lib/config.js

@@ -0,0 +1,210 @@
+/**
+ * config.js —— 配置控制面（与插件入口解耦，可单独阅读与单测）
+ *
+ * 优先级（低 → 高）：
+ *   1) 插件目录 config.json   2) $DSH_HOME/escalation-review.config.json
+ *   3) 显式 configPath        4) 宿主 config（apply 的第二参）
+ * 另有第 5 层在 index.js 里：Host 设置的 **user 覆盖层**（配置页保存的那层，每 2 秒重读 → 免重启生效）。
+ *
+ * 之所以把 BOOT_LOG / 默认值放这里：它们与"配置从哪来、落到哪"是同一件事，
+ * 而 index.js 只关心控制流（钩子接线）。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const DEFAULT_TIMEOUT_MS = 100_000
+const DEFAULT_ATTEMPT_TIMEOUT_MS = 30_000
+const DEFAULT_RETRY_DELAY_MS = 5_000
+const DEFAULT_MIN_ATTEMPT_MS = 2_000
+const DEFAULT_HISTORY_LIMIT = 12
+const DEFAULT_TRANSCRIPT_LIMIT = 40
+const DEFAULT_TEXT_LIMIT = 900
+const PACKAGE_DIR = dirname(dirname(fileURLToPath(import.meta.url)))
+const DEFAULT_LOG_NAME = 'dsh-escalation-review.log'
+
+/** 诊断日志：落在 $DSH_HOME（不依赖可能被重定向/删掉的 TMP）。 */
+const BOOT_LOG = (() => {
+  try {
+    const home = typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME.length > 0
+      ? process.env.DSH_HOME
+      : join(homedir(), '.dsh')
+    return join(home, 'escalation-review.log')
+  } catch {
+    return join(tmpdir(), DEFAULT_LOG_NAME)
+  }
+})()
+
+// ─────────────────────────────────────────────────────────────── 配置（控制面）
+
+
+/** 标准思考强度档位（模型不支持某档时由 provider 决定，评审失败即按 failMode 处理）。 */
+export const REASONING_EFFORTS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
+
+export const DEFAULT_CONFIG = {
+  devMode: false, // 开发者模式：配置页显示调试项（运行模式 / 策略自检）
+  enabled: false, // 介入开关：true 时接管**所有**沙箱越界的审批（与权限预设、profile 完全解耦）
+  enabledText: '', // GUI 表单用（'true'/'false' 文本）；非空时覆盖 enabled
+  mode: 'enforce', // observe | enforce（随包默认 enforce：开关打开后按评审结果放行/拒绝）
+  selfTest: false, // true：第一次越界后用**伪造动作**跑一遍策略自测（绝不执行工具）
+  selfTestText: '', // GUI 表单用（文本）；非空时覆盖 selfTest（'true'/'false'）
+  selftestModule: '', // 可选：附加自测模块的绝对路径（留空则按装载器的默认来源查找）
+  timeoutMs: DEFAULT_TIMEOUT_MS,
+  attemptTimeoutMs: DEFAULT_ATTEMPT_TIMEOUT_MS, // 单次尝试上限
+  retryDelayMs: DEFAULT_RETRY_DELAY_MS, // 两次尝试之间的等待
+  minAttemptMs: DEFAULT_MIN_ATTEMPT_MS, // 剩余预算低于此值就不再重试
+  reasoningEffort: '', // 评审调用的思考强度：''＝跟随会话/模型默认；否则 off|minimal|low|medium|high|xhigh|max
+  failMode: 'deny', // 评审失败/超时：deny | ask
+  denyMode: 'deny', // 政策拒绝：deny | ask（ask 时交回人工，对齐 Codex 非 strict 档）
+    probeRunner: 'inproc', // 只读探针执行方式：inproc=进程内（默认，不 spawn）| shell=沙箱内只读命令
+  provider: '',
+  model: '',
+  allowedHosts: [],
+  allowedHostsText: '', // GUI 表单用（逗号/换行分隔）；非空时覆盖 allowedHosts
+  policyExtra: '',
+  logPath: '',
+  historyLimit: DEFAULT_HISTORY_LIMIT,
+  transcriptLimit: DEFAULT_TRANSCRIPT_LIMIT,
+  textLimit: DEFAULT_TEXT_LIMIT,
+}
+
+/** 容忍 `//` 与块注释的 JSON 解析（字符串内的注释符不误伤）。 */
+export function parseConfigText(text) {
+  const source = String(text)
+  let out = ''
+  let inString = false
+  let escaped = false
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i]
+    if (inString) {
+      out += ch
+      if (escaped) escaped = false
+      else if (ch === '\\') escaped = true
+      else if (ch === '"') inString = false
+      continue
+    }
+    if (ch === '"') {
+      inString = true
+      out += ch
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '/') {
+      while (i < source.length && source[i] !== '\n') i += 1
+      out += '\n'
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      i += 2
+      while (i < source.length && !(source[i] === '*' && source[i + 1] === '/')) i += 1
+      i += 1
+      continue
+    }
+    out += ch
+  }
+  const value = JSON.parse(out)
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('config must be a JSON object')
+  }
+  return value
+}
+
+function sanitize(patch) {
+  const out = {}
+  if (patch === null || typeof patch !== 'object') return out
+  if (patch.mode === 'observe' || patch.mode === 'enforce') out.mode = patch.mode
+  // 思考强度：只接受标准档位 id（'' 表示跟随会话/模型默认）
+  if (typeof patch.reasoningEffort === 'string') {
+    const effort = patch.reasoningEffort.trim()
+    if (effort === '' || REASONING_EFFORTS.has(effort)) out.reasoningEffort = effort
+  }
+  if (patch.failMode === 'deny' || patch.failMode === 'ask') out.failMode = patch.failMode
+  if (patch.denyMode === 'deny' || patch.denyMode === 'ask') out.denyMode = patch.denyMode
+    if (patch.probeRunner === 'inproc' || patch.probeRunner === 'shell') out.probeRunner = patch.probeRunner
+  if (typeof patch.selftestModule === 'string' && patch.selftestModule.trim().length > 0) out.selftestModule = patch.selftestModule.trim()
+  if (typeof patch.selfTest === 'boolean') out.selfTest = patch.selfTest
+  if (Number.isFinite(patch.timeoutMs) && patch.timeoutMs >= 1000) out.timeoutMs = Math.min(Math.floor(patch.timeoutMs), 300_000)
+  if (Number.isFinite(patch.attemptTimeoutMs) && patch.attemptTimeoutMs >= 1000) out.attemptTimeoutMs = Math.min(Math.floor(patch.attemptTimeoutMs), 300_000)
+  if (Number.isFinite(patch.retryDelayMs) && patch.retryDelayMs >= 0) out.retryDelayMs = Math.min(Math.floor(patch.retryDelayMs), 60_000)
+  if (Number.isFinite(patch.minAttemptMs) && patch.minAttemptMs >= 0) out.minAttemptMs = Math.min(Math.floor(patch.minAttemptMs), 60_000)
+  for (const key of ['provider', 'model', 'policyExtra', 'logPath', 'configPath']) {
+    if (typeof patch[key] === 'string') out[key] = patch[key]
+  }
+  if (Array.isArray(patch.allowedHosts)) {
+    out.allowedHosts = patch.allowedHosts.filter((h) => typeof h === 'string' && h.trim().length > 0).map((h) => h.trim())
+  }
+  for (const key of ['historyLimit', 'transcriptLimit', 'textLimit']) {
+    if (Number.isFinite(patch[key]) && patch[key] > 0) out[key] = Math.floor(patch[key])
+  }
+
+  // GUI 表单（设置页）用的是**文本字段**：官方的 SettingsFormModel 只带 settingsTextField /
+  // settingsNumberField 两种控件，所以布尔/数组以文本暴露，在这里解析成规范值。
+  if (typeof patch.selfTestText === 'string' && patch.selfTestText.trim().length > 0) {
+    out.selfTestText = patch.selfTestText.trim()
+    out.selfTest = /^(true|1|yes|on|开|是)$/i.test(out.selfTestText)
+  }
+  if (typeof patch.devMode === 'boolean') out.devMode = patch.devMode
+  if (typeof patch.devModeText === 'string' && patch.devModeText.trim().length > 0) out.devMode = /^(true|1|yes|on|开|是)$/i.test(patch.devModeText.trim())
+  if (typeof patch.enabled === 'boolean') out.enabled = patch.enabled
+  if (typeof patch.enabledText === 'string' && patch.enabledText.trim().length > 0) {
+    out.enabledText = patch.enabledText.trim()
+    out.enabled = /^(true|1|yes|on|开|是)$/i.test(out.enabledText)
+  }
+  if (typeof patch.allowedHostsText === 'string' && patch.allowedHostsText.trim().length > 0) {
+    out.allowedHostsText = patch.allowedHostsText.trim()
+    out.allowedHosts = out.allowedHostsText
+      .split(/[,\n;]/)
+      .map((h) => h.trim())
+      .filter((h) => h.length > 0)
+  }
+  return out
+}
+
+/**
+ * 解析生效配置。优先级（低 → 高）：
+ *   1) 插件目录 config.json   2) $DSH_HOME/escalation-review.config.json   3) 显式 configPath   4) 宿主 config
+ */
+export function resolveConfig(options = {}) {
+  const dshHome = typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME.length > 0
+    ? process.env.DSH_HOME
+    : join(homedir(), '.dsh')
+  const candidates = [
+    join(PACKAGE_DIR, 'config.json'),
+    join(dshHome, 'escalation-review.config.json'),
+    // GUI 配置卡写出来的用户覆盖（由根平面的伴生 entry lib/settings-bridge.js 维护）→ 文件层里优先级最高
+    join(dshHome, 'escalation-review.ui.json'),
+  ]
+  if (typeof options.configPath === 'string' && options.configPath.length > 0) candidates.push(options.configPath)
+
+  let merged = { ...DEFAULT_CONFIG }
+  const loaded = []
+  const errors = []
+  for (const file of candidates) {
+    if (!existsSync(file)) continue
+    try {
+      merged = { ...merged, ...sanitize(parseConfigText(readFileSync(file, 'utf8'))) }
+      loaded.push(file)
+    } catch (error) {
+      errors.push(`${file}: ${String(error?.message ?? error)}`)
+    }
+  }
+  merged = { ...merged, ...sanitize(options) }
+  merged.loadedConfigFiles = loaded
+  merged.configErrors = errors
+  merged.logPath = merged.logPath.length > 0 ? merged.logPath : BOOT_LOG
+  return merged
+}
+
+// index.js 需要这些常量（实现仍是本模块私有，这里只是显式再导出）
+export {
+  BOOT_LOG,
+  sanitize,
+  DEFAULT_HISTORY_LIMIT,
+  DEFAULT_TEXT_LIMIT,
+  DEFAULT_TIMEOUT_MS,
+  DEFAULT_ATTEMPT_TIMEOUT_MS,
+  DEFAULT_RETRY_DELAY_MS,
+  DEFAULT_MIN_ATTEMPT_MS,
+  DEFAULT_TRANSCRIPT_LIMIT,
+  PACKAGE_DIR,
+}

package/lib/decisions.js

@@ -0,0 +1,67 @@
+/**
+ * decisions.js —— `tools/pre-execute` 的动作构造（从 index.js 抽出的纯函数）
+ *
+ * 三态契约沿用 DSH：返回 `next()`（放行到下游）/ `{kind:'deny'|'ask'}`。
+ * 抽出来的理由：这段文案与分支在 index.js 里连着被改了三轮（熔断、失败处理、denyMode），
+ * 属于"每次都进的补丁点"；纯函数化之后可单测，index.js 只负责接线。
+ *
+ * 这里**不做任何 IO、不读配置**：所有输入由调用方给出，输出就是钩子该返回的对象。
+ *
+ * 文案语言（2026-09-27 定）：
+ *   · **不提供 `displayReason`** —— 客户端的取值是 `displayReason ?? reason`，即 displayReason 优先；
+ *     而官方那个字段是"由发起方提供译文"，我提供不了所有语言（只有 en/zh 会把日语用户也盖成中英）。
+ *   · 本地化交给**模型**：策略里要求 reviewer 用"用户在本会话里使用的语言"写 reason/rationale。
+ *   · 因此插件只加一个**语言中性**的 `escalation-review:` 前缀，可见内容主要是模型那段话。
+ */
+
+/**
+ * 评审失败（异常/超时）的动作 —— fail-closed：只有显式 `failMode: 'ask'` 才交回人工。
+ * @param {object} input - { gated, cfg, exec, message }
+ */
+export function reviewFailureAction({ gated, cfg, exec, message, deniedName, deniedCode }) {
+  // 未启用「自动批准」时插件不介入，失败也不改变任何行为（零介入原则）
+  if (!gated) return { kind: 'pass' }
+  if (cfg.failMode === 'ask') {
+    return {
+      kind: 'ask',
+      reason: `escalation-review: review failed (${message}) — your call`,
+    }
+  }
+  return {
+    kind: 'deny',
+    reason: `escalation-review: review failed, body not executed — ${message}`,
+    info: { name: deniedName, code: deniedCode, reason: message },
+  }
+}
+
+/** 连续拒绝熔断后的动作：不再拒绝，交回人工（照 Codex circuit_breaker：避免把任务卡死）。 */
+export function circuitBreakerAction({ exec, breaker }) {
+  return {
+    kind: 'ask',
+    reason: `escalation-review: ${breaker.consecutive} consecutive denials — asking you instead of blocking`,
+  }
+}
+
+/**
+ * 评审给出拒绝时的动作：按 `denyMode` 决定拒绝还是交回人工。
+ * （放行路径不在这里 —— 它还要向 agent 注册一次性审批 answerer，属于宿主接线。）
+ * @param {object} input - { cfg, exec, decision, deniedName, deniedCode }
+ */
+export function reviewRejectedAction({ cfg, exec, decision, deniedName, deniedCode }) {
+  const hasReason = decision?.reason !== undefined && decision.reason !== null
+  // 分层（2026-09-28 按用户口径定）：评审器判 allow/deny/ask，**是否交回人工由配置 denyMode 决定**。
+  // 评审器的 ask 只表示"我判不了"（证据自相矛盾/范围无法确定），它**不能越过配置**去决定问人 ——
+  // 否则 denyMode: deny 会被架空（自测里"无授权改 hosts"就是这么变成 ask 的）。
+  if (cfg.denyMode === 'ask') {
+    return {
+      kind: 'ask',
+      reason: `escalation-review: denied${hasReason ? ` — ${decision.reason}` : ''}`,
+    }
+  }
+  return {
+    kind: 'deny',
+    // 理由必须进**顶层 reason**：宿主把这一行显示给模型（info.reason 模型看不到）
+    reason: `escalation-review: rejected, body not executed${hasReason ? ` — ${decision.reason}` : ''}`,
+    info: { name: deniedName, code: deniedCode, ...(hasReason ? { reason: decision.reason } : {}) },
+  }
+}

package/lib/dsh-packages.js

@@ -0,0 +1,128 @@
+/**
+ * dsh-packages.js —— 解析并导入 @deepseek-ai/* 包
+ *
+ * 为什么需要它：插件用 GUI 的「添加插件」安装时是 **link:** 依赖（软链到源码目录），
+ * 于是模块 URL 落在 workspace 里，而 ESM 是**按模块自身路径**往上找 node_modules 的
+ * —— workspace 树里没有 @deepseek-ai/*，裸 import 会 ERR_MODULE_NOT_FOUND
+ * （实测：copy 安装时能解析，link 安装后不能）。
+ *
+ * 解法：用 createRequire 以 **profile 的 package.json** 为解析根拿到绝对路径，再 import。
+ *
+ * ⚠️ 关键（2026-09-27 实测定位，踩了很久）：
+ *   `require.resolve()` 是按 **`require` 条件**解析的 → 对双构建包（如 `@deepseek-ai/schemastery`：
+ *   `exports['.'].import = lib/index.mjs`、`require = lib/index.cjs`）拿到的是 **CJS 入口**。
+ *   而在 **Electron 主进程**里 `import()` 那个 CJS 会 `ERR_REQUIRE_ESM_RACE_CONDITION`
+ *   （CJS 内部再去 require ESM 实现，撞上加载竞态）→ 表现为"拿不到 schemastery" → `Config = undefined`
+ *   → 设置命名空间不被服务 → 配置页永远不出现。
+ *   所以这里**主动按 `import` 条件挑入口**，并且在 `.cjs` 有同名 `.mjs` 时优先 `.mjs`。
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** 上一次成功导入时命中的解析根（给日志用：别再写死"按 profile"）。 */
+let lastRoot = null
+
+/** 最近一次成功导入所使用的解析根（应用自身 / profile / 裸 import / asar 猜测）。 */
+export function lastResolutionRoot() {
+  return lastRoot
+}
+
+/** 解析根候选：**运行中的应用自身优先**，再 desktop profile，再 profiles 根。 */
+function resolutionRoots() {
+  const home =
+    typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME.length > 0 ? process.env.DSH_HOME : join(homedir(), '.dsh')
+  const profile = process.env.DSH_PROFILE
+  const roots = []
+  // ⚠️ 优先用**运行中的应用自身**内置的包（新版把 0.2.0 的包放在 app.asar 内层 dsh/ 下）。
+  //    升级后 profile 的 node_modules 可能仍是旧版本（实测 0.1.7-rc.2），先解析 profile 会加载到旧包。
+  if (typeof process.resourcesPath === 'string' && process.resourcesPath.length > 0) {
+    roots.push(join(process.resourcesPath, 'app.asar', 'dsh', 'package.json'))
+    roots.push(join(process.resourcesPath, 'app', 'dsh', 'package.json'))
+  }
+  if (typeof profile === 'string' && profile.length > 0) roots.push(join(home, 'profiles', profile, 'package.json'))
+  roots.push(join(home, 'profiles', 'desktop', 'package.json'), join(home, 'profiles', 'package.json'))
+  return roots
+}
+
+/** 从一个 `exports` 条件对象里挑出 ESM 入口。 */
+function pickImportTarget(value) {
+  if (typeof value === 'string') return value
+  if (value === null || value === undefined || typeof value !== 'object') return undefined
+  return value.import ?? value.node ?? value.module ?? value.default
+}
+
+/** 按 `import` 条件把一个包说明符解析成**绝对文件路径**（拿不到就返回 undefined）。 */
+function resolveEsmEntry(req, specifier) {
+  try {
+    const packageJson = req.resolve(`${specifier}/package.json`)
+    if (existsSync(packageJson)) {
+      const pkg = JSON.parse(readFileSync(packageJson, 'utf8'))
+      const target = pickImportTarget(pkg.exports?.['.']) ?? pkg.module ?? pkg.main
+      if (typeof target === 'string') {
+        const file = join(dirname(packageJson), target)
+        if (existsSync(file)) return file
+      }
+    }
+  } catch {
+    /* 包没导出 ./package.json → 走下面的通用回退 */
+  }
+  const resolved = req.resolve(specifier)
+  if (typeof resolved === 'string' && resolved.endsWith('.cjs')) {
+    const asMjs = resolved.replace(/\.cjs$/, '.mjs')
+    if (existsSync(asMjs)) return asMjs
+  }
+  return resolved
+}
+
+/**
+ * 导入一个 DSH 内部包。失败时 throw，并把每次尝试的原因带在 error.attempts 上。
+ * @param specifier - 例如 '@deepseek-ai/schemastery'
+ */
+export async function importDshPackage(specifier) {
+  const attempts = []
+  for (const manifest of resolutionRoots()) {
+    if (!existsSync(manifest)) continue
+    try {
+      const req = createRequire(manifest)
+      const entry = resolveEsmEntry(req, specifier)
+      lastRoot = manifest
+      return await import(pathToFileURL(entry).href)
+    } catch (error) {
+      attempts.push(`${manifest}: ${error?.code ?? error?.message ?? error}`)
+    }
+  }
+  try {
+    const bare = await import(specifier)
+    lastRoot = 'bare import'
+    return bare
+  } catch (error) {
+    attempts.push(`bare import: ${error?.code ?? error?.message ?? error}`)
+  }
+  const resources = typeof process.resourcesPath === 'string' && process.resourcesPath.length > 0 ? process.resourcesPath : ''
+  if (resources.length > 0) {
+    const guess = join(resources, 'app.asar', 'dsh', 'node_modules', ...specifier.split('/'), 'lib', 'index.mjs')
+    try {
+      lastRoot = guess
+      return await import(pathToFileURL(guess).href)
+    } catch (error) {
+      attempts.push(`asar guess ${guess}: ${error?.code ?? error?.message ?? error}`)
+    }
+  }
+  const failure = new Error(`cannot import ${specifier}`)
+  failure.attempts = attempts
+  throw failure
+}
+
+/** 拿到默认导出的“类 zod”对象（schemastery 有 default / 命名导出两种形态）。 */
+export async function importSchema() {
+  const mod = await importDshPackage('@deepseek-ai/schemastery')
+  const schema = mod?.default ?? mod
+  if (schema === undefined || typeof schema.object !== 'function') {
+    throw new Error('@deepseek-ai/schemastery did not expose a schema builder')
+  }
+  return schema
+}