dsh-subagent-profile 0.3.2 → 0.3.4

package/lib/core/presets-sync.mjs

@@ -1,34 +1,37 @@
-// lib/core/presets-sync.mjs — bundled agent-preset self-install (moved verbatim from
-// index.mjs; import-free — node builtins only, no @deepseek-ai dependency).
+// lib/core/presets-sync.mjs — bundled agent 预设自安装（从 index.mjs 逐字移出；
+// 仅 node 内置，无 @deepseek-ai 依赖）。
 //
-// On host startup the plugin syncs the bundled `presets/` tree into the DSH
-// agent-presets discovery root (~/.dsh/.agent-presets) so the "orchestrator"
-// mode appears in the new-session picker without manual copying — the same
-// self-install pattern as the shipped dsh-liangshen bundle. The sync is
-// per-directory and idempotent (byte-identical trees are skipped; target files
-// the bundle no longer ships are pruned); directories the plugin does not own
-// are never touched. node:fs cpSync is avoided deliberately: on Node 22 for
-// Windows, fs.cpSync({ recursive: true }) can crash the process when a source
-// path contains non-ASCII (CJK home dir, nodejs/node#54476), so the copy is
-// per-entry, preserving source mtimes.
-
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, utimesSync } from 'node:fs';
-import { basename, dirname, join, relative } from 'node:path';
+// 宿主启动时插件把 bundled `presets/` 树同步进 DSH agent-presets 发现根
+// （~/.dsh/.agent-presets），使「编排者模式」无需手动复制就出现在新建会话
+// 选择器里——与官方 dsh-liangshen bundle 相同的自安装模式。同步按目录、
+// 经哈希门控：per-target sidecar（.dsh-sync.json）记录 bundled 内容哈希与派生树
+// 快照哈希，下次运行跳过未变化的树、跳过（绝不覆盖）用户改过的树；两侧都变时
+// 先把用户侧归档到 .user-modified-<timestamp>/ 再写入升级后的 bundled 内容。
+// bundle 不再提供的目标文件会被剪除；插件不拥有的目录永不触碰。
+// 刻意不用 node:fs cpSync：Node 22 的 Windows 上，fs.cpSync({ recursive: true })
+// 在源路径含非 ASCII（CJK 主目录，nodejs/node#54476）时可能崩溃进程，故逐条
+// 复制并保留源 mtime。
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
 
-// Absolute path of the bundled preset tree inside this package. This module
-// lives in lib/core/, two levels below the package root, so the URL must climb
-// back up two segments to still point at the repo-root `presets/` directory
-// (same resolved value as when this function lived in index.mjs at the package
-// root; Task 8.6 moved the module from lib/ to lib/core/ and the climb must be
-// `../../`, not `../` — preflight's preset-tree reconciliation caught the stale
-// one returning lib/presets, which silently disabled the startup self-install).
+// 本包内 bundled 预设树的绝对路径。本模块在 lib/core/，比包根低两层，URL 必须
+// 上爬两段才能指向仓库根 `presets/` 目录（与它还在包根的 index.mjs 时解析到的
+// 值相同；写错成 `../` 会指向不存在的 lib/presets，从而静默禁用启动自安装）。
 export function bundledPresetsRoot() {
   return fileURLToPath(new URL('../../presets', import.meta.url));
 }
 
 export const MTIME_TOLERANCE_MS = 1000;
 
