@waterplus-ai/waterbuddy 0.1.37 → 0.1.78

package/lib/host/expert-store.js

@@ -0,0 +1,245 @@
+/**
+ * 专家配置的持久化：启用白名单 + 自定义专家。
+ *
+ * **存在 `$DSH_HOME/waterbuddy-experts.json`，而不是 settings 命名空间**。宿主 settings 服务的
+ * `update()` 只对**已注册**的命名空间生效，未注册会直接抛
+ * `settings namespace "..." is not registered`；注册要传一个 schemastery schema，而本插件是
+ * 零依赖纯 JS 包，构造不了它。文件存储与本插件既有做法一致（见 `waterbuddy-device.json`），
+ * 也免得为了两个字段去引入宿主内部依赖。
+ *
+ * 两个设计点：
+ *
+ * - **`enabled` 是白名单，且只在用户动过开关后才落盘**。未配置时视为「内置专家全部启用」，
+ *   这样以后新增的内置专家默认可用，而不是被一份陈旧的清单永久挡在外面。
+ * - **写入带 `revision` 乐观并发**。两个窗口同时编辑时，落后的一方会被拒绝，而不是后写者
+ *   静默覆盖先写者。
+ */
+import { randomUUID } from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { EXPERT_DIVISIONS } from './experts.js'
+
+/** 配置文件名，位于 `$DSH_HOME` 下。 */
+export const EXPERTS_STATE_FILENAME = 'waterbuddy-experts.json'
+
+/** 配置文件路径；`DSH_HOME` 与插件其它持久化文件同源。 */
+export function expertStateFile() {
+  return path.join(process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), EXPERTS_STATE_FILENAME)
+}
+
+/** 自定义专家数量上限。 */
+export const CUSTOM_EXPERT_LIMIT = 200
+
+/** 自定义专家的 slug 前缀：用来把「只能读」的内置专家和「可改」的自定义专家分开。 */
+export const CUSTOM_SLUG_PREFIX = 'custom-'
+
+/** 各字段的长度上限（正文上限较大，persona 本来就是长提示词）。 */
+export const CUSTOM_FIELD_LIMITS = { name: 60, description: 300, emoji: 8, prompt: 20000 }
+
+/** 是否是我们生成的自定义专家 slug。 */
+export function isCustomSlug(slug) {
+  return typeof slug === 'string' && slug.startsWith(CUSTOM_SLUG_PREFIX)
+}
+
+/** 把任意存储值收敛成合法状态：坏字段逐项丢弃，不让一条脏数据把整个页面打挂。 */
+export function normalizeExpertState(raw) {
+  const value = raw && typeof raw === 'object' ? raw : {}
+  return {
+    // `undefined` = 从未配置 = 内置专家全开；空数组是明确的「全关」，两者不能混。
+    enabled: Array.isArray(value.enabled)
+      ? value.enabled.filter(slug => typeof slug === 'string' && slug.length > 0)
+      : undefined,
+    customExperts: Array.isArray(value.customExperts)
+      ? value.customExperts.filter(isStoredCustomExpert)
+      : [],
+    revision: Number.isSafeInteger(value.revision) && value.revision >= 0 ? value.revision : 0,
+  }
+}
+
+/** 存储里的自定义专家是否结构完整（长度与格式在写入侧校验，这里只保证读得出来）。 */
+function isStoredCustomExpert(value) {
+  return Boolean(
+    value
+    && typeof value === 'object'
+    && isCustomSlug(value.slug)
+    && typeof value.name === 'string'
+    && typeof value.description === 'string'
+    && typeof value.division === 'string'
+    && typeof value.prompt === 'string',
+  )
+}
+
+/** 某位专家当前是否启用。 */
+export function isExpertEnabled(state, slug) {
+  return state.enabled === undefined || state.enabled.includes(slug)
+}
+
+/**
+ * 校验并规范化一份来自客户端的自定义专家输入。
+ *
+ * @param input - 请求体里的 `expert`。
+ * @param options.slug - 已有 slug（编辑时传入；不传则新建）。
+ * @returns 规范化后的自定义专家。
+ * @throws 字段缺失或越界时抛出带错误码的 Error。
+ */
+export function validateCustomExpert(input, options = {}) {
+  const source = input && typeof input === 'object' ? input : {}
+  const name = String(source.name || '').trim()
+  const description = String(source.description || '').trim()
+  const division = String(source.division || '').trim()
+  const prompt = String(source.prompt || '').trim()
+  const emoji = String(source.emoji || '').trim() || '🧠'
+
+  if (!name) throw new Error('EXPERT_NAME_REQUIRED: 名称不能为空')
+  if (!description) throw new Error('EXPERT_DESCRIPTION_REQUIRED: 描述不能为空')
+  if (!prompt) throw new Error('EXPERT_PROMPT_REQUIRED: 提示词不能为空')
+  if (!Object.prototype.hasOwnProperty.call(EXPERT_DIVISIONS, division)) {
+    throw new Error(`EXPERT_DIVISION_UNKNOWN: 未知分类 "${division}"`)
+  }
+  for (const [field, limit] of Object.entries(CUSTOM_FIELD_LIMITS)) {
+    const value = field === 'name' ? name : field === 'description' ? description : field === 'prompt' ? prompt : emoji
+    if (Array.from(value).length > limit) {
+      throw new Error(`EXPERT_FIELD_TOO_LONG: ${field} 超过 ${limit} 字上限`)
+    }
+  }
+  const avatar = String(source.avatar || '').trim()
+  if (avatar && !/^https?:\/\//i.test(avatar)) {
+    throw new Error('EXPERT_AVATAR_INVALID: 自定义专家的头像请填 http(s) 图片地址')
+  }
+  if (avatar.length > 500) throw new Error('EXPERT_FIELD_TOO_LONG: avatar 超过 500 字上限')
+  return {
+    slug: options.slug || `${CUSTOM_SLUG_PREFIX}${randomUUID()}`,
+    name,
+    description,
+    division,
+    emoji,
+    ...(avatar ? { avatar } : {}),
+    prompt,
+  }
+}
+
+/**
+ * 建立配置存储。
+ *
+ * @param options.file - 配置文件路径，默认 {@link expertStateFile}（测试注入临时文件）。
+ * @returns 读写接口。
+ */
+export function createExpertStore(options = {}) {
+  const file = options.file || expertStateFile()
+  // 名册当前有哪些 slug（由调用方在目录加载完成后提供）。用来识别「白名单来自上一代名册」：
+  // 那种情况下它一个都对不上，若照字面当成「全关」，用户换一次名册就会看到全部专家被停用。
+  const knownSlugs = options.knownSlugs
+
+  const read = () => {
+    let state
+    try {
+      state = normalizeExpertState(JSON.parse(fs.readFileSync(file, 'utf8')))
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        // 坏文件不能让设置页打不开：退回默认值并记一条 warning，下次写入会覆盖它。
+        console.warn('[WaterBuddy] expert config is unreadable:', error.message)
+      }
+      return normalizeExpertState(undefined)
+    }
+    if (state.enabled !== undefined && state.enabled.length > 0) {
+      const known = typeof knownSlugs === 'function' ? knownSlugs() : undefined
+      if (known && known.size > 0 && state.enabled.every(slug => !known.has(slug))) {
+        return { ...state, enabled: undefined }
+      }
+    }
+    return state
+  }
+
+  /** 先写临时文件再 rename：进程被杀也不会留下半截 JSON。 */
+  const write = next => {
+    const temporary = `${file}.tmp`
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 })
+    fs.renameSync(temporary, file)
+    try { fs.chmodSync(file, 0o600) } catch { /* 文件系统不支持就算了 */ }
+    return read()
+  }
+
+  /** 修订号校验：落后的一方直接拒绝，避免静默覆盖。 */
+  const checkRevision = expected => {
+    const current = read().revision
+    if (!Number.isSafeInteger(expected) || expected !== current) {
+      throw new Error(`EXPERT_REVISION_CONFLICT: 配置已被其他窗口修改（当前修订号 ${current}）`)
+    }
+    return current
+  }
+
+  /** 写后回读确认：解析结果与预期不一致就当作没写成功。 */
+  const commit = next => {
+    const persisted = write(next)
+    if (persisted.revision !== next.revision) {
+      throw new Error('EXPERT_STATE_NOT_PERSISTED: 专家配置未落盘')
+    }
+    return persisted
+  }
+
+  return {
+    file,
+    read,
+    /**
+     * 整体替换启用白名单。
+     * @param enabled - 启用的 slug 列表。
+     * @param expectedRevision - 客户端读到的修订号。
+     */
+    async replaceEnabled(enabled, expectedRevision) {
+      const current = checkRevision(expectedRevision)
+      if (!Array.isArray(enabled) || enabled.some(slug => typeof slug !== 'string')) {
+        throw new Error('EXPERT_ENABLED_INVALID: 启用列表格式不正确')
+      }
+      return commit({
+        enabled: [...new Set(enabled)],
+        customExperts: read().customExperts,
+        revision: current + 1,
+      })
+    },
+    /**
+     * 新建或更新一位自定义专家。新建时自动启用。
+     * @param input - 客户端提交的专家字段。
+     * @param expectedRevision - 客户端读到的修订号。
+     */
+    async saveCustom(input, expectedRevision) {
+      const current = checkRevision(expectedRevision)
+      const previous = read()
+      const existing = input?.slug ? previous.customExperts.find(item => item.slug === input.slug) : undefined
+      if (input?.slug && !existing) {
+        throw new Error(`EXPERT_NOT_CUSTOM: ${input.slug} 不是可编辑的自定义专家`)
+      }
+      const expert = validateCustomExpert(input, existing ? { slug: existing.slug } : {})
+      const customExperts = existing
+        ? previous.customExperts.map(item => (item.slug === expert.slug ? expert : item))
+        : [...previous.customExperts, expert]
+      if (customExperts.length > CUSTOM_EXPERT_LIMIT) {
+        throw new Error(`EXPERT_CUSTOM_LIMIT: 自定义专家最多 ${CUSTOM_EXPERT_LIMIT} 位`)
+      }
+      // 新建的专家默认启用：白名单未配置时本来就「全开」，已配置成白名单才需要显式加入。
+      // 编辑已有专家不动启用状态——用户特意关掉的专家不该因为改个描述又被打开。
+      const enabled = existing || previous.enabled === undefined
+        ? previous.enabled
+        : [...new Set([...previous.enabled, expert.slug])]
+      return commit({ enabled, customExperts, revision: current + 1 })
+    },
+    /**
+     * 删除一位自定义专家，并从启用白名单里摘掉。
+     * @param slug - 自定义专家 slug。
+     * @param expectedRevision - 客户端读到的修订号。
+     */
+    async deleteCustom(slug, expectedRevision) {
+      const current = checkRevision(expectedRevision)
+      const previous = read()
+      if (!previous.customExperts.some(item => item.slug === slug)) {
+        throw new Error(`EXPERT_NOT_CUSTOM: ${slug} 不是可编辑的自定义专家`)
+      }
+      return commit({
+        enabled: previous.enabled === undefined ? undefined : previous.enabled.filter(item => item !== slug),
+        customExperts: previous.customExperts.filter(item => item.slug !== slug),
+        revision: current + 1,
+      })
+    },
+  }
+}

