dsh-subagent-profile 0.3.2 → 0.3.3

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，失败记
@@ -270,9 +252,8 @@ export function detectVersions(reader = readPackageVersion) {
   return { versions, warnings };
 }
 
-// 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 +267,7 @@ export const __fallbacks = {
 export {
   assertSubagentMaxDepth,
   resolveChildDepth,
-  // ---- test seam / injectable loader (see loadSoft doc) ----
+  // ---- 测试接缝 / 可注入加载器（见 loadSoft 文档）----
   loadSoft,
   foldConsumedWork,
   finalAssistantOutput,
@@ -296,6 +277,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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subagent-profile",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Dispatch one-shot subtasks to derived subagents with per-task overrides (preset/model/provider/reasoningEffort/persona/tool whitelist), a runtime-derived cost guard, a subagent-profiles service, observability metadata, and a web-GUI settings page plus a dispatch tool-call card.",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
     "lib",
     "cordis.patch.yml",
     "presets",
-    "docs",
+    "docs/screenshots",
     "README.md",
     "README.zh.md"
   ],
@@ -74,7 +74,6 @@
   ],
   "license": "MIT",
   "scripts": {
-    "release": "node scripts/release.mjs",
     "test": "node --test \"test/**/*.test.mjs\"",
     "test:bare": "node --test test/pure.test.mjs test/input-schema.test.mjs test/catalog-integrity.test.mjs",
     "preflight": "node scripts/preflight.mjs",