dsh-subagent-profile 0.3.0 → 0.3.1

package/lib/core/http-routes.mjs

@@ -1,8 +1,9 @@
-// lib/core/http-routes.mjs — settings HTTP loopback routes for the Client UI,
-// moved verbatim from index.mjs's `ctx.inject(['webServer'], (scope) => {...})`
-// block. Local lib references only: sanitizeProfile from
-// lib/core/pure.mjs, TOOL_ZH/TOOL_CATEGORY from lib/core/catalog.mjs, BUILTIN_SEEDS from
-// lib/core/profiles-store.mjs; no @deepseek-ai dependency.
+// lib/core/http-routes.mjs — settings HTTP loopback routes for the Client UI.
+// Read routes (list / options summary / per-model efforts / tools) + write
+// routes (set-enabled / add / remove / reset / reset-all / set-profile-enabled).
+// The /options catalog (models / presets / tools / efforts) is served from the
+// shared catalog cache (lib/core/catalog-cache.mjs), so these routes no longer
+// walk the llm directory themselves.
 //
 // Injection: every apply-closure / ctx dependency is an explicit parameter —
 //   store         the profile store (profiles Map / persistProfiles /
@@ -11,20 +12,17 @@
 //                 /set-enabled),
 //   setEnabled    writes it,
 //   syncTool      unregisters/registers the dispatch tool on /set-enabled,
-//   getLlm / getAgentPresets / getTools
-//                 request-time service getters (ctx.get('llm') etc. are read
-//                 per request, never at apply time),
-//   logger        ctx.logger (route error / tools-directory warnings).
+//   catalog       the shared catalog cache (getSnapshot / invalidate),
+//   logger        ctx.logger (route error warnings).
 // The factory returns the scope.effect setup function so the caller keeps the
 // exact original registration shape: effect(() => register + disposer).
 //
-// 8 条路由各抽为模块级处理函数（if 链分发保持）；/options 的目录构建抽
-// collectModelDirectory / collectSystemPresets / collectToolsDirectory。
-// 行为逐字不变（错误文案/状态码/schema）。
+// 写路由各抽为模块级处理函数（if 链分发保持）；/options 拆三读路由 + 手动刷新，
+// 目录数据统一来自 catalog 快照。
 
 import { sanitizeProfile } from './pure.mjs';
-import { TOOL_ZH, TOOL_CATEGORY } from './catalog.mjs';
 import { BUILTIN_SEEDS } from './profiles-store.mjs';
+import { detectVersions } from './shims.mjs';
 
 // Only the loopback interfaces may drive the settings HTTP routes.
 const LOOPBACKS = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
@@ -80,123 +78,36 @@ async function handleList(deps, res) {
   return json(res, 200, { ok: true, profiles: listClean(deps.store) });
 }
 