package/lib/host/expert-tools.js

@@ -0,0 +1,416 @@
+/**
+ * 专家工具：把名册变成模型可召唤的专家分身。
+ *
+ * 三个工具：
+ * - `list_experts`    浏览名册（无参只回分区与计数，省 token）
+ * - `summon_expert`   召唤单个专家
+ * - `summon_experts`  并行召唤一队专家（有上限与并发约束）
+ *
+ * 召唤走 `ctx.subagents`：把 persona 注入子代理（provider 的 `persona` 能力），
+ * 并用 `toolFilter` 禁掉这三个工具本身——否则专家会继续召唤专家，无限套娃。
+ */
+import { EXPERT_DIVISIONS, readExpertPersona } from './experts.js'
+
+/** 三个工具的名字。`summon*` 会互相禁用，列表见 {@link EXPERT_SUMMON_DENY}。 */
+export const EXPERT_TOOL_NAMES = ['list_experts', 'summon_expert', 'summon_experts']
+
+/** 子代理里要禁掉的工具：阻止专家递归召唤。 */
+export const EXPERT_SUMMON_DENY = [...EXPERT_TOOL_NAMES]
+
+/** 一次批量召唤的专家数上限。 */
+export const SUMMON_EXPERTS_MAX = 8
+
+/** 批量召唤的并发上限。 */
+export const SUMMON_EXPERTS_CONCURRENCY = 4
+
+/** 单个任务的码点上限（按码点算，避免 emoji 被误判超长）。 */
+export const SUMMON_TASK_MAX_CHARS = 8000
+
+/** 名册里回给模型的描述截断长度。 */
+export const EXPERT_DESCRIPTION_MAX_CHARS = 120
+
+/** 默认子代理 provider：内置 `providerName: spawn` 支持 persona/toolFilter/depthLimit。 */
+export const DEFAULT_EXPERT_PROVIDER = 'spawn'
+
+/** provider 必须声明这两项能力，否则召唤会静默丢掉专家身份或防套娃。 */
+const REQUIRED_PROVIDER_CAPABILITIES = ['persona', 'toolFilter']
+
+/**
+ * 受限并发映射，且**保持结果顺序与输入一致**。
+ *
+ * 没有用 `Promise.all(items.map(...))`：那样会一次性起 N 个子代理。
+ * @param items - 待处理项。
+ * @param limit - 并发上限（小于 1 时按 1 处理）。
+ * @param worker - 处理单项，接收 `(item, index)`。
+ * @returns 与 `items` 等长、顺序一致的结果数组。
+ */
+export async function mapPool(items, limit, worker) {
+  const results = new Array(items.length)
+  const width = Math.max(1, Math.min(Number(limit) || 1, items.length || 1))
+  let next = 0
+  const run = async () => {
+    while (true) {
+      const index = next
+      next += 1
+      if (index >= items.length) return
+      results[index] = await worker(items[index], index)
+    }
+  }
+  await Promise.all(Array.from({ length: width }, run))
+  return results
+}
+
+/** 按码点计算长度：`.length` 会把 emoji 算成 2，导致误判超长。 */
+function codePointLength(text) {
+  return Array.from(String(text)).length
+}
+
+/** 把子代理输出的 ContentBlock 数组拼成纯文本。 */
+function blocksToText(blocks) {
+  if (!Array.isArray(blocks)) return ''
+  return blocks
+    .filter(block => block && block.type === 'text' && typeof block.text === 'string')
+    .map(block => block.text)
+    .join('\n')
+    .trim()
+}
+
+/**
+ * 非 `completed` 的终止原因都算失败——与内置 subagent 工具同一口径，
+ * 避免把半截输出当成成功结果交给模型。
+ * @param stopReason - 子代理的终止原因。
+ * @returns 失败说明；`completed` 返回 `undefined`。
+ */
+function stopReasonError(stopReason) {
+  switch (stopReason) {
+    case 'completed':
+      return undefined
+    case 'aborted':
+      return '专家分身被取消'
+    case 'error':
+      return '专家分身运行失败'
+    case 'max-tokens':
+      return '专家分身达到 token 上限而未完成'
+    case 'refusal':
+      return '专家分身拒绝执行该任务'
+    default:
+      // 可扩展联合：不认识的终止原因按失败处理，而不是把半截结果当成功。
+      return `专家分身异常结束（${String(stopReason)}）`
+  }
+}
+
+/**
+ * 解析并校验子代理 provider。
+ *
+ * 缺 provider 或缺能力都必须显式失败：静默降级会表现为"专家召唤成功但回答的是通用助手"，
+ * 比报错更难排查。
+ * @param subagents - `ctx.subagents`。
+ * @param config - 插件配置。
+ * @returns `{ providerName, provider }`。
+ */
+export function resolveExpertProvider(subagents, config) {
+  const providerName = String(config?.expertProvider || DEFAULT_EXPERT_PROVIDER).trim()
+  if (!subagents?.getProvider) {
+    throw new Error('EXPERT_SUBAGENTS_UNAVAILABLE: 宿主没有 subagents 服务，专家召唤不可用')
+  }
+  const provider = subagents.getProvider(providerName)
+  if (!provider) {
+    throw new Error(`EXPERT_PROVIDER_UNAVAILABLE: 子代理 provider "${providerName}" 未注册`)
+  }
+  const missing = REQUIRED_PROVIDER_CAPABILITIES.filter(name => provider.capabilities?.[name] !== true)
+  if (missing.length > 0) {
+    throw new Error(
+      `EXPERT_PROVIDER_INCAPABLE: provider "${providerName}" 缺少 ${missing.join('、')} 能力`,
+    )
+  }
+  return { providerName, provider }
+}
+
+/** 按 slug 找专家；找不到时同时接受精确名字，并把候选写进报错里让模型自我纠正。 */
+function findExpert(catalog, reference) {
+  const wanted = String(reference || '').trim()
+  if (!wanted) throw new Error('EXPERT_REQUIRED: 必须给出专家 slug 或名称')
+  const bySlug = catalog.bySlug.get(wanted.toLowerCase())
+  if (bySlug) return bySlug
+  const all = [...catalog.bySlug.values()]
+  const byName = all.find(expert => expert.name === wanted)
+  if (byName) return byName
+  const partial = all.filter(expert => expert.name.includes(wanted) || expert.slug.includes(wanted.toLowerCase()))
+  const hint = partial.length > 0
+    ? `。相近的专家：${partial.slice(0, 5).map(expert => expert.slug).join('、')}`
+    : `。用 list_experts 查看名册`
+  throw new Error(`EXPERT_NOT_FOUND: 找不到专家 "${wanted}"${hint}`)
+}
+
+/** 校验任务文本。 */
+function requireTask(task) {
+  const text = String(task || '').trim()
+  if (!text) throw new Error('EXPERT_TASK_REQUIRED: 必须给出要专家完成的任务')
+  if (codePointLength(text) > SUMMON_TASK_MAX_CHARS) {
+    throw new Error(`EXPERT_TASK_TOO_LONG: 任务超过 ${SUMMON_TASK_MAX_CHARS} 字上限`)
+  }
+  return text
+}
+
+/**
+ * 构造三个工具定义。
+ *
+ * 名册用 `getCatalog()` 惰性获取而不是直接传入：注册发生在同步的 `apply` 里，
+ * 而名册读取是异步的；工具执行本身就是 async，等第一次调用时再取即可。
+ *
+ * @param options.getCatalog - 返回名册（Promise），结果会被缓存。
+ * @param options.getEnabled - 返回启用白名单（`undefined` = 全部启用），同步读取。
+ * @param options.config - 插件配置（读 `expertProvider`、`expertMaxDepth`）。
+ * @param options.subagents - `ctx.subagents`，测试里用替身注入。
+ * @returns 可直接交给 `ctx.tools.register` 的工具定义数组。
+ */
+export function createExpertToolDefinitions({ getCatalog, getEnabled, config, subagents }) {
+  /**
+   * 该专家当前是否启用。`undefined` 表示「未配置 = 全部启用」（见 expert-store）。
+   * 每次执行都重新读，所以用户在设置页一开关就立刻生效，不需要重启。
+   */
+  const isEnabled = slug => {
+    const enabled = typeof getEnabled === 'function' ? getEnabled() : undefined
+    return enabled === undefined || enabled.includes(slug)
+  }
+
+  /** 只保留启用中的专家；一个分类被全部关掉时整条不显示，免得名册里冒出空分类。 */
+  const visibleDivisions = catalog => catalog.divisions
+    .map(division => ({ ...division, experts: division.experts.filter(expert => isEnabled(expert.slug)) }))
+    .filter(division => division.experts.length > 0)
+
+  /** 名册总览：分区永远给（便宜），指定分区时才附专家列表。 */
+  const divisionOverview = catalog => visibleDivisions(catalog).map(division => ({
+    slug: division.slug,
+    name: division.name,
+    count: division.experts.length,
+  }))
+
+  const expertBrief = expert => ({
+    slug: expert.slug,
+    name: expert.name,
+    emoji: expert.emoji,
+    description: codePointLength(expert.description) > EXPERT_DESCRIPTION_MAX_CHARS
+      ? `${Array.from(expert.description).slice(0, EXPERT_DESCRIPTION_MAX_CHARS).join('')}…`
+      : expert.description,
+  })
+
+  /** 召唤一个专家并等它跑完；失败按仓库口径抛出（注册表转成 isError）。 */
+  async function summonOnce(expert, task, exec) {
+    if (!exec?.agent) {
+      throw new Error('EXPERT_REQUIRES_AGENT: 专家召唤需要所属的 agent 会话')
+    }
+    // 停用的专家必须显式拒绝：静默"召唤成功"会让人以为开关没生效。
+    if (!isEnabled(expert.slug)) {
+      throw new Error(`EXPERT_DISABLED: 专家 ${expert.slug} 已在设置里停用`)
+    }
+    const { providerName, provider } = resolveExpertProvider(subagents, config)
+    const persona = await readExpertPersona(expert)
+    if (!persona) {
+      throw new Error(`EXPERT_PERSONA_EMPTY: ${expert.slug} 的正文为空`)
+    }
+    const maxDepth = Number(config?.expertMaxDepth)
+    const run = await subagents.start(providerName, {
+      label: `expert:${expert.slug}`,
+      prompt: [{ type: 'text', text: task }],
+      parent: exec.agent,
+      persona,
+      // 禁掉召唤工具：专家不该再召唤专家。
+      toolFilter: { deny: EXPERT_SUMMON_DENY },
+      ...(Number.isSafeInteger(maxDepth) && maxDepth >= 0 ? { maxDepth } : {}),
+      signal: exec.signal,
+    })
+    try {
+      const result = await run.result
+      const output = blocksToText(result.output)
+      const failure = stopReasonError(result.stopReason)
+      if (failure !== undefined) {
+        throw new Error(`${failure}：${output || '（无输出）'}`)
+      }
+      return { expert: expert.slug, name: expert.name, provider: providerName, output }
+    } finally {
+      // 无论成功失败都要释放子代理资源。
+      await run.dispose()
+    }
+  }
+
+  return [
+    {
+      name: 'list_experts',
+      description:
+        '浏览专家名册。不传 division 时只返回分区与各分区专家数量；传了 division 才返回该分区的专家名单。',
+      // 注意：本插件是纯 JS、绕过了 `defineTool`，所以 parameters / output.schema 都必须写成
+      // **原始 JSON Schema**（`required` 是对象级的字符串数组）。宿主里的内置工具用的是
+      // 属性级 `required: true` 的「spec 方言」，那由 `defineTool` 转换——我们不经过它。
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          division: {
+            type: 'string',
+            description: `分区 slug，可选值：${Object.keys(EXPERT_DIVISIONS).join('、')}`,
+          },
+        },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['divisions', 'experts'],
+          properties: {
+            divisions: { type: 'array', items: { type: 'object' } },
+            experts: { type: 'array', items: { type: 'object' } },
+          },
+        },
+        render: (_args, value) => [{
+          type: 'text',
+          text: value.experts.length > 0
+            ? `专家名单（${value.experts.length} 位）：\n${value.experts
+              .map(expert => `- ${expert.slug}（${expert.name}）：${expert.description}`)
+              .join('\n')}`
+            : `专家分区共 ${value.divisions.length} 个：\n${value.divisions
+              .map(division => `- ${division.slug}（${division.name}）：${division.count} 位`)
+              .join('\n')}\n用 division 参数查看某个分区的专家。`,
+        }],
+      },
+      async execute(args) {
+        const catalog = await getCatalog()
+        const divisions = visibleDivisions(catalog)
+        const division = String(args?.division || '').trim()
+        if (!division) {
+          return { divisions: divisionOverview(catalog), experts: [] }
+        }
+        const matched = divisions.find(item => item.slug === division || item.name === division)
+        if (!matched) {
+          throw new Error(
+            `EXPERT_DIVISION_UNKNOWN: 没有分区 "${division}"，可选：${divisions.map(item => item.slug).join('、')}`,
+          )
+        }
+        return {
+          divisions: divisionOverview(catalog),
+          experts: matched.experts.map(expertBrief),
+        }
+      },
+    },
+
+    {
+      name: 'summon_expert',
+      description:
+        '召唤一位专家分身执行任务，并等它返回结果。专家是独立的子代理，拥有该领域的系统提示词与完整的常备工具集。',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['expert', 'task'],
+        properties: {
+          expert: {
+            type: 'string',
+            description: '专家 slug（用 list_experts 查询），也接受精确的专家名称',
+          },
+          task: {
+            type: 'string',
+            description: `交给该专家的任务，尽量写清背景、已知条件与要交付的东西（上限 ${SUMMON_TASK_MAX_CHARS} 字）`,
+          },
+        },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['expert', 'name', 'provider', 'output'],
+          properties: {
+            expert: { type: 'string' },
+            name: { type: 'string' },
+            provider: { type: 'string' },
+            output: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [{
+          type: 'text',
+          text: `【${value.name}】\n${value.output}`,
+        }],
+      },
+      async execute(args, exec) {
+        const catalog = await getCatalog()
+        const expert = findExpert(catalog, args?.expert)
+        const task = requireTask(args?.task)
+        return summonOnce(expert, task, exec)
+      },
+    },
+
+    {
+      name: 'summon_experts',
+      description:
+        `并行召唤多位专家，每个专家拿到自己的任务。最多 ${SUMMON_EXPERTS_MAX} 位，同时最多跑 ${SUMMON_EXPERTS_CONCURRENCY} 位。`
+        + '单个专家失败不影响其他专家，结果里会逐条标明。',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['items'],
+        properties: {
+          items: {
+            type: 'array',
+            description: '要召唤的专家与各自的任务',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              required: ['expert', 'task'],
+              properties: {
+                expert: { type: 'string', description: '专家 slug' },
+                task: { type: 'string', description: '交给该专家的任务' },
+              },
+            },
+          },
+        },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['results'],
+          properties: {
+            results: { type: 'array', items: { type: 'object' } },
+          },
+        },
+        render: (_args, value) => {
+          const ok = value.results.filter(item => item.ok).length
+          const lines = value.results.map((item, index) => {
+            const head = `${index + 1}. ${item.expert}`
+            return item.ok ? `${head}\n${item.output}` : `${head} —— 失败：${item.error}`
+          })
+          return [{
+            type: 'text',
+            text: `召唤 ${value.results.length} 位专家，成功 ${ok} 位，失败 ${value.results.length - ok} 位。\n\n${lines.join('\n\n')}`,
+          }]
+        },
+      },
+      async execute(args, exec) {
+        const catalog = await getCatalog()
+        const items = args?.items
+        if (!Array.isArray(items) || items.length === 0) {
+          throw new Error('EXPERT_ITEMS_REQUIRED: 必须给出要召唤的专家列表')
+        }
+        if (items.length > SUMMON_EXPERTS_MAX) {
+          throw new Error(`EXPERT_ITEMS_TOO_MANY: 一次最多召唤 ${SUMMON_EXPERTS_MAX} 位专家`)
+        }
+        // 先整体校验：坏参数应当在起任何子代理之前失败，否则会留下半跑的专家。
+        const plan = items.map((item, index) => {
+          try {
+            return { expert: findExpert(catalog, item?.expert), task: requireTask(item?.task) }
+          } catch (error) {
+            throw new Error(`EXPERT_ITEM_INVALID: 第 ${index + 1} 项：${error.message}`)
+          }
+        })
+        const results = await mapPool(plan, SUMMON_EXPERTS_CONCURRENCY, async ({ expert, task }) => {
+          try {
+            const settled = await summonOnce(expert, task, exec)
+            return { ok: true, expert: expert.slug, name: expert.name, output: settled.output }
+          } catch (error) {
+            // 单个专家失败不拖垮整批：把失败收敛成结果项。
+            return { ok: false, expert: expert.slug, name: expert.name, error: error.message }
+          }
+        })
+        return { results }
+      },
+    },
+  ]
+}