@waterplus-ai/waterbuddy 0.1.38 → 0.1.78

package/lib/client/index.js

@@ -18,6 +18,7 @@ window.__ModuleLoader__.load({
     }
 
     function WaterBuddyName() {
+      // 只保留蓝色字标；不再显示 「Powered by DSH」。
       return jsxs(Fragment, {
         children: [
           jsx('strong', {
@@ -31,17 +32,7 @@ window.__ModuleLoader__.load({
             },
             children: 'WaterBuddy',
           }),
-          jsx('small', {
-            style: {
-              color: 'var(--dsw-text-tertiary, #7b8494)',
-              fontSize: 10,
-              fontWeight: 500,
-              opacity: 0.7,
-              whiteSpace: 'nowrap',
-            },
-            children: 'Powered by DSH',
-          }),
-        ],
+          ],
       })
     }
 
@@ -507,11 +498,12 @@ window.__ModuleLoader__.load({
       const logout = async () => { await fetch('/api/waterbuddy/logout', { method: 'POST' }); setUser(null); setOpen(false); setSession({ qrCode: '', status: '', error: '', loading: false }) }
       const name = userName(user)
       const buttonStyle = { borderRadius: 10, padding: '9px 18px', fontSize: 13, fontWeight: 600, cursor: 'pointer' }
-      // 额度以美元记账、按人民币向用户展示；折算与格式化都在 Host 侧完成
+      // 额度以美元记账、按积分向用户展示；折算与格式化都在 Host 侧完成
       // （见 formatBalanceText），客户端只渲染文本，不自己拿汇率算。
+      // Host 未给文本时用占位符，不回落到金额——展示口径由 Host 独占，避免两处不一致。
       const balanceText = typeof llm?.balanceText === 'string' && llm.balanceText
         ? llm.balanceText
-        : `$${Number(llm?.balance || 0).toFixed(2)}`
+        : '--'
       // 用户把默认模型换成别人的提供方时，消耗的不是我们的额度，一律不展示额度。
       const managesQuota = llm?.managesQuota === true
       const exhausted = managesQuota && llm?.exhausted === true
@@ -527,7 +519,10 @@ window.__ModuleLoader__.load({
         const isAdmin = user?.isAdmin === 1 || user?.isAdmin === true
         return jsxs(Fragment, { children: [
           jsx('div', { style: { position: 'relative', padding: '28px 28px 44px', textAlign: 'center', color: '#fff', background: 'linear-gradient(135deg, #0f6fd6 0%, #1d9bf0 58%, #38bdf8 100%)' }, children: [
-            jsx('button', { type: 'button', onClick: () => setOpen(false), 'aria-label': '关闭', style: { position: 'absolute', top: 14, right: 16, width: 30, height: 30, border: 0, borderRadius: '50%', background: 'rgba(255,255,255,.18)', color: '#fff', fontSize: 20, lineHeight: 1, cursor: 'pointer' }, children: '×' }),
+            // zIndex 必须显式给：标题那两行是**整行宽的块级元素**，盒子右端一直伸到按钮
+            // 下方，而它们在 DOM 里排在按钮之后（后绘制者在上），会抢走按钮中下部的点击
+            // ——表现为「上半能点、下半点不中」。定位元素给了 z-index 才稳定盖住它们。
+            jsx('button', { type: 'button', onClick: () => setOpen(false), 'aria-label': '关闭', style: { position: 'absolute', zIndex: 1, top: 14, right: 16, width: 30, height: 30, border: 0, borderRadius: '50%', background: 'rgba(255,255,255,.18)', color: '#fff', fontSize: 20, lineHeight: 1, cursor: 'pointer' }, children: '×' }),
             jsx('div', { style: { fontSize: 12, opacity: .82, letterSpacing: 1 }, children: 'WATERBUDDY' }),
             jsx('div', { style: { marginTop: 8, fontSize: 15, fontWeight: 600 }, children: 'WaterBuddy' }),
             jsx('div', { style: { position: 'absolute', left: '50%', bottom: -35, transform: 'translateX(-50%)', padding: 5, borderRadius: '50%', background: '#fff', boxShadow: '0 6px 18px rgba(15,23,42,.18)' }, children: jsx(UserAvatar, { user, size: 62 }) }),
@@ -565,7 +560,8 @@ window.__ModuleLoader__.load({
           }),
           open ? jsx('div', { style: { position: 'fixed', inset: 0, zIndex: 1000, background: 'rgba(15, 23, 42, .42)', backdropFilter: 'blur(5px)', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }, onClick: event => { if (event.target === event.currentTarget) setOpen(false) }, children: jsx('div', { style: { width: 420, maxWidth: 'calc(100vw - 32px)', borderRadius: 22, background: '#fff', overflow: 'hidden', boxShadow: '0 24px 80px rgba(15,23,42,.28)' }, children: user ? userPanel() : jsxs('div', { children: [
             jsxs('div', { style: { position: 'relative', padding: '22px 26px 0', textAlign: 'center' }, children: [
-              jsx('button', { type: 'button', onClick: () => setOpen(false), 'aria-label': '关闭', style: { position: 'absolute', top: 14, right: 16, width: 30, height: 30, border: 0, borderRadius: '50%', background: '#f1f5f9', color: '#64748b', fontSize: 20, lineHeight: 1, cursor: 'pointer' }, children: '×' }),
+              // 与已登录面板同一个坑：标题/说明是整行宽的块级元素，必须靠 z-index 让按钮稳定在上。
+              jsx('button', { type: 'button', onClick: () => setOpen(false), 'aria-label': '关闭', style: { position: 'absolute', zIndex: 1, top: 14, right: 16, width: 30, height: 30, border: 0, borderRadius: '50%', background: '#f1f5f9', color: '#64748b', fontSize: 20, lineHeight: 1, cursor: 'pointer' }, children: '×' }),
               jsx('img', { src: SSO.image, alt: SSO.title, style: { display: 'block', width: 52, height: 52, objectFit: 'contain', margin: '0 auto' } }),
               jsx('h3', { style: { margin: '10px 0 4px', color: '#162033', fontSize: 21 }, children: 'WaterBuddy' }),
               jsx('p', { style: { margin: 0, color: '#7b8799', fontSize: 12.5 }, children: '登录后同步水务之窗账号与知识库权限' }),
@@ -584,7 +580,905 @@ window.__ModuleLoader__.load({
       return null
     }
 
-    const inject = ['slots']
+    /**
+     * 写剪贴板。
+     *
+     * `navigator.clipboard` 只在安全上下文可用，而且在内嵌 webview 里可能被权限策略挡掉；
+     * 这里落到 `execCommand('copy')` 兜底（已废弃，但仍是 webview 里最可靠的一条路）。
+     * @param text - 要复制的内容。
+     * @throws 两条路都不通时抛出，由调用方提示用户。
+     */
+    async function writeClipboard(text) {
+      if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+        try {
+          await navigator.clipboard.writeText(text)
+          return
+        } catch { /* 落到下面的兜底 */ }
+      }
+      // 兜底：WebKit 对"完全不可见"的 textarea 常常拒绝复制，所以留 1px 与极小透明度，
+      // 并且必须 focus + select 之后再 execCommand。整段仍是同步的，手势不会丢。
+      const area = document.createElement('textarea')
+      area.value = text
+      area.setAttribute('readonly', '')
+      area.style.position = 'fixed'
+      area.style.top = '0'
+      area.style.left = '0'
+      area.style.width = '1px'
+      area.style.height = '1px'
+      area.style.padding = '0'
+      area.style.border = '0'
+      area.style.opacity = '0.01'
+      document.body.append(area)
+      area.focus()
+      area.select()
+      const ok = typeof document.execCommand === 'function' && document.execCommand('copy')
+      area.remove()
+      if (!ok) throw new Error('clipboard-unavailable')
+    }
+
+    /**
+     * 新会话 hero 的品牌标记：用我们左上角那个 mark，替换宿主默认的鸟形图标。
+     * slot 的 owner props 会给 `size`（正方形边长），照它渲染即可。
+     */
+    function WaterBuddyHeroMark({ size }) {
+      const edge = typeof size === 'number' && size > 0 ? size : 24
+      // 与侧边栏左上角同一个 mark（模块级 data URI）。之前这里写的是
+      // `/waterplus-mark.png`，该路径在 hero 里取不到，渲染成了黑方块。
+      return jsx('img', {
+        src: mark,
+        alt: 'WaterBuddy',
+        width: edge,
+        height: edge,
+        style: { width: edge, height: edge, objectFit: 'contain', borderRadius: '22%' },
+      })
+    }
+
+    // ── locales.js ──────────────────────────────────────────────────────────
+
+    /** 专家页的样式常量：与插件其它界面一致，全部内联，不引入样式表。 */
+    const EXPERT_STYLE = {
+      card: { border: '1px solid #e6ecf5', borderRadius: 14, background: '#fff', padding: '14px 16px', display: 'flex', flexDirection: 'column', gap: 8 },
+      field: { height: 34, padding: '0 10px', border: '1px solid #dbe3ee', borderRadius: 9, background: '#fff', color: '#162033', fontSize: 13 },
+      primary: { height: 34, padding: '0 16px', border: 0, borderRadius: 9, background: '#2f6fed', color: '#fff', fontSize: 13, fontWeight: 600, cursor: 'pointer' },
+      ghost: { height: 32, padding: '0 12px', border: '1px solid #dbe3ee', borderRadius: 9, background: '#fff', color: '#334155', fontSize: 12.5, cursor: 'pointer' },
+      tab: active => ({ height: 32, padding: '0 14px', border: '1px solid ' + (active ? '#2f6fed' : '#dbe3ee'), borderRadius: 9, background: active ? '#eef4ff' : '#fff', color: active ? '#2f6fed' : '#475569', fontSize: 13, fontWeight: active ? 600 : 400, cursor: 'pointer' }),
+      label: { color: '#8a94a6', fontSize: 12, marginBottom: 6 },
+      overlay: { position: 'fixed', inset: 0, zIndex: 40, background: 'rgba(15,23,42,.42)', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 24 },
+      modal: { width: 'min(720px, 100%)', maxHeight: '80vh', borderRadius: 16, background: '#fff', display: 'flex', flexDirection: 'column', overflow: 'hidden' },
+      modalHead: { padding: '14px 18px', borderBottom: '1px solid #eef2f8', display: 'flex', alignItems: 'center', gap: 10 },
+      modalBody: { padding: '14px 18px', overflowY: 'auto' },
+      modalFoot: { padding: '12px 18px', borderTop: '1px solid #eef2f8', display: 'flex', justifyContent: 'flex-end', gap: 8 },
+      pre: { margin: 0, color: '#334155', fontSize: 12.5, lineHeight: 1.7, whiteSpace: 'pre-wrap', wordBreak: 'break-word', fontFamily: 'inherit' },
+    }
+
+    // ── catalog.js ───────────────────────────────────────────────────
+
+    /** 触发器源 id：引用 chip 的 `source` 必须与注册过的源一致，否则宿主无法把 chip 归属到我们。 */
+    const EXPERT_SOURCE_ID = division => 'waterbuddy-experts:' + division
+
+    /** 把专家投影成宿主的原生引用（chip）。slug 只作内部 ref，不进标签、不进剪贴板。 */
+    function buildExpertReference(expert) {
+      return {
+        source: EXPERT_SOURCE_ID(expert.division),
+        ref: expert.slug,
+        label: expert.name,
+        // 新版宿主渲染成内置代理图标；旧宿主忽略该字段并保留默认标记。
+        appearance: 'session',
+        clipboardText: '@' + expert.name + ' ',
+      }
+    }
+
+    /**
+     * 取当前会话的输入机，用来写原生引用。
+     *
+     * 与参考实现同一条路径：`sessions.scope(id)` → `conversation.input.for(actx)`。
+     * 宿主没给这些服务时返回 undefined，调用方回落到纯文本插入。
+     */
+    function resolveExpertInputTarget(ctx, sessionId) {
+      if (typeof ctx.get !== 'function') return undefined
+      try {
+        const sessions = ctx.get('sessions')
+        const current = sessionId ?? sessions?.list?.getSnapshot?.().current
+        if (current === undefined) return undefined
+        const actx = sessions.scope?.(current) ?? sessions.binding?.(current)?.ctx
+        if (actx === undefined) return undefined
+        return ctx.get('conversation')?.input?.for?.(actx)
+      } catch {
+        return undefined
+      }
+    }
+
+    /**
+     * 草稿里已有 chip 时，新 chip 要追加在它们之后。
+     *
+     * 宿主公开的 `draft` 是剪贴板文本（每个引用只占一个字符），所以坐标不能直接用
+     * `draft.length`；这里按参考实现把引用压缩成 \uFFFC 后再数前缀。
+     */
+    function expertInsertionSpan(target) {
+      const snapshot = target.state.getSnapshot()
+      let text = snapshot.draft
+      for (const occurrence of [...(snapshot.occurrences ?? [])].sort((a, b) => b.offset - a.offset)) {
+        const length = occurrence.length ?? 1
+        if (occurrence.offset < 0 || length < 1 || occurrence.offset + length > text.length) continue
+        text = text.slice(0, occurrence.offset) + '\uFFFC' + text.slice(occurrence.offset + length)
+      }
+      let end = 0
+      while (text[end] === '\uFFFC') {
+        end += 1
+        if (/\s/u.test(text[end] ?? '') && text[end] !== '\n') end += 1
+      }
+      return { start: end, end, draftRev: snapshot.draftRev, detectText: text }
+    }
+
+    /** 插入专家引用 chip（坐标由 {@link expertInsertionSpan} 算出）；返回是否成功。 */
+    function insertExpertReference(target, reference) {
+      try {
+        return target.insertReference(reference, expertInsertionSpan(target)) === true
+      } catch {
+        return false
+      }
+    }
+
+    /** 草稿正文（去掉 chip）是否为空——只有在用户还没写正文时才补任务示例。 */
+    function expertDraftBodyIsEmpty(target) {
+      try {
+        const span = expertInsertionSpan(target)
+        const text = span.detectText || ''
+        return (text.slice(0, span.start) + text.slice(span.end)).replace(/\uFFFC/gu, '').trim() === ''
+      } catch {
+        return false
+      }
+    }
+
+    /**
+     * 在 chip 之后补一段任务示例。
+     *
+     * 用 `insertText`：它存在于输入 facade 上但没有写进公开契约（参考实现同样靠 `insertText?` 兜底）。
+     * 宿主没有这个方法就安静跳过——补示例只是省事，不该因此报错。
+     */
+    function appendExpertTaskExample(target, expert) {
+      const example = expertTaskExample(expert)
+      if (!example || typeof target.insertText !== 'function') return false
+      try {
+        const snapshot = target.state.getSnapshot()
+        const at = String(snapshot.draft || '').length
+        return target.insertText('\n\n' + example, { start: at, end: at, draftRev: snapshot.draftRev }) === true
+      } catch {
+        return false
+      }
+    }
+
+    /** 名册读取（`@` 菜单与工具栏共用）。每次现读，用户一改开关立刻生效。 */
+    async function loadExpertRoster() {
+      const response = await fetch('/api/waterbuddy/experts')
+      const payload = await response.json()
+      if (!response.ok) throw new Error(payload.error || 'load-failed')
+      return { experts: payload.experts || [], divisions: payload.divisions || [] }
+    }
+
+    /** `@` 菜单的最近一次启用快照：`lexicon` / `codec.clipboardText` 是同步接口，只能读缓存。 */
+    let expertMentionCache = []
+
+    /** chip 的剪贴板投影：参考实现用的是 `@名字 `。 */
+    function expertMentionText(slug) {
+      const expert = expertMentionCache.find(item => item.slug === slug)
+      return expert ? '@' + expert.name + ' ' : '@' + String(slug) + ' '
+    }
+
+    /**
+     * 分类 / 状态 / 搜索三个筛选控件。
+     *
+     * 纯展示：状态由 `ExpertRoster` 持有，这里只回调上去（与参考实现的 category-select 对应）。
+     */
+    function ExpertCategoryFilters({ divisions, total, division, status, query, onDivision, onStatus, onQuery }) {
+    return jsxs('div', { style: { display: 'flex', gap: 10, flexWrap: 'wrap', alignItems: 'flex-end', margin: '16px 0' }, children: [
+      jsxs('div', { style: { display: 'grid' }, children: [
+        jsx('span', { style: EXPERT_STYLE.label, children: '分类' }),
+        jsxs('select', {
+          value: division,
+          onChange: event => onDivision(event.target.value),
+          style: { ...EXPERT_STYLE.field, minWidth: 190 },
+          children: [
+            jsx('option', { value: 'all', children: '全部（' + total + '）' }),
+            divisions.map(item => jsx('option', { value: item.slug, children: item.name + '（' + item.count + '）' }, item.slug)),
+          ],
+        }),
+      ] }),
+      jsxs('div', { style: { display: 'grid' }, children: [
+        jsx('span', { style: EXPERT_STYLE.label, children: '状态' }),
+        jsxs('select', {
+          value: status,
+          onChange: event => onStatus(event.target.value),
+          style: { ...EXPERT_STYLE.field, minWidth: 140 },
+          children: [
+            jsx('option', { value: 'all', children: '全部状态' }),
+            jsx('option', { value: 'enabled', children: '已启用' }),
+            jsx('option', { value: 'disabled', children: '已停用' }),
+          ],
+        }),
+      ] }),
+      jsxs('div', { style: { display: 'grid', flex: 1, minWidth: 220 }, children: [
+        jsx('span', { style: EXPERT_STYLE.label, children: '搜索' }),
+        jsx('input', {
+          name: 'expert-search',
+          value: query,
+          placeholder: '搜索专家、职责或分类',
+          onChange: event => onQuery(event.target.value),
+          style: { ...EXPERT_STYLE.field, width: '100%' },
+        }),
+      ] }),
+    ] })
+    }
+
+    /**
+     * 任务示例：插好专家 chip 之后，如果用户还没写正文，就补一句"该交代什么"。
+     *
+     * 按**分类**给（参考实现是按专家逐条人工维护，我们先用分类级，够用且好维护）。
+     * 它只用来帮用户把需求说清楚，**不代表给专家额外授权**——不要在这里写具体结论或口径。
+     *
+     * 生效条件：宿主必须让 `conversation.input.for(actx)` 暴露 `insertText`。**0.1.6-alpha.1 上它没有**
+     * ——公开契约 `SessionInput` 只有 `beginCommand` / `insertReference` / `setDraft` 等，
+     * `insertText` 属于内部 `InputFacade`。所以当前版本插完 chip 不会补示例（实测确认），
+     * 代码保留为前向兼容：宿主哪天暴露了，这段就自动生效，不需要再改调用方。
+     */
+    const EXPERT_TASK_EXAMPLES = {
+      supply: '先说明对象与现状（哪座厂/哪段管网、规模、已掌握的数据），再给排查或处置步骤、判断依据，以及哪些结论需要实测数据才能确认。',
+      drainage: '先说明管网类型、管龄与已有记录，再给排查范围与方法、判定标准，并区分"日常养护 / 小修 / 改造"。',
+      quality: '先说明水源与工艺、异常指标与出现时间，再给判定依据、处置步骤与观察指标；涉及健康风险请明确上报路径。',
+      digital: '先说明业务目标、现有系统与数据来源，再给方案对比（成本 / 风险 / 改动范围），并指出数据由谁维护。',
+      policy: '先说明地域与适用层级，再给条文依据与对照结论；记不准的条款请标出需核对原文。',
+    }
+
+    /** 取某位专家的任务示例；没有对应示例时返回 undefined（不补，保持草稿干净）。 */
+    function expertTaskExample(expert) {
+      return EXPERT_TASK_EXAMPLES[expert && expert.division]
+    }
+
+    // ── expert-discovery.js ──────────────────────────────────────────
+
+    /**
+     * 输入框左侧的专家入口。
+     *
+     * 选中后写入的是**宿主原生引用 chip**，不是纯文本：chip 是原子的、可整体删除、由宿主
+     * 正确序列化——就是内置 `@` 提及的行为。写入走 slot `inject` 注入的 `insertExpert`；
+     * 拿不到输入机时回落到把召唤指令写进草稿，绝不静默什么都不做。
+     */
+    /** 专家菜单宽度；横向夹取与菜单本体共用同一个值。 */
+    const MENU_WIDTH = 320
+
+    function ExpertInputEntry(props) {
+      if (props && typeof props.insertExpert === 'function') return ExpertInputButton(props)
+      if (props && props.inputActions && typeof props.inputActions.setDraft === 'function') {
+        return ExpertInputButton({ ...props, insertExpert: undefined })
+      }
+      // 两条路都不通就整体不渲染：附加控件不能把输入区搞崩。
+      return null
+    }
+
+    /** 真正的按钮：读草稿、拉启用中的专家、写入引用（或回落召唤指令）。 */
+    function ExpertInputButton({ inputActions, insertExpert, useInput }) {
+      const { useEffect, useRef, useState } = require('react')
+      // 只有拿到 useInput 才当作 hook 用；拿不到就用普通函数，钩子顺序因此稳定。
+      const readDraft = typeof useInput === 'function' ? useInput : () => undefined
+      const draft = readDraft(state => (state && state.draft) || '') || ''
+      const [open, setOpen] = useState(false)
+      const rootRef = useRef(null)
+      // 菜单最大高度按**按钮上方的可用空间**算（参考实现的 resolveExpertMenuPosition 同法）：
+      // 固定写 320 会让 10 位专家的分组列表必然出现滚动条。
+      const [menuMaxHeight, setMenuMaxHeight] = useState(360)
+      // 菜单相对按钮的横向偏移。固定 left:0 会让靠右的按钮把菜单顶出视口，整页出现横向滚动条；
+      // 参考实现按视口夹取，这里照做。
+      const [menuLeft, setMenuLeft] = useState(0)
+      const [experts, setExperts] = useState(null)
+      const [query, setQuery] = useState('')
+      const [notice, setNotice] = useState('')
+
+      useEffect(() => {
+        if (!open) return undefined
+        const root = rootRef.current
+        if (!root || typeof root.getBoundingClientRect !== 'function') return undefined
+        const rect = root.getBoundingClientRect()
+        const viewportHeight = (typeof window !== 'undefined' && window.innerHeight) || 800
+        const viewportWidth = (typeof window !== 'undefined' && window.innerWidth) || 1200
+        // 高度够用即可：既不占满整屏（占满像"弹了个页面"），也不至于只露三项。
+        const space = Math.floor(rect.top - 4 - 12)
+        setMenuMaxHeight(Math.max(200, Math.min(space, Math.min(420, Math.floor(viewportHeight * 0.55)))))
+        // 横向夹取：与参考实现同一算式，保证菜单左右都不越出视口（12px 内边距）。
+        setMenuLeft(Math.max(12 - rect.left, Math.min(0, viewportWidth - 12 - MENU_WIDTH - rect.left)))
+        return undefined
+      }, [open])
+
+      useEffect(() => {
+        // 点击/触摸到菜单与按钮之外就收起（参考实现监听的是 document 的 pointerdown）。
+        // 测试替身没有 document.addEventListener，所以先探测再用。
+        if (!open || typeof document === 'undefined' || typeof document.addEventListener !== 'function') {
+          return undefined
+        }
+        const onPointerDown = event => {
+          const target = event && event.target
+          const root = rootRef.current
+          if (root && target && typeof root.contains === 'function' && root.contains(target)) return
+          setOpen(false)
+        }
+        document.addEventListener('pointerdown', onPointerDown)
+        return () => document.removeEventListener('pointerdown', onPointerDown)
+      }, [open])
+
+      useEffect(() => {
+        // 名册只在第一次展开时拉，而且只保留启用中的专家——停用的召唤了也会被拒。
+        if (!open || experts !== null) return undefined
+        let cancelled = false
+        fetch('/api/waterbuddy/experts')
+          .then(async response => {
+            const payload = await response.json()
+            if (!response.ok) throw new Error(payload.error || 'load-failed')
+            return payload
+          })
+          .then(payload => { if (!cancelled) setExperts((payload.experts || []).filter(expert => expert.enabled)) })
+          .catch(() => { if (!cancelled) setExperts([]) })
+        return () => { cancelled = true }
+      }, [open])
+
+      const pick = expert => {
+        if (typeof insertExpert === 'function' && insertExpert(buildExpertReference(expert), expert) === true) {
+          setNotice('')
+          setOpen(false)
+          setQuery('')
+          return
+        }
+        // 兜底：引用写不进去时至少把意图留下。
+        if (inputActions && typeof inputActions.setDraft === 'function') {
+          const instruction = '召唤「' + expert.name + '」完成：'
+          inputActions.setDraft(draft.trim() ? draft.replace(/\s+$/, '') + '\n' + instruction : instruction)
+          setOpen(false)
+          setQuery('')
+          return
+        }
+        setNotice('无法写入输入框')
+      }
+
+      const needle = query.trim().toLowerCase()
+      const shown = (experts || []).filter(expert => !needle
+        || expert.name.toLowerCase().includes(needle)
+        || expert.description.toLowerCase().includes(needle)
+        || String(expert.divisionName || '').toLowerCase().includes(needle))
+      // 按分类分组渲染（与参考实现的菜单一致）：模型侧的分区就是这里的分组。
+      const grouped = []
+      for (const expert of shown) {
+        const last = grouped[grouped.length - 1]
+        if (last && last.slug === expert.division) last.experts.push(expert)
+        else grouped.push({ slug: expert.division, name: expert.divisionName || expert.division, experts: [expert] })
+      }
+
+      return jsxs('div', { ref: rootRef, style: { position: 'relative' }, children: [
+        jsx('button', {
+          type: 'button',
+          'aria-label': '召唤专家',
+          'aria-expanded': open,
+          onClick: () => setOpen(value => !value),
+          style: {
+            display: 'flex', alignItems: 'center', gap: 6, height: 28, padding: '0 10px',
+            border: '1px solid ' + (open ? '#2f6fed' : '#dbe3ee'), borderRadius: 8,
+            background: open ? '#eef4ff' : '#fff', color: open ? '#2f6fed' : '#475569',
+            fontSize: 12.5, cursor: 'pointer',
+          },
+          children: [
+            // 用户提供的图标：人形 + 右上角星芒（1024 视图、面性填充）。
+            // 原样内联其 path，不改几何；fill 用 currentColor 以跟随主题与悬停色。
+            jsx('svg', {
+              viewBox: '0 0 1024 1024',
+              width: 15,
+              height: 15,
+              fill: 'currentColor',
+              'aria-hidden': true,
+              children: jsx('path', {
+                d: 'M770.08 96.32c1.728 0.64 3.072 1.984 3.712 3.712l38.848 107.584c0.64 1.728 1.984 3.104 3.712 3.712l107.584 38.848a6.144 6.144 0 0 1 0 11.584l-107.584 38.848a6.144 6.144 0 0 0-3.712 3.712l-38.848 107.584a6.144 6.144 0 0 1-11.584 0L723.36 304.32a6.144 6.144 0 0 0-3.712-3.712L612.064 261.76a6.144 6.144 0 0 1 0-11.584l107.584-38.848a6.144 6.144 0 0 0 3.712-3.712l38.848-107.584c1.184-3.2 4.704-4.8 7.872-3.68zM576 160h-192Q264.704 160 180.352 244.352 96 328.704 96 448v192q0 119.296 84.352 203.648Q264.704 928 384 928h256q119.296 0 203.648-84.352Q928 759.296 928 640v-128h-64v128q0 92.8-65.6 158.4Q732.8 864 640 864h-256q-92.8 0-158.4-65.6Q160 732.8 160 640v-192q0-92.8 65.6-158.4Q291.2 224 384 224h192V160z m96 248.224L568.224 512 672 615.776l45.248-45.28L658.752 512l58.496-58.496L672 408.224zM320 608v-160h64v160h-64z',
+              }),
+            }),
+            jsx('span', { children: '召唤专家' }),
+          ],
+        }),
+        open ? jsxs('div', {
+          style: {
+            // boxSizing: border-box 让 `width` 就是实宽——夹取算式按 MENU_WIDTH 计算，两者必须一致，
+            // 否则在窄窗口下菜单仍会比算式宽出一圈内边距并与视口打架。
+            boxSizing: 'border-box',
+            position: 'absolute', bottom: 34, left: menuLeft, zIndex: 30, width: MENU_WIDTH, maxHeight: menuMaxHeight,
+            overflowY: 'auto', padding: 8, border: '1px solid #e2e8f0', borderRadius: 12,
+            background: '#fff', boxShadow: '0 12px 32px rgba(15,23,42,.16)', overflowX: 'hidden',
+          },
+          children: [
+            jsx('input', {
+              name: 'expert-input-search',
+              value: query,
+              placeholder: '搜索名称、领域或关键词',
+              onChange: event => setQuery(event.target.value),
+              style: { boxSizing: 'border-box', width: '100%', height: 30, padding: '0 8px', marginBottom: 8, border: '1px solid #dbe3ee', borderRadius: 8, fontSize: 12.5 },
+            }),
+            notice ? jsx('div', { style: { padding: '4px 6px', color: '#b91c1c', fontSize: 11.5 }, children: notice }) : null,
+            experts === null
+              ? jsx('div', { style: { padding: '10px 6px', color: '#94a3b8', fontSize: 12.5 }, children: '正在加载…' })
+              : shown.length === 0
+                ? jsx('div', { style: { padding: '10px 6px', color: '#94a3b8', fontSize: 12.5 }, children: experts.length === 0 ? '没有启用中的专家' : '没有匹配的专家' })
+                : grouped.map(group => jsxs('div', { key: group.slug, children: [
+                  jsx('div', { style: { padding: '6px 8px 4px', color: '#94a3b8', fontSize: 11 }, children: group.name }),
+                  group.experts.map(expert => jsxs('button', {
+                    type: 'button',
+                    key: expert.slug,
+                    onClick: () => pick(expert),
+                    style: { boxSizing: 'border-box', display: 'flex', alignItems: 'flex-start', gap: 8, width: '100%', padding: '7px 8px', border: 0, borderRadius: 8, background: 'transparent', textAlign: 'left', cursor: 'pointer' },
+                    children: [
+                      expert.avatar
+                      ? jsx('img', { src: expert.avatar, alt: '', style: { width: 24, height: 24, borderRadius: '50%', objectFit: 'cover', flexShrink: 0 } })
+                      : jsx('span', { style: { fontSize: 16, lineHeight: '18px' }, children: expert.emoji || '🧠' }),
+                      jsxs('span', { style: { minWidth: 0, display: 'grid', gap: 2 }, children: [
+                        jsx('strong', { style: { color: '#162033', fontSize: 12.5 }, children: expert.name }),
+                        jsx('small', { style: { color: '#8a94a6', fontSize: 11.5, lineHeight: 1.5 }, children: expert.description }),
+                      ] }),
+                    ],
+                  }, expert.slug)),
+                ] })),
+          ],
+        }) : null,
+      ] })
+    }
+
+    /**
+     * 一个分类的 `@` 触发器源。
+     *
+     * 与参考实现一致：候选只给该分类里**启用中**的专家；选中后插入的是同一个原生引用
+     * chip（所以打字 `@` 和点工具栏按钮得到的 token 完全一样）。`codec` 是宿主用来把
+     * chip 序列化给模型的：提交时逐引用调用，失败会挡住发送，不会静默降级成剪贴板文本。
+     */
+    function createExpertTriggerSource(ctx, division, index) {
+      const inDivision = () => expertMentionCache.filter(expert => expert.division === division.slug)
+      return {
+        trigger: '@',
+        name: EXPERT_SOURCE_ID(division.slug),
+        order: 100 + index,
+        showGroupTitle: false,
+        async candidates(_session, request) {
+          const { experts } = await loadExpertRoster()
+          expertMentionCache = experts.filter(expert => expert.enabled)
+          const needle = String((request && request.query) || '').toLowerCase()
+          return inDivision()
+            .filter(expert => !needle
+              || expert.name.toLowerCase().includes(needle)
+              || expert.description.toLowerCase().includes(needle))
+            .map(expert => ({
+              name: expert.name,
+              hint: expert.slug,
+              section: division.name,
+              // 有头像就用头像当菜单行图标（宿主允许候选带 icon 组件）；
+              // 注意：**插入后的 chip 用不了图片** —— ReferenceInsert.appearance 只认
+              // 'session' | 'file' | 'folder' 三个内置字形，那里是宿主的限制。
+              ...(expert.avatar
+                ? { icon: () => jsx('img', { src: expert.avatar, alt: '', style: { width: 16, height: 16, borderRadius: '50%', objectFit: 'cover' } }) }
+                : {}),
+            }))
+        },
+        onPick(pick) {
+          const slug = (pick && pick.candidate && pick.candidate.hint) || ''
+          const expert = expertMentionCache.find(item => item.slug === slug)
+          if (expert === undefined) return undefined
+          const reference = buildExpertReference(expert)
+          const sessionId = pick && pick.session ? pick.session.sessionId : undefined
+          const target = resolveExpertInputTarget(ctx, sessionId)
+          // 拿不到输入机时把引用交给管线自己插（参考实现同样这样回落）。
+          if (target === undefined) return { insert: reference }
+          try {
+            if (target.insertReference(reference, (pick && pick.span) || expertInsertionSpan(target)) !== true) {
+              return undefined
+            }
+            appendExpertTaskExample(target, expert)
+            return 'handled'
+          } catch {
+            return undefined
+          }
+        },
+        /**
+         * 点击历史/草稿里的 chip 时，宿主会逐个源问「这次预览你要不要接管」。
+         * 没有源接受，它就回落到**默认手势：按文件路径打开文档预览** —— 于是把专家名当路径
+         * 去 realpath，报 `ENOENT: …/智慧水务案例专家` 并在右侧弹出一个报错面板。
+         * 这里返回 true 表示我们接管这次手势（不做别的事），把那个回落挡住。
+         */
+        openReference() {
+          return true
+        },
+        lexicon: () => inDivision().map(expert => expert.name),
+        subscribeLexicon: () => () => {},
+        codec: {
+          clipboardText: expertMentionText,
+          async serialize(slug) {
+            const { experts } = await loadExpertRoster()
+            const expert = experts.find(item => item.slug === slug && item.enabled)
+            if (expert === undefined) throw new Error('专家不可用')
+            return '@' + expert.name + ' '
+          },
+        },
+      }
+    }
+
+    /**
+     * 提示词弹窗（只读）。
+     *
+     * 是**真组件**（由 `jsx(ExpertPromptDialog, ...)` 渲染），不是普通函数调用：
+     * 直接函数调用会把它的 hook 并进父组件的 hook 序列，弹窗一开一关就改变 hook 数量，
+     * React 会抛 "Rendered more hooks than during the previous render"。
+     */
+    function ExpertPromptDialog({ dialog, onClose }) {
+      return jsx('div', { style: EXPERT_STYLE.overlay, onClick: event => { if (event.target === event.currentTarget) onClose() }, children:
+        jsxs('div', { style: EXPERT_STYLE.modal, children: [
+          jsxs('div', { style: EXPERT_STYLE.modalHead, children: [
+            jsx('strong', { style: { color: '#0f172a', fontSize: 14 }, children: dialog.expert.name }),
+            jsx('span', { style: { color: '#94a3b8', fontSize: 11.5 }, children: dialog.expert.slug }),
+            jsx('button', { type: 'button', onClick: onClose, style: { ...EXPERT_STYLE.ghost, marginLeft: 'auto' }, children: '关闭' }),
+          ] }),
+          jsx('div', { style: EXPERT_STYLE.modalBody, children:
+            dialog.loading
+              ? jsx('span', { style: { color: '#7b8799', fontSize: 12.5 }, children: '正在加载提示词…' })
+              : jsx('pre', { style: EXPERT_STYLE.pre, children: dialog.body }) }),
+          jsxs('div', { style: EXPERT_STYLE.modalFoot, children: [
+            jsx('button', {
+              type: 'button',
+              onClick: () => { void writeClipboard(dialog.body || '').catch(() => onClose()) },
+              style: EXPERT_STYLE.ghost,
+              children: '复制提示词',
+            }),
+          ] }),
+        ] }) })
+    }
+
+    /**
+     * 自定义专家编辑器（新建 / 编辑）。
+     *
+     * **刻意不用 hook**：表单草稿由 `ExpertRoster` 持有（`form` + `onField`）。
+     * 弹窗若自己 `useState`，它就会被并进父组件的 hook 序列，弹窗一开一关改变 hook 数量，
+     * React 会抛 "Rendered more hooks than during the previous render"。
+     */
+    function ExpertCustomEditor({ dialog, divisions, busy, form, onField, onSave, onDelete, onClose }) {
+      return jsx('div', { style: EXPERT_STYLE.overlay, onClick: event => { if (event.target === event.currentTarget) onClose() }, children:
+        jsxs('div', { style: EXPERT_STYLE.modal, children: [
+          jsxs('div', { style: EXPERT_STYLE.modalHead, children: [
+            jsx('strong', { style: { color: '#0f172a', fontSize: 14 }, children: dialog.mode === 'create' ? '新建专家' : '编辑专家' }),
+            jsx('span', { style: { color: '#94a3b8', fontSize: 11.5 }, children: '' }),
+            jsx('button', { type: 'button', onClick: onClose, style: { ...EXPERT_STYLE.ghost, marginLeft: 'auto' }, children: '关闭' }),
+          ] }),
+          jsx('div', { style: EXPERT_STYLE.modalBody, children:
+            jsxs('div', { style: { display: 'grid', gap: 12 }, children: [
+              jsxs('div', { style: { display: 'grid', gridTemplateColumns: '80px 1fr 200px', gap: 10 }, children: [
+                jsxs('div', { style: { display: 'grid' }, children: [
+                  jsx('span', { style: EXPERT_STYLE.label, children: '图标' }),
+                  jsx('input', { name: 'expert-emoji', value: form.emoji, onChange: event => onField('emoji', event.target.value), style: EXPERT_STYLE.field }),
+                ] }),
+                jsxs('div', { style: { display: 'grid' }, children: [
+                  jsx('span', { style: EXPERT_STYLE.label, children: '名称' }),
+                  jsx('input', { name: 'expert-name', value: form.name, onChange: event => onField('name', event.target.value), style: EXPERT_STYLE.field }),
+                ] }),
+                jsxs('div', { style: { display: 'grid' }, children: [
+                  jsx('span', { style: EXPERT_STYLE.label, children: '分类' }),
+                  jsxs('select', { value: form.division, onChange: event => onField('division', event.target.value), style: EXPERT_STYLE.field, children:
+                    divisions.map(item => jsx('option', { value: item.slug, children: item.name }, item.slug)) }),
+                ] }),
+              ] }),
+              jsxs('div', { style: { display: 'grid' }, children: [
+                jsx('span', { style: EXPERT_STYLE.label, children: '头像图片地址（可留空，留空则用上面的图标）' }),
+                jsx('input', { name: 'expert-avatar', value: form.avatar || '', placeholder: 'https://…/avatar.png', onChange: event => onField('avatar', event.target.value), style: EXPERT_STYLE.field }),
+              ] }),
+              jsxs('div', { style: { display: 'grid' }, children: [
+                jsx('span', { style: EXPERT_STYLE.label, children: '职责描述（显示在卡片上）' }),
+                jsx('input', { name: 'expert-description', value: form.description, onChange: event => onField('description', event.target.value), style: EXPERT_STYLE.field }),
+              ] }),
+              jsxs('div', { style: { display: 'grid' }, children: [
+                jsx('span', { style: EXPERT_STYLE.label, children: '提示词正文（作为专家分身的系统提示词）' }),
+                jsx('textarea', {
+                  name: 'expert-prompt',
+                  value: form.prompt,
+                  onChange: event => onField('prompt', event.target.value),
+                  style: { ...EXPERT_STYLE.field, height: 260, padding: 10, lineHeight: 1.6, resize: 'vertical', fontFamily: 'inherit' },
+                }),
+              ] }),
+            ] }) }),
+          jsxs('div', { style: EXPERT_STYLE.modalFoot, children: [
+            dialog.mode === 'edit'
+              ? jsx('button', { type: 'button', disabled: busy, onClick: () => { void onDelete() }, style: { ...EXPERT_STYLE.ghost, marginRight: 'auto', color: '#b91c1c' }, children: '删除' })
+              : null,
+            jsx('button', { type: 'button', onClick: onClose, style: EXPERT_STYLE.ghost, children: '取消' }),
+            jsx('button', { type: 'button', disabled: busy, onClick: () => { void onSave() }, style: EXPERT_STYLE.primary, children: '保存' }),
+          ] }),
+        ] }) })
+    }
+
+    // ── roster.js ────────────────────────────────────────────────────
+
+    /** 正文缓存：`slug → persona 正文`。跨渲染存活，供"预取后同步写剪贴板"用。 */
+    const promptCache = new Map()
+
+    /** 取一位专家的 persona 正文（展示用原文）。 */
+    async function fetchExpertBody(slug) {
+      const response = await fetch('/api/waterbuddy/experts?slug=' + encodeURIComponent(slug))
+      const payload = await response.json()
+      if (!response.ok) throw new Error(payload.error || 'load-failed')
+      return payload.body || ''
+    }
+
+    /** 设置里的「专家」页：浏览、启用停用、以及管理自定义专家。
+     *
+     * 三件事刻意分开：
+     * - 名册快照只带元数据，**正文按需拉**（10 份 persona 动辄十几 KB，不能塞进首屏）；
+     * - 启用状态是**整体替换的白名单**并带修订号，两个窗口同时改时落后一方会被拒绝；
+     * - 停用只影响可召唤范围，不隐藏卡片——用户在设置里要能看到并重新打开它。
+     */
+    function ExpertRoster() {
+      const { useEffect, useState } = require('react')
+      const [snapshot, setSnapshot] = useState(null)
+      const [error, setError] = useState('')
+      const [busy, setBusy] = useState(false)
+      const [tab, setTab] = useState('all')
+      const [division, setDivision] = useState('all')
+      const [status, setStatus] = useState('all')
+      const [query, setQuery] = useState('')
+      const [dialog, setDialog] = useState(null)
+      // 弹窗的表单草稿由这里持有：弹窗自己不 use hook，才不会改变本组件的 hook 数量。
+      const [form, setForm] = useState(null)
+
+      const load = async () => {
+        try {
+          const response = await fetch('/api/waterbuddy/experts')
+          const payload = await response.json()
+          if (!response.ok) throw new Error(payload.error || 'load-failed')
+          setSnapshot(payload)
+          setError('')
+        } catch (err) {
+          setError(err.message)
+        }
+      }
+
+      useEffect(() => {
+        let cancelled = false
+        fetch('/api/waterbuddy/experts')
+          .then(async response => {
+            const payload = await response.json()
+            if (!response.ok) throw new Error(payload.error || 'load-failed')
+            return payload
+          })
+          .then(payload => { if (!cancelled) setSnapshot(payload) })
+          .catch(err => { if (!cancelled) setError(err.message) })
+        return () => { cancelled = true }
+      }, [])
+
+      /** 所有写操作共用：带上当前修订号，成功后用返回值刷新快照。 */
+      const mutate = async (path, payload) => {
+        setBusy(true)
+        try {
+          const response = await fetch(path, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ ...payload, expectedRevision: snapshot.revision }),
+          })
+          const body = await response.json()
+          if (!response.ok) throw new Error(body.error || 'save-failed')
+          setSnapshot(current => ({ ...current, ...body }))
+          setError('')
+          return true
+        } catch (err) {
+          setError(err.message)
+          // 修订号冲突（别的窗口刚改过）时主动重拉一次：让用户直接看到最新状态并重试，
+          // 而不是停在一份永远写不进去的陈旧快照上。
+          if (/REVISION_CONFLICT/.test(err.message)) await load()
+          return false
+        } finally {
+          setBusy(false)
+        }
+      }
+
+      const toggle = expert => {
+        const next = (snapshot.experts || [])
+          .filter(item => (item.slug === expert.slug ? !expert.enabled : item.enabled))
+          .map(item => item.slug)
+        return mutate('/api/waterbuddy/experts/enabled', { enabled: next })
+      }
+
+      const openPrompt = async expert => {
+        setDialog({ mode: 'view', expert, body: '', loading: true })
+        try {
+          const response = await fetch('/api/waterbuddy/experts?slug=' + encodeURIComponent(expert.slug))
+          const payload = await response.json()
+          if (!response.ok) throw new Error(payload.error || 'load-failed')
+          setDialog({ mode: 'view', expert, body: payload.body || '', loading: false })
+        } catch (err) {
+          setDialog(null)
+          setError(err.message)
+        }
+      }
+
+      /**
+       * 复制提示词。
+       *
+       * 关键在时序：WebKit（Tauri 用的就是它）要求剪贴板写入发生在**用户手势的同步调用栈**里，
+       * 先 `await fetch` 再写就会被拒（`NotAllowedError`），连 execCommand 兜底也一起失效——
+       * 这正是"复制提示词不起效果"的原因。所以：悬停/聚焦时先把正文预取进缓存，点击时
+       * 缓存命中就是同步发起写入，手势不丢；没命中才走异步路径（并在失败时提示再点一次）。
+       */
+      const copyPrompt = async expert => {
+        const cached = promptCache.get(expert.slug)
+        if (cached !== undefined) {
+          try {
+            await writeClipboard(cached)
+            setError('')
+          } catch (err) {
+            setError('复制失败：' + err.message)
+          }
+          return
+        }
+        try {
+          const body = await fetchExpertBody(expert.slug)
+          promptCache.set(expert.slug, body)
+          await writeClipboard(body)
+          setError('')
+        } catch (err) {
+          setError('复制失败：' + err.message + '（正文已缓存，再点一次即可）')
+        }
+      }
+
+      /** 悬停/聚焦时预取正文，让点击那一刻能同步写入剪贴板。 */
+      const prefetchPrompt = expert => {
+        if (promptCache.has(expert.slug)) return
+        void fetchExpertBody(expert.slug)
+          .then(body => { promptCache.set(expert.slug, body) })
+          .catch(() => {})
+      }
+
+      const experts = snapshot ? snapshot.experts || [] : []
+      const divisions = snapshot ? snapshot.divisions || [] : []
+
+      /** 打开新建/编辑弹窗：初始化表单草稿。 */
+      const openEditor = (mode, expert) => {
+        setForm({
+          slug: expert.slug || '',
+          name: expert.name || '',
+          description: expert.description || '',
+          division: expert.division || (divisions[0] ? divisions[0].slug : 'supply'),
+          emoji: expert.emoji || '🧠',
+          avatar: expert.avatar || '',
+          prompt: expert.prompt || '',
+        })
+        setDialog({ mode, expert })
+      }
+      const onField = (key, value) => setForm(current => ({ ...current, [key]: value }))
+      const needle = query.trim().toLowerCase()
+      const shown = experts.filter(expert => {
+        if (tab === 'custom' && !expert.custom) return false
+        if (tab === 'builtin' && expert.custom) return false
+        if (division !== 'all' && expert.division !== division) return false
+        if (status === 'enabled' && !expert.enabled) return false
+        if (status === 'disabled' && expert.enabled) return false
+        if (!needle) return true
+        return (
+          expert.name.toLowerCase().includes(needle)
+          || expert.description.toLowerCase().includes(needle)
+          || expert.slug.toLowerCase().includes(needle)
+          || expert.divisionName.toLowerCase().includes(needle)
+        )
+      })
+
+      if (snapshot === null && !error) {
+        return jsx('div', { style: { color: '#7b8799', fontSize: 13 }, children: '正在加载专家名册…' })
+      }
+
+      const header = jsxs('div', { style: { display: 'flex', alignItems: 'center', gap: 12, flexWrap: 'wrap', marginBottom: 4 }, children: [
+        jsx('h2', { style: { margin: 0, color: '#0f172a', fontSize: 19, fontWeight: 600 }, children: '专家' }),
+        jsx('span', { style: { padding: '2px 8px', borderRadius: 6, background: '#f1f5f9', color: '#64748b', fontSize: 11.5 }, children: 'v' + (snapshot && snapshot.version ? snapshot.version : '') }),
+        jsx('span', { style: { color: '#8a94a6', fontSize: 12.5 }, children: experts.length + ' 位专家 · 已启用 ' + (snapshot ? snapshot.enabledCount : 0) }),
+        jsxs('span', { style: { marginLeft: 'auto', display: 'flex', gap: 8 }, children: [
+          jsx('button', {
+            type: 'button',
+            disabled: busy || snapshot?.settingsAvailable === false,
+            onClick: () => openEditor('create', {}),
+            style: EXPERT_STYLE.primary,
+            children: '新建专家',
+          }),
+          jsx('button', { type: 'button', onClick: () => { void load() }, style: EXPERT_STYLE.ghost, children: '刷新' }),
+        ] }),
+      ] })
+
+      const filters = ExpertCategoryFilters({
+        divisions,
+        total: experts.length,
+        division,
+        status,
+        query,
+        onDivision: setDivision,
+        onStatus: setStatus,
+        onQuery: setQuery,
+      })
+
+      const card = expert => jsxs('div', { style: EXPERT_STYLE.card, children: [
+        jsxs('div', { style: { display: 'flex', alignItems: 'flex-start', gap: 10 }, children: [
+          expert.avatar
+            ? jsx('img', { src: expert.avatar, alt: '', style: { width: 32, height: 32, borderRadius: '50%', objectFit: 'cover', flexShrink: 0 } })
+            : jsx('span', { style: { fontSize: 22, lineHeight: '24px' }, children: expert.emoji || '🧠' }),
+          jsxs('div', { style: { minWidth: 0, display: 'grid', gap: 3, flex: 1 }, children: [
+            jsxs('div', { style: { display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }, children: [
+              jsx('strong', { style: { color: '#0f172a', fontSize: 13.5 }, children: expert.name }),
+              jsx('span', { style: { padding: '1px 7px', borderRadius: 6, background: expert.custom ? '#fef3c7' : '#eef2f8', color: expert.custom ? '#92400e' : '#64748b', fontSize: 11 }, children: expert.custom ? '自定义' : '内置' }),
+              jsx('span', { style: { color: '#94a3b8', fontSize: 11.5 }, children: expert.divisionName }),
+            ] }),
+            jsx('span', { style: { color: '#7b8799', fontSize: 12, lineHeight: 1.6 }, children: expert.description }),
+          ] }),
+          jsx('button', {
+            type: 'button',
+            'aria-label': (expert.enabled ? '停用 ' : '启用 ') + expert.name,
+            'aria-pressed': expert.enabled,
+            disabled: busy,
+            onClick: () => { void toggle(expert) },
+            style: { flexShrink: 0, width: 42, height: 24, padding: 0, border: 0, borderRadius: 12, background: expert.enabled ? '#22c55e' : '#cbd5e1', cursor: 'pointer', position: 'relative' },
+            children: jsx('span', { style: { position: 'absolute', top: 3, left: expert.enabled ? 21 : 3, width: 18, height: 18, borderRadius: '50%', background: '#fff', transition: 'left .15s' } }),
+          }),
+        ] }),
+        jsxs('div', { style: { display: 'flex', gap: 8, borderTop: '1px solid #eef2f8', paddingTop: 10, marginTop: 'auto' }, children: [
+          jsx('button', { type: 'button', onClick: () => { void openPrompt(expert) }, style: EXPERT_STYLE.ghost, children: '查看提示词' }),
+          jsx('button', {
+            type: 'button',
+            onClick: () => { void copyPrompt(expert) },
+            // 悬停/聚焦就预取：点击时缓存已就绪，剪贴板写入能落在手势的同步栈里。
+            onMouseEnter: () => prefetchPrompt(expert),
+            onFocus: () => prefetchPrompt(expert),
+            style: EXPERT_STYLE.ghost,
+            children: '复制提示词',
+          }),
+          expert.custom
+            ? jsx('button', { type: 'button', onClick: () => openEditor('edit', expert), style: { ...EXPERT_STYLE.ghost, marginLeft: 'auto' }, children: '编辑' })
+            : null,
+        ] }),
+      ] })
+
+      return jsxs(Fragment, { children: [
+        header,
+        jsxs('div', { style: { display: 'flex', gap: 8, marginTop: 14 }, children: [
+          jsx('button', { type: 'button', onClick: () => setTab('all'), style: EXPERT_STYLE.tab(tab === 'all'), children: '全部' }),
+          jsx('button', { type: 'button', onClick: () => setTab('builtin'), style: EXPERT_STYLE.tab(tab === 'builtin'), children: '内置' }),
+          jsx('button', { type: 'button', onClick: () => setTab('custom'), style: EXPERT_STYLE.tab(tab === 'custom'), children: '自定义' }),
+        ] }),
+        filters,
+        error ? jsx('div', { style: { marginBottom: 12, padding: '8px 10px', borderRadius: 10, background: '#fef2f2', color: '#b91c1c', fontSize: 12.5 }, children: error }) : null,
+        shown.length === 0
+          ? jsx('div', { style: { padding: '28px 0', color: '#94a3b8', fontSize: 13, textAlign: 'center' }, children: '没有匹配的专家' })
+          : jsx('div', { style: { display: 'grid', gap: 12, gridTemplateColumns: 'repeat(auto-fill, minmax(320px, 1fr))' }, children: shown.map(expert => jsx('div', { key: expert.slug, children: card(expert)})) }),
+        dialog ? ExpertDialog({ dialog, divisions, busy, form, onField, setDialog, mutate }) : null,
+      ] })
+    }
+
+    /**
+     * 弹窗分发：按 `dialog.mode` 选择提示词弹窗或自定义专家编辑器。
+     *
+     * 这里用**普通函数调用**而不是组件：两个弹窗都不使用 hook（表单草稿在 `ExpertRoster`），
+     * 所以调用它们不会改变本组件的 hook 数量，真实 React 与测试替身的行为一致。
+     */
+    function ExpertDialog({ dialog, divisions, busy, form, onField, setDialog, mutate }) {
+      const close = () => setDialog(null)
+      if (dialog.mode === 'view') {
+        return ExpertPromptDialog({ dialog, onClose: close })
+      }
+      return ExpertCustomEditor({
+        dialog,
+        divisions,
+        busy,
+        form,
+        onField,
+        onClose: close,
+        onSave: async () => {
+          if (await mutate('/api/waterbuddy/experts/custom', { expert: form })) close()
+        },
+        onDelete: async () => {
+          if (await mutate('/api/waterbuddy/experts/custom/delete', { slug: dialog.expert.slug })) close()
+        },
+      })
+    }
+
+    // `inputTriggers` 必须**声明**才能拿到：`ctx.get` 同样受 inject 边界限制（实测未声明时
+    // 拿到 undefined，@ 菜单静默不注册）。参考实现同样把它列在 inject 里。
+    const inject = ['slots', 'inputTriggers']
     function apply(ctx) {
       ctx.effect(() => {
         const normalizeTitle = () => {
@@ -623,6 +1517,114 @@ window.__ModuleLoader__.load({
         }))
       ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register({ name: 'sidebar.footer.action', id: 'waterbuddy-user', order: 90, label: '登录 WaterBuddy' }, UserAction))
       ctx.slots.inject('settings.onboarding', () => ctx.slots.register({ name: 'settings.onboarding', id: 'welcome-notice', priority: -1000, order: -100 }, SkipWelcomeNotice))
+      // 专家名册页：在设置左侧列出一项「专家」。`label` 用纯字符串——本插件的界面文案
+      // 都是硬编码中文，没有走宿主词典（见 AGENTS.md 的产物面边界）。
+      ctx.slots.inject('settings.section', () => ctx.slots.register({
+        name: 'settings.section',
+        id: 'waterbuddy-experts',
+        order: 95,
+        label: '专家',
+      }, ExpertRoster))
+      // 新会话 hero：标记换成我们的（宿主默认是鸟形图标）。
+      ctx.slots.inject('conversation.hero.brand.mark', () =>
+        ctx.slots.register({ name: 'conversation.hero.brand.mark', priority: -10 }, WaterBuddyHeroMark))
+
+      // hero 标题换成我们的话术。
+      //
+      // 不能用 `ctx.locale.register('conversation', ...)` 覆盖：该服务对已存在的
+      // (namespace, locale) 直接抛错（`already has locale`），插件覆盖不了宿主词条。
+      // 所以在 DOM 层替换这两个已知默认标题（中/英）；文案一变就自动不再匹配，
+      // 不会误改别的东西。标题归一化那个观察器挂在 document.head 上，这里只动 body，
+      // 两者互不干涉。
+      ctx.effect(() => {
+        if (typeof document === 'undefined' || typeof MutationObserver !== 'function') return undefined
+        const DEFAULTS = new Set(['探索未至之境', 'Into the Unknown'])
+        const HEADLINE = '我们要做什么？'
+        // NodeFilter.SHOW_TEXT 依规范就是 4；用数值以免依赖测试环境里没有的 NodeFilter 全局。
+        const SHOW_TEXT = 4
+        const swap = root => {
+          if (!root || typeof document.createTreeWalker !== 'function') return
+          const walker = document.createTreeWalker(root, SHOW_TEXT)
+          for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+            const text = node.nodeValue || ''
+            if (DEFAULTS.has(text.trim())) node.nodeValue = text.replace(text.trim(), HEADLINE)
+          }
+        }
+        swap(document.body)
+        const observer = new MutationObserver(() => swap(document.body))
+        observer.observe(document.body, { childList: true, subtree: true })
+        return () => observer.disconnect()
+      }, 'waterbuddy: hero headline')
+
+      // 会话输入框左侧的专家入口。`inject` 是宿主支持的 slot owner 注入：框架按会话调用它，
+      // 把返回值并进组件 props——我们的实现靠它拿到当前会话的输入机，才能写原生引用 chip。
+      ctx.slots.inject('conversation.input.left', () => ctx.slots.register({
+        name: 'conversation.input.left',
+        id: 'waterbuddy-experts',
+        order: 90,
+        label: '召唤专家',
+        inject: sessionId => ({
+          /**
+           * 插入专家引用 chip；草稿还没写正文时再补一段任务示例（与参考实现一致）。
+           * 补示例失败不影响插入结果——chip 已经进去了。
+           */
+          insertExpert: (reference, expert) => {
+            const target = resolveExpertInputTarget(ctx, sessionId)
+            if (target === undefined) return false
+            if (!insertExpertReference(target, reference)) return false
+            if (expertDraftBodyIsEmpty(target)) appendExpertTaskExample(target, expert)
+            return true
+          },
+        }),
+      }, ExpertInputEntry))
+
+      // 每个分类注册一个 `@` 触发器源：打字 @ 直接列专家，选中的 token 与工具栏按钮一致。
+      // 用 `ctx.get` 软取服务：服务缺失只让这个菜单消失，绝不让整个插件加载失败。
+      ctx.effect(() => {
+        const inputTriggers = typeof ctx.get === 'function' ? ctx.get('inputTriggers') : undefined
+        if (!inputTriggers || typeof inputTriggers.registerSource !== 'function') {
+          console.warn('[WaterBuddy] expert @ menu disabled: host exposes no inputTriggers service')
+          return undefined
+        }
+        let disposers = []
+        let cancelled = false
+        // 专家名集合：给下面的「历史 chip 点击守卫」用（同一次名册请求）。
+        let expertNames = new Set()
+        loadExpertRoster()
+          .then(({ divisions, experts }) => {
+            if (cancelled) return
+            expertNames = new Set(experts.map(expert => expert.name))
+            disposers = divisions.map((division, index) => inputTriggers.registerSource(createExpertTriggerSource(ctx, division, index)))
+          })
+          .catch(error => console.warn('[WaterBuddy] expert @ menu disabled:', error.message))
+
+        // 历史消息里的 `@专家名` 会被宿主的**消息渲染器**渲染成「文件提及」
+        // （`<button data-ref-chip="file" title="@专家名">`），点它就按文件路径打开预览，
+        // 于是报 `ENOENT: <工作区>/专家名`。那条路径不经过输入触发器源，`openReference` 拦不到，
+        // 所以只能在捕获阶段把命中我们专家名的那些点击接管掉。
+        let removeGuard
+        if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+          const onClick = event => {
+            const target = event.target
+            const button = target && typeof target.closest === 'function'
+              ? target.closest('button[data-ref-chip="file"]')
+              : null
+            if (!button) return
+            const name = String(button.getAttribute('title') || '').replace(/^@/, '').trim()
+            if (!name || !expertNames.has(name)) return
+            event.preventDefault()
+            event.stopPropagation()
+          }
+          document.addEventListener('click', onClick, true)
+          removeGuard = () => document.removeEventListener('click', onClick, true)
+        }
+
+        return () => {
+          cancelled = true
+          if (removeGuard) removeGuard()
+          for (const dispose of disposers) dispose()
+        }
+      }, 'waterbuddy: expert @ menu')
     }
 
     exports.inject = inject