dsh-subagent-profile 0.3.2 → 0.3.3

package/lib/core/presets-sync.mjs

@@ -1,136 +1,256 @@
-// lib/core/presets-sync.mjs — bundled agent-preset self-install (moved verbatim from
-// index.mjs; import-free — node builtins only, no @deepseek-ai dependency).
-//
-// 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';
-import { fileURLToPath } from 'node:url';
-
-// 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).
-export function bundledPresetsRoot() {
-  return fileURLToPath(new URL('../../presets', import.meta.url));
-}
-
-export const MTIME_TOLERANCE_MS = 1000;
-
-export function filesUnder(root) {
-  const out = [];
-  const walk = (dir) => {
-    for (const entry of readdirSync(dir)) {
-      const path = join(dir, entry);
-      if (statSync(path).isDirectory()) walk(path);
-      else out.push(path);
-    }
-  };
-  walk(root);
-  return out;
-}
-
-// File identity is bytes; size/mtime are only a fast negative check.
-export function sameFile(a, b) {
-  const sa = statSync(a);
-  const sb = statSync(b);
-  if (sa.size !== sb.size) return false;
-  if (Math.abs(sa.mtimeMs - sb.mtimeMs) > MTIME_TOLERANCE_MS) return false;
-  return readFileSync(a).equals(readFileSync(b));
-}
-
-export function copyTreeSync(sourceDir, targetDir) {
-  mkdirSync(targetDir, { recursive: true });
-  for (const entry of readdirSync(sourceDir)) {
-    const source = join(sourceDir, entry);
-    const target = join(targetDir, entry);
-    const st = statSync(source);
-    if (st.isDirectory()) copyTreeSync(source, target);
-    else {
-      copyFileSync(source, target);
-      utimesSync(target, st.atime, st.mtime);
-    }
-  }
-}
-
-// Remove target files not in `keep`, then only the directories emptied by it.
-export function pruneExtras(root, keep) {
-  const parents = new Set();
-  for (const file of filesUnder(root)) {
-    if (!keep.has(relative(root, file))) {
-      parents.add(dirname(file));
-      rmSync(file, { force: true });
-    }
-  }
-  for (const start of parents) {
-    let dir = start;
-    while (dir !== undefined && relative(root, dir) !== '') {
-      if (existsSync(dir) && readdirSync(dir).length === 0) {
-        rmSync(dir, { recursive: true, force: true });
-        dir = dirname(dir);
-      } else dir = undefined;
-    }
-  }
-}
-
-// Copy `sourceDir` into `targetDir` idempotently; returns 'synced' or 'current'.
-export function syncOnePreset(sourceDir, targetDir) {
-  const sourceFiles = filesUnder(sourceDir);
-  const sourceSet = new Set(sourceFiles.map((f) => relative(sourceDir, f)));
-  if (existsSync(targetDir) && !statSync(targetDir).isDirectory()) {
-    rmSync(targetDir, { recursive: true, force: true });
-  }
-  if (!existsSync(targetDir)) {
-    copyTreeSync(sourceDir, targetDir);
-    pruneExtras(targetDir, sourceSet);
-    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; }
-  }
-  if (!dirty) {
-    for (const file of filesUnder(targetDir)) {
-      if (!sourceSet.has(relative(targetDir, file))) { dirty = true; break; }
-    }
-  }
-  if (!dirty) return 'current';
-  pruneExtras(targetDir, sourceSet);
-  copyTreeSync(sourceDir, targetDir);
-  pruneExtras(targetDir, sourceSet);
-  return 'synced';
-}
-
-// Sync every preset directory under `presets/` into the target discovery root.
-export function syncBundledPresets(targetRoot) {
-  const result = { synced: [], current: [], failed: [] };
-  const sourceRoot = bundledPresetsRoot();
-  mkdirSync(targetRoot, { recursive: true });
-  if (existsSync(sourceRoot)) {
-    for (const entry of readdirSync(sourceRoot)) {
-      const source = join(sourceRoot, entry);
-      if (!statSync(source).isDirectory()) continue;
-      const id = basename(source);
-      try {
-        const outcome = syncOnePreset(source, join(targetRoot, id));
-        (outcome === 'synced' ? result.synced : result.current).push(id);
-      } catch (error) {
-        result.failed.push({ id, error: error instanceof Error ? error.message : String(error) });
-      }
-    }
-  }
-  return result;
-}
+// lib/core/presets-sync.mjs — bundled agent 预设自安装（从 index.mjs 逐字移出；
+// 仅 node 内置，无 @deepseek-ai 依赖）。
+//
+// 宿主启动时插件把 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';
+
+// 本包内 bundled 预设树的绝对路径。本模块在 lib/core/，比包根低两层，URL 必须
+// 上爬两段才能指向仓库根 `presets/` 目录（与它还在包根的 index.mjs 时解析到的
+// 值相同；Task 8.6 把模块从 lib/ 挪到 lib/core/ 后爬升必须写成 `../../` 而不是
+// `../`——preflight 的 preset 树对账抓到了那个错误版本指向不存在的 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) => {
+    for (const entry of readdirSync(dir)) {
+      const path = join(dir, entry);
+      if (statSync(path).isDirectory()) walk(path);
+      else out.push(path);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+// 文件同一性按字节；size/mtime 只作快速否定检查。
+export function sameFile(a, b) {
+  const sa = statSync(a);
+  const sb = statSync(b);
+  if (sa.size !== sb.size) return false;
+  if (Math.abs(sa.mtimeMs - sb.mtimeMs) > MTIME_TOLERANCE_MS) return false;
+  return readFileSync(a).equals(readFileSync(b));
+}
+
+export function copyTreeSync(sourceDir, targetDir) {
+  mkdirSync(targetDir, { recursive: true });
+  for (const entry of readdirSync(sourceDir)) {
+    const source = join(sourceDir, entry);
+    const target = join(targetDir, entry);
+    const st = statSync(source);
+    if (st.isDirectory()) copyTreeSync(source, target);
+    else {
+      copyFileSync(source, target);
+      utimesSync(target, st.atime, st.mtime);
+    }
+  }
+}
+
+// 删除 `keep` 之外的 target 文件，再只删因此清空的目录。
+export function pruneExtras(root, keep) {
+  const parents = new Set();
+  for (const file of filesUnder(root)) {
+    if (!keep.has(relative(root, file))) {
+      parents.add(dirname(file));
+      rmSync(file, { force: true });
+    }
+  }
+  for (const start of parents) {
+    let dir = start;
+    while (dir !== undefined && relative(root, dir) !== '') {
+      if (existsSync(dir) && readdirSync(dir).length === 0) {
+        rmSync(dir, { recursive: true, force: true });
+        dir = dirname(dir);
+      } else dir = undefined;
+    }
+  }
+}
+
+// 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 bundledHash = hashTree(sourceDir);
+  if (existsSync(targetDir) && !statSync(targetDir).isDirectory()) {
+    // M8：target 意外是文件（同名冲突）时先改名备份再清，避免直接 rmSync 丢失用户内容。
+    try { renameSync(targetDir, `${targetDir}.removed-${Date.now()}`); } catch { rmSync(targetDir, { recursive: true, force: true }); }
+  }
+  if (!existsSync(targetDir)) {
+    copyTreeSync(sourceDir, targetDir);
+    writeSidecar(targetDir, bundledHash, hashTree(targetDir));
+    return 'synced';
+  }
+  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';
+  }
+  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';
+  }
+  copyTreeSync(sourceDir, targetDir);
+  pruneExtras(targetDir, computeKeep(sourceDir, targetDir));
+  writeSidecar(targetDir, bundledHash, hashTree(targetDir));
+  return 'synced';
+}
+
+// 把 `presets/` 下每个 preset 目录同步进目标发现根。
+export function syncBundledPresets(targetRoot) {
+  const result = { synced: [], current: [], userModified: [], failed: [] };
+  const sourceRoot = bundledPresetsRoot();
+  mkdirSync(targetRoot, { recursive: true });
+  if (existsSync(sourceRoot)) {
+    for (const entry of readdirSync(sourceRoot)) {
+      const source = join(sourceRoot, entry);
+      if (!statSync(source).isDirectory()) continue;
+      const id = basename(source);
+      try {
+        const outcome = syncOnePreset(source, join(targetRoot, 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) });
+      }
+    }
+  }
+  return result;
+}

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,29 @@ 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（M4：descriptor 非空才 append）。
   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 (typeof request.descriptor === 'string' && request.descriptor !== '') 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 +177,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 +212,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 +232,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 },