agentworkshop 0.7.24 → 0.7.33

package/server/plugins-builtin/rag-bridge/client.mjs

@@ -0,0 +1,108 @@
+/**
+ * rag-bridge 客户端面板 —— 经 ctx.ui.registerPanel 注入 'plugins.page' 插槽。
+ * 自包含 ESM(零导入);ctx 由宿主 loader 注入(fetch 带鉴权/t 命名空间翻译)。
+ * 健康徽标(后端/Web/知识库) + 快捷检索框,30s 自动刷新,返回清理函数供卸载回收。
+ */
+export function setup(ctx) {
+  // 面板样式(自包含注入,幂等;不依赖宿主页面样式表)
+  const styleId = 'aw-rb-styles'
+  if (!document.getElementById(styleId)) {
+    document.head.append(ctx.el('style', { id: styleId }, [`
+      .aw-rb { display:flex; flex-direction:column; gap:8px; font-size:12px; }
+      .aw-rb-row { display:flex; gap:8px; align-items:center; flex-wrap:wrap; }
+      .aw-rb-cell { display:inline-flex; align-items:center; gap:4px; }
+      .aw-rb-dot { width:8px; height:8px; border-radius:50%; display:inline-block; }
+      .aw-rb-dot-ok { background:#35e0a0; }
+      .aw-rb-dot-bad { background:#e05a5a; }
+      .aw-rb-input { flex:1; min-width:200px; padding:5px 9px; border:1px solid color-mix(in srgb, currentColor 24%, transparent); border-radius:7px; background:transparent; color:inherit; }
+      .aw-rb-btn { padding:5px 13px; border:1px solid color-mix(in srgb, currentColor 28%, transparent); border-radius:7px; background:transparent; color:inherit; cursor:pointer; }
+      .aw-rb-btn:disabled { opacity:.5; cursor:default; }
+      .aw-rb-results { display:flex; flex-direction:column; gap:6px; }
+      .aw-rb-empty { opacity:.6; }
+      .aw-rb-hit { padding:6px 8px; border:1px solid color-mix(in srgb, currentColor 12%, transparent); border-radius:7px; }
+      .aw-rb-hit-head { font-size:11px; opacity:.85; }
+      .aw-rb-hit-brief { opacity:.7; margin-top:2px; }
+    `]))
+  }
+
+  ctx.ui.registerPanel({
+    slot: 'plugins.page',
+    name: 'kb-panel',
+    titleKey: 'panel.title',
+    order: 10,
+    mount(el) {
+      const t = k => ctx.t(`panel.${k}`)
+      const timer = setInterval(refresh, 30_000)
+
+      function dot(ok) {
+        return ctx.el('span', {
+          class: `aw-rb-dot ${ok ? 'aw-rb-dot-ok' : 'aw-rb-dot-bad'}`,
+          title: ok ? t('ok') : t('bad'),
+        })
+      }
+
+      const backendCell = ctx.el('span', { class: 'aw-rb-cell' }, [dot(false), ` ${t('backend')}`])
+      const webCell = ctx.el('span', { class: 'aw-rb-cell' }, [dot(false), ` ${t('web')}`])
+      const kbCell = ctx.el('span', { class: 'aw-rb-cell aw-mono' }, [dot(false), ` ${t('kb')}: -`])
+      const counterCell = ctx.el('span', { class: 'aw-rb-cell faint' }, [
+        `${t('counters')}: ${t('store')} 0 · ${t('index')} 0`,
+      ])
+      const statusRow = ctx.el('div', { class: 'aw-rb-row' }, [backendCell, webCell, kbCell, counterCell])
+
+      const input = ctx.el('input', {
+        class: 'aw-rb-input',
+        placeholder: t('searchPlaceholder'),
+      })
+      input.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter') void runSearch()
+      })
+      const btn = ctx.el('button', { class: 'aw-rb-btn' }, [t('searchBtn')])
+      btn.addEventListener('click', () => void runSearch())
+      const results = ctx.el('div', { class: 'aw-rb-results' })
+
+      el.append(
+        ctx.el('div', { class: 'aw-rb' }, [
+          statusRow,
+          ctx.el('div', { class: 'aw-rb-row' }, [input, btn]),
+          results,
+        ]),
+      )
+
+      async function refresh() {
+        const h = await ctx.fetch('/api/plugins/rag-bridge/health').catch(() => null)
+        backendCell.replaceChildren(dot(Boolean(h?.backend?.ok)), ` ${t('backend')}`)
+        webCell.replaceChildren(dot(Boolean(h?.web?.ok)), ` ${t('web')}`)
+        kbCell.replaceChildren(dot(Boolean(h?.kb?.id)), ` ${t('kb')}: ${h?.kb?.id ? String(h.kb.id).slice(0, 8) : '-'}(${h?.auth === 'bearer' ? t('bearer') : t('anonymous')})`)
+        counterCell.replaceChildren(`${t('counters')}: ${t('store')} ${h?.counters?.store ?? 0} · ${t('index')} ${h?.counters?.index ?? 0}`)
+      }
+
+      async function runSearch() {
+        const q = String(input.value ?? '').trim()
+        if (!q) return
+        btn.disabled = true
+        btn.textContent = t('searching')
+        results.replaceChildren()
+        const r = await ctx.fetch(`/api/plugins/rag-bridge/search?q=${encodeURIComponent(q)}&top_k=5`).catch(() => null)
+        btn.disabled = false
+        btn.textContent = t('searchBtn')
+        const items = Array.isArray(r?.results) ? r.results.slice(0, 5) : []
+        if (!items.length) {
+          results.append(ctx.el('div', { class: 'aw-rb-empty' }, [t('empty')]))
+          return
+        }
+        for (const [i, h] of items.entries()) {
+          const brief = String(h?.content ?? '').replace(/\s+/g, ' ').trim().slice(0, 140)
+          results.append(ctx.el('div', { class: 'aw-rb-hit' }, [
+            ctx.el('div', { class: 'aw-rb-hit-head aw-mono' }, [
+              `${i + 1}. [${Number(h?.score ?? 0).toFixed(3)}] ${h?.doc_path ?? '-'}`,
+            ]),
+            ctx.el('div', { class: 'aw-rb-hit-brief' }, [brief]),
+          ]))
+        }
+      }
+
+      void refresh()
+      return () => clearInterval(timer)
+    },
+  })
+}

