@waterplus-ai/waterbuddy 0.1.38 → 0.1.78

package/lib/host/experts.js

@@ -0,0 +1,318 @@
+/**
+ * 专家名册：把 `assets/experts/<分区>/<slug>.md` 读成可召唤的专家目录。
+ *
+ * 每份 persona 的正文是**完整的系统提示词**（十几 KB 量级），所以启动时只读
+ * frontmatter 做目录，正文留到真正召唤时再读（见 `readExpertPersona`）。
+ *
+ * 文件格式（frontmatter + 正文，正文即系统提示词）：
+ *
+ *     ---
+ *     name: 供水管网水力建模专家
+ *     description: 一句话说明这位专家解决什么问题
+ *     emoji: 🚰
+ *     division: supply
+ *     ---
+ *     # 正文，会作为 persona 注入子代理
+ *
+ * frontmatter 只支持单行 `key: value`（值可用单/双引号包裹），不支持嵌套与多行，
+ * 这样解析器不需要引入 YAML 依赖——本插件是零依赖的纯 JS 包。
+ */
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 分区 slug → 展示名。新增分区只改这一处。 */
+export const EXPERT_DIVISIONS = {
+  supply: '供水',
+  drainage: '排水',
+  quality: '水质',
+  digital: '数字化',
+  policy: '政策标准',
+  operations: '运营服务',
+  management: '集团管理',
+  general: '通用办公',
+}
+
+/**
+ * 分区目录名与 persona slug 只允许这种形状：小写字母/数字，用连字符分隔。
+ * `..`、`/`、盘符、大小写混排一律不合法，因此拿 slug 拼路径不会越出名册目录。
+ */
+export const EXPERT_PATH_SEGMENT_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+/** frontmatter 的起始读取量与上限：正常一两百字节就够，异常文件也不至于读爆内存。 */
+const FRONTMATTER_HEAD_BYTES = 1024
+const FRONTMATTER_MAX_BYTES = 64 * 1024
+
+/** 内置名册目录，与本模块同包分发。 */
+export const DEFAULT_EXPERTS_DIR = fileURLToPath(new URL('../../assets/experts', import.meta.url))
+
+/** 去掉 BOM：带 BOM 时行首匹配不到 `---`，整份 frontmatter 都会读不出来。 */
+export function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+}
+
+/**
+ * 消毒 persona，使其能安全穿过系统提示词的严格 `{{…}}` 插值。
+ *
+ * 提示词装配对每个 section 跑严格插值，正文里只要出现完整花括号组就会抛错；
+ * 这里在相邻的两个 `{` 之间插一个零宽空格（U+200B），插值器就看不见 `{{` 了，
+ * 而视觉上完全不变。三连 `{{{` 需要插两处，`replace` 的全局匹配天然覆盖。
+ *
+ * @param text - persona 正文。
+ * @returns 插值安全的等长（零宽字符会让码点变长，显示长度不变）文本。
+ */
+export function sanitizePersona(text) {
+  return String(text).replace(/\{(?=\{)/g, '{\u200B')
+}
+
+/**
+ * 读文件头，直到出现 frontmatter 结束标记或到达上限。
+ *
+ * 只读头部是为了让「几百份 persona 的目录」不必把正文全读进内存。
+ * @param filePath - persona 文件绝对路径。
+ * @returns 文件头部文本（可能不含结束标记，由调用方判定）。
+ */
+async function readFrontmatterHead(filePath) {
+  const handle = await fs.open(filePath, 'r')
+  try {
+    const chunks = []
+    let total = 0
+    let offset = 0
+    while (total < FRONTMATTER_MAX_BYTES) {
+      const size = Math.min(FRONTMATTER_HEAD_BYTES, FRONTMATTER_MAX_BYTES - total)
+      const buffer = Buffer.allocUnsafe(size)
+      const { bytesRead } = await handle.read(buffer, 0, size, offset)
+      if (bytesRead === 0) break
+      chunks.push(buffer.subarray(0, bytesRead))
+      total += bytesRead
+      offset += bytesRead
+      // 结束标记必须在头部内：读到就停，避免把正文读进来。
+      if (Buffer.concat(chunks).toString('utf8').includes('\n---')) break
+    }
+    return Buffer.concat(chunks).toString('utf8')
+  } finally {
+    await handle.close()
+  }
+}
+
+/**
+ * 解析 persona 的 frontmatter。
+ *
+ * @param text - 文件文本（至少包含 frontmatter）。
+ * @returns 键值映射；没有 frontmatter 时返回空对象。
+ */
+export function parseExpertFrontmatter(text) {
+  const lines = stripBom(String(text)).split(/\r?\n/)
+  if (lines[0]?.trim() !== '---') return {}
+  const fields = {}
+  for (let index = 1; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (line.trim() === '---') return fields
+    const separator = line.indexOf(':')
+    if (separator <= 0) continue
+    const key = line.slice(0, separator).trim()
+    let value = line.slice(separator + 1).trim()
+    if (
+      value.length >= 2
+      && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1)
+    }
+    if (key) fields[key] = value
+  }
+  // 没有闭合的 `---`：frontmatter 不完整，按"没有"处理，由调用方报缺字段。
+  return {}
+}
+
+/** 去掉 frontmatter，返回正文。 */
+export function expertBody(text) {
+  const lines = stripBom(String(text)).split(/\r?\n/)
+  if (lines[0]?.trim() !== '---') return String(text).trim()
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index].trim() === '---') return lines.slice(index + 1).join('\n').trim()
+  }
+  return ''
+}
+
+/**
+ * 扫描名册目录，只读 frontmatter 建立目录。
+ *
+ * 分区顺序按 `EXPERT_DIVISIONS` 的声明顺序（而非 `readdir` 的返回顺序），
+ * 专家在分区内按 slug 排序，保证同一次构建的目录顺序稳定。
+ *
+ * @param rootDir - 名册根目录，默认 {@link DEFAULT_EXPERTS_DIR}。
+ * @returns `{ divisions, bySlug }`；`divisions` 是 `[{ slug, name, experts }]`。
+ * @throws 当文件名不合法、缺必填字段或 slug 重复时——名册是自己发布的资产，
+ *   坏文件必须显式失败，不能悄悄少一个专家。
+ */
+export async function loadExpertCatalog(rootDir = DEFAULT_EXPERTS_DIR) {
+  const divisions = []
+  const bySlug = new Map()
+  let divisionEntries = []
+  try {
+    divisionEntries = await fs.readdir(rootDir, { withFileTypes: true })
+  } catch (error) {
+    if (error.code === 'ENOENT') return { divisions, bySlug }
+    throw error
+  }
+
+  for (const entry of divisionEntries) {
+    if (!entry.isDirectory() || !EXPERT_PATH_SEGMENT_PATTERN.test(entry.name)) continue
+    const divisionSlug = entry.name
+    const experts = []
+    const files = (await fs.readdir(path.join(rootDir, divisionSlug))).filter(name => name.endsWith('.md')).sort()
+    for (const file of files) {
+      const slug = file.slice(0, -3)
+      if (!EXPERT_PATH_SEGMENT_PATTERN.test(slug)) {
+        throw new Error(`EXPERT_SLUG_INVALID: ${divisionSlug}/${file} 只允许小写字母数字与连字符`)
+      }
+      const filePath = path.join(rootDir, divisionSlug, file)
+      const fields = parseExpertFrontmatter(await readFrontmatterHead(filePath))
+      const name = (fields.name || '').trim()
+      const description = (fields.description || '').trim()
+      if (!name || !description) {
+        throw new Error(`EXPERT_FRONTMATTER_INCOMPLETE: ${divisionSlug}/${file} 缺少 name 或 description`)
+      }
+      if (bySlug.has(slug)) {
+        throw new Error(`EXPERT_SLUG_DUPLICATE: ${slug} 在名册中重复`)
+      }
+      if (fields.division && fields.division !== divisionSlug) {
+        throw new Error(
+          `EXPERT_DIVISION_MISMATCH: ${divisionSlug}/${file} 的 division=${fields.division} 与目录不一致`,
+        )
+      }
+      const expert = {
+        slug,
+        division: divisionSlug,
+        name,
+        description,
+        emoji: (fields.emoji || '').trim(),
+        // 头像图片：http(s) URL 直接用；否则当作与本 md 同目录的文件名，
+        // 由 `/api/waterbuddy/experts/avatar` 按需吐出来（不塞进名册快照）。
+        avatar: (fields.avatar || '').trim(),
+        filePath,
+        custom: false,
+      }
+      experts.push(expert)
+      bySlug.set(slug, expert)
+    }
+    if (experts.length > 0) {
+      divisions.push({
+        slug: divisionSlug,
+        name: EXPERT_DIVISIONS[divisionSlug] || divisionSlug,
+        experts,
+      })
+    }
+  }
+
+  return { divisions, bySlug }
+}
+
+/**
+ * 读取一位专家的原始正文（未消毒），供界面展示。
+ *
+ * 展示用原文，注入子代理用 {@link readExpertPersona}——后者插了零宽空格，虽然肉眼不可见，
+ * 但不该混进界面里被用户复制走的文本。
+ *
+ * @param expert - {@link loadExpertCatalog} 产出的条目。
+ * @returns persona 正文。
+ */
+export async function readExpertBody(expert) {
+  // 自定义专家的正文来自 settings，没有文件可读。
+  if (typeof expert.body === 'string') return expert.body
+  return expertBody(await fs.readFile(expert.filePath, 'utf8'))
+}
+
+/**
+ * 把自定义专家并进内置名册，产出一份新名册（不改原对象）。
+ *
+ * slug 冲突时**内置优先**：内置专家的 slug 是自己发布的资产，不能让一条自定义数据把它顶掉，
+ * 否则删掉自定义项后重启会换回内置内容，行为难以解释。
+ *
+ * @param catalog - 内置名册。
+ * @param customExperts - `{ slug, division, name, description, emoji, prompt }` 数组。
+ * @returns 合并后的名册（结构与 {@link loadExpertCatalog} 一致）。
+ */
+export function mergeCustomExperts(catalog, customExperts) {
+  if (!Array.isArray(customExperts) || customExperts.length === 0) return catalog
+  const bySlug = new Map(catalog.bySlug)
+  const divisions = catalog.divisions.map(division => ({ ...division, experts: [...division.experts] }))
+  const byDivision = new Map(divisions.map(division => [division.slug, division]))
+  for (const custom of customExperts) {
+    if (!custom || bySlug.has(custom.slug)) continue
+    const expert = {
+      slug: custom.slug,
+      division: custom.division,
+      name: custom.name,
+      description: custom.description,
+      emoji: custom.emoji,
+      avatar: custom.avatar || '',
+      body: custom.prompt,
+      custom: true,
+    }
+    bySlug.set(expert.slug, expert)
+    const division = byDivision.get(expert.division)
+    if (division) {
+      division.experts.push(expert)
+    } else {
+      const created = {
+        slug: expert.division,
+        name: EXPERT_DIVISIONS[expert.division] || expert.division,
+        experts: [expert],
+      }
+      byDivision.set(expert.division, created)
+      divisions.push(created)
+    }
+  }
+  return { divisions, bySlug }
+}
+
+/**
+ * 所有专家共用的**交付纪律**，注入 persona 时前置。
+ *
+ * 模型天然会把"检索过程"和"内部存疑"一起写进产出：实测用户拿到的成品文档里出现过
+ * `getThemeTree` / `searchPolicies` / `modelId=11` 这类内部细节，以及"这段是 AI 扩写的"
+ * "某接口鉴权失败"这类不该给业务方看的判断。这些属于过程与内部信息，不是交付物。
+ * 统一在这里前置一次，避免 32 份 persona 各写一遍、也避免新加专家时漏掉。
+ */
+export const EXPERT_OUTPUT_RULES = [
+  '## 交付纪律（对所有产出生效）',
+  '',
+  '- 产出是给**业务用户**看的。**不要**出现工具名、接口名、参数名、模型 ID、知识库 ID、',
+  '  文件路径、命令，或任何检索/调用步骤（例如 getThemeTree、searchPolicies、getCaseDetail、',
+  '  listKbNodesTree、modelId=11、kbIds 一律不写）。',
+  '- **不要**把内部判断写进产出（例如"这段是 AI 扩写的""某个接口鉴权失败""未能核验"）。',
+  '  需要提示可靠性时，只用一句业务语言，例如"部分数据来自公开报道，建议以官方发布为准"。',
+  '  技术性的说明留在**对话回复**里，不要写进交付的文件。',
+  '- 引用来源写**业务名称**（如"水务加案例库""住建部 2025 年典型案例名单"），不写工具名。',
+  '- 产出要能直接拿去用：先给结论与依据；不要过程日志，也不要复述收到的任务。',
+  '- 检索不到或不确定的内容，宁可不写，也不要用推测补全。',
+  '',
+].join('\n')
+
+/**
+ * 读取一位专家的完整 persona 正文（已消毒），供注入子代理。
+ *
+ * @param expert - {@link loadExpertCatalog} 产出的条目。
+ * @returns 可直接作为 `persona` 传入的文本。
+ */
+export async function readExpertPersona(expert) {
+  const body = await readExpertBody(expert)
+  return sanitizePersona(`${EXPERT_OUTPUT_RULES}\n${body}`)
+}
+
+/**
+ * 解析一位专家的头像图片路径。
+ *
+ * @param expert - 名册条目。
+ * @returns `{ kind: 'remote', url }` 表示直接用外链；`{ kind: 'file', path }` 表示本地文件
+ *   （相对路径相对该专家的 md 所在目录）；`undefined` 表示没有配头像。
+ */
+export function resolveExpertAvatar(expert) {
+  const raw = String(expert?.avatar || '').trim()
+  if (!raw) return undefined
+  if (/^https?:\/\//i.test(raw)) return { kind: 'remote', url: raw }
+  if (raw.includes('..') || raw.startsWith('/')) return undefined
+  if (!expert.filePath) return undefined
+  return { kind: 'file', path: path.join(path.dirname(expert.filePath), raw) }
+}

package/lib/host/index.js

@@ -3,6 +3,9 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { WATERPLUS_PERSONA } from '../shared/persona.js'
+import { createExpertStore, isExpertEnabled } from './expert-store.js'
+import { createExpertToolDefinitions } from './expert-tools.js'
+import { EXPERT_DIVISIONS, loadExpertCatalog, mergeCustomExperts, readExpertBody, resolveExpertAvatar } from './experts.js'
 import { bindLlmCredential, describeLlmCredential, ensureLlmCredential, formatBalanceText, isGatewayActive, readActiveProvider, refreshLlmQuota, restoreDeviceLlmCredential, switchDefaultProviderWithRetry } from './llm-gateway.js'
 
 const WATERPLUS_ICON = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64')
@@ -380,12 +383,278 @@ export async function bootstrapLlmCredential(ctx, config) {
   return llmStatus || null
 }
 
-export const inject = ['webServer', 'systemPrompt', 'credentials', 'settings']
+/**
+ * 安全读取宿主服务：未注入时 cordis 的访问可能抛错而不是返回 undefined，
+ * 而专家是**附加能力**，不能因为拿不到服务就把整个插件挡在启动之外。
+ * @param ctx - 插件上下文。
+ * @param name - 服务名。
+ * @returns 服务实例，取不到时返回 `undefined`。
+ */
+function readService(ctx, name) {
+  try {
+    return ctx?.[name]
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 专家模式的系统提示词段。
+ *
+ * 只列分区与数量，不列具体专家——名册可能很大，逐个列会把提示词撑爆；
+ * 模型需要时自己调 `list_experts`。
+ * @param catalog - 已加载的名册。
+ * @returns 提示词文本（不含 `{{`，避免插值抛错）。
+ */
+function expertPromptSection(catalog) {
+  const divisions = catalog.divisions
+    .map(division => `- ${division.slug}（${division.name}）：${division.experts.length} 位`)
+    .join('\n')
+  return [
+    '## 专家召唤模式',
+    '',
+    '本会话有一份水务行业专家名册，专家是可召唤的子代理（各自带该领域的系统提示词）。',
+    '',
+    '**关键：用户在输入框里选中的专家会以「引用 chip」的形式出现在消息里，显示为 @专家名；'
+      + '消息中剩下的文字就是交给这位专家的任务。** 看到这种 @引用时，按名字直接召唤该专家'
+      + '（先 `list_experts` 确认可用，再 `summon_expert`），**不要**把它当成文件路径、工作区引用'
+      + '或需要检索的文档——那会白白翻一遍工作区。',
+    '',
+    '工具用法：',
+    '- `list_experts`：不传参数只回分区与数量；传 division 才展开该分区的专家',
+    '- `summon_expert(expert, task)`：召唤一位专家，task 里写清背景、已知条件、要交付的东西',
+    '- `summon_experts`：并行召唤多位（最多 8 位），适合需要多领域视角的任务',
+    '',
+    '用户没有指定专家、但任务明显需要某个领域的深度分析时，你也可以主动召唤。',
+    '',
+    `名册共 ${catalog.bySlug.size} 位专家，分 ${catalog.divisions.length} 个方向：`,
+    divisions,
+    '',
+    '专家返回的是独立分析，仍需你结合上下文判断后再交付给用户。',
+  ].join('\n')
+}
+
+/**
+ * 专家名册的只读路由，供设置页浏览。
+ *
+ * 用 `?slug=` 取单个专家的正文，而不是再开一条路径：一条 GET 不值得引入路径解析。
+ * 展示返回**未消毒**的原文（见 `readExpertBody`），零宽空格不该出现在用户能复制的文本里。
+ *
+ * @param catalog - 名册 Promise，与工具共用同一份。
+ * @returns 路由定义数组。
+ */
+/** 插件自身版本号，供设置页展示（单一出处：package.json）。 */
+let cachedPluginVersion
+function pluginVersion() {
+  if (cachedPluginVersion === undefined) {
+    try {
+      cachedPluginVersion = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version || ''
+    } catch {
+      cachedPluginVersion = ''
+    }
+  }
+  return cachedPluginVersion
+}
+
+function expertRoutes(snapshot, store) {
+  /** 把一位专家压成界面需要的形状（含当前启用状态与是否自定义）。 */
+  const brief = (expert, state) => ({
+    slug: expert.slug,
+    name: expert.name,
+    emoji: expert.emoji,
+    description: expert.description,
+    division: expert.division,
+    divisionName: EXPERT_DIVISIONS[expert.division] || expert.division,
+    custom: expert.custom === true,
+    enabled: isExpertEnabled(state, expert.slug),
+    // 外链直接用；本地图片走我们的取图路由（按需读、带缓存，不塞进快照）。
+    avatar: expert.avatar
+      ? (resolveExpertAvatar(expert)?.kind === 'remote'
+        ? expert.avatar
+        : '/api/waterbuddy/experts/avatar?slug=' + encodeURIComponent(expert.slug))
+      : '',
+  })
+
+  /** 统一把异常收敛成 JSON：带错误码的校验失败返回 400，其余 502。 */
+  const guard = handler => async (req, res) => {
+    try {
+      await handler(req, res)
+    } catch (error) {
+      const code = /^(EXPERT_[A-Z_]+):/.exec(error.message)?.[1]
+      json(res, code ? 400 : 502, { error: error.message })
+    }
+  }
+
+  const readBody = async req => {
+    try {
+      return await readJsonBody(req)
+    } catch {
+      throw new Error('EXPERT_BODY_INVALID: 请求参数格式不正确')
+    }
+  }
+
+  return [
+    {
+      kind: 'exact',
+      path: '/api/waterbuddy/experts',
+      handler: guard(async (req, res) => {
+        if (req.method !== 'GET') return json(res, 405, { error: 'method-not-allowed' })
+        const slug = new URL(req.url, 'http://127.0.0.1').searchParams.get('slug')
+        const { catalog, state } = await snapshot()
+        if (slug) {
+          const expert = catalog.bySlug.get(slug)
+          if (!expert) return json(res, 404, { error: 'expert-not-found' })
+          // 展示返回未消毒的原文：零宽空格不该出现在用户能复制走的文本里。
+          return json(res, 200, { expert: brief(expert, state), body: await readExpertBody(expert) })
+        }
+        const experts = [...catalog.bySlug.values()].map(expert => brief(expert, state))
+        json(res, 200, {
+          experts,
+          divisions: catalog.divisions.map(division => ({
+            slug: division.slug,
+            name: division.name,
+            count: division.experts.length,
+          })),
+          enabledCount: experts.filter(expert => expert.enabled).length,
+          revision: state.revision,
+          // 版本号由宿主下发：客户端不该自己硬编码一份会漂移的副本。
+          version: pluginVersion(),
+        })
+      }),
+    },
+    {
+      kind: 'exact',
+      path: '/api/waterbuddy/experts/avatar',
+      handler: guard(async (req, res) => {
+        if (req.method !== 'GET') return json(res, 405, { error: 'method-not-allowed' })
+        const slug = new URL(req.url, 'http://127.0.0.1').searchParams.get('slug') || ''
+        const { catalog } = await snapshot()
+        const expert = catalog.bySlug.get(slug)
+        const avatar = expert ? resolveExpertAvatar(expert) : undefined
+        if (!avatar) return json(res, 404, { error: 'avatar-not-found' })
+        if (avatar.kind === 'remote') return json(res, 400, { error: 'avatar-is-remote' })
+        const extension = (avatar.path.match(/\.[a-z0-9]+$/i) || [''])[0].toLowerCase()
+        const types = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.svg': 'image/svg+xml' }
+        const type = types[extension]
+        if (!type) return json(res, 415, { error: 'avatar-type-unsupported' })
+        let bytes
+        try { bytes = await fs.promises.readFile(avatar.path) } catch { return json(res, 404, { error: 'avatar-not-found' }) }
+        res.writeHead(200, { 'content-type': type, 'cache-control': 'public, max-age=3600' })
+        res.end(bytes)
+      }),
+    },
+    {
+      kind: 'exact',
+      path: '/api/waterbuddy/experts/enabled',
+      handler: guard(async (req, res) => {
+        if (req.method !== 'POST') return json(res, 405, { error: 'method-not-allowed' })
+        const body = await readBody(req)
+        await store.replaceEnabled(body.enabled, body.expectedRevision)
+        const { catalog, state } = await snapshot()
+        const experts = [...catalog.bySlug.values()].map(expert => brief(expert, state))
+        json(res, 200, {
+          experts,
+          enabledCount: experts.filter(expert => expert.enabled).length,
+          revision: state.revision,
+        })
+      }),
+    },
+    {
+      kind: 'exact',
+      path: '/api/waterbuddy/experts/custom',
+      handler: guard(async (req, res) => {
+        if (req.method !== 'POST') return json(res, 405, { error: 'method-not-allowed' })
+        const body = await readBody(req)
+        const state = await store.saveCustom(body.expert, body.expectedRevision)
+        const { catalog } = await snapshot()
+        const experts = [...catalog.bySlug.values()].map(expert => brief(expert, state))
+        json(res, 200, {
+          experts,
+          enabledCount: experts.filter(expert => expert.enabled).length,
+          revision: state.revision,
+        })
+      }),
+    },
+    {
+      kind: 'exact',
+      path: '/api/waterbuddy/experts/custom/delete',
+      handler: guard(async (req, res) => {
+        if (req.method !== 'POST') return json(res, 405, { error: 'method-not-allowed' })
+        const body = await readBody(req)
+        const state = await store.deleteCustom(String(body.slug || ''), body.expectedRevision)
+        const { catalog } = await snapshot()
+        const experts = [...catalog.bySlug.values()].map(expert => brief(expert, state))
+        json(res, 200, {
+          experts,
+          enabledCount: experts.filter(expert => expert.enabled).length,
+          revision: state.revision,
+        })
+      }),
+    },
+  ]
+}
+
+function setupExpertTools(ctx, config, { getCatalog, getEnabled }) {
+  const tools = readService(ctx, 'tools')
+  const subagents = readService(ctx, 'subagents')
+  if (!tools?.register || !subagents) {
+    console.warn('[WaterBuddy] experts disabled: host exposes no tools/subagents service')
+    return []
+  }
+
+  // 名册就绪前提示词段先留空，下一轮请求就有了。
+  let loaded
+  void getCatalog().then(value => { loaded = value }).catch(() => {})
+
+  const disposers = []
+  try {
+    for (const definition of createExpertToolDefinitions({
+      getCatalog,
+      getEnabled,
+      config,
+      subagents,
+    })) {
+      disposers.push(tools.register(definition))
+    }
+    disposers.push(ctx.systemPrompt.section({
+      name: 'waterplus:experts',
+      order: 110,
+      text: context => {
+        // 专家分身自己不该再被引导去召唤专家（与工具侧的 toolFilter 双保险）。
+        if (context?.agent?.session?.header?.parentSession !== undefined) return ''
+        return loaded ? expertPromptSection(loaded) : ''
+      },
+    }))
+  } catch (error) {
+    console.warn('[WaterBuddy] expert tools registration failed:', error.message)
+    for (const dispose of disposers) {
+      try { dispose() } catch { /* 已失败，回滚本身不再抛 */ }
+    }
+    return []
+  }
+  return disposers
+}
+
+export const inject = ['webServer', 'systemPrompt', 'credentials', 'settings', 'tools', 'subagents']
 export { normalizeAvatar, setUpstreamTransport }
 
 export function apply(ctx, config) {
   readPersistedAuth()
   ctx.effect(() => {
+    // 内置名册读一次（异步、失败只记日志）；自定义专家与启用状态存在 settings 里，
+    // 每次快照时合并，所以用户在设置页改完立刻生效，不需要重启。
+    const builtinCatalog = loadExpertCatalog(config?.expertsDir || undefined)
+    builtinCatalog.catch(error => console.warn('[WaterBuddy] expert catalog failed to load:', error.message))
+    // 状态存在 $DSH_HOME/waterbuddy-experts.json（`expertsStateFile` 可覆盖，测试用临时文件）。
+    // 名册加载完成后记下全部 slug，供 store 判断白名单是否来自上一代名册。
+    let knownExpertSlugs
+    const expertStore = createExpertStore({ file: config?.expertsStateFile, knownSlugs: () => knownExpertSlugs })
+    const expertSnapshot = async () => {
+      const state = expertStore.read()
+      const catalog = mergeCustomExperts(await builtinCatalog, state.customExperts)
+      knownExpertSlugs = new Set(catalog.bySlug.keys())
+      return { catalog, state }
+    }
     const routes = [
       { kind: 'exact', path: '/waterplus-mark.png', handler: (_req, res) => { res.writeHead(200, { 'content-type': 'image/png', 'cache-control': 'public, max-age=3600' }); res.end(WATERPLUS_ICON) } },
       { kind: 'exact', path: '/manifest.webmanifest', handler: (_req, res) => { res.writeHead(200, { 'content-type': 'application/manifest+json; charset=utf-8', 'cache-control': 'public, max-age=3600' }); res.end(MANIFEST) } },
@@ -422,16 +691,21 @@ export function apply(ctx, config) {
       { kind: 'exact', path: '/api/waterbuddy/llm/refresh', handler: async (req, res) => { if (req.method !== 'POST') return json(res, 405, { error: 'method-not-allowed' }); try { json(res, 200, { llm: await bootstrapLlmCredential(ctx, config) }) } catch (error) { json(res, 502, { error: error.message }) } } },
       { kind: 'exact', path: '/api/waterbuddy/logout', handler: async (_req, res) => { currentUser = undefined; for (const session of sessions.values()) delete session.token; clearPersistedAuth(); if (llmLogoutHook) { try { await withTimeout(Promise.resolve().then(() => llmLogoutHook()), LLM_SWAP_TIMEOUT_MS, 'llm-unbind') } catch (error) { console.warn('[WaterBuddy] llm restore after logout failed:', error.message) } } json(res, 200, { ok: true }) } },
       { kind: 'prefix', path: '/api/waterbuddy/mcp', handler: async (req, res) => { try { await proxyMcp(req, res) } catch (error) { json(res, 502, { error: error.message }) } } },
+      ...expertRoutes(expertSnapshot, expertStore),
     ]
     const disposers = routes.map(route => ctx.webServer.register(route))
     const disposeTitle = ctx.webServer.tapIndex(html => html.replace(/<title>[^<]*<\/title>/i, '<title>WaterBuddy</title>').replace(/<link[^>]+rel=["']icon["'][^>]*>/i, '<link rel="icon" type="image/png" href="/waterplus-mark.png" />'))
     const disposePersona = ctx.systemPrompt.section({ name: 'waterplus:persona', order: 100, text: WATERPLUS_PERSONA })
+    const expertDisposers = setupExpertTools(ctx, config, {
+      getCatalog: async () => (await expertSnapshot()).catalog,
+      getEnabled: () => expertStore.read().enabled,
+    })
     // 尽力而为：宿主没有 credentials 服务（例如测试替身）时直接跳过，不发网络请求。
     if (ctx.credentials?.set) {
       llmLoginHook = token => bindLlmCredential(ctx, token, { config })
       llmLogoutHook = () => restoreDeviceLlmCredential(ctx, { config })
       void bootstrapLlmCredential(ctx, config)
     }
-    return () => { for (const dispose of disposers) dispose(); disposeTitle(); disposePersona(); sessions.clear(); currentUser = undefined; persistedAuth = undefined }
+    return () => { for (const dispose of disposers) dispose(); disposeTitle(); disposePersona(); for (const dispose of expertDisposers) dispose(); sessions.clear(); currentUser = undefined; persistedAuth = undefined }
   }, 'waterbuddy: identity and auth')
 }

package/lib/host/llm-gateway.js

@@ -26,7 +26,7 @@ export const LOW_BALANCE_HINT = 0
 
 /**
  * 额度以美元记账（sub2api 的 `user.balance` 单位，见 SUB2API-TOKEN-QUOTA-PLAN §19.1），
- * 但产品按人民币向用户交代额度，所以**只折算展示文本**：`balance` 字段保持美元，
+ * 但产品按**积分**向用户交代额度，所以**只折算展示文本**：`balance` 字段保持美元，
  * `lowBalance` / `exhausted` 的阈值比较依赖美元口径，不能被折算污染。
  *
  * 默认汇率取 DeepSeek 官方两套价目表的隐含汇率（Flash $0.15↔¥1 = 6.67；
@@ -34,17 +34,26 @@ export const LOW_BALANCE_HINT = 0
  */
 export const DEFAULT_USD_TO_CNY_RATE = 6.8
 
+/** 积分口径：1 元 = 100 积分（产品定义）。 */
+export const POINTS_PER_YUAN = 100
+
 /** 展示汇率：插件 config 优先，缺失或非法时回落默认值。 */
 export function resolveUsdToCnyRate(config) {
   const rate = Number(config?.balanceUsdToCnyRate)
   return Number.isFinite(rate) && rate > 0 ? rate : DEFAULT_USD_TO_CNY_RATE
 }
 
-/** 把美元余额折算成人民币展示文本。只用于展示，不参与任何计费或阈值判断。 */
+/**
+ * 把美元余额折算成积分展示文本：美元 → 人民币 → ×`POINTS_PER_YUAN`，取整。
+ *
+ * 只用于展示，不参与任何计费或阈值判断。取整会带来不足 1 积分（< ¥0.01）的误差，
+ * 显示上不可见；额度是否耗尽仍由 `exhausted` 决定，不靠这里显示成 0 来判断。
+ */
 export function formatBalanceText(balanceUsd, config) {
   const amount = Number(balanceUsd)
   const usd = Number.isFinite(amount) ? amount : 0
-  return `¥${(usd * resolveUsdToCnyRate(config)).toFixed(2)}`
+  const points = Math.round(usd * resolveUsdToCnyRate(config) * POINTS_PER_YUAN)
+  return `${points} 积分`
 }
 
 const DEVICE_ID_PATTERN = /^[A-Za-z0-9._:-]{8,128}$/