dsh-subagent-profile 0.3.2 → 0.3.3

package/lib/core/catalog-cache.mjs

@@ -19,6 +19,49 @@ import { TOOL_ZH, TOOL_CATEGORY } from './catalog.mjs';
 
 const DEFAULT_TTL_MS = 60000;
 
+// --- 工具分组/中文名的薄覆盖层（schema 声明优先，缺失回退）------------------------
+//
+// 工具目录里每一条的 group（分类）与 zh（中文名）优先取工具 schema 自带声明字段，
+// 其次才回退数据表/前缀/预设名。宿主 tools.schemas() 当前只投影 name/description/
+// parameters（无 category/group/zh 字段）；此层在宿主未来为 schema 补上
+// 分组/中文声明时自动优先采用，缺失时按既有回退链兜底——不新增任何硬编码条目。
+
+// 读取 schema 声明的分组候选（可接受的字段名集合内部固定，非外部注入）。
+function schemaDeclaredGroup(schema) {
+  if (schema === null || typeof schema !== 'object') return undefined;
+  if (typeof schema.category === 'string' && schema.category.length > 0) return schema.category;
+  if (typeof schema.group === 'string' && schema.group.length > 0) return schema.group;
+  return undefined;
+}
+
+// 读取 schema 声明的中文名候选（宿主有 zh/label 声明时优先）。
+function schemaDeclaredZh(schema) {
+  if (schema === null || typeof schema !== 'object') return undefined;
+  if (typeof schema.zh === 'string' && schema.zh.length > 0) return schema.zh;
+  if (typeof schema.label === 'string' && schema.label.length > 0) return schema.label;
+  return undefined;
+}
+
+// core 层无数据表条目时的缺省分组。
+const DEFAULT_CORE_GROUP = '其他';
+
+// 工具的分组解析链：schema 声明 → 数据表（core）/ 前缀（plugin）/ 预设名（custom）。
+// `source` 是工具来源（'global' 或 preset id），`layer` 为 layerOf(source)。
+export function resolveToolCategory(schema, name, source, layer) {
+  const declared = schemaDeclaredGroup(schema);
+  if (declared !== undefined) return declared;
+  if (layer === 'core') return TOOL_CATEGORY[name] ?? DEFAULT_CORE_GROUP;
+  if (layer === 'plugin') return name.includes('_') ? name.split('_')[0] : name;
+  return source;
+}
+
+// 工具中文名解析链：schema 声明 → 数据表 → 空串（沿用原缺省）。
+export function resolveToolZh(schema, name) {
+  const declared = schemaDeclaredZh(schema);
+  if (declared !== undefined) return declared;
+  return TOOL_ZH[name] ?? '';
+}
+
 // --- 目录构建（无缓存；行为与 http-routes 原 collector 逐字一致）----------------
 
 // llm 目录：providers + 每 provider models + 每模型 efforts。listProviders 失败
@@ -96,17 +139,12 @@ async function collectToolsDirectory(getTools, getAgentPresets, logger) {
       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 groupOf = (schema, name, source) => resolveToolCategory(schema, name, source, layerOf(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) });
+        tools.push({ name: s.name, description: typeof s.description === 'string' ? s.description : '', zh: resolveToolZh(s, s.name), source, layer: layerOf(source), group: groupOf(s, s.name, source) });
       }
     };
     const toolsService = typeof getTools === 'function' ? getTools() : undefined;

package/lib/core/catalog.mjs

@@ -1,10 +1,10 @@
-// lib/core/catalog.mjs — settings-page data tables moved verbatim from index.mjs
-// (import-free, no @deepseek-ai dependency — node builtins only, none used
-// here). The /options tool-directory builder itself lives in lib/core/catalog-cache.mjs:
-// it reads ctx.tools/agentPresets (non-pure), so it is not part of this module.
+// lib/core/catalog.mjs — 设置页数据表，从 index.mjs 逐字拆出
+// （import-free，无 @deepseek-ai 依赖）。/options 工具目录构建器在
+// lib/core/catalog-cache.mjs：它读取 ctx.tools/agentPresets（非纯函数），
+// 不属于本模块。
 