package/server/plugins-builtin/rag-bridge/i18n.json

@@ -0,0 +1,60 @@
+{
+  "zh-CN": {
+    "settings": {
+      "base_url": "rag-knowledge 后端地址",
+      "web_url": "rag-knowledge Web 地址",
+      "token": "rag-knowledge API Token"
+    },
+    "group": {
+      "conn": "rag-knowledge 连接",
+      "auth": "rag-knowledge 鉴权"
+    },
+    "panel": {
+      "title": "工业知识库(rag-knowledge)",
+      "backend": "后端",
+      "web": "Web",
+      "kb": "知识库",
+      "counters": "累计",
+      "store": "经验沉淀",
+      "index": "文档入库",
+      "searchPlaceholder": "检索工业知识(诊断报告/经验/规范)…",
+      "searchBtn": "检索",
+      "searching": "检索中…",
+      "empty": "未检索到相关内容",
+      "refresh": "刷新",
+      "ok": "正常",
+      "bad": "不可达",
+      "anonymous": "匿名",
+      "bearer": "鉴权"
+    }
+  },
+  "en": {
+    "settings": {
+      "base_url": "rag-knowledge backend URL",
+      "web_url": "rag-knowledge Web URL",
+      "token": "rag-knowledge API token"
+    },
+    "group": {
+      "conn": "rag-knowledge connection",
+      "auth": "rag-knowledge auth"
+    },
+    "panel": {
+      "title": "Industrial knowledge base (rag-knowledge)",
+      "backend": "Backend",
+      "web": "Web",
+      "kb": "Knowledge base",
+      "counters": "Total",
+      "store": "Experiences",
+      "index": "Documents",
+      "searchPlaceholder": "Search industrial knowledge (reports/lessons/specs)…",
+      "searchBtn": "Search",
+      "searching": "Searching…",
+      "empty": "No results",
+      "refresh": "Refresh",
+      "ok": "Up",
+      "bad": "Down",
+      "anonymous": "Anonymous",
+      "bearer": "Auth"
+    }
+  }
+}

