dsh-subagent-profile 0.3.2 → 0.3.4

package/lib/core/reminder-store.mjs

@@ -0,0 +1,172 @@
+// lib/core/reminder-store.mjs — 提醒系统 host 侧 store + 审计同源。
+// 一条提醒 = 一条治理审计记录（经 audit 钩子写入 governance-audit.jsonl，与 [6] 审计
+// 同源）；每个用户动作（采纳/忽略/拒绝/关闭）与「标记已读」都追加审计留痕。P0 三要件：
+// severity 上色（P0 由 client 用错误色渲染）、常驻至已读（unread 标记，绝不自动消失）、
+// 带 session 标识（sessionId 字段；全局异常显式 null，client 标注「全局」）。
+// 隐私红线：只落结构字段（severity/kind/title/detail/sessionId/时间戳）与「未采纳」
+// 条目的展示字段（子会话 id/模式、prompt 摘要 ≤200 字符、结算摘要结构、估算成本）。
+// prompt 摘要不存原文，结算摘要无子输出正文；其余提醒类不携带这些字段（null）。
+// 落盘 subagent-evolution/reminders.json（原子写 tmp+rename；损坏/形状不符
+// fail-soft 从空起步）。import-free（仅 node 内置），可被裸 CI 单测。
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const SEVERITIES = new Set(['P0', 'P1', 'P2']);
+const MAX_REMINDERS = 200;
+
+function isRecordShape(rec) {
+  return rec !== null && typeof rec === 'object' && typeof rec.id === 'string'
+    && typeof rec.severity === 'string' && typeof rec.kind === 'string'
+    && typeof rec.title === 'string' && typeof rec.detail === 'string';
+}
+
+// 结算摘要形状守卫（宽松）：只接受非数组对象，具体字段逐个归一。
+function isSettleShape(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeSettled(value) {
+  if (!isSettleShape(value)) return null;
+  return {
+    stopReason: typeof value.stopReason === 'string' ? value.stopReason : '',
+    elapsedMs: Number.isFinite(value.elapsedMs) ? value.elapsedMs : null,
+    ...(Number.isFinite(value.childTotalTokens) ? { childTotalTokens: value.childTotalTokens } : {}),
+    ...(isSettleShape(value.childUsage) ? { childUsage: value.childUsage } : {}),
+    ...(typeof value.childSessionId === 'string' && value.childSessionId !== '' ? { childSessionId: value.childSessionId } : {}),
+  };
+}
+
+function loadState(stateFile, state, warn) {
+  if (stateFile === undefined) return;
+  try {
+    if (!existsSync(stateFile)) return;
+    const parsed = JSON.parse(readFileSync(stateFile, 'utf8'));
+    if (parsed === null || typeof parsed !== 'object' || parsed.v !== 1 || !Array.isArray(parsed.reminders)) {
+      warn('reminder store: 提醒文件版本或形状不符，从空状态起步');
+      return;
+    }
+    for (const raw of parsed.reminders) {
+      if (!isRecordShape(raw)) continue;
+      state.reminders.push({
+        id: raw.id,
+        severity: SEVERITIES.has(raw.severity) ? raw.severity : 'P2',
+        kind: raw.kind,
+        title: raw.title,
+        detail: raw.detail,
+        sessionId: typeof raw.sessionId === 'string' && raw.sessionId !== '' ? raw.sessionId : null,
+        childId: typeof raw.childId === 'string' && raw.childId !== '' ? raw.childId : null,
+        childSessionId: typeof raw.childSessionId === 'string' && raw.childSessionId !== '' ? raw.childSessionId : null,
+        childMode: typeof raw.childMode === 'string' && raw.childMode !== '' ? raw.childMode : null,
+        promptExcerpt: typeof raw.promptExcerpt === 'string' ? raw.promptExcerpt : '',
+        settled: normalizeSettled(raw.settled),
+        costEstimated: Number.isFinite(raw.costEstimated) ? raw.costEstimated : null,
+        unread: raw.unread !== false,
+        createdAt: Number.isFinite(raw.createdAt) ? raw.createdAt : 0,
+        action: typeof raw.action === 'string' ? raw.action : null,
+        actedAt: Number.isFinite(raw.actedAt) ? raw.actedAt : null,
+      });
+    }
+  } catch (error) {
+    warn('reminder store: 提醒文件读取失败，从空状态起步（' + (error instanceof Error ? error.message : String(error)) + '）');
+  }
+}
+
+function persistState(stateFile, state, warn) {
+  if (stateFile === undefined) return;
+  const tmp = stateFile + '.tmp';
+  try {
+    mkdirSync(dirname(stateFile), { recursive: true });
+    writeFileSync(tmp, JSON.stringify({ v: 1, reminders: state.reminders }, null, 2), 'utf8');
+    renameSync(tmp, stateFile);
+  } catch (error) {
+    try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    warn('reminder store: 提醒文件写入失败（' + (error instanceof Error ? error.message : String(error)) + '）');
+  }
+}
+
+function auditReminder(audit, kind, reminder, action) {
+  audit({
+    kind,
+    reminderId: reminder.id,
+    severity: reminder.severity,
+    reminderKind: reminder.kind,
+    ...(reminder.sessionId !== null ? { sessionId: reminder.sessionId } : {}),
+    ...(action !== undefined ? { action } : {}),
+  });
+}
+
+// 产生一条提醒：severity 非法回退 P2；空 sessionId 归一 null（全局）。「未采纳」
+// 条目额外携带子会话 id/模式、prompt 摘要（≤200 字符再截一次防超）、结算摘要与估算
+// 成本；其余提醒类这些字段为空/null。创建即审计。
+function recordReminder(state, persist, audit, { severity, kind, title, detail, sessionId, childId, childSessionId, childMode, promptExcerpt, settled, costEstimated }) {
+  const reminder = {
+    id: 'r-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8),
+    severity: SEVERITIES.has(severity) ? severity : 'P2',
+    kind: typeof kind === 'string' && kind !== '' ? kind : 'event',
+    title: typeof title === 'string' ? title : '',
+    detail: typeof detail === 'string' ? detail : '',
+    sessionId: typeof sessionId === 'string' && sessionId !== '' ? sessionId : null,
+    childId: typeof childId === 'string' && childId !== '' ? childId : null,
+    childSessionId: typeof childSessionId === 'string' && childSessionId !== '' ? childSessionId : null,
+    childMode: typeof childMode === 'string' && childMode !== '' ? childMode : null,
+    promptExcerpt: typeof promptExcerpt === 'string' ? promptExcerpt.slice(0, 200) : '',
+    settled: normalizeSettled(settled),
+    costEstimated: Number.isFinite(costEstimated) ? costEstimated : null,
+    unread: true,
+    createdAt: Date.now(),
+    action: null,
+    actedAt: null,
+  };
+  state.reminders.push(reminder);
+  if (state.reminders.length > state.maxReminders) state.reminders.shift();
+  persist();
+  auditReminder(audit, 'reminder-created', reminder);
+  return reminder;
+}
+
+// 标记已读（unread=false）：P0 角标常驻至已读的「已读」动作，逐条留痕。
+function ackReminders(state, persist, audit, ids) {
+  const list = Array.isArray(ids) ? ids : [];
+  const acked = [];
+  for (const reminder of state.reminders) {
+    if (reminder.unread !== true || !list.includes(reminder.id)) continue;
+    reminder.unread = false;
+    acked.push(reminder.id);
+    auditReminder(audit, 'reminder-acked', reminder);
+  }
+  if (acked.length > 0) persist();
+  return acked;
+}
+
+// 用户动作（采纳/忽略/拒绝/关闭）：互斥终态 + 审计留痕（关闭留痕要求）。
+function actOnReminder(state, persist, audit, id, action) {
+  const reminder = state.reminders.find((r) => r.id === id);
+  if (reminder === undefined) return false;
+  if (action !== 'adopt' && action !== 'ignore' && action !== 'reject' && action !== 'dismiss') return false;
+  reminder.action = action;
+  reminder.actedAt = Date.now();
+  reminder.unread = false;
+  persist();
+  auditReminder(audit, 'reminder-action', reminder, action);
+  return true;
+}
+
+function listReminders(state, unreadOnly) {
+  const all = [...state.reminders].reverse();
+  return unreadOnly ? all.filter((r) => r.unread === true) : all;
+}
+
+export function createReminderStore({ dshHome, audit = () => {}, warn = () => {}, maxReminders = MAX_REMINDERS } = {}) {
+  const state = { reminders: [], maxReminders: Number.isFinite(maxReminders) && maxReminders > 0 ? maxReminders : MAX_REMINDERS };
+  const stateFile = dshHome !== undefined && dshHome !== '' ? join(dshHome, 'subagent-evolution', 'reminders.json') : undefined;
+  loadState(stateFile, state, warn);
+  const persist = () => persistState(stateFile, state, warn);
+  return {
+    record: (entry) => recordReminder(state, persist, audit, entry),
+    ack: (ids) => ackReminders(state, persist, audit, ids),
+    actOn: (id, action) => actOnReminder(state, persist, audit, id, action),
+    list: ({ unreadOnly = false } = {}) => listReminders(state, unreadOnly),
+    unreadCount: () => state.reminders.filter((r) => r.unread === true).length,
+  };
+}

package/lib/core/shims.mjs

@@ -1,51 +1,42 @@
-// lib/core/shims.mjs — facade. The ONLY module that imports the
-// @deepseek-ai symbols index.mjs relies on, converging the previously
-// top-level-scattered import surface. Two failure classes:
+// lib/core/shims.mjs — facade。唯一 import index.mjs 依赖的 @deepseek-ai
+// 符号的模块，收敛此前散落在顶层的 import 面。两类失败：
 //
-//   Guard-type (fail-loud, NO fallback): assertSubagentMaxDepth /
-//   resolveChildDepth are STATICALLY imported and re-exported. A rename/removal
-//   in the host rc makes this module — and therefore index.mjs — fail at load
-//   time with the ESM link error "The requested module ... does not provide an
-//   export named '...'". That is exactly the loading-time isolation the spec
-//   wants for the delegation-depth safety gates: no weakened reimplementation is
-//   ever substituted, so a child can never be dispatched past MAX_DEPTH.
+//   守卫型（fail-loud，无回退）：assertSubagentMaxDepth / resolveChildDepth
+//   是**静态** import 并再导出。宿主 rc 里改名/移除会让本模块——进而
+//   index.mjs——在加载时以 ESM 链接错误失败（"The requested module ... does
+//   not provide an export named '...'"）。这正是委派深度安全闸想要的加载时
+//   隔离：绝不替换为弱化实现，子 Agent 永远不可能派发超过 MAX_DEPTH。
 //
-//   Function-mapping (fail-soft + warn): foldConsumedWork / finalAssistantOutput
-//   / createUserMessage / appendDelegatedPolicyOverrides /
-//   captureDelegatedPolicyOverrides / resolveChildAgentOptions / defineTool are
-//   loaded with a dynamic top-level-await import wrapped in try/catch. On an
-//   import failure (or a renamed/absent named export) the module still loads, a
-//   console.warn is emitted (module top level has no ctx, so no logger), and a
-//   local functionally-equivalent (or safe-degraded) implementation is used.
+//   函数映射型（fail-soft + warn）：foldConsumedWork / finalAssistantOutput /
+//   createUserMessage / appendDelegatedPolicyOverrides /
+//   captureDelegatedPolicyOverrides / resolveChildAgentOptions / defineTool
+//   用 try/catch 包裹的动态顶层 await import 加载。导入失败（或命名导出被
+//   改名/移除）时模块仍能加载，发出 console.warn（模块顶层没有 ctx，没有
+//   logger），并使用本地功能等价（或安全降级）实现。
 //
-//   A dynamic import whose package loads but whose named export was renamed or
-//   removed resolves the destructure to `undefined` WITHOUT throwing, so loadSoft
-//   also verifies the value is a function before accepting it.
+//   动态 import 的包能加载但命名导出被改名/移除时，解构结果为 `undefined`
+//   且**不抛**，所以 loadSoft 还校验值是函数后才接受。
 
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
-// Guard-type: static, fail-loud — no fallback. Kept as the only two
-// static @deepseek-ai imports; a missing export aborts module load with a clear
-// error BEFORE apply can run, which is the isolation this class exists for.
+// 守卫型：静态、fail-loud、无回退。只保留这两个静态 @deepseek-ai import；
+// 导出缺失会在 apply 能运行之前就以明确错误中止模块加载——这正是本类存在的隔离。
 import { assertSubagentMaxDepth, resolveChildDepth } from '@deepseek-ai/dsh-subagent';
 import { toStopReason } from './pure.mjs';
 
-// warn: at module top level there is no ctx / logger, so degrade to console.warn.
-// The prefix keeps the source recognizable in a shared host log.
+// warn：模块顶层没有 ctx / logger，降级用 console.warn。
+// 前缀让来源在共享宿主日志中可辨认。
 function warn(...parts) {
   console.warn('[dsh-subagent-profile]', ...parts);
 }
 
-// Load one function-mapping `@deepseek-ai` symbol, returning a local fallback when
-// the package or the named export is unavailable. `warnMessage` carries the
-// actionable user-facing text. `importer` is an injectable loader (defaults to
-// the dynamic `import` — see DYNAMIC_IMPORT) so tests / future loaders can
-// override the failure route (e.g. stub it to throw, or return a module object
-// missing the symbol). It is exported as a seam for that purpose.
+// 加载一个函数映射型 `@deepseek-ai` 符号，包或命名导出不可用时返回本地回退。
+// `warnMessage` 携带可操作的用户面向文案。`importer` 是可注入加载器（缺省为
+// 动态 `import`——见 DYNAMIC_IMPORT），测试 / 未来加载器可覆盖失败路径
+// （如 stub 成抛错，或返回缺该符号的模块对象）。为此导出为接缝。
 //
-// Note: `import` is a keyword and cannot be used as a value reference
-// (`importer = import` is a SyntaxError), so the default is a thin wrapper around
-// the dynamic import expression.
+// 注意：`import` 是关键字，不能作值引用（`importer = import` 是 SyntaxError），
+// 故缺省值是动态 import 表达式的薄包装。
 const DYNAMIC_IMPORT = (specifier) => import(specifier);
 async function loadSoft(pkg, symbol, fallback, warnMessage, importer = DYNAMIC_IMPORT) {
   try {
@@ -60,11 +51,9 @@ async function loadSoft(pkg, symbol, fallback, warnMessage, importer = DYNAMIC_I
   }
 }
 
-// --- local fallbacks (import-free, duck-typed, functionally equivalent) ----
-// Each is the minimal local reimplementation that preserves the observable
-// contract of the shipped helper; these are exported via `__fallbacks` so tests
-// can exercise the degraded path even though the junction packages resolve
-// successfully here.
+// --- 本地回退（import-free、duck-typed、功能等价）------------------------------
+// 每个都是保留官方助手可观察契约的最小本地实现；经 `__fallbacks` 导出，测试在
+// junction 包解析成功时也能走降级路径。
 
 // foldConsumedWork: **近似、非等价**——readResult 只读 `.end`（终止 turn/end 事件）来
 // 推导 stopReason。shipped fold 是精密的 stepped/claimed 状态机；本降级实现取最后一个
@@ -80,8 +69,8 @@ function foldConsumedWorkFallback(events) {
   return { ...(end === undefined ? {} : { end }), droppedUnrun: false };
 }
 
-// finalAssistantOutput: identical fold rule — last non-empty assistant/message,
-// else accumulated text-delta chunks, else undefined.
+// finalAssistantOutput：相同的 fold 规则——最后一个非空 assistant/message，
+// 否则累加的 text-delta 分片，再否则 undefined。
 function finalAssistantOutputFallback(events) {
   let message;
   const partial = [];
@@ -99,11 +88,10 @@ function finalAssistantOutputFallback(events) {
   return text.length > 0 ? [{ type: 'text', text }] : undefined;
 }
 
-// createUserMessage: build the user-role message the followup driver needs. The
-// shipped helper uses a branded MessageId + deepFreeze; the fallback provides the
-// same observable shape (role/content/id/source) with a fresh random id. Note:
-// the returned object is MUTABLE (no deepFreeze) — consumers must NOT rely on
-// the shipped deepFreeze immutability; treat it as a plain message object.
+// createUserMessage：构造 followup 驱动需要的 user 角色消息。官方助手用品牌化
+// MessageId + deepFreeze；回退提供相同可观察形状（role/content/id/source）加
+// 新鲜随机 id。注意：返回对象是**可变**的（无 deepFreeze）——消费方不得依赖
+// 官方 deepFreeze 的不可变性；把它当普通消息对象。
 function createUserMessageFallback(input) {
   return {
     ...input,
@@ -112,10 +100,9 @@ function createUserMessageFallback(input) {
   };
 }
 
-// appendDelegatedPolicyOverrides: the delegation policy is authored INTO the
-// child's log for reconstruction. This is also the security-relevant
-// "approval: never" pin, so it must NOT be a no-op — reproduce the append
-// faithfully to keep the child's own log reconstructable and the pin visible.
+// appendDelegatedPolicyOverrides：委派策略写进子会话日志供重建。这也是安全
+// 相关的「approval: never」钉，绝不能是 no-op——忠实复现追加，保持子会话自身
+// 日志可重建、钉可见。
 function appendDelegatedPolicyOverridesFallback(childSession, overrides) {
   const o = overrides || {};
   if (o.sandboxMode !== undefined) {
@@ -126,9 +113,8 @@ function appendDelegatedPolicyOverridesFallback(childSession, overrides) {
   }
 }
 
-// captureDelegatedPolicyOverrides: the parent's explicit sandbox override (or
-// undefined when none) plus the approval pin 'never' when the parent has an
-// approval service. Optional chaining keeps a mock parent (tests) working.
+// captureDelegatedPolicyOverrides：父的显式沙箱覆盖（无则 undefined）加父有
+// approval 服务时的审批钉 'never'。可选链让 mock 父（测试）正常工作。
 function captureDelegatedPolicyOverridesFallback(parent) {
   return {
     sandboxMode: parent.ctx?.get?.('sandboxPolicy')?.overrideOf?.(parent.session),
@@ -136,10 +122,9 @@ function captureDelegatedPolicyOverridesFallback(parent) {
   };
 }
 
-// resolveChildAgentOptions: merge the parent's route (provider/model/maxTokens,
-// present-only) with the per-child overrides and stamp the child's own depth.
-// This must preserve the child-config semantics — a no-op here would silently
-// break delegation routing.
+// resolveChildAgentOptions：合并父路由（provider/model/maxTokens，存在才带）
+// 与 per-child 覆盖，并盖上子自身的深度。必须保持子配置语义——no-op 会静默
+// 破坏委派路由。
 function resolveChildAgentOptionsFallback(parent, requested, childDepth) {
   const parentProvider = parent.options?.provider;
   const parentModel = parent.options?.model;
@@ -153,19 +138,16 @@ function resolveChildAgentOptionsFallback(parent, requested, childDepth) {
   };
 }
 
-// defineTool: the dispatch tool cannot exist without dsh-tools. Fail-loud at the
-// point of use with a clear, actionable message — the module still LOADS, and
-// calling this during apply surfaces the exact missing-dependency story instead
-// of a cryptic module-not-found at import time（加载不崩溃，调用点才报错）。
+// defineTool：没有 dsh-tools 就没有 dispatch 工具。在用途点 fail-loud 并给出
+// 清晰可操作的文案——模块仍然加载，apply 期间调用它才暴露确切的缺失依赖
+// （加载不崩溃，调用点才报错）。
 function defineToolFallback() {
   throw new Error('dsh-tools 缺失：dispatch 工具不可用');
 }
 
-// --- wire the function-mapping symbols (module top-level await) --------------
-// The seven loads are independent, so they run in parallel (Promise.all) to cut
-// module-load latency; each still degrades to its local fallback on failure. We
-// keep the real functions when the junction resolves, and the fallbacks when a
-// host rc renamed/removed a symbol.
+// --- 接线函数映射型符号（模块顶层 await）---------------------------------------
+// 七个加载相互独立，并行（Promise.all）以削减模块加载延迟；每个失败仍降级到
+// 本地回退。junction 解析成功时保留真函数，宿主 rc 改名/移除符号时用回退。
 const [foldConsumedWork, finalAssistantOutput, createUserMessage, appendDelegatedPolicyOverrides, captureDelegatedPolicyOverrides, resolveChildAgentOptions, defineTool] = await Promise.all([
   loadSoft('@deepseek-ai/dsh-agent', 'foldConsumedWork', foldConsumedWorkFallback, 'dsh-agent 的 foldConsumedWork 不可用，结果裁切使用本地降级实现'),
   loadSoft('@deepseek-ai/dsh-subagent', 'finalAssistantOutput', finalAssistantOutputFallback, 'dsh-subagent 的 finalAssistantOutput 不可用，子结果选取使用本地降级实现'),
@@ -176,9 +158,9 @@ const [foldConsumedWork, finalAssistantOutput, createUserMessage, appendDelegate
   loadSoft('@deepseek-ai/dsh-tools', 'defineTool', defineToolFallback, 'dsh-tools 缺失：dispatch 工具不可用'),
 ]);
 
-// readResult: shipped shape. The terminal turn reason comes from foldConsumedWork;
-// the selected output comes from finalAssistantOutput (last non-empty assistant
-// message, else joined text-delta chunks, else undefined -> []).
+// readResult：官方形状。终止 turn 的原因来自 foldConsumedWork；选取的输出来自
+// finalAssistantOutput（最后一个非空 assistant/message，否则拼接的 text-delta
+// 分片，再否则 undefined -> []）。
 function readResult(child, boundary, cancelled) {
   const own = child.session.events.slice(boundary);
   const end = foldConsumedWork(own).end;
@@ -187,7 +169,7 @@ function readResult(child, boundary, cancelled) {
   return { output: finalAssistantOutput(own) ?? [], stopReason };
 }
 
-// --- version detection (pure probe) ------------------------------------------
+// --- 版本探测（纯探测）--------------------------------------------------------
 // 读取 @deepseek-ai 三包（subagent/agent/llm）的 package.json version，与
 // peerDependencies 范围（>=PEER_MIN <PEER_MAX）比对后产出中文 warnings。纯探测：
 // 只读 manifest、不 import 新符号、不触发副作用；每包独立 try/catch，失败记
@@ -209,6 +191,16 @@ function readPackageVersion(pkg) {
   }
 }
 
+// 读本插件自身 package.json version（fail-soft 'unknown'），供维护区显示当前版本。
+function readOwnPluginVersion() {
+  try {
+    const manifest = requirePkg('../../package.json');
+    return typeof manifest.version === 'string' && manifest.version !== '' ? manifest.version : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
 // 极简 semver 比较：major.minor.patch + 可选 `-预发布` 段（覆盖 peerDependencies
 // 范围判断所需）。预发布 < 正式版；预发布段逐段比较，纯数字段按数值、否则按字典序
 // （`0.1.0-rc.10` > `0.1.0-rc.6`）。
@@ -267,12 +259,11 @@ export function detectVersions(reader = readPackageVersion) {
       warnings.push(`@deepseek-ai/${pkg} 版本 ${version} 超出 peerDependencies 范围（>=${PEER_MIN} <${PEER_MAX}），派发行为可能与预期不符`);
     }
   }
-  return { versions, warnings };
+  return { versions, warnings, pluginVersion: readOwnPluginVersion() };
 }
 
-// Test-only access to the local degraded implementations (package imports
-// resolve here, so the real functions win; __fallbacks lets a test exercise the
-// fail-soft path without deleting node_modules).
+// 仅供测试访问本地降级实现（包导入在这里可解析，真函数胜出；`__fallbacks`
+// 让测试无需删 node_modules 即可走 fail-soft 路径）。
 export const __fallbacks = {
   foldConsumedWork: foldConsumedWorkFallback,
   finalAssistantOutput: finalAssistantOutputFallback,
@@ -286,7 +277,7 @@ export const __fallbacks = {
 export {
   assertSubagentMaxDepth,
   resolveChildDepth,
-  // ---- test seam / injectable loader (see loadSoft doc) ----
+  // ---- 测试接缝 / 可注入加载器（见 loadSoft 文档）----
   loadSoft,
   foldConsumedWork,
   finalAssistantOutput,
@@ -296,6 +287,6 @@ export {
   resolveChildAgentOptions,
   defineTool,
   readResult,
-  // ---- version probe seam (see detectVersions doc) ----
+  // ---- 版本探测接缝（见 detectVersions 文档）----
   readPackageVersion,
 };

package/lib/core/whitelist.mjs

@@ -1,22 +1,28 @@
-// lib/core/whitelist.mjs — target-preset whitelist derived from the runtime
-// roster, not hard-coded: system-trust presets when agentPresets exists, else
-// the shipped fallback names. Moved verbatim from index.mjs;
-// import-free (no @deepseek-ai dependency).
+// lib/core/whitelist.mjs — 目标预设白名单：从运行时名册推导，不硬编码——
+// agentPresets 存在时取 system-trust 预设，否则用官方回退名单。从 index.mjs
+// 逐字移出；import-free（无 @deepseek-ai 依赖）。
 //
-// Injection note: the original apply-closure version took `agentCtx` and read
-// `agentCtx.get('agentPresets')` itself. The caller now injects the service —
-// `resolveWhitelist(parent.ctx.get('agentPresets'))` — so the module does not
-// depend on apply-closure state. `parent.ctx.get('agentPresets')` yields the
-// exact same value (service or undefined), so the fallback semantics are
-// unchanged. FALLBACK_WHITELIST is exported for the tests.
-
-// The target-preset whitelist is derived from the runtime roster, not
-// hard-coded: system-trust presets when agentPresets exists, else the
-// shipped fallback names.
+// 注入说明：原 apply 闭包版本自带 `agentCtx` 并自己读
+// `agentCtx.get('agentPresets')`。调用方现在注入服务——
+// `resolveWhitelist(parent.ctx.get('agentPresets'))`——使模块不依赖 apply 闭包
+// 状态。`parent.ctx.get('agentPresets')` 得到完全相同的结果（服务或 undefined），
+// 回退语义不变。FALLBACK_WHITELIST 导出供测试用。
 export const FALLBACK_WHITELIST = ['standard', 'code', 'minimal'];
 
-export async function resolveWhitelist(agentPresets) {
-  if (agentPresets === undefined) return FALLBACK_WHITELIST;
+// 逃生舱叠加（可选）：escapeSet 是非 system-trust 预设的显式放行集（Set 或数组，
+// 由调用方在开关打开时传入）。只叠加——base 集原样保留、去重；逃生舱绝不替代或
+// 缩减 base 集，也不升级 base 成员的语义（逃生舱成员仍属「非 system 放行」）。
+// escapeSet 缺省/为空时零叠加（行为与旧单参调用完全一致）。
+function withEscapeSet(base, escapeSet) {
+  if (escapeSet === undefined) return base;
+  const extras = [...escapeSet].filter((id) => typeof id === 'string' && id !== '');
+  if (extras.length === 0) return base;
+  return [...new Set([...base, ...extras])];
+}
+
+export async function resolveWhitelist(agentPresets, escapeSet) {
+  if (agentPresets === undefined) return withEscapeSet(FALLBACK_WHITELIST, escapeSet);
   const presets = await agentPresets.list();
-  return (presets ?? []).filter((preset) => preset && preset.trust === 'system').map((preset) => preset.id);
+  const base = (presets ?? []).filter((preset) => preset && preset.trust === 'system').map((preset) => preset.id);
+  return withEscapeSet(base, escapeSet);
 }