-// Tool-name → 中文说明 map, shown beside the raw tool name in the toolFilter
-// picker. Tools absent here fall back to their raw name.
+// 工具名 → 中文说明 map，toolFilter 选择器里显示在原始工具名旁。
+// 未收录的工具回退显示原始名。
 export const TOOL_ZH = {
   'bash': '终端命令',
   'pwsh': 'PowerShell 命令',

package/lib/core/cost-guard.mjs

@@ -2,30 +2,28 @@
 // 仅引用 lib/core/pure.mjs 的 assertHardLimits；无 @deepseek-ai 依赖。
 //
 // 运行时推导的 cost guard，两部分：
-//   ① always-on hard caps (assertHardLimits, in lib/core/pure.mjs) — maxTokens /
-//      maxDepth are hard delegation caps, independent of the `llm` service, so
-//      they must NOT stop applying when `llm` is absent（历史教训：早期版本在
-//      llm 缺失时直接 return，连带跳过了硬上限，属缺陷——硬上限永远前置）。
-//   ② llm capability — validates provider / model / reasoningEffort against the
-//      live provider directory. When the `llm` service is absent OR its provider
-//      directory is empty (an adapter without discovery), capability cannot be
-//      verified: per `allowFailOpen`（迁移开关）either
-//      fail-open compat (warn + skip; v1 数据迁移中) or fail-loud reject. A
-//      profile that requests none of provider/model/reasoningEffort has nothing
-//      to verify and always passes (valid in a headless deployment).
+//   * always-on hard caps（assertHardLimits，在 lib/core/pure.mjs）——maxTokens /
+//     maxDepth 是硬性委派上限，与 `llm` 服务无关，llm 缺失时绝不能停止生效
+//     （历史教训：早期版本在 llm 缺失时直接 return，连带跳过硬上限，属缺陷——
+//     硬上限永远前置）。
+//   * llm 能力校验——对 live provider 目录校验 provider / model /
+//     reasoningEffort。`llm` 服务缺失或其 provider 目录为空（无发现能力的
+//     adapter）时能力无法核验：按 `allowFailOpen`（迁移开关）二选一——
+//     fail-open 兼容（warn + 跳过；v1 数据迁移中）或 fail-loud 拒绝。profile
+//     若 provider/model/reasoningEffort 都未请求，无校验项，恒通过（无头部署
+//     下合法）。
 //
 // 目录读取改走共享 catalog 快照（lib/core/catalog-cache.mjs）：assertCostGuard 的
 // `catalog` 参数是缓存实例，`catalog.getSnapshot(llm)` 返回缓存过的 providers /
 // modelsByProvider。缓存只提速目录解析、不复检安全门——provider/model/effort 的
 // 校验逻辑与 fail-loud 文案逐字不变；reasoningEffort 走直连 resolveCallConfig
 // （校验调用，非目录读取，不入缓存）。
-// Used by both the provider's authoritative check and the dispatch tool's
-// pre-check. `allowFailOpen`/`logger` are injected because this function is
-// module-scoped and cannot reach the apply closure's `allowFailOpen`/`ctx.logger`.
+// 本函数同时供 provider 权威校验与 dispatch 工具预检使用。`allowFailOpen`/`logger`
+// 经注入传入：函数是模块级作用域，够不到 apply 闭包里的 `allowFailOpen`/`ctx.logger`。
 
 import { assertHardLimits } from './pure.mjs';
 
-// ② 仅当 profile 请求了需核验能力面的字段时才进入 llm 校验（无头/headless 部署下
+// 仅当 profile 请求了需核验能力面的字段时才进入 llm 校验（无头/headless 部署下
 // persona-only / toolFilter-only 的 profile 合法，不应被 fail-loud 拒绝）。
 function needsLlmCheck(profile) {
   return ['provider', 'model', 'reasoningEffort'].some(
@@ -42,23 +40,22 @@ function handleUnverifiable(allowFailOpen, logger) {
   throw new Error('dispatch: 模型能力不可验证：fail-loud 拒绝（可在配置中显式开启兼容模式）');
 }
 
-// ④ provider 注册校验（目录非空时才能判定「不在目录」）。providers 来自 catalog 快照。
+// provider 注册校验（目录非空时才能判定「不在目录」）。providers 来自 catalog 快照。
 function assertProviderRegistered(dir, profile) {
   if (typeof profile.provider !== 'string' || profile.provider.length === 0) return;
-  if (!(dir.providers ?? []).some((provider) => provider && provider.id === profile.provider)) {
-    throw new Error(`dispatch: provider "${profile.provider}" is not a registered provider`);
+  const providers = Array.isArray(dir.providers) ? dir.providers : [];
+  if (!providers.some((provider) => provider && provider.id === profile.provider)) {
+    throw new Error(`dispatch: provider "${profile.provider}" 未注册（不在当前 provider 目录中，可在设置页改用已注册的 provider）`);
   }
 }
 
-// ⑤ model 校验。resolveModelInfo does not reject unknown models (catalog
-//    membership is advisory), so validate against the advertised catalog
-//    instead. An EMPTY catalog (adapter without discovery) cannot be verified
-//    and is skipped — 目录级空集已在 ③ 走 allowFailOpen 分支，此处仅兜底
-//    per-provider 空目录。A non-empty catalog that does not advertise the model
-//    fails loud. An unverifiable lookup (listModels(undefined) when no provider
-//    is known) becomes a clean fail-loud error instead of leaking "undefined".
-//    modelsByProvider 来自快照；快照未覆盖的 provider（undefined / 不在名册）
-//    走直连 listModels 兜底，保持原 fail-loud 文案逐字。
+// model 校验。resolveModelInfo 不拒绝未知模型（目录成员关系只是建议性的），
+// 所以改为对照已发布的目录校验。空目录（无发现能力的 adapter）无法核验，
+// 跳过——目录级空集已在 llm 门走 allowFailOpen 分支，此处仅兜底
+// per-provider 空目录。非空目录未发布该模型则 fail-loud。不可核验的查询
+// （provider 未知时 listModels(undefined)）变成干净的 fail-loud 错误，而不是
+// 泄漏 "undefined"。modelsByProvider 来自快照；快照未覆盖的 provider
+// （undefined / 不在名册）走直连 listModels 兜底，保持原 fail-loud 文案逐字。
 async function assertModelAdvertised(llm, profile, effectiveProvider, modelsByProvider) {
   if (typeof profile.model !== 'string' || profile.model.length === 0) return;
   const cached = modelsByProvider !== undefined ? modelsByProvider[String(effectiveProvider)] : undefined;
@@ -75,48 +72,78 @@ async function assertModelAdvertised(llm, profile, effectiveProvider, modelsByPr
     }
   }
   if (modelsError !== undefined) {
-    throw new Error(`dispatch: cannot validate model "${profile.model}" without a provider: ${modelsError instanceof Error ? modelsError.message : String(modelsError)}`, { cause: modelsError });
+    throw new Error(`dispatch: 无法校验模型 "${profile.model}"：provider 目录查询失败（${modelsError instanceof Error ? modelsError.message : String(modelsError)}），可稍后重试或在设置页关闭模型能力校验`, { cause: modelsError });
   }
   const listed = models ?? [];
   const known = listed.length > 0 && listed.some((model) => model && (model.id === profile.model || model.name === profile.model));
   if (listed.length > 0 && !known) {
-    throw new Error(`dispatch: model "${profile.model}" is not advertised by provider "${String(effectiveProvider)}"`);
+    throw new Error(`dispatch: 模型 "${profile.model}" 不在 provider "${String(effectiveProvider)}" 的目录中（可换用该 provider 已发布的模型）`);
   }
 }
 
-// ⑥ reasoningEffort 校验。
+// reasoningEffort 校验。
 async function assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel) {
   if (typeof profile.reasoningEffort !== 'string' || profile.reasoningEffort.length === 0) return;
   try {
     await llm.resolveCallConfig({ provider: effectiveProvider, model: effectiveModel, reasoningEffort: profile.reasoningEffort });
   } catch (error) {
-    throw new Error(`dispatch: reasoningEffort "${profile.reasoningEffort}" is not supported by provider "${String(effectiveProvider)}" model "${String(effectiveModel)}": ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    throw new Error(`dispatch: reasoningEffort "${profile.reasoningEffort}" 不受 provider "${String(effectiveProvider)}" 的模型 "${String(effectiveModel)}" 支持（${error instanceof Error ? error.message : String(error)}），可改用一个该模型支持的 effort 值`, { cause: error });
   }
 }
 
-export async function assertCostGuard(parent, profile, allowFailOpen, logger, catalog) {
-  // ① 硬上限 always-on（不依赖 llm）。
+// 能力面逐项校验的统一接线：判定通过回调 verdict:'pass'；失败先回调 verdict:'fail'
+// （含 error.message 作 detail）再 rethrow 原错误（文案不变）。
+async function runChecked(check, field, checkedAgainst, fn) {
+  try {
+    await fn();
+    check({ field, checkedAgainst, verdict: 'pass' });
+  } catch (error) {
+    check({ field, checkedAgainst, verdict: 'fail', detail: error.message });
+    throw error;
+  }
+}
+
+// llm 门的逐项记录：verdict 对应实际走向，detail 注明 fail-open/fail-loud。
+function checkLlmGate(check, allowFailOpen, detailFailLoud, detailFailOpen) {
+  check({ field: 'llm', verdict: allowFailOpen === true ? 'pass' : 'fail', detail: allowFailOpen === true ? detailFailOpen : detailFailLoud });
+}
+
+export async function assertCostGuard(parent, profile, allowFailOpen, logger, catalog, onCheck) {
+  // 可选逐项回调；onCheck 缺省时归一为 no-op，行为逐字不变（现有调用点不加参数，零漂移）。
+  const check = typeof onCheck === 'function' ? onCheck : () => {};
+
+  // 硬上限 always-on（不依赖 llm）。
   assertHardLimits(profile.maxTokens, profile.maxDepth);
 
-  // ② 无 llm 能力面字段 → 无可核验，直接通过（headless 部署合法）。
-  if (!needsLlmCheck(profile)) return;
+  // 无 llm 能力面字段 → 无可核验，直接通过（headless 部署合法）。
+  if (!needsLlmCheck(profile)) {
+    check({ field: 'llm', verdict: 'pass', detail: '无需核验（未请求 provider/model/reasoningEffort）' });
+    return;
+  }
 
   const llm = parent.ctx.get('llm');
-  // ③ llm 缺失 → 无法核验：按 allowFailOpen 决定 fail-open / fail-loud。
-  if (llm === undefined) return handleUnverifiable(allowFailOpen, logger);
+  // llm 缺失 → 无法核验：按 allowFailOpen 决定 fail-open / fail-loud。
+  if (llm === undefined) {
+    checkLlmGate(check, allowFailOpen, 'llm 缺失：fail-loud 拒绝', 'llm 缺失：fail-open 跳过核验');
+    return handleUnverifiable(allowFailOpen, logger);
+  }
 
   // llm 存在：目录读取走共享 catalog 快照（缓存只提速目录解析，校验逻辑不变）。
   const snapshot = await catalog.getSnapshot(llm);
-  const dir = snapshot.llm;
-  if (dir.providersError !== undefined || dir.providers.length === 0) {
+  // M10：快照形状守卫——畸形快照（llm 缺失 / providers 非数组）不得被静默放行，
+  // 归一为「目录为空」走同一 fail-loud / fail-open 门。
+  const dir = (snapshot !== null && typeof snapshot === 'object' && snapshot.llm !== null && typeof snapshot.llm === 'object') ? snapshot.llm : {};
+  const providers = Array.isArray(dir.providers) ? dir.providers : [];
+  if (dir.providersError !== undefined || providers.length === 0) {
+    checkLlmGate(check, allowFailOpen, 'provider 目录为空：fail-loud 拒绝', 'provider 目录为空：fail-open 跳过核验');
     return handleUnverifiable(allowFailOpen, logger);
   }
 
-  // ④ provider 注册校验。
-  assertProviderRegistered(dir, profile);
+  // provider 注册校验。
+  await runChecked(check, 'provider', 'catalogProviders', () => assertProviderRegistered(dir, profile));
   const effectiveProvider = profile.provider !== undefined ? profile.provider : parent.options.provider;
   const effectiveModel = profile.model !== undefined ? profile.model : parent.options.model;
-  // ⑤ model 校验 + ⑥ reasoningEffort 校验。
-  await assertModelAdvertised(llm, profile, effectiveProvider, dir.modelsByProvider);
-  await assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel);
+  // model 校验 + reasoningEffort 校验。
+  await runChecked(check, 'model', 'providerModelList', () => assertModelAdvertised(llm, profile, effectiveProvider, dir.modelsByProvider));
+  await runChecked(check, 'reasoningEffort', 'resolveCallConfig', () => assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel));
 }