package/server/plugins-builtin/rag-bridge/index.mjs

@@ -0,0 +1,411 @@
+/**
+ * rag-bridge —— rag-knowledge 知识库桥接插件。
+ *
+ * 把本地 rag-knowledge 服务(FastAPI 后端 + Nuxt web)集成为 AgentWorkShop 的
+ * 团队知识库:启动即确保「aw-industrial」知识库存在,并向 agent 注入三个工具——
+ * kb_search(全库检索)/ kb_store(经验沉淀)/ kb_index(文档入库)。
+ * 另开放 /health、/search、/experience 三个插件 API 便于运维探查。
+ * 服务不可达时工具返回 isError 文本(含原因与修复建议),绝不抛异常拖垮宿主。
+ */
+const KB_NAME = 'aw-industrial'
+const CATEGORIES = ['best_practice', 'troubleshooting', 'lesson_learned', 'optimization', 'tip', 'workflow', 'decision']
+const SEVERITIES = ['critical', 'important', 'normal', 'tip'] // rag-knowledge ExperienceCreate.severity 枚举
+const DEFAULT_BASE = 'http://127.0.0.1:8770' // FastAPI 后端
+const DEFAULT_WEB = 'http://127.0.0.1:6789' // Nuxt web(文档写盘)
+
+export default {
+  name: 'rag-bridge',
+  version: '1.1.0',
+  description: 'rag-knowledge 知识库桥接:工业知识检索/经验沉淀/文档入库三工具',
+  auth: 'user', // 平台转发层按此声明统一校验(缺省 'none' 开放)
+  client: './client.mjs', // 前端面板(插件页注入;i18n 见 i18n.json)
+  // 插件配置分组:插件调用平台 API 增加自己的设置分区(设置页独立成区、可折叠)。
+  // id 由宿主收敛进 plugin-rag-bridge* 命名空间,不会与其它插件/平台分组撞车;
+  // 插件卸载或停用时这两个分区随之消失,不残留空区块。
+  configGroups: [
+    { id: 'default', labelKey: 'plugin.rag-bridge.group.conn', label: 'rag-knowledge 连接', description: '后端与 Web 地址(保存即热生效)', order: 400 },
+    { id: 'auth', labelKey: 'plugin.rag-bridge.group.auth', label: 'rag-knowledge 鉴权', description: '服务端开启鉴权时所需 Token', order: 410, collapsed: true },
+  ],
+  // 插件设置声明:key 强制编址 plugins.rag-bridge.<key>,进 SystemConfigService 后
+  // 前端设置页自动渲染(labelKey 解析 i18n.json 的 plugin.rag-bridge.settings.*);
+  // group 指向上面声明的分区 → 字段按分区隔离展示
+  settings: [
+    { key: 'base_url', type: 'string', default: DEFAULT_BASE, group: 'default', labelKey: 'plugin.rag-bridge.settings.base_url', label: 'rag-knowledge 后端地址', description: 'FastAPI 后端(http/https,host 限 127.0.0.1/localhost);保存即热生效' },
+    { key: 'web_url', type: 'string', default: DEFAULT_WEB, group: 'default', labelKey: 'plugin.rag-bridge.settings.web_url', label: 'rag-knowledge Web 地址', description: 'Nuxt Web(文档写盘/目录);保存即热生效' },
+    { key: 'token', type: 'string', default: '', group: 'auth', labelKey: 'plugin.rag-bridge.settings.token', label: 'rag-knowledge API Token', description: '服务端开启鉴权时的 MCP/API Token(Authorization: Bearer);空=匿名;保存即热生效' },
+  ],
+  async setup(ctx) {
+    // ---- 运行态 ----
+    const state = { outbound: true } // base_url 非法时禁用全部出站调用
+    const base = () => trimSlash(String(ctx.config?.get?.('plugins.rag-bridge.base_url') || ctx.kv.get('kb.base_url') || DEFAULT_BASE))
+    const web = () => trimSlash(String(ctx.config?.get?.('plugins.rag-bridge.web_url') || ctx.kv.get('kb.web_url') || DEFAULT_WEB))
+    const kbId = () => String(ctx.kv.get('kb.id') || '')
+    // 鉴权 token(系统配置优先,kv 兜底):rag-knowledge 开启 server.auth 时所有 /api/*
+    // 要求 Bearer;backend 与 web 都认 Authorization: Bearer / X-KB-Token 两种头
+    const kbToken = () => String(ctx.config?.get?.('plugins.rag-bridge.token') || ctx.kv.get('kb.token') || '').trim()
+    const authHeaders = () => {
+      const t = kbToken()
+      return t ? { 'authorization': `Bearer ${t}`, 'x-kb-token': t } : {}
+    }
+
+    // ---- kv 默认值(幂等) ----
+    if (ctx.kv.get('kb.base_url') == null) ctx.kv.set('kb.base_url', DEFAULT_BASE)
+    if (ctx.kv.get('kb.web_url') == null) ctx.kv.set('kb.web_url', DEFAULT_WEB)
+    ctx.kv.set('kb.name', KB_NAME)
+
+    // base_url 守卫:仅 http/https 且 host 必须是 127.0.0.1/localhost(不合法则禁用出站)。
+    // 每次配置变更都重算 —— 否则改错地址后旧判定会一直沿用,「独立配置即时生效」不成立。
+    const applyOutboundGuard = () => {
+      try {
+        const u = new URL(base())
+        if ((u.protocol !== 'http:' && u.protocol !== 'https:') || !['127.0.0.1', 'localhost'].includes(u.hostname)) {
+          throw new Error(`base_url 必须是 http(s)://127.0.0.1|localhost,实际 ${base()}`)
+        }
+        state.outbound = true
+      }
+      catch (err) {
+        state.outbound = false
+        ctx.logger.error(`出站调用已禁用:${err?.message ?? err}(修正 rag-bridge 的「后端地址」后即恢复)`)
+      }
+    }
+    applyOutboundGuard()
+    // 配置热更新(runtime-settings 变更)→ 立即重算出站开关与下次探活
+    ctx.config.onChange(() => applyOutboundGuard())
+
+    // ---- ensureKB:幂等初始化(失败仅告警,不阻塞装载) ----
+    try {
+      await ensureKB()
+      ctx.logger.info(`rag-bridge 就绪:kb=${KB_NAME}(${kbId() || '待建'}),出站=${state.outbound ? '启用' : '禁用'}`)
+    }
+    catch (err) {
+      ctx.logger.warn(`ensureKB 未完成(不影响装载,工具会在服务可用后按需重试):${err?.message ?? err}`)
+    }
+
+    // ================= 出站 HTTP(重试 + 超时 + success 断言) =================
+
+    function sleep(ms) {
+      return new Promise(resolve => ctx.timer.setTimeout(resolve, ms))
+    }
+
+    /** 单次 JSON 请求;429/网络错误按 1s*重试次数退避,最多重试 2 次;检索类调用方传 timeoutMs:30000 */
+    async function callJson(method, url, body, { timeoutMs = 15000, retries = 2, headers = {} } = {}) {
+      let lastErr = ''
+      const h = { ...authHeaders(), ...headers }
+      for (let attempt = 0; attempt <= retries; attempt++) {
+        if (attempt > 0) await sleep(1000 * attempt) // 退避 1s*n
+        try {
+          const res = method === 'GET'
+            ? await ctx.http.get(url, { timeoutMs, headers: h })
+            : await ctx.http.post(url, body ?? {}, { timeoutMs, headers: h })
+          if (res.status === 429) {
+            lastErr = `HTTP 429(限流)`
+            continue
+          }
+          if (!res.ok) return { ok: false, status: res.status, error: `HTTP ${res.status}` }
+          const json = await res.json().catch(() => null)
+          if (json == null) return { ok: false, status: res.status, error: '响应不是合法 JSON' }
+          return { ok: true, status: res.status, body: json }
+        }
+        catch (err) {
+          lastErr = err?.message ?? String(err) // 网络错误/超时(AbortSignal.timeout)
+        }
+      }
+      return { ok: false, error: lastErr || '未知错误' }
+    }
+
+    /** rag 业务调用:铁律——HTTP 200 但 body.success !== true 一律视为失败 */
+    async function ragCall(method, url, body, opts = {}) {
+      const r = await callJson(method, url, body, opts)
+      if (!r.ok) return r
+      if (r.body?.success !== true) {
+        return { ok: false, error: `服务返回 success!=true:${JSON.stringify(r.body).slice(0, 200)}` }
+      }
+      return r
+    }
+
+    const outboundOff = () => ({ ok: false, error: '出站调用已禁用:kv["kb.base_url"] 非法(仅允许 http/https 且 host 为 127.0.0.1/localhost)' })
+
+    // ================= ensureKB(catalog 查找 → 建库 → experience init) =================
+
+    async function ensureKB() {
+      // ① catalog 查找同名库(响应 {success,count,knowledgeBases:[{kbId,name,...}]})
+      const cat = state.outbound
+        ? await callJson('GET', `${web()}/api/kb/catalog`, null, { timeoutMs: 10000 })
+        : { ok: false, error: '出站已禁用' }
+      if (cat.ok) {
+        const list = Array.isArray(cat.body?.knowledgeBases) ? cat.body.knowledgeBases : []
+        const hit = list.find(kb => kb?.name === KB_NAME)
+        if (hit?.kbId) ctx.kv.set('kb.id', hit.kbId)
+      }
+      else {
+        ctx.logger.warn(`catalog 不可达(${cat.error}),跳过查找直接尝试建库`)
+      }
+      // ② 无则建库(响应 {success,knowledgeBase:{id,name,path,...}})
+      if (!kbId()) {
+        const created = state.outbound
+          ? await ragCall('POST', `${web()}/api/kb/create`, { name: KB_NAME, description: 'AgentWorkShop 工业知识库(诊断报告/经验教训/操作规范)' }, { timeoutMs: 15000 })
+          : { ok: false, error: '出站已禁用' }
+        if (!created.ok) throw new Error(`创建知识库 ${KB_NAME} 失败:${created.error}`)
+        const id = created.body?.knowledgeBase?.id
+        if (!id) throw new Error(`建库响应缺少 knowledgeBase.id:${JSON.stringify(created.body).slice(0, 200)}`)
+        ctx.kv.set('kb.id', id)
+      }
+      // ③ 经验文件夹初始化(容忍已初始化/失败:仅告警)
+      const init = state.outbound
+        ? await ragCall('POST', `${base()}/api/v1/experience/${kbId()}/init`, {}, { timeoutMs: 15000 })
+        : { ok: false, error: '出站已禁用' }
+      if (!init.ok) ctx.logger.warn(`experience init 未成功(可忽略或稍后手动重试):${init.error}`)
+    }
+
+    /** 工具侧兜底:kv 无 kb.id 时按需重跑 ensureKB */
+    async function requireKbId() {
+      if (kbId()) return kbId()
+      await ensureKB()
+      if (kbId()) return kbId()
+      return null
+    }
+
+    // ================= 工具 ×3(omp host 工具,lead/worker 全员可用) =================
+
+    ctx.omp.registerTool({
+      name: 'kb_search',
+      label: '全库检索',
+      description: '检索工业知识库(诊断报告/经验教训/操作规范),作业前先查历史经验,避免重复踩坑。',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: '检索问题(自然语言,中英文均可)' },
+          kb_id: { type: 'string', description: '限定知识库 ID(缺省为 aw-industrial)' },
+          top_k: { type: 'number', description: '返回条数上限(默认 5,经 stage2 精筛)' },
+        },
+        required: ['query'],
+      },
+      roles: ['lead', 'worker'],
+      handler: async (args) => {
+        if (!state.outbound) {
+          return { text: `知识库检索不可用:${outboundOff().error}。修复后重启服务。`, isError: true }
+        }
+        const query = String(args.query ?? '').trim()
+        if (!query) return { text: 'query 必填(要查什么问题)。', isError: true }
+        const kb = String(args.kb_id ?? '').trim() || kbId() || undefined
+        const topK = Math.min(Math.max(Math.round(Number(args.top_k) || 5), 1), 20)
+        const r = await ragCall('POST', `${base()}/api/v1/search/two-stage`,
+          { query, kb_id: kb, stage2_top_k: topK }, { timeoutMs: 30000 })
+        if (!r.ok) {
+          return { text: `检索失败:${r.error}。请确认 rag 后端(${base()})已启动(rag-knowledge 目录 start.bat / ragctl),稍后重试。`, isError: true }
+        }
+        const results = Array.isArray(r.body?.stage2?.results) ? r.body.stage2.results : []
+        if (results.length === 0) {
+          return { text: `未检索到相关经验/文档(查询:「${query}」)。可尝试更换关键词,或确认资料是否已用 kb_index 入库。` }
+        }
+        const top = results.slice(0, 5)
+        const lines = top.map((h, i) => {
+          const score = Number(h?.score ?? 0).toFixed(4)
+          const path = String(h?.doc_path ?? '(无路径)')
+          const brief = String(h?.content ?? '').replace(/\s+/g, ' ').trim().slice(0, 160)
+          return `${i + 1}. [score=${score}] ${path}\n   ${brief}${String(h?.content ?? '').length > 160 ? '…' : ''}`
+        })
+        return { text: `检索到 ${results.length} 条(展示前 ${top.length} 条):\n${lines.join('\n')}` }
+      },
+    })
+
+    ctx.omp.registerTool({
+      name: 'kb_store',
+      label: '经验沉淀',
+      description: '把本次作业中值得复用的经验(最佳实践/踩坑教训/操作要点)写入知识库,供团队后续检索。',
+      parameters: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: '经验标题(一句话概括)' },
+          category: { type: 'string', enum: CATEGORIES, description: '经验类别' },
+          problem: { type: 'string', description: '遇到的问题/场景' },
+          solution: { type: 'string', description: '解决方案/操作步骤' },
+          key_lessons: { type: 'array', items: { type: 'string' }, description: '关键教训(条目列表,可选)' },
+          tags: { type: 'array', items: { type: 'string' }, description: '标签(可选)' },
+          severity: { type: 'string', enum: SEVERITIES, description: '严重程度(critical/important/normal/tip,可选,缺省 normal)' },
+        },
+        required: ['title', 'category'],
+      },
+      roles: ['lead', 'worker'],
+      handler: async (args) => {
+        if (!state.outbound) {
+          return { text: `经验沉淀不可用:${outboundOff().error}。修复后重启服务。`, isError: true }
+        }
+        const title = String(args.title ?? '').trim()
+        if (!title) return { text: 'title 必填(经验标题)。', isError: true }
+        const category = String(args.category ?? '').trim()
+        if (!CATEGORIES.includes(category)) {
+          return { text: `category 必须是以下之一:${CATEGORIES.join('/')}`, isError: true }
+        }
+        const kb = await requireKbId()
+        if (!kb) {
+          return { text: `经验沉淀失败:知识库 ${KB_NAME} 不存在且自动建库失败(检查 web ${web()} 是否启动)。`, isError: true }
+        }
+        const body = {
+          title,
+          category,
+          problem: String(args.problem ?? ''),
+          solution: String(args.solution ?? ''),
+        }
+        const lessons = (Array.isArray(args.key_lessons) ? args.key_lessons : []).map(s => String(s).trim()).filter(Boolean)
+        if (lessons.length) body.key_lessons = lessons
+        const tags = (Array.isArray(args.tags) ? args.tags : []).map(s => String(s).trim()).filter(Boolean)
+        if (tags.length) body.tags = tags
+        const severity = String(args.severity ?? '').trim()
+        if (severity) {
+          // rag-knowledge ExperienceCreate.severity 是枚举,非法值会被 422 拒收——先在本侧校验
+          if (!SEVERITIES.includes(severity)) {
+            return { text: `severity 必须是以下之一:${SEVERITIES.join('/')}`, isError: true }
+          }
+          body.severity = severity
+        }
+        const r = await ragCall('POST', `${base()}/api/v1/experience/${kb}`, body, { timeoutMs: 30000 })
+        if (!r.ok) {
+          return { text: `经验沉淀失败:${r.error}。请确认 rag 后端(${base()})已启动后重试。`, isError: true }
+        }
+        const expId = String(r.body?.experience?.id ?? '(未返回 id)')
+        ctx.kv.bump('store.count')
+        return { text: `经验已沉淀:${title}(id=${expId},category=${category},kb=${KB_NAME})。` }
+      },
+    })
+
+    ctx.omp.registerTool({
+      name: 'kb_index',
+      label: '文档入库',
+      description: '把一份 markdown 文档写入知识库并建立向量/图谱索引,供 kb_search 日后检索。',
+      parameters: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: '文档标题(同时作为文件名)' },
+          content: { type: 'string', description: '文档正文(markdown)' },
+          tags: { type: 'array', items: { type: 'string' }, description: '标签(可选)' },
+        },
+        required: ['title', 'content'],
+      },
+      roles: ['lead', 'worker'],
+      handler: async (args) => {
+        if (!state.outbound) {
+          return { text: `文档入库不可用:${outboundOff().error}。修复后重启服务。`, isError: true }
+        }
+        const title = String(args.title ?? '').trim()
+        const content = String(args.content ?? '')
+        if (!title) return { text: 'title 必填(文档标题)。', isError: true }
+        if (!content.trim()) return { text: 'content 必填(markdown 正文,不能为空)。', isError: true }
+        const kb = await requireKbId()
+        if (!kb) {
+          return { text: `文档入库失败:知识库 ${KB_NAME} 不存在且自动建库失败(检查 web ${web()} 是否启动)。`, isError: true }
+        }
+        const tags = (Array.isArray(args.tags) ? args.tags : []).map(s => String(s).trim()).filter(Boolean)
+        // 第 1 步:web 写盘(响应 {success,document:{path,...}})
+        const docName = safeFileName(title)
+        const w = await ragCall('POST', `${web()}/api/kb/documents/create`,
+          { kbId: kb, name: docName, content, description: title }, { timeoutMs: 30000 })
+        if (!w.ok) {
+          return { text: `文档入库卡在第 1 步(web 写盘 ${web()}/api/kb/documents/create):${w.error}。未产生索引,可直接重试。`, isError: true }
+        }
+        const docPath = String(w.body?.document?.path ?? '')
+        if (!docPath) {
+          return { text: '文档入库卡在第 1 步:写盘成功但响应缺少 document.path,无法继续索引。', isError: true }
+        }
+        // 第 2 步:backend 索引(content 直传,doc_path 用写盘返回路径)
+        const r = await ragCall('POST', `${base()}/api/v1/search/index-document`,
+          { kb_id: kb, doc_path: docPath, doc_name: docName, description: title, content, tags }, { timeoutMs: 60000 })
+        if (!r.ok) {
+          return { text: `文档入库卡在第 2 步(backend 索引 ${base()}/api/v1/search/index-document):${r.error}。文档已写盘(${docPath}),服务恢复后可重试入库(同名会生成新文件)。`, isError: true }
+        }
+        const chunks = Number(r.body?.vector_index?.total_chunks ?? 0)
+        ctx.kv.bump('index.count')
+        return { text: `文档已入库:${docPath}(向量分块 ${chunks},kb=${KB_NAME}),可立即用 kb_search 检索。` }
+      },
+    })
+
+    // ================= 插件 API ×3(/api/plugins/rag-bridge/**) =================
+
+    /** 从 h3 event 取查询参数(转发层只预挂 awBody;query 在 event.path 上) */
+    function queryOf(event) {
+      const raw = String(event?.path ?? event?.node?.req?.url ?? '')
+      const q = {}
+      try {
+        const u = new URL(raw, 'http://local')
+        for (const [k, v] of u.searchParams.entries()) q[k] = v
+      }
+      catch { /* 忽略,返回空 */ }
+      return q
+    }
+
+    // 健康:后端 + web 存活、kb.id(缺失时按需自愈 ensureKB,token 后配的场景)、出站开关
+    ctx.route('GET', '/health', async () => {
+      const backend = state.outbound
+        ? await callJson('GET', `${base()}/api/v1/health`, null, { timeoutMs: 5000, retries: 0 })
+        : { ok: false, error: '出站已禁用' }
+      const webR = state.outbound
+        ? await callJson('GET', `${web()}/api/kb/catalog`, null, { timeoutMs: 5000, retries: 0 })
+        : { ok: false, error: '出站已禁用' }
+      if (!kbId() && state.outbound && backend.ok && webR.ok) {
+        await ensureKB().catch(() => {}) // 装载期 401/不可达导致 kb.id 缺失 → 探活时自愈
+      }
+      return {
+        plugin: 'rag-bridge',
+        outbound: state.outbound,
+        auth: kbToken() ? 'bearer' : 'anonymous',
+        // token 配置与「实测是否被接受」分开呈现:401/403 = 明确被拒(运维一眼看出 token 配错),
+        // 网络不通/超时为 null(未知),2xx 或非鉴权类失败为 true(未被拒)
+        token: {
+          configured: Boolean(kbToken()),
+          accepted: backend.ok ? true : (backend.status === 401 || backend.status === 403 ? false : null),
+        },
+        kb: { name: KB_NAME, id: kbId() || null },
+        backend: { url: base(), ok: backend.ok, ...(backend.ok ? { status: backend.body?.status ?? null } : { status: backend.status ?? null, error: backend.error }) },
+        web: { url: web(), ok: webR.ok, ...(webR.ok ? { knowledgeBases: webR.body?.count ?? null } : { error: webR.error }) },
+        counters: { store: ctx.kv.get('store.count') ?? 0, index: ctx.kv.get('index.count') ?? 0 },
+      }
+    })
+
+    // 检索:复用 two-stage(?q=&kb_id=&top_k=)
+    ctx.route('GET', '/search', async (event) => {
+      const q = queryOf(event)
+      const query = String(q.q ?? '').trim()
+      if (!query) return { success: false, error: '缺少参数 q(检索词)' }
+      if (!state.outbound) return { success: false, error: outboundOff().error }
+      const kb = String(q.kb_id ?? '').trim() || kbId() || undefined
+      const topK = Math.min(Math.max(Math.round(Number(q.top_k) || 5), 1), 20)
+      const r = await ragCall('POST', `${base()}/api/v1/search/two-stage`,
+        { query, kb_id: kb, stage2_top_k: topK }, { timeoutMs: 30000 })
+      if (!r.ok) return { success: false, error: r.error }
+      return { success: true, query, total_results: r.body?.total_results ?? null, results: r.body?.stage2?.results ?? [] }
+    })
+
+    // 经验列表:GET {base}/api/v1/experience/{kb_id} → {success,count,experiences:[...]}(?limit= 截取)
+    ctx.route('GET', '/experience', async (event) => {
+      const q = queryOf(event)
+      if (!state.outbound) return { success: false, error: outboundOff().error }
+      const kb = await requireKbId()
+      if (!kb) return { success: false, error: `知识库 ${KB_NAME} 不存在且自动建库失败(检查 web ${web()})` }
+      const limit = Math.min(Math.max(Math.round(Number(q.limit) || 20), 1), 100)
+      const r = await ragCall('GET', `${base()}/api/v1/experience/${kb}`, null, { timeoutMs: 15000 })
+      if (!r.ok) return { success: false, error: `经验列表不可用:${r.error}` }
+      const all = Array.isArray(r.body?.experiences) ? r.body.experiences : []
+      return {
+        success: true,
+        kb: { name: KB_NAME, id: kb },
+        count: all.length,
+        experiences: all.slice(0, limit),
+      }
+    })
+  },
+}
+
+// ================= 纯函数小工具 =================
+
+function trimSlash(s) {
+  return s.replace(/\/+$/, '')
+}
+
+/** 标题 → 安全文件名(剔除路径非法字符;确保 .md 后缀) */
+function safeFileName(title) {
+  // eslint-disable-next-line no-control-regex -- 文件名净化:必须剔除控制字符
+  let name = String(title).replace(/[\\/:*?"<>|\u0000-\u001f]/g, '-').replace(/\s+/g, ' ').trim().replace(/^[.\s]+|[.\s]+$/g, '')
+  if (!name) name = 'untitled'
+  if (name.length > 80) name = name.slice(0, 80).trim()
+  return name.toLowerCase().endsWith('.md') ? name : `${name}.md`
+}