+// 同步元数据：sidecar 记录最近一次 bundled/目标内容哈希，归档前缀命名三方
+// 用户编辑备份。两者都是插件本地记账、非 preset 内容——hashTree 排除它们、
+// prune 保留它们（否则 sidecar 自身写入会让目标哈希自指漂移，归档会被剪掉）。
+export const SIDECAR_NAME = '.dsh-sync.json';
+export const ARCHIVE_PREFIX = '.user-modified-';
+
 export function filesUnder(root) {
   const out = [];
   const walk = (dir) => {
@@ -42,7 +45,7 @@ export function filesUnder(root) {
   return out;
 }
 
-// File identity is bytes; size/mtime are only a fast negative check.
+// 文件同一性按字节；size/mtime 只作快速否定检查。
 export function sameFile(a, b) {
   const sa = statSync(a);
   const sb = statSync(b);
@@ -65,7 +68,7 @@ export function copyTreeSync(sourceDir, targetDir) {
   }
 }
 
-// Remove target files not in `keep`, then only the directories emptied by it.
+// 删除 `keep` 之外的 target 文件，再只删因此清空的目录。
 export function pruneExtras(root, keep) {
   const parents = new Set();
   for (const file of filesUnder(root)) {
@@ -85,38 +88,151 @@ export function pruneExtras(root, keep) {
   }
 }
 
-// Copy `sourceDir` into `targetDir` idempotently; returns 'synced' or 'current'.
+// preset 树内容哈希：每文件的相对路径 + 字节喂进 sha1。同步元数据（sidecar 与
+// 任何 `.user-modified-*` 归档）被排除——它是插件记账、非 preset 内容，纳入会使
+// 派生树哈希在 sidecar 被重写（自指）或归档创建时立即漂移。
+export function hashTree(root) {
+  const hash = createHash('sha1');
+  for (const file of filesUnder(root).sort()) {
+    const rel = relative(root, file);
+    if (isSyncMetadata(rel)) continue;
+    hash.update(rel);
+    hash.update('\0');
+    hash.update(readFileSync(file));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+// 相对 preset 根的路径是否为同步元数据（sidecar 文件，或 `.user-modified-*`
+// 归档目录下的任何内容）。
+export function isSyncMetadata(rel) {
+  const head = rel.split(sep)[0];
+  return head === SIDECAR_NAME || head.startsWith(ARCHIVE_PREFIX);
+}
+
+export function sidecarPath(targetDir) {
+  return join(targetDir, SIDECAR_NAME);
+}
+
+// 读 sidecar；缺失或畸形（版本错 / 哈希字段缺 / 解析失败）按缺失处理，使下次
+// 同步走保守的首跑路径，而不是信任损坏的记账。
+function readSidecar(targetDir) {
+  const path = sidecarPath(targetDir);
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (parsed && parsed.version === 1 && typeof parsed.bundledHash === 'string' && typeof parsed.targetHash === 'string') {
+      return parsed;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeSidecar(targetDir, bundledHash, targetHash) {
+  writeFileSync(sidecarPath(targetDir), `${JSON.stringify({ version: 1, bundledHash, targetHash }, null, 2)}\n`);
+}
+
+// 复制一个文件系统条目（文件或目录），保留逐条语义与源 mtime——与 copyTreeSync
+// 自身文件分支同形。
+function copyEntry(source, dest) {
+  const st = statSync(source);
+  if (st.isDirectory()) copyTreeSync(source, dest);
+  else {
+    copyFileSync(source, dest);
+    utimesSync(dest, st.atime, st.mtime);
+  }
+}
+
+// 覆盖前把当前（用户可见的）preset 树归档到
+// <targetDir>/.user-modified-<timestamp>/。sidecar 与既有归档被排除，归档不会
+// 嵌套。写失败返回 false——调用方必须跳过本次同步、保留用户编辑原样
+// （fail-safe：备份失败绝不允许成为销毁用户内容的许可）。
+function archiveUserTree(targetDir) {
+  const archiveDir = join(targetDir, `${ARCHIVE_PREFIX}${Date.now()}`);
+  // 先拍下要归档的条目再创建 archiveDir：归档位于 targetDir 之下，mkdirSync 后
+  // 再读目录会把归档本身读进来，无限递归进它自己。
+  const entries = [];
+  for (const entry of readdirSync(targetDir)) {
+    if (entry === SIDECAR_NAME || entry.startsWith(ARCHIVE_PREFIX)) continue;
+    entries.push(entry);
+  }
+  try {
+    mkdirSync(archiveDir, { recursive: true });
+    for (const entry of entries) {
+      copyEntry(join(targetDir, entry), join(archiveDir, entry));
+    }
+    return true;
+  } catch {
+    try { rmSync(archiveDir, { recursive: true, force: true }); } catch { /* best effort */ }
+    return false;
+  }
+}
+
+// pruneExtras 的 keep 集：同步后树必须保留的一切——bundled 文件、sidecar、
+// 既有 `.user-modified-*` 归档下的每个文件。keep 里没有归档条目的话，
+// pruneExtras 会在同步当下删掉归档，静默丢弃它本该保留的用户编辑。
+function computeKeep(sourceDir, targetDir) {
+  const keep = new Set(filesUnder(sourceDir).map((f) => relative(sourceDir, f)));
+  keep.add(SIDECAR_NAME);
+  if (existsSync(targetDir)) {
+    for (const entry of readdirSync(targetDir)) {
+      if (!entry.startsWith(ARCHIVE_PREFIX)) continue;
+      const dir = join(targetDir, entry);
+      if (!statSync(dir).isDirectory()) continue;
+      for (const f of filesUnder(dir)) keep.add(relative(targetDir, f));
+    }
+  }
+  return keep;
+}
+
+// 同步一个 preset 目录。返回 'synced'（写入或升级）、'current'（未变）或
+// 'user-modified'（target 偏离上次同步快照而跳过——绝不覆盖用户编辑）。判定表：
+//   - target 不存在                  → 复制 + 写 sidecar          → 'synced'
+//   - 无 sidecar、target 存在        → 一次性归档 + 同步          → 'synced'
+//   - bundled 未变、target 相同      → 'current'
+//   - bundled 未变、target 漂移      → 'user-modified'（跳过）
+//   - bundled 变了                   → 漂移则先归档，再同步       → 'synced'
 export function syncOnePreset(sourceDir, targetDir) {
-  const sourceFiles = filesUnder(sourceDir);
-  const sourceSet = new Set(sourceFiles.map((f) => relative(sourceDir, f)));
+  const bundledHash = hashTree(sourceDir);
   if (existsSync(targetDir) && !statSync(targetDir).isDirectory()) {
-    rmSync(targetDir, { recursive: true, force: true });
+    // target 意外是文件（同名冲突）时先改名备份再清，避免直接 rmSync 丢失用户内容。
+    try { renameSync(targetDir, `${targetDir}.removed-${Date.now()}`); } catch { rmSync(targetDir, { recursive: true, force: true }); }
   }
   if (!existsSync(targetDir)) {
     copyTreeSync(sourceDir, targetDir);
-    pruneExtras(targetDir, sourceSet);
+    writeSidecar(targetDir, bundledHash, hashTree(targetDir));
     return 'synced';
   }
-  let dirty = false;
-  for (const file of sourceFiles) {
-    const dest = join(targetDir, relative(sourceDir, file));
-    if (!existsSync(dest) || !sameFile(file, dest)) { dirty = true; break; }
+  const sidecar = readSidecar(targetDir);
+  // 无 sidecar + 既有 target = 门控前状态：无法判断用户是否编辑过，按「可能编辑
+  // 过」处理，在首次门控同步前归档一次（一次性迁移）。
+  if (sidecar === undefined) {
+    if (!archiveUserTree(targetDir)) return 'user-modified';
+    copyTreeSync(sourceDir, targetDir);
+    pruneExtras(targetDir, computeKeep(sourceDir, targetDir));
+    writeSidecar(targetDir, bundledHash, hashTree(targetDir));
+    return 'synced';
   }
-  if (!dirty) {
-    for (const file of filesUnder(targetDir)) {
-      if (!sourceSet.has(relative(targetDir, file))) { dirty = true; break; }
-    }
+  const currentTargetHash = hashTree(targetDir);
+  if (sidecar.bundledHash === bundledHash) {
+    return sidecar.targetHash === currentTargetHash ? 'current' : 'user-modified';
+  }
+  // bundled 升级。用户也改过 target（快照漂移）时先归档其树，编辑不会静默丢失。
+  if (sidecar.targetHash !== currentTargetHash) {
+    if (!archiveUserTree(targetDir)) return 'user-modified';
   }
-  if (!dirty) return 'current';
-  pruneExtras(targetDir, sourceSet);
   copyTreeSync(sourceDir, targetDir);
-  pruneExtras(targetDir, sourceSet);
+  pruneExtras(targetDir, computeKeep(sourceDir, targetDir));
+  writeSidecar(targetDir, bundledHash, hashTree(targetDir));
   return 'synced';
 }
 
-// Sync every preset directory under `presets/` into the target discovery root.
+// 把 `presets/` 下每个 preset 目录同步进目标发现根。
 export function syncBundledPresets(targetRoot) {
-  const result = { synced: [], current: [], failed: [] };
+  const result = { synced: [], current: [], userModified: [], failed: [] };
   const sourceRoot = bundledPresetsRoot();
   mkdirSync(targetRoot, { recursive: true });
   if (existsSync(sourceRoot)) {
@@ -126,7 +242,9 @@ export function syncBundledPresets(targetRoot) {
       const id = basename(source);
       try {
         const outcome = syncOnePreset(source, join(targetRoot, id));
-        (outcome === 'synced' ? result.synced : result.current).push(id);
+        if (outcome === 'synced') result.synced.push(id);
+        else if (outcome === 'current') result.current.push(id);
+        else result.userModified.push(id);
       } catch (error) {
         result.failed.push({ id, error: error instanceof Error ? error.message : String(error) });
       }

package/lib/core/prices.mjs

@@ -0,0 +1,46 @@
+// lib/core/prices.mjs — 模型单价表（纯数据）。
+// 来源：docs/measured-params.md / docs/cost-closed-loop-design.md（2026-08-24 实测）。
+// 口径：估算、非精确计费；A 级为「单次均价」、B 级为「五段单价」（元/千 token）。
+// 可被 A″ / F 数据层复用（同源同表，不散落魔法数）。
+
+// A 级：模型 → 单次均价（元/次）。同规模派发实测：flash 0.0039、继承父（pro）0.0104。
+export const MODEL_AVG_COST = Object.freeze({
+  'deepseek-v4-flash': 0.0039,
+  'deepseek-v4-pro': 0.0104,
+});
+
+// B 级：模型 → 五段单价（元/千 token）。当前仅有单次均价实测，五段单价先按
+// 均价占位（input/output 同价），保留键结构供未来实测回填；cache 段缺数据记 null。
+export const MODEL_USAGE_PRICES = Object.freeze({
+  'deepseek-v4-flash': Object.freeze({
+    inputTokens: null,
+    outputTokens: null,
+    cacheReadTokens: null,
+    cacheWriteTokens: null,
+    reasoningTokens: null,
+    avgCost: MODEL_AVG_COST['deepseek-v4-flash'],
+  }),
+  'deepseek-v4-pro': Object.freeze({
+    inputTokens: null,
+    outputTokens: null,
+    cacheReadTokens: null,
+    cacheWriteTokens: null,
+    reasoningTokens: null,
+    avgCost: MODEL_AVG_COST['deepseek-v4-pro'],
+  }),
+});
+
+// 模型名归一：常见别名/前缀统一到价格键；未知返回 undefined（fail-soft 不猜价）。
+export function priceKeyFor(model) {
+  if (typeof model !== 'string' || model === '') return undefined;
+  const m = model.trim().toLowerCase();
+  if (MODEL_AVG_COST[m] !== undefined) return m;
+  if (m.includes('flash')) return 'deepseek-v4-flash';
+  if (m.includes('pro')) return 'deepseek-v4-pro';
+  return undefined;
+}
+
+export function avgCostFor(model) {
+  const key = priceKeyFor(model);
+  return key === undefined ? undefined : MODEL_AVG_COST[key];
+}

package/lib/core/profile-directory.mjs

@@ -0,0 +1,139 @@
+// lib/core/profile-directory.mjs — 派发方案目录的单一数据源。
+// profileSectionText（模型可见段）与 profileSnapshotOf（决策轨迹记录面）都从
+// 本模块的 profileDirectoryRows 派生，构造保证「模型看到 ≡ 记录面」的 id、顺序与
+// 字段集。未来 F 数据层注入 avg_cost / success_rate 只改这里一处。
+//
+// 仅依赖 lib/core/pure.mjs（tierSortKey）；无 @deepseek-ai 依赖，可被 bare-CI
+// 单测直接 import。
+
+import { tierSortKey } from './pure.mjs';
+
+// 决策输入快照阈值：profiles_snapshot 条目数与 description 截断长度。
+const MAX_PROFILE_SNAPSHOT_ENTRIES = 6;
+const PROFILE_DESC_CHARS = 80;
+
+function snapshotEntry(row, maxDesc) {
+  const description = typeof row.description === 'string' ? row.description : '';
+  return {
+    id: row.id,
+    ...(description !== '' ? { description: description.length > maxDesc ? `${description.slice(0, maxDesc)}…` : description } : {}),
+    ...(typeof row.preset === 'string' && row.preset !== '' ? { preset: row.preset } : {}),
+    ...(typeof row.model === 'string' && row.model !== '' ? { model: row.model } : {}),
+    ...(typeof row.provider === 'string' && row.provider !== '' ? { provider: row.provider } : {}),
+    ...(typeof row.tokenTier === 'string' && row.tokenTier !== '' ? { tokenTier: row.tokenTier } : {}),
+    ...(typeof row.avgCost === 'number' && Number.isFinite(row.avgCost) ? { avgCost: row.avgCost } : {}),
+    ...(typeof row.successRate === 'number' && Number.isFinite(row.successRate) ? { successRate: row.successRate } : {}),
+  };
+}
+
+// 模型可见 profile 目录快照：输入为 profileDirectoryRows 的结构化行。description
+// 截断、条目数截到 maxEntries；chosenId 超出 maxEntries 时并入该条并打
+// chosenOutsideSnapshot（37b：截断不得制造审计空洞）。
+export function profileSnapshotOf(profiles, { maxEntries = MAX_PROFILE_SNAPSHOT_ENTRIES, maxDesc = PROFILE_DESC_CHARS, chosenId } = {}) {
+  const list = Array.isArray(profiles) ? profiles : [];
+  const full = [];
+  for (const row of list) {
+    if (row === null || typeof row !== 'object' || typeof row.id !== 'string' || row.id === '') continue;
+    if (row.enabled === false) continue;
+    full.push(snapshotEntry(row, maxDesc));
+  }
+  const entries = full.slice(0, maxEntries);
+  let truncated = full.length > maxEntries;
+  if (typeof chosenId === 'string' && chosenId !== '' && chosenId !== '(inline)' && !entries.some((e) => e.id === chosenId)) {
+    const chosen = full.find((e) => e.id === chosenId);
+    if (chosen !== undefined) {
+      entries.push({ ...chosen, chosenOutsideSnapshot: true });
+      truncated = true;
+    }
+  }
+  return { entries, truncated, total: full.length };
+}
+
+// store 兼容 createProfileStore 返回形态（含 profiles Map）；也接受数组（测试与
+// 非标准调用方）。只保留启用且 id 合法的方案；按 tokenTier cheap-first 稳定排序，
+// tier 相同按 id 升序（确定性，不依赖 Map 插入序的跨运行差异）。
+export function profileDirectoryRows(store) {
+  const source = store !== null && typeof store === 'object' && store.profiles !== undefined
+    ? [...store.profiles.values()]
+    : (Array.isArray(store) ? store : []);
+  return source
+    .filter((p) => p !== null && typeof p === 'object' && typeof p.id === 'string' && p.id !== '' && p.enabled !== false)
+    .sort((a, b) => tierSortKey(a.tokenTier) - tierSortKey(b.tokenTier) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .map((p) => ({
+      id: p.id,
+      description: typeof p.description === 'string' ? p.description : '',
+      ...(typeof p.preset === 'string' && p.preset !== '' ? { preset: p.preset } : {}),
+      ...(typeof p.model === 'string' && p.model !== '' ? { model: p.model } : {}),
+      ...(typeof p.provider === 'string' && p.provider !== '' ? { provider: p.provider } : {}),
+      ...(typeof p.tokenTier === 'string' && p.tokenTier !== '' ? { tokenTier: p.tokenTier } : {}),
+      ...(typeof p.avgCost === 'number' && Number.isFinite(p.avgCost) ? { avgCost: p.avgCost } : {}),
+      ...(typeof p.successRate === 'number' && Number.isFinite(p.successRate) ? { successRate: p.successRate } : {}),
+    }));
+}
+
+
+// 从 summaries.json 的 l1/l2 聚合为每个 profile 提取 { avgCost, successRate, n }。
+// 匹配优先级：profile.model → L2 model 轴；profile.preset → L2 preset 轴。多个 L1
+// 组共享同一轴值时按成本与部署量合并（avg_cost = Σestimated_cost / Σpriced；
+// successRate = Σcompleted / Σdeployments）。无数据返回 null，调用方省略显示。
+export function profileStatsFromSummaries(store, summaries) {
+  const rows = profileDirectoryRows(store);
+  const l2 = summaries !== null && typeof summaries === 'object' && summaries.l2 !== null && typeof summaries.l2 === 'object' ? summaries.l2 : {};
+  const byModel = new Map();
+  const byPreset = new Map();
+  for (const [key, group] of Object.entries(l2)) {
+    if (group === null || typeof group !== 'object') continue;
+    const modelMatch = /:model:([^|]+)$/.exec(key);
+    if (modelMatch) {
+      const arr = byModel.get(modelMatch[1]) ?? [];
+      arr.push(group);
+      byModel.set(modelMatch[1], arr);
+      continue;
+    }
+    const presetMatch = /:preset:([^|]+)$/.exec(key);
+    if (presetMatch) {
+      const arr = byPreset.get(presetMatch[1]) ?? [];
+      arr.push(group);
+      byPreset.set(presetMatch[1], arr);
+    }
+  }
+  const merge = (groups) => {
+    let deployments = 0;
+    let completed = 0;
+    let priced = 0;
+    let cost = 0;
+    for (const g of groups) {
+      deployments += Number.isFinite(g.deployments_total) ? g.deployments_total : 0;
+      completed += Number.isFinite(g.outcome?.completed) ? g.outcome.completed : 0;
+      priced += Number.isFinite(g.cost?.priced) ? g.cost.priced : 0;
+      cost += Number.isFinite(g.cost?.estimated_cost) ? g.cost.estimated_cost : 0;
+    }
+    if (deployments <= 0 && priced <= 0) return null;
+    return {
+      avgCost: priced > 0 ? Number((cost / priced).toFixed(4)) : null,
+      successRate: deployments > 0 ? Number((completed / deployments).toFixed(3)) : null,
+      n: deployments,
+    };
+  };
+  const out = new Map();
+  for (const row of rows) {
+    let stats = null;
+    if (typeof row.model === 'string' && row.model !== '') stats = merge(byModel.get(row.model) ?? []);
+    if (stats === null && typeof row.preset === 'string' && row.preset !== '') stats = merge(byPreset.get(row.preset) ?? []);
+    if (stats !== null) out.set(row.id, stats);
+  }
+  return out;
+}
+
+// 用 stats map 为目录行补 avgCost/successRate（F 数据层 join）。stats 为
+// profileStatsFromSummaries 的返回值；行上已有 avgCost/successRate 时优先保留
+// 显式值（store 侧/测试注入），stats 只补缺失。
+export function applyProfileStats(rows, stats) {
+  const map = stats instanceof Map ? stats : new Map(Object.entries(stats ?? {}));
+  return rows.map((row) => ({
+    ...row,
+    ...(row.avgCost === undefined && map.get(row.id)?.avgCost !== null && map.get(row.id)?.avgCost !== undefined ? { avgCost: map.get(row.id).avgCost } : {}),
+    ...(row.successRate === undefined && map.get(row.id)?.successRate !== null && map.get(row.id)?.successRate !== undefined ? { successRate: map.get(row.id).successRate } : {}),
+    ...(map.get(row.id)?.n !== undefined ? { n: map.get(row.id).n } : {}),
+  }));
+}

package/lib/core/profile-provider.mjs

@@ -3,15 +3,13 @@
 // `ctx.subagents.registerProvider({...})` 块逐字拆出。仅引用 lib + shims；
 // 无 @deepseek-ai 依赖（shims 是唯一入口）。
 //
-// Injection: every apply-closure / ctx dependency is an explicit parameter —
-//   subagents   the registry this provider is registered into
-//               (subagents.registerProvider is called by the factory),
-//   store       the profile store (getAllowFailOpen for the cost guard),
-//   getEnabled  reads the apply-closure `enabled` flag (start fails loud when
-//               off),
-//   logger      ctx.logger (decision-level child log).
-// The factory returns whatever registerProvider returns (the caller keeps the
-// original `if (typeof disposeProvider === 'function') ctx.effect(...)` shape).
+// 注入：所有 apply 闭包 / ctx 依赖都是显式参数——
+//   subagents   本 provider 注册进的注册表（工厂内调用 subagents.registerProvider），
+//   store       profile store（getAllowFailOpen 供 cost guard），
+//   getEnabled  读取 apply 闭包 `enabled` 标志（关时 start fail-loud），
+//   logger      ctx.logger（决策级子会话日志）。
+// 工厂返回 registerProvider 的返回值（调用方保持原有
+// `if (typeof disposeProvider === 'function') ctx.effect(...)` 形状）。
 //
 // start 按预检段（runStartPreflight）/ 结算+取消接线段（wireChildLifecycle）
 // 拆为模块级私有函数；start 内嵌 setup 按 ①-⑦ 步拆 setupChild +
@@ -40,26 +38,32 @@ import { DELEGATION_CONTEXT, buildDispatchMeta } from './delegation.mjs';
 // agentOptions，一次性返回 start 后续段所需的全部状态。
 async function runStartPreflight(request, deps) {
   if (!deps.getEnabled()) {
-    throw new Error('dispatch: the subagent-profile plugin is disabled (re-enable it in 设置 → 子 Agent 方案)');
+    throw new Error('dispatch: 插件已禁用（可在设置 → 子 Agent 方案 中重新启用）');
   }
   const profile = request.profile;
   if (profile === undefined) {
-    throw new Error('dispatch: request.profile is missing (the dispatch tool must resolve a profile before starting)');
+    throw new Error('dispatch: request.profile 缺失（dispatch 工具在启动子 Agent 前必须解析出 profile，请检查调用参数）');
   }
   const parent = request.parent;
   // 同步捕获委派策略，在首个 await 之前——之后的父会话切换属于父的未来，
   // 不属于本 child（shipped captureDelegatedPolicyOverrides）。
   const delegated = captureDelegatedPolicyOverrides(parent);
-  // 权威 preset whitelist 检查（对照运行时名册）。
-  const whitelist = new Set(await resolveWhitelist(parent.ctx.get('agentPresets')));
+  // 权威 preset whitelist 检查（对照运行时名册）。逃生舱只叠加：开关开时
+  // getEscapeSet 返回放行集，否则空数组（零叠加）。
+  const whitelist = new Set(await resolveWhitelist(parent.ctx.get('agentPresets'), deps.getEscapeSet()));
   if (typeof profile.preset === 'string' && profile.preset !== 'inherit' && !whitelist.has(profile.preset)) {
-    throw new Error(`dispatch: preset "${profile.preset}" is not in the target-preset whitelist`);
+    throw new Error(`dispatch: 预设 "${profile.preset}" 不在 system-trust 白名单（可在设置页改用受信任预设）`);
+  }
+  // 放行审计（provider 渠道）：成员经逃生舱放行时同样写高可见治理审计（「每个放行
+  // 都留痕」的绝对语义覆盖非 dispatch 渠道）。成本闸在本函数下方、交集在子会话
+  // setup 时执行——审计快照按 provider 渠道口径标注。
+  if (typeof deps.recordEscapeAllowProvider === 'function' && deps.getEscapeSet().includes(profile.preset)) {
+    deps.recordEscapeAllowProvider(parent, profile.preset);
   }
   // 权威 cost guard（运行时推导；硬上限始终生效，llm 能力核验由 allowFailOpen 门控；
   // llm 目录读取走共享 catalog 快照）。
   await assertCostGuard(parent, profile, deps.store.getAllowFailOpen(), deps.logger, deps.catalog);
-  // Delegation depth: shipped helpers — assert the cap value, then resolve
-  // the child depth (parent floor + 1) and enforce the cap.
+  // 委派深度：官方助手——先断言上限值，再解析子深度（父底 + 1）并执行上限。
   assertSubagentMaxDepth(profile.maxDepth);
   const childDepth = resolveChildDepth(parent, profile.maxDepth);
   const childId = randomUUID();
@@ -88,9 +92,8 @@ function buildProviderMeta(parent, profile, swapPreset, childDepth) {
   });
 }
 
-// agentOptions: shipped resolveChildAgentOptions — parent route inherited
-// unless the profile overrides provider/model/maxTokens, stamped with the
-// child's own delegation depth.
+// agentOptions：官方 resolveChildAgentOptions——父路由继承，除非 profile 覆盖
+// provider/model/maxTokens，并盖上子自身的委派深度。
 function buildProviderAgentOptions(parent, profile, childDepth) {
   return resolveChildAgentOptions(parent, {
     ...(profile.provider !== undefined ? { provider: profile.provider } : {}),
@@ -103,7 +106,7 @@ function buildProviderAgentOptions(parent, profile, childDepth) {
 async function startProvider(request, deps) {
   const { parent, profile, delegated, childId, swapPreset, meta, agentOptions } = await runStartPreflight(request, deps);
   if (request.signal !== undefined && request.signal.aborted) {
-    throw new Error('dispatch: subagent request was aborted before child publication');
+    throw new Error('dispatch: 子 Agent 请求在发布前已被取消（可重试一次派发）');
   }
   const handle = await parent.ctx.agents.create({
     sessionId: childId,
@@ -118,12 +121,12 @@ async function startProvider(request, deps) {
 // --- start 内嵌 setup(childCtx)：按 ①-⑦ 步装配子 Agent 会话（从 start 拆出）-------
 
 async function setupChild(childCtx, { parent, profile, swapPreset, delegated, request }) {
-  // ① Preset composition: explicit swap mounts the target preset; otherwise
-  // compose from the parent. Rosterless + explicit swap fails loud.
+  // ① 预设组合：显式 swap 挂载目标预设；否则从父组合。无名册 + 显式 swap
+  // fail-loud。
   const childPresets = childCtx.get('agentPresets');
   if (swapPreset) {
     if (childPresets === undefined) {
-      throw new Error('dispatch: cannot swap preset in a rosterless deployment');
+      throw new Error('dispatch: 无法在无预设名册的部署中切换预设（该部署不支持自定义预设挂载，可省略 preset 以继承父预设）');
     }
     await childPresets.mount(childCtx, profile.preset);
   } else if (childPresets !== undefined) {
@@ -131,12 +134,12 @@ async function setupChild(childCtx, { parent, profile, swapPreset, delegated, re
   }
   // ② Tool intersection（safety gate 1，实现见 restrictChildTools）。
   restrictChildTools(childCtx, parent, profile);
-  // ③ Delegation scope declaration (when systemPrompt is available).
+  // ③ 委派范围声明（systemPrompt 可用时）。
   const systemPrompt = childCtx.get('systemPrompt');
   if (systemPrompt !== undefined) {
     systemPrompt.context({ name: 'subagent:delegation', order: 120, text: DELEGATION_CONTEXT });
   }
-  // ④ Persona shadow (overrides deployment:persona at order 0). 双防线 prefix.
+  // ④ Persona 影子段（覆盖 order 0 的 deployment:persona）。双防线 prefix。
   if (profile.persona !== undefined && systemPrompt !== undefined) {
     systemPrompt.section({
       name: 'deployment:persona',
@@ -144,30 +147,30 @@ async function setupChild(childCtx, { parent, profile, swapPreset, delegated, re
       text: profile.persona.length > 0 ? `${GUIDANCE_PREFIX}${profile.persona}` : profile.persona,
     });
   }
-  // ⑤ Reasoning-effort injection into every child request.
+  // ⑤ 推理档位注入每个子请求。
   if (profile.reasoningEffort !== undefined) {
     childCtx.on('agent/request', async (_payload, next) => {
       const resolved = await next();
       return { ...resolved, reasoningEffort: profile.reasoningEffort };
     });
   }
-  // ⑥ Descriptor append inside the child's first turn.
+  // ⑥ Descriptor append inside the child's first turn（descriptor 存在才 append；
+  // 核心注入的是对象（snapshotJsonValue 快照），早期版本为字符串，故只判存在不判类型）。
   let appended = false;
   childCtx.on('agent/pre-step', async ({ agent }, next) => {
     const decision = await next();
     if (!appended && decision.kind === 'enter') {
       appended = true;
-      agent.session.append('subagent/descriptor', request.descriptor);
+      if (request.descriptor !== undefined && request.descriptor !== null) agent.session.append('subagent/descriptor', request.descriptor);
     }
     return decision;
   });
-  // ⑦ Delegation policy appends (shipped helper).
+  // ⑦ 委派策略追加（官方助手）。
   appendDelegatedPolicyOverrides(childCtx.agent.session, delegated);
 }
 
-// ② Tool intersection (safety gate 1): parent set ∩ child set, minus
-// run_code, minus deny, then narrowed by allow when present (pure core in
-// lib/core/intersection.mjs: computeEffectiveAllow).
+// ② 工具交集（安全门 1）：父集 ∩ 子集，减去 run_code、减去 deny，存在 allow
+// 时再收窄（纯核心在 lib/core/intersection.mjs：computeEffectiveAllow）。
 function restrictChildTools(childCtx, parent, profile) {
   const parentNames = new Set(parent.ctx.tools.schemas(parent).map((schema) => schema.name));
   const childNames = childCtx.tools.schemas(childCtx.agent).map((schema) => schema.name);
@@ -175,14 +178,14 @@ function restrictChildTools(childCtx, parent, profile) {
   // shipped restrict 不对 allow:[] throw——在此 fail-loud，让空交集显式化
   // （throw ⇒ setupAndPublish 回滚创建）。
   if (effective.length === 0) {
-    throw new Error('dispatch: child tool intersection is empty (zero tools)');
+    throw new Error('dispatch: 子工具交集为空（父工具集与子工具集无交集，或 toolFilter 过滤后为空，可放宽过滤器后重试）');
   }
-  // restrict throws on unknown/scope-local/reserved allow sets: wrap
-  // in a clean error and rethrow to trigger creation rollback.
+  // restrict 对未知/scope-local/保留 allow 集抛错：包成干净错误再 rethrow，
+  // 触发创建回滚。
   try {
     childCtx.tools.restrict({ allow: effective });
   } catch (error) {
-    throw new Error(`dispatch: child tool restriction failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    throw new Error(`dispatch: 子工具限制失败（未能按交集限制子工具集：${error instanceof Error ? error.message : String(error)}），可检查 toolFilter 是否含未知工具`, { cause: error });
   }
 }
 
@@ -210,7 +213,7 @@ function wireChildLifecycle(handle, request, childId, swapPreset, profile, logge
         await child.whenIdle();
       }
       const settled = readResult(child, boundary, flags.cancelled);
-      // Decision-level log at result settlement (readResult, before return).
+      // 决策级日志在结果结算时（readResult，返回前）。
       logger.info('[dsh-subagent-profile] child:', JSON.stringify({ childId, preset: profile.preset ?? 'inherit', swapPreset, stopReason: settled.stopReason }));
       return settled;
     } finally {
@@ -230,8 +233,8 @@ function wireChildLifecycle(handle, request, childId, swapPreset, profile, logge
   };
 }
 
-export function createProfileProvider({ subagents, store, getEnabled, logger, catalog }) {
-  const deps = { store, getEnabled, logger, catalog };
+export function createProfileProvider({ subagents, store, getEnabled, logger, catalog, getEscapeSet }) {
+  const deps = { store, getEnabled, logger, catalog, getEscapeSet };
   return subagents.registerProvider({
     name: 'profile',
     capabilities: { outputSchema: false, depthLimit: true, toolFilter: true, persona: true },