koishi-plugin-isthattrue 0.2.2 → 0.2.5

package/README.md

@@ -1,103 +1,109 @@
-# koishi-plugin-isthattrue
+# koishi-plugin-chatluna-fact-check
 
-[![npm](https://img.shields.io/npm/v/koishi-plugin-isthattrue?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-isthattrue)
+[![npm](https://img.shields.io/npm/v/koishi-plugin-chatluna-fact-check?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-chatluna-fact-check)
 
-事实核查插件 - 使用多 Agent LLM 架构验证消息真实性
-
-## 功能特点
-
-- 多 Agent 协作：主控 Agent 编排任务，子搜索 Agent 并行检索
-- 多搜索源支持：Tavily、Anspire、Kimi、智谱、Chatluna Search
-- 支持文本和图片内容（OCR 识别）
-- 可引用消息进行核查
-- 输出判定结果：TRUE / FALSE / PARTIALLY_TRUE / UNCERTAIN
+事实核查插件，提供两个核心工具：
+- `fact_check`：快速搜索聚合（默认）
+- `deep_search`：迭代式深度搜索（可选）
 
 ## 安装
 
 ```bash
-npm install koishi-plugin-isthattrue
+npm install koishi-plugin-chatluna-fact-check
 ```
 
-## 依赖
+## 最小配置
+
+```yaml
+chatluna-fact-check:
+  api:
+    apiKeys:
+      - [ollama, '', 'https://ollama.com/api/web_search', true]
+  factCheck:
+    enableChatlunaSearch: false
+    chatlunaSearchModel: ''
+    chatlunaSearchDiversifyModel: ''
+    timeout: 60000
+    maxRetries: 2
+    proxyMode: follow-global
+    proxyAddress: ''
+    logLLMDetails: false
+  agent:
+    enable: true
+    enableQuickTool: true
+    quickToolName: fact_check
+    grokModel: x-ai/grok-4-1
+  deepSearch:
+    enable: false
+```
 
-- [koishi-plugin-chatluna](https://github.com/ChatLunaLab/chatluna) - LLM 服务接入
+## API Key / Base URL 对照表
 
-## 使用方法
+推荐优先在 `api.apiKeys` 表格中集中填写（来源 / key / base url / 启用开关）。
 
-```
-tof [内容]        # 核查指定内容
-tof               # 引用一条消息后使用，核查被引用的消息
-```
+| key | base url | 说明 |
+|---|---|---|
+| `api.apiKeys` 中 `provider=ollama` 的 `apiKey` | `api.apiKeys` 中 `provider=ollama` 的 `baseUrl` | 统一填写 Ollama 凭据（唯一入口）；key 留空再回退 `OLLAMA_API_KEY` |
+| `N/A`（`factCheck.enableChatlunaSearch`） | `N/A` | 依赖 `chatluna-search-service` 内部配置，不在本插件配置 API key |
 
-别名：`鉴定`、`核查`
+## FactCheck 配置
 
-## 配置说明
+`factCheck` 负责核查流程的运行参数：
+- Chatluna 搜索模型：`factCheck.chatlunaSearchModel`
+- 搜索关键词多样化：`factCheck.chatlunaSearchDiversifyModel`
+- 搜索集成开关：`factCheck.enableChatlunaSearch`
+- 超时与重试：`factCheck.timeout` / `factCheck.maxRetries`
+- 代理与调试：`factCheck.proxyMode` / `factCheck.proxyAddress` / `factCheck.logLLMDetails`
 
-### 模型配置
+### Gemini 搜索模型要求
 
-| 配置项 | 说明 | 推荐 |
-|--------|------|------|
-| mainModel | 主控 Agent 模型，用于编排和最终判决 | Gemini-3-Flash |
-| subSearchModel | 子搜索 Agent 模型，用于深度搜索 | Grok-4-1 |
+`factCheck.chatlunaSearchModel`（及 `agent.geminiModel`）填写 Gemini 模型时，**必须满足以下条件**，否则会报 `Cannot read properties of undefined (reading 'model')` 错误：
 
-### 搜索 API 配置
+1. **使用 Gemini 适配器**（`koishi-plugin-chatluna-gemini-adapter`），不可使用 OpenAI 兼容中转。
+2. **Gemini 适配器内仅开启**以下两项联网工具，其余工具（如代码执行等）关闭：
+   - `Google Search`（网络搜索）
+   - `URL context`（URL 内容读取）
 
-| 配置项 | 说明 |
-|--------|------|
-| tavilyApiKey | Tavily API Key（可选） |
-| anspireApiKey | Anspire API Key（可选） |
-| kimiApiKey | Kimi API Key（可选） |
-| zhipuApiKey | 智谱 API Key（可选） |
-| chatlunaSearchModel | Chatluna Search 使用的模型 |
-| enableChatlunaSearch | 启用 Chatluna 搜索集成 |
-| chatlunaSearchDiversifyModel | 搜索关键词多样化模型 |
+> 原因：`chatluna-search-service` 的 `web_search` 工具在 `summaryType` 为 `balanced` 时需要向 LLM 发送 configurable，若适配器或工具配置不兼容，configurable 解析的 `model` 字段会为 undefined 导致崩溃。Gemini 原生适配器 + 仅开启搜索类工具可规避此问题。
 
-### Agent 配置
+## 搜索源上下文注入
 
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| timeout | 60000 | 单次请求超时时间（毫秒） |
-| maxRetries | 2 | 失败重试次数 |
+### 1) `fact_check` 追加上下文（仅附加参考，不改变最终判定）
 
-### 其他设置
+- Chatluna Search：`agent.appendChatlunaSearchContext` + `agent.chatlunaSearchContext*`
+- Ollama Search：`agent.appendOllamaSearchContext` + `agent.ollamaSearchContext*`
 
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| verbose | false | 显示详细验证过程 |
-| outputFormat | auto | 输出格式（auto/markdown/plain） |
-| useForwardMessage | true | 使用合并转发消息展示详情（仅 QQ） |
-| bypassProxy | false | 绕过系统代理 |
-| logLLMDetails | false | 打印 LLM 请求详情（调试用） |
+触发条件与失败行为：
+- 开关为 `true` 且依赖可用才会执行
+- 超时或调用失败会“跳过该上下文”，不会中断 `fact_check`
 
-## 工作流程
+### 2) `deep_search` 迭代来源
 
-1. 用户发送 `tof` 命令（可引用消息或直接输入内容）
-2. MessageParser 提取文本和图片，如有图片则进行 OCR
-3. 主控 Agent 分析内容，生成搜索计划
-4. 子搜索 Agent 并行执行多源搜索
-5. 主控 Agent 综合搜索结果，输出最终判定
+- `deepSearch.useChatlunaSearchTool`：调用 `web_search`
+- `api.apiKeys` 中启用 `ollama` 行：允许 DeepSearch 调用 Ollama Search
 
-## 架构
+失败行为：
+- 工具调用失败时回退到模型搜索
+- 若来源整体不可用，最终报告会降置信度并提示来源不足
 
+## DeepSearch（可选）
+
+推荐配置：
+
+```yaml
+chatluna-fact-check:
+  deepSearch:
+    enable: true
+    controllerModel: google/gemini-3-flash
+    maxIterations: 3
+    perIterationTimeout: 30000
+    useChatlunaSearchTool: true
 ```
-src/
-├── index.ts              # 插件入口，注册 tof 命令
-├── config.ts             # 配置 Schema
-├── types.ts              # TypeScript 类型定义
-├── agents/
-│   ├── mainAgent.ts      # 主控 Agent（编排 + 判决）
-│   └── subSearchAgent.ts # 子搜索 Agent（多源检索）
-├── services/
-│   ├── chatluna.ts       # Chatluna LLM 适配器
-│   ├── chatlunaSearch.ts # Chatluna Search 集成
-│   ├── messageParser.ts  # 消息解析（文本/图片）
-│   ├── tavily.ts         # Tavily 搜索
-│   ├── anspire.ts        # Anspire 搜索
-│   ├── kimi.ts           # Kimi 搜索
-│   └── zhipu.ts          # 智谱搜索
-└── utils/
-    └── prompts.ts        # LLM Prompt 模板
-```
+
+## 调试与排障
+
+- `factCheck.proxyMode`：排障建议先设为 `direct`
+- `factCheck.logLLMDetails`：仅排障时打开
 
 ## License
 

package/client/index.ts

@@ -0,0 +1,325 @@
+import { Context } from '@koishijs/client'
+import { computed, defineComponent, inject, onBeforeUnmount, onMounted, type ComputedRef, watch, h } from 'vue'
+
+type NavSection = {
+  key: 'tools' | 'models' | 'search' | 'services' | 'debug'
+  title: string
+}
+
+type NavGroup = {
+  title: string
+  sections: NavSection[]
+}
+
+const PLUGIN_NAMES = new Set([
+  'isthattrue', // legacy package name
+  'chatluna-fact-check',
+  'koishi-plugin-isthattrue', // legacy package name
+  'koishi-plugin-chatluna-fact-check',
+])
+
+const NAV_GROUPS: NavGroup[] = [
+  {
+    title: '工具与模型',
+    sections: [
+      { key: 'tools', title: '工具注册' },
+      { key: 'models', title: 'LLM AI 接入' },
+    ],
+  },
+  {
+    title: '搜索与服务',
+    sections: [
+      { key: 'search', title: '搜索策略' },
+      { key: 'services', title: '外部服务' },
+    ],
+  },
+  {
+    title: '调试/兼容',
+    sections: [
+      { key: 'debug', title: '调试与排障' },
+    ],
+  },
+] 
+
+const NAV_SECTIONS: NavSection[] = NAV_GROUPS.flatMap((group) => group.sections)
+const SECTION_TITLE_ALIASES: Record<NavSection['key'], string[]> = {
+  tools: ['工具注册', 'Fact Check 工具', 'Deep Search 工具', 'Web Fetch 工具'],
+  models: ['LLM AI 接入', '模型接入', 'AI 模型接入'],
+  search: ['搜索策略', '搜索配置', '超时配置', '排序与策略', '最大字数'],
+  services: ['外部服务', 'Grok 网络搜索', 'Jina Reader 配置'],
+  debug: ['调试与排障', '调试'],
+}
+
+const STYLE_ID = 'isthattrue-nav-style'
+
+function ensureStyle() {
+  if (document.getElementById(STYLE_ID)) return
+  const style = document.createElement('style')
+  style.id = STYLE_ID
+  style.textContent = `
+.isthattrue-nav {
+  position: fixed;
+  top: 260px;
+  right: 60px;
+  z-index: 1000;
+  width: 140px;
+  max-width: 90vw;
+  user-select: none;
+}
+.isthattrue-nav-header {
+  padding: 6px 10px;
+  border-radius: 999px;
+  border: 1px solid var(--k-color-border, #4b5563);
+  background: color-mix(in srgb, var(--k-color-bg, #1f2937) 94%, white);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  cursor: move;
+  touch-action: none;
+}
+.isthattrue-nav-handle {
+  color: var(--k-text-light, #9ca3af);
+  font-size: 14px;
+  line-height: 1;
+}
+.isthattrue-nav-toggle {
+  border: none;
+  background: transparent;
+  color: var(--k-text-light, #9ca3af);
+  cursor: pointer;
+  padding: 0;
+  font-size: 14px;
+  line-height: 1;
+}
+.isthattrue-nav-body {
+  margin-top: 8px;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.isthattrue-nav.collapsed .isthattrue-nav-body {
+  display: none;
+}
+.isthattrue-nav-item {
+  border: none;
+  background: transparent;
+  color: var(--k-text, #d1d5db);
+  text-align: left;
+  padding: 6px 4px;
+  cursor: pointer;
+  font-size: 14px;
+  line-height: 1.4;
+}
+.isthattrue-nav-item:hover {
+  color: var(--k-color-primary, #4f7cff);
+}
+.isthattrue-nav-item.active {
+  color: var(--k-color-primary, #4f7cff);
+}
+.isthattrue-nav-group {
+  margin-top: 4px;
+  padding: 6px 4px 2px;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--k-text-light, #9ca3af);
+  opacity: 0.9;
+}
+/* Shrink nested sub-section headers inside intersect groups (e.g. DeepSearch sub-sections) */
+.k-schema-group .k-schema-group .k-schema-header {
+  font-size: 0.85em;
+  margin-top: 0.4em;
+  margin-bottom: 0.2em;
+}
+`
+  document.head.appendChild(style)
+}
+
+function normalizeText(text: string) {
+  return text.replace(/\s+/g, '').trim()
+}
+
+function getSectionNodes() {
+  return Array.from(document.querySelectorAll<HTMLElement>(
+    '.k-schema-section-title, .k-schema-header, h2.k-schema-header'
+  ))
+}
+
+function findHeaderBySection(section: NavSection) {
+  const targets = [section.title, ...(SECTION_TITLE_ALIASES[section.key] || [])]
+    .map(item => normalizeText(item))
+    .filter(Boolean)
+  const headers = getSectionNodes()
+  for (const header of headers) {
+    const text = normalizeText(header.textContent || '')
+    if (!text) continue
+    if (targets.some(target => text.includes(target))) return header
+  }
+  return null
+}
+
+function matchSectionByHeaderText(text: string): NavSection | undefined {
+  const normalized = normalizeText(text)
+  return NAV_SECTIONS.find((section) => {
+    const candidates = [section.title, ...(SECTION_TITLE_ALIASES[section.key] || [])]
+      .map(item => normalizeText(item))
+      .filter(Boolean)
+    return candidates.some(candidate => normalized.includes(candidate))
+  })
+}
+
+function mountFloatingNav() {
+  ensureStyle()
+
+  const existing = document.querySelector<HTMLElement>('.isthattrue-nav')
+  existing?.remove()
+
+  const root = document.createElement('div')
+  root.className = 'isthattrue-nav'
+  root.innerHTML = `
+<div class="isthattrue-nav-header">
+  <span class="isthattrue-nav-handle">⋮⋮</span>
+  <button class="isthattrue-nav-toggle" type="button">⌄</button>
+</div>
+<div class="isthattrue-nav-body"></div>
+`
+  document.body.appendChild(root)
+
+  const body = root.querySelector<HTMLElement>('.isthattrue-nav-body')!
+  const toggle = root.querySelector<HTMLButtonElement>('.isthattrue-nav-toggle')!
+  const header = root.querySelector<HTMLElement>('.isthattrue-nav-header')!
+
+  const itemMap = new Map<string, HTMLButtonElement>()
+  for (const group of NAV_GROUPS) {
+    const groupTitle = document.createElement('div')
+    groupTitle.className = 'isthattrue-nav-group'
+    groupTitle.textContent = group.title
+    body.appendChild(groupTitle)
+
+    for (const section of group.sections) {
+      const button = document.createElement('button')
+      button.type = 'button'
+      button.className = 'isthattrue-nav-item'
+      button.textContent = section.title
+      button.addEventListener('click', () => {
+        const target = findHeaderBySection(section)
+        if (target) {
+          target.scrollIntoView({ behavior: 'smooth', block: 'start' })
+        }
+      })
+      body.appendChild(button)
+      itemMap.set(section.key, button)
+    }
+  }
+
+  toggle.addEventListener('click', (event) => {
+    event.stopPropagation()
+    const collapsed = root.classList.toggle('collapsed')
+    toggle.textContent = collapsed ? '⌃' : '⌄'
+  })
+
+  let dragStartX = 0
+  let dragStartY = 0
+  let startRight = 0
+  let startTop = 0
+
+  header.addEventListener('pointerdown', (event) => {
+    const target = event.target as HTMLElement
+    if (target.closest('.isthattrue-nav-toggle')) return
+    event.preventDefault()
+    header.setPointerCapture(event.pointerId)
+    dragStartX = event.clientX
+    dragStartY = event.clientY
+    startRight = parseFloat(root.style.right || '60')
+    startTop = parseFloat(root.style.top || '260')
+  })
+
+  header.addEventListener('pointermove', (event) => {
+    if (!header.hasPointerCapture(event.pointerId)) return
+    const dx = event.clientX - dragStartX
+    const dy = event.clientY - dragStartY
+    root.style.top = `${Math.max(0, startTop + dy)}px`
+    root.style.right = `${Math.max(0, startRight - dx)}px`
+  })
+
+  const onPointerEnd = (event: PointerEvent) => {
+    if (header.hasPointerCapture(event.pointerId)) {
+      header.releasePointerCapture(event.pointerId)
+    }
+  }
+  header.addEventListener('pointerup', onPointerEnd)
+  header.addEventListener('pointercancel', onPointerEnd)
+
+  let observer: IntersectionObserver | null = null
+  const refreshActive = () => {
+    observer?.disconnect()
+    observer = new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue
+        const text = (entry.target.textContent || '').trim()
+        const section = matchSectionByHeaderText(text)
+        if (!section) continue
+        for (const item of itemMap.values()) item.classList.remove('active')
+        itemMap.get(section.key)?.classList.add('active')
+        break
+      }
+    }, {
+      root: null,
+      rootMargin: '-20% 0px -60% 0px',
+      threshold: 0,
+    })
+
+    const headers = getSectionNodes()
+    for (const node of headers) {
+      const text = node.textContent || ''
+      if (matchSectionByHeaderText(text)) {
+        observer.observe(node)
+      }
+    }
+  }
+
+  const mutationObserver = new MutationObserver(() => {
+    window.setTimeout(refreshActive, 200)
+  })
+  mutationObserver.observe(document.body, { childList: true, subtree: true })
+
+  window.setTimeout(refreshActive, 300)
+
+  return () => {
+    observer?.disconnect()
+    mutationObserver.disconnect()
+    root.remove()
+  }
+}
+
+const FactCheckDetailsLoader = defineComponent({
+  name: 'FactCheckDetailsLoader',
+  setup() {
+    const pluginName = inject<ComputedRef<string>>('plugin:name')
+    const isOwn = computed(() => {
+      const current = pluginName?.value
+      return !!current && PLUGIN_NAMES.has(current)
+    })
+
+    let dispose: (() => void) | null = null
+
+    const tryMount = () => {
+      dispose?.()
+      dispose = null
+      if (!isOwn.value) return
+      dispose = mountFloatingNav()
+    }
+
+    onMounted(tryMount)
+    watch(isOwn, tryMount)
+    onBeforeUnmount(() => dispose?.())
+    return () => h('div', { style: { display: 'none' } })
+  },
+})
+
+export default (ctx: Context) => {
+  ctx.slot({
+    type: 'plugin-details',
+    component: FactCheckDetailsLoader,
+    order: -999,
+  })
+}