-// /options 的模型目录 + 每模型 reasoning-effort 等级（llm 可选，失败仅清空）。
-async function collectModelDirectory(llm) {
-  const models = [];
-  const efforts = {};
-  const providers = await llm.listProviders();
-  for (const provider of (providers ?? [])) {
-    const providerId = provider && provider.id;
-    if (typeof providerId !== 'string') continue;
-    let modelList = [];
-    try { modelList = await llm.listModels(providerId); } catch { /* skip this provider's catalog */ }
-    for (const model of (modelList ?? [])) {
-      if (!model || typeof model.id !== 'string') continue;
-      models.push({
-        provider: providerId,
-        providerName: provider.name ?? providerId,
-        id: model.id,
-        name: model.name ?? model.id
-      });
-      try {
-        const info = await llm.resolveModelInfo(providerId, model.id);
-        const effortsList = info && info.reasoning && Array.isArray(info.reasoning.efforts) ? info.reasoning.efforts : [];
-        efforts[model.id] = effortsList.map((effort) => ({
-          id: effort.id,
-          name: effort.name ?? effort.id,
-          ...(effort.description !== undefined ? { description: effort.description } : {})
-        }));
-      } catch { /* exact-model lookup may reject; skip its efforts */ }
-    }
-  }
-  return { models, efforts };
+// 轻量摘要：enabled + 模型目录（含 provider 信息，客户端据此派生提供方列表）+ 预设名册。
+async function handleSummary(deps, res) {
+  const snapshot = await deps.catalog.getSnapshot();
+  return json(res, 200, { ok: true, enabled: deps.getEnabled(), models: snapshot.models, presets: snapshot.presets });
 }
 
-// System-trust presets（agentPresets 可选，fail-soft）。
-async function collectSystemPresets(agentPresets) {
-  const presets = [];
-  try {
-    const list = await agentPresets.list();
-    for (const preset of (list ?? [])) {
-      if (preset && preset.trust === 'system') {
-        presets.push({ id: preset.id, name: preset.name ?? preset.id });
-      }
-    }
-  } catch { /* presets roster unavailable; leave empty */ }
-  return presets;
+// 每模型 reasoning-effort 等级（懒加载；model 命中快照的 efforts 表）。
+async function handleEfforts(deps, url, res) {
+  const model = url.searchParams.get('model');
+  const snapshot = await deps.catalog.getSnapshot();
+  const efforts = (typeof model === 'string' && model !== '' && snapshot.efforts[model] !== undefined) ? snapshot.efforts[model] : [];
+  return json(res, 200, { ok: true, efforts });
 }
 
-// Full tool directory = global layer (deployment plugins) + every preset's
-// standing scope (the agent.cordis.yml tool rows). Each tool is tagged with
-// its source: 'global' or the preset id — the grouping is fully dynamic,
-// derived from the runtime's preset roster.
-async function collectToolsDirectory(getTools, getAgentPresets) {
-  const tools = [];
-  const seen = new Set();
-  const OFFICIAL_PRESETS = ['standard', 'code', 'minimal', 'cordis'];
-  const layerOf = (source) => {
-    if (source === 'global') return 'plugin';
-    if (OFFICIAL_PRESETS.includes(source)) return 'core';
-    return 'custom';
-  };
-  const groupOf = (name, source) => {
-    const layer = layerOf(source);
-    if (layer === 'core') return TOOL_CATEGORY[name] ?? '其他';
-    if (layer === 'plugin') return name.includes('_') ? name.split('_')[0] : name;
-    return source;
-  };
-  const push = (schemas, source) => {
-    for (const s of (Array.isArray(schemas) ? schemas : [])) {
-      if (!s || typeof s.name !== 'string' || s.name === 'run_code' || seen.has(s.name)) continue;
-      seen.add(s.name);
-      tools.push({ name: s.name, description: typeof s.description === 'string' ? s.description : '', zh: TOOL_ZH[s.name] ?? '', source, layer: layerOf(source), group: groupOf(s.name, source) });
-    }
-  };
-  const toolsService = getTools();
-  if (toolsService && typeof toolsService.schemas === 'function') {
-    push(toolsService.schemas(), 'global');
-    const agentPresets = getAgentPresets();
-    if (agentPresets !== undefined && typeof agentPresets.list === 'function' && typeof agentPresets.standingKeyFor === 'function') {
-      const presets = await agentPresets.list();
-      for (const preset of (presets ?? [])) {
-        if (!preset || typeof preset.id !== 'string') continue;
-        try {
-          push(toolsService.schemas(await agentPresets.standingKeyFor(preset.id)), preset.id);
-        } catch { /* one preset's standing scope unavailable; skip */ }
-      }
-    }
-  }
-  return tools;
+// 完整工具目录（面板打开时取）。
+async function handleTools(deps, res) {
+  const snapshot = await deps.catalog.getSnapshot();
+  return json(res, 200, { ok: true, tools: snapshot.tools });
 }
 
-async function handleOptions(deps, res) {
-  const models = [];
-  const efforts = {};
-  const presets = [];
-  // Model directory + per-model reasoning-effort levels. The `llm` service
-  // is optional (headless): a failure only empties the lists, never breaks
-  // the settings page.
-  const llm = deps.getLlm();
-  if (llm !== undefined) {
-    try {
-      const { models: found, efforts: levels } = await collectModelDirectory(llm);
-      models.push(...found);
-      Object.assign(efforts, levels);
-    } catch { /* llm directory unavailable; leave options empty */ }
-  }
-  // System-trust presets (agentPresets is optional; fail-soft).
-  const agentPresets = deps.getAgentPresets();
-  if (agentPresets !== undefined) {
-    presets.push(...await collectSystemPresets(agentPresets));
-  }
-  // Full tool directory = global layer + every preset's standing scope.
-  let tools = [];
-  try {
-    tools = await collectToolsDirectory(deps.getTools, deps.getAgentPresets);
-  } catch (error) {
-    deps.logger.warn('[dsh-subagent-profile] tools directory failed:', error instanceof Error ? error.message : String(error));
-  }
-  return json(res, 200, { ok: true, enabled: deps.getEnabled(), models, efforts, presets, tools });
+// 版本探测：三包 version + 越界/未知的中文 warnings（纯探测，同步）。
+function handleVersions(res) {
+  const { versions, warnings } = detectVersions();
+  return json(res, 200, { ok: true, versions, warnings });
+}
+
+// 手动刷新：清缓存兜底（TTL 过期前的目录变更经此立即生效）。
+async function handleRefresh(deps, res) {
+  deps.catalog.invalidate();
+  return json(res, 200, { ok: true, refreshed: true });
 }
 
 async function handleSetEnabled(deps, req, res) {
@@ -222,6 +133,11 @@ async function handleAdd(deps, req, res) {
     return json(res, 400, { ok: false, error: `写入被拒绝：${detail}` });
   }
   const hadToolFilter = profile.toolFilter !== undefined;
+  // tokenTier 不参与上方通用 merge 循环：sanitizeProfile 对「未提供」恒回填
+  // balanced，若进循环会破坏「未传→保留 existing」语义（编辑内置 researcher
+  // 时 cheap 会被重置为 balanced）。故单独用 raw-body 守卫：传了才写（strict
+  // 模式下非法值已在上面 400 拒绝，clean.tokenTier 必为合法 enum）。
+  const hadTokenTier = profile.tokenTier !== undefined;
   const existing = deps.store.profiles.get(clean.id);
   const seed = BUILTIN_SEEDS.find((s) => s.id === clean.id);
   const isBuiltin = (existing !== undefined && existing.builtin === true) || seed !== undefined;
@@ -245,6 +161,7 @@ async function handleAdd(deps, req, res) {
       delete merged.toolFilter;
     }
   }
+  if (hadTokenTier) merged.tokenTier = clean.tokenTier;
   if (merged.enabled !== undefined) merged.enabled = merged.enabled === false ? false : true;
   deps.store.profiles.set(merged.id, { ...merged, ...(isBuiltin ? { builtin: true } : {}), persisted: true });
   deps.store.deletedBuiltins.delete(merged.id);
@@ -297,8 +214,8 @@ async function handleSetProfileEnabled(deps, req, res) {
   return persistOk(res, { id, enabled: existing.enabled }, deps.store.persistProfiles());
 }
 
-export function createHttpRoutes({ webServer, store, getEnabled, setEnabled, syncTool, getLlm, getAgentPresets, getTools, logger }) {
-  const deps = { store, getEnabled, setEnabled, syncTool, getLlm, getAgentPresets, getTools, logger };
+export function createHttpRoutes({ webServer, store, getEnabled, setEnabled, syncTool, catalog, logger }) {
+  const deps = { store, getEnabled, setEnabled, syncTool, catalog, logger };
   // 路由分发（if 链保持，判断顺序与 404/500 兜底不变）。
   const handler = async (req, res) => {
     const remote = req.socket?.remoteAddress;
@@ -307,7 +224,11 @@ export function createHttpRoutes({ webServer, store, getEnabled, setEnabled, syn
     const sub = (url.pathname.replace(/^\/subagent-profiles/, '') || '/').replace(/\/+$/, '') || '/';
     try {
       if (req.method === 'GET' && (sub === '/' || sub === '/list')) return handleList(deps, res);
-      if (req.method === 'GET' && sub === '/options') return handleOptions(deps, res);
+      if (req.method === 'GET' && sub === '/options/summary') return handleSummary(deps, res);
+      if (req.method === 'GET' && sub === '/options/versions') return handleVersions(res);
+      if (req.method === 'GET' && sub === '/options/efforts') return handleEfforts(deps, url, res);
+      if (req.method === 'GET' && sub === '/options/tools') return handleTools(deps, res);
+      if (req.method === 'POST' && sub === '/options/refresh') return handleRefresh(deps, res);
       if (req.method === 'POST' && sub === '/set-enabled') return handleSetEnabled(deps, req, res);
       if (req.method === 'POST' && sub === '/add') return handleAdd(deps, req, res);
       if (req.method === 'POST' && sub === '/remove') return handleRemove(deps, req, res);

package/lib/core/profile-provider.mjs

@@ -1,4 +1,4 @@
-// lib/core/profile-provider.mjs — `profile` 子 Agent provider
+// lib/core/profile-provider.mjs — `profile` 子 Agent provider
 // （setup/start/prepareContinuable），从 index.mjs 的
 // `ctx.subagents.registerProvider({...})` 块逐字拆出。仅引用 lib + shims；
 // 无 @deepseek-ai 依赖（shims 是唯一入口）。
@@ -55,8 +55,9 @@ async function runStartPreflight(request, deps) {
   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`);
   }
-  // 权威 cost guard（运行时推导；硬上限始终生效，llm 能力核验由 allowFailOpen 门控）。
-  await assertCostGuard(parent, profile, deps.store.getAllowFailOpen(), deps.logger);
+  // 权威 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.
   assertSubagentMaxDepth(profile.maxDepth);
@@ -229,8 +230,8 @@ function wireChildLifecycle(handle, request, childId, swapPreset, profile, logge
   };
 }
 
-export function createProfileProvider({ subagents, store, getEnabled, logger }) {
-  const deps = { store, getEnabled, logger };
+export function createProfileProvider({ subagents, store, getEnabled, logger, catalog }) {
+  const deps = { store, getEnabled, logger, catalog };
   return subagents.registerProvider({
     name: 'profile',
     capabilities: { outputSchema: false, depthLimit: true, toolFilter: true, persona: true },

package/lib/core/profiles-store.mjs

@@ -1,4 +1,4 @@
-// lib/core/profiles-store.mjs — profile registry store and enable/disable switch
+// lib/core/profiles-store.mjs — profile registry store and enable/disable switch
 // (moved verbatim from index.mjs and refactored into a factory; import-free —
 // node builtins + lib/core/pure.mjs only, no @deepseek-ai dependency).
 //
@@ -42,8 +42,8 @@ export function dshHome() {
 //    connection.defaults.thinking — this deployment leaves thinking unset,
 //    so the full set is advertised for deepseek-v4-flash).
 export const BUILTIN_SEEDS = [
-  { id: 'swap-standard', name: '标准编码', description: '切换到 standard 预设的完整编码工具集。当父会话不是 standard、但子任务需要完整编码能力时用。', preset: 'standard', builtin: true },
-  { id: 'researcher', name: '调研检索', description: '关闭深度推理省 token，继承父工具。适合查资料、汇总、背景调研，不适合改代码。', reasoningEffort: 'off', persona: 'You are a research subagent: search, read, and summarize only. Do not modify code or files.', builtin: true }
+  { id: 'swap-standard', name: '标准编码', description: '切换到 standard 预设的完整编码工具集。当父会话不是 standard、但子任务需要完整编码能力时用。', preset: 'standard', tokenTier: 'balanced', builtin: true },
+  { id: 'researcher', name: '调研检索', description: '关闭深度推理省 token，继承父工具。适合查资料、汇总、背景调研，不适合改代码。', reasoningEffort: 'off', persona: 'You are a research subagent: search, read, and summarize only. Do not modify code or files.', tokenTier: 'cheap', builtin: true }
 ];
 
 // --- 模块级 store 函数（从工厂拆出；per-apply 状态经 `state` 注入）---------------

package/lib/core/pure.mjs

@@ -1,4 +1,4 @@
-// lib/core/pure.mjs — import-free pure helpers (extracted from index.mjs and grown
+// lib/core/pure.mjs — import-free pure helpers (extracted from index.mjs and grown
 // by later refactors). No @deepseek-ai imports and no external dependencies:
 // @deepseek-ai symbols converge in lib/core/shims.mjs (the only such entry point),
 // and this module is safe to import from bare-CI tests without the junction
@@ -197,6 +197,19 @@ function sanitizeToolFilterField(value, clean, warnings) {
   if (Object.keys(tf).length > 0) clean.toolFilter = tf;
 }
 
+// tokenTier：成本/深度分层（cheap/balanced/premium），供目录排序与结果卡
+// 展示分层。合法值透传；非法值剔除 + warn（与 maxTokens 等超限字段同口径——
+// 剔除而非回填缺省值）。缺省 'balanced' 在 sanitizeProfile 末尾按「字段未提供」
+// 单独回填，非法值不受该回填影响。
+const TOKEN_TIERS = new Set(['cheap', 'balanced', 'premium']);
+function sanitizeTokenTierField(value, clean, warnings) {
+  if (typeof value !== 'string' || !TOKEN_TIERS.has(value)) {
+    warnings.push({ field: 'tokenTier', reason: 'tokenTier 必须为 cheap/balanced/premium 之一' });
+    return;
+  }
+  clean.tokenTier = value;
+}
+
 // --- 结果回收默认剪枝 ----------------------------------------------------------
 // 子结果默认复用宿主 `toolResultPruner.pruneContent` 预剪（纯函数、零 LLM），
 // 在 `textFrom` 之前执行，把回灌进父上下文的体积压到阈值内。
@@ -281,7 +294,7 @@ export function assertResultSchemaConsistency(schema) {
 const KNOWN_PROFILE_FIELDS = new Set([
   'id', 'name', 'description', 'persona', 'preset', 'provider', 'model',
   'reasoningEffort', 'enabled', 'maxTokens', 'maxDepth', 'toolFilter',
-  'builtin', 'deleted',
+  'tokenTier', 'builtin', 'deleted',
 ]);
 
 /**
@@ -305,6 +318,7 @@ export function sanitizeProfile(profile, options = {}) {
   if (profile === null || typeof profile !== 'object' || Array.isArray(profile)) {
     return { clean, warnings: [{ field: '(root)', reason: 'profile 不是对象' }] };
   }
+  let tokenTierProvided = false;
   for (const [key, value] of Object.entries(profile)) {
     if (!KNOWN_PROFILE_FIELDS.has(key)) {
       warnings.push({ field: key, reason: '未知字段已忽略' });
@@ -327,10 +341,27 @@ export function sanitizeProfile(profile, options = {}) {
       case 'toolFilter':
         sanitizeToolFilterField(value, clean, warnings);
         break;
+      case 'tokenTier':
+        tokenTierProvided = true;
+        sanitizeTokenTierField(value, clean, warnings);
+        break;
       default:
         clean[key] = value;
         break;
     }
   }
+  // tokenTier 缺省 'balanced'：仅当字段未被提供时回填；被提供的非法值已在
+  // sanitizeTokenTierField 剔除（clean 保持无该键），不会被此回填覆盖。
+  if (!tokenTierProvided) clean.tokenTier = 'balanced';
   return { clean, warnings };
 }
+
+// --- tokenTier 目录排序 ---------------------------------------------------------
+// tokenTier 排序权重：cheap→balanced→premium。dispatch:profiles 目录行按此
+// 升序排列（省 token 方案在前）。缺省/未知 tier 按 balanced 处理，保证旧数据
+// 与无 tokenTier 字段的 profile 落到中间档而非报错。
+export const TIER_ORDER = { cheap: 0, balanced: 1, premium: 2 };
+export function tierSortKey(tokenTier) {
+  const order = TIER_ORDER[tokenTier];
+  return order === undefined ? TIER_ORDER.balanced : order;
+}

package/lib/core/shims.mjs

@@ -1,4 +1,4 @@
-// lib/core/shims.mjs — facade. The ONLY module that imports the
+// 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:
 //
@@ -23,6 +23,7 @@
 //   also verifies the value is a function before accepting it.
 
 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.
@@ -186,6 +187,89 @@ 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，失败记
+// 'unknown'。headless / 宿主裁剪部署下任一包都可能缺失，此时 warnings 非空，
+// 设置页据此在顶部渲染 amber 提示条（不阻断派发）。
+const requirePkg = createRequire(import.meta.url);
+const PEER_MIN = '0.1.0-rc.6';
+const PEER_MAX = '0.2.0';
+const PROBED_PACKAGES = ['dsh-subagent', 'dsh-agent', 'dsh-llm'];
+
+// 读单包 version（每包独立 try/catch，失败记 'unknown'）。用 createRequire 直接
+// require 包的 package.json（返回解析后的对象），免去 fs 读取与 JSON.parse。
+function readPackageVersion(pkg) {
+  try {
+    const manifest = requirePkg(`@deepseek-ai/${pkg}/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`）。
+function compareSemver(a, b) {
+  const [aCore, aPre = ''] = a.split('-');
+  const [bCore, bPre = ''] = b.split('-');
+  const aNums = aCore.split('.').map((n) => Number(n));
+  const bNums = bCore.split('.').map((n) => Number(n));
+  for (let i = 0; i < 3; i++) {
+    const x = aNums[i] ?? 0;
+    const y = bNums[i] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  if (aPre === bPre) return 0;
+  if (aPre === '') return 1;   // 正式版 > 预发布
+  if (bPre === '') return -1;
+  const aParts = aPre.split('.');
+  const bParts = bPre.split('.');
+  const len = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < len; i++) {
+    const x = aParts[i];
+    const y = bParts[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const xNumeric = /^\d+$/.test(x);
+    const yNumeric = /^\d+$/.test(y);
+    if (xNumeric && yNumeric) {
+      const diff = Number(x) - Number(y);
+      if (diff !== 0) return diff;
+    } else if (xNumeric !== yNumeric) {
+      return xNumeric ? -1 : 1;   // 数字标识 < 非数字标识（semver 约定）
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+// 版本是否落在 peerDependencies 范围（>=PEER_MIN 且 <PEER_MAX）。
+function inPeerRange(version) {
+  return compareSemver(version, PEER_MIN) >= 0 && compareSemver(version, PEER_MAX) < 0;
+}
+
+// detectVersions(reader?) — 纯探测三包版本并产出 { versions, warnings }。
+// `reader` 可选注入（默认 readPackageVersion），供测试模拟「包缺失 / 版本越界」
+// 而无需删除 node_modules（与 loadSoft 的 importer 注入同一思路）。
+export function detectVersions(reader = readPackageVersion) {
+  const versions = {};
+  for (const pkg of PROBED_PACKAGES) versions[pkg] = reader(pkg);
+  const warnings = [];
+  for (const pkg of PROBED_PACKAGES) {
+    const version = versions[pkg];
+    if (version === 'unknown') {
+      warnings.push(`未检测到 @deepseek-ai/${pkg} 版本（包缺失或被宿主裁剪）——请确认其已按 peerDependencies 范围安装`);
+    } else if (!inPeerRange(version)) {
+      warnings.push(`@deepseek-ai/${pkg} 版本 ${version} 超出 peerDependencies 范围（>=${PEER_MIN} <${PEER_MAX}），派发行为可能与预期不符`);
+    }
+  }
+  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).
@@ -212,4 +296,6 @@ export {
   resolveChildAgentOptions,
   defineTool,
   readResult,
+  // ---- version probe seam (see detectVersions doc) ----
+  readPackageVersion,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subagent-profile",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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",
@@ -77,6 +77,7 @@
     "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"
+    "preflight": "node scripts/preflight.mjs",
+    "leak-scan": "node scripts/leak-scan.mjs"
   }
 }