RAG 工具配置

本文引用的源码文件

本文引用的文件

引言

本文件面向 AI Helper 扩展（Manifest V3，版本 2.3.1）与独立本地 Agent（Node.js，版本 2.3.1），系统性说明 RAG（检索增强生成）工具的配置、动态注册机制、知识库选择界面、状态管理、配置项、以及扩展端与 Agent 端的通信协议。文档同时给出添加新知识库源、调整检索参数和优化查询性能的实践路径，并解释错误处理策略与运行时约束。

项目结构

RAG 能力横跨两个进程：

扩展端（src/）：负责工具定义、动态注册、选项页面板、侧边栏 @ 知识库选择、与 Agent 的 HTTP 调用封装。
Agent 端（agent/src/rag/）：负责知识库生命周期、文档解析与分块、向量嵌入、向量存储、检索、安装引导与能力检测。

graph TB
subgraph "扩展端"
BG["Background<br/>tool-executor.js"]
OPT["Options 面板<br/>knowledge-panel.js / toolbox-rag.js"]
SP["Side Panel<br/>agent-at-selector.js"]
end
subgraph "Agent 端"
SRV["HTTP Server<br/>/api/status, /api/rag/*"]
MGR["RagManager<br/>manager.js"]
CFG["RAG 配置<br/>config.js"]
SRCH["Searcher<br/>searcher.js"]
STORE["VectraStore<br/>store/vectra.js"]
end
BG --> |"fetch /api/status"| SRV
BG --> |"execute knowledge_*"| MGR
OPT --> |"agentApi /api/rag/*"| SRV
SP --> |"chrome.runtime.sendMessage RAG_LIST_COLLECTIONS"| BG
BG --> |"转发 Agent RAG API"| SRV
MGR --> CFG
MGR --> SRCH
SRCH --> STORE

图表来源

章节来源

核心组件

RAG 工具定义：src/background/tools/rag-tools.js 暴露 RAG_TOOLS，包含 knowledge_search、knowledge_ingest、knowledge_list。
Background 动态注册：src/background/tool-executor.js 中的 loadRagTools、unloadRagTools、syncRagToolsToStorage 负责将 RAG 工具注入全局工具表并同步到 storage.ragTools。
选项页 RAG 能力面板：src/options/toolbox-rag.js 读取 /api/status 的 ragAvailable，展示安装引导、进度轮询与一键安装。
知识库管理面板：src/options/knowledge-panel.js 负责门控、列表渲染、创建/编辑/导入/搜索/启停/删除等交互。
侧边栏知识库选择：src/side_panel/agent-at-selector.js 提供 @知识库 列表、多选引用、禁用库手动引用提示。
Agent RAG 核心：agent/src/rag/config.js、manager.js、searcher.js 实现配置、生命周期、检索与阈值旁路探测。

章节来源

架构总览

RAG 工具在扩展端是“按需启用”的动态工具：只有当用户开启总开关且当前 Agent 支持 RAG 时，Background 才会把 RAG 工具注入执行器；否则卸载并清空 storage.ragTools。Agent 端通过 /api/status 返回 ragAvailable，并在 /api/rag/* 路由中按需加载 RAG 模块；未就绪时返回 503。

sequenceDiagram
participant User as "用户"
participant Options as "Options 面板"
participant BG as "Background"
participant Agent as "Agent Server"
participant Manager as "RagManager"
User->>Options : 打开「知识库」标签
Options->>Agent : GET /api/status
Agent-->>Options : { ragAvailable, nodeVersion }
alt ragAvailable=true
Options->>BG : 通知 RELOAD_RAG_TOOLS
BG->>Agent : GET /api/status校验 ragAvailable
BG->>BG : loadRagTools() 注入 RAG_TOOLS
BG->>BG : syncRagToolsToStorage()
BG-->>Options : 工具已加载
else ragAvailable=false
Options->>Options : 显示安装引导或不可用提示
end

图表来源

详细组件分析

1. RAG 工具动态注册与缓存同步

工具定义：RAG_TOOLS 声明三个工具，类别为 knowledge，执行位置为 background。
加载流程：
- 检查全局开关 ragEnabled。
- 若关闭则调用内部卸载逻辑。
- 通过 checkAgentRagAvailable() 请求活跃 Agent 的 /api/status，仅当 ragAvailable === true 才继续。
- 遍历 RAG_TOOLS，注入 RAW_TOOLS、BUILTIN_TOOLS、TOOL_EXECUTION_MAP、TOOL_HANDLERS，并记录到 ragToolIds。
- 重建 Background 处理器映射后，调用 syncRagToolsToStorage() 写入 storage.ragTools。
卸载流程：
- 从 RAW_TOOLS、BUILTIN_TOOLS 移除对应条目。
- 清理 TOOL_EXECUTION_MAP、TOOL_HANDLERS。
- 重建处理器映射并同步 storage.ragTools。

flowchart TD
Start(["开始"]) --> CheckToggle["检查 ragEnabled"]
CheckToggle --> |false| UnloadInternal["unloadRagToolsInternal()"]
UnloadInternal --> End(["结束"])
CheckToggle --> |true| CheckAgent["checkAgentRagAvailable()"]
CheckAgent --> |false| End
CheckAgent --> |true| Register["注入 RAG_TOOLS 到全局工具表"]
Register --> Rebuild["rebuildBgHandlers()"]
Rebuild --> Sync["syncRagToolsToStorage()"]
Sync --> End

图表来源

章节来源

2. 知识库选择界面

选项页知识库面板：
- 门控：Agent 未连接、总开关关闭、Agent 能力未就绪分别渲染不同引导。
- 列表：卡片展示名称、描述、统计（文档数/分块数）、模型信息、操作按钮（编辑、导入、检索测试、文档管理、启停、删除）。
- 搜索与筛选：支持按名称/描述模糊搜索，按启用状态筛选。
侧边栏 @ 知识库选择：
- 通过 fetchKnowledgeCollections() 经 Background 转发 Agent RAG API，带 TTL 缓存。
- 列表排序：启用库在前、停用库在后。
- 多选引用：再次点击取消；禁用库仍可手动引用，chip 显示“手动引用”。
- 已选标记：.picked、.agent-at-active 高亮。

flowchart TD
Open["@ 触发知识库选择"] --> Fetch["fetchKnowledgeCollections(force=false)"]
Fetch --> Enabled{"ragEnabled=true?"}
Enabled --> |否| ShowDisabled["显示 '知识检索已关闭'"]
Enabled --> |是| CacheHit{"TTL 命中?"}
CacheHit --> |是| RenderList["渲染知识库列表"]
CacheHit --> |否| CallBG["sendMessage RAG_LIST_COLLECTIONS"]
CallBG --> Sort["启用库在前，停用库在后"]
Sort --> RenderList
RenderList --> Select["selectKnowledgeByAt(kb)"]
Select --> UpdateChips["renderKnowledgeIndicator()"]

图表来源

章节来源

3. RAG 工具状态管理

知识库连接状态：
- 扩展端通过 loadRagStatus() 读取 /api/status 的 ragAvailable 与 nodeVersion。
- 选项页根据 connected、unreachable、ragAvailable、install.running 渲染不同状态区。
索引构建进度：
- Agent 端 RagManager 维护 _ingestProgress Map，前端轮询 /api/rag/collections/{id}/ingest/status。
- 进度阶段包括 parsing、chunking、embedding、storing、rebuilding，完成后 done=true。
查询性能监控：
- Searcher 默认 topK=5、threshold=0.3；对超大 topK 进行上界限制（SEARCH_TOPK_MAX=50）。
- 关键词通道扫描上限 KEYWORD_SCAN_LIMIT=20000，避免大库检索卡顿。
- 旁路探测：过滤为空时放宽阈值（threshold-0.2），区分“无数据”与“被过滤”。

stateDiagram-v2
[*] --> Idle
Idle --> Connecting : "GET /api/status"
Connecting --> Ready : "ragAvailable=true"
Connecting --> Installing : "install.running"
Installing --> Ready : "安装成功"
Installing --> Error : "安装失败"
Ready --> Searching : "knowledge_search"
Searching --> Result : "hasContext/fallback"
Result --> Searching

图表来源

章节来源

4. RAG 工具配置选项

向量模型选择：
- 本地模式：默认 Xenova/bge-small-zh-v1.5，512 维，非对称检索需查询前缀。
- 远端模式：openai-compat，需 endpoint、apiKey、modelName，可选 dimensions。
- 前端提供连通性测试，自动探测并回填 dimensions。
相似度阈值设置：
- 默认 threshold=0.3；Searcher 钳制到 [-1,1]；旁路探测使用 threshold-0.2。
分块策略调整：
- 默认 chunkSize=400、overlap=80；超过 CHUNK_SIZE_WARN_LIMIT=500 告警。
- 变更分块参数会触发索引重建。
其他配置：
- 知识库启用/停用：影响 LLM 自主检索，不影响 @ 手动引用。
- URL 导入内网放行策略：由 config.ragUrlIngest 控制，构造参数可注入覆盖。

classDiagram
class RagConfig {
+string RAG_ROOT
+string COLLECTIONS_REGISTRY
+string MODELS_DIR
+object DEFAULT_EMBEDDING_CONFIG
+object DEFAULT_CHUNK_CONFIG
+number CHUNK_SIZE_WARN_LIMIT
+object DEFAULT_SEARCH_CONFIG
+number EMBED_BATCH_SIZE
}
class RagManager {
+createCollection(input)
+updateCollection(id, input)
+deleteCollection(id)
+toggleCollection(id)
+ingestText(id, input)
+ingestFile(id, input)
+getIngestProgress(id)
}
class Searcher {
+search(query, options)
-_boostByKeywords(query, candidates)
}
RagManager --> RagConfig : "使用默认配置"
Searcher --> RagConfig : "读取默认检索参数"

图表来源

章节来源

5. RAG 工具与 Agent 服务的通信协议

能力探测：
- 扩展端调用 /api/status，读取 ragAvailable、nodeVersion。
- Agent 启动时检测 Node 版本与依赖，返回 ragAvailable。
安装引导：
- 前端调用 /api/rag/install 启动安装，轮询 /api/rag/install/status。
- 安装成功后通知 Background 重新加载 RAG 工具。
知识库操作：
- 列表：GET /api/rag/collections。
- 创建：POST /api/rag/collections。
- 更新：PUT /api/rag/collections/{id}。
- 删除：DELETE /api/rag/collections/{id}。
- 启停：POST /api/rag/collections/{id}/toggle。
- 导入进度：GET /api/rag/collections/{id}/ingest/status。
- 向量连通性测试：POST /api/rag/test-embedding。
错误处理：
- Agent 未连接或不可达：前端显示“Agent 未连接”或“无法获取代理状态”。
- 依赖未安装：显示包清单、命令、一键安装按钮。
- 安装失败：展示错误与日志尾部，支持重试与重新检测。
- 知识库操作失败：统一 toast 提示错误消息。

sequenceDiagram
participant FE as "前端"
participant AG as "Agent"
participant BG as "Background"
FE->>AG : GET /api/status
AG-->>FE : { ragAvailable, nodeVersion }
alt 依赖未安装
FE->>AG : POST /api/rag/install
AG-->>FE : { started : true }
loop 每 2s
FE->>AG : GET /api/rag/install/status
AG-->>FE : { running, logTail }
end
FE->>BG : chrome.runtime.sendMessage(RELOAD_RAG_TOOLS)
else 能力就绪
FE->>BG : 直接启用 RAG 工具
end

图表来源

章节来源

依赖关系分析

扩展端依赖：
- chrome.storage.local：读写 ragEnabled、ragTools。
- chrome.runtime.sendMessage：与 Background 通信（RELOAD_RAG_TOOLS、RAG_LIST_COLLECTIONS）。
- agentApi：封装对 Agent HTTP 接口的调用。
Agent 端依赖：
- fs/promises：文件系统操作（注册表、索引、文档备份）。
- crypto：随机 ID 生成。
- security.js：路径沙箱校验。
- vector store：VectraStore 提供向量存储与检索。
- embedding provider：本地 transformers.js 或远端 OpenAI 兼容接口。

graph LR
BG["Background"] --> Storage["chrome.storage.local"]
BG --> Runtime["chrome.runtime"]
BG --> AgentAPI["Agent HTTP API"]
OPT["Options"] --> AgentAPI
SP["Side Panel"] --> BG
MGR["RagManager"] --> FS["fs/promises"]
MGR --> Security["security.js"]
MGR --> Store["VectraStore"]
MGR --> Embed["EmbeddingProvider"]

图表来源

章节来源

性能与容量特性

向量存储规模：
- 小型：1,000 分块，~3MB 磁盘，~5MB 内存，<1ms 查询延迟。
- 中型：10,000 分块，~30MB 磁盘，~50MB 内存，1-5ms 查询延迟。
- 大型：100,000 分块，~300MB 磁盘，~500MB 内存，5-50ms 查询延迟。
- 超大：1,000,000 分块，~3GB 磁盘，~5GB 内存，50-500ms 查询延迟。
检索优化：
- topK 上界限制为 50，候选集按 topK*2 进入排序与关键词扫描。
- 关键词通道扫描上限 20,000 分块，避免大库检索卡顿。
- 旁路探测区分“无数据”与“被过滤”，提升召回体验。
模型与批大小：
- 默认本地模型 512 维，查询前缀用于非对称检索。
- 远端模式批量大小固定 10，兼容平台单次批量上限。

章节来源

故障排查指南

Agent 未连接：
- 现象：选项页显示“Agent 未连接”。
- 处理：先连接 Agent，再回到「知识库」标签。
RAG 功能未启用：
- 现象：选项页显示“知识检索功能未启用”。
- 处理：开启总开关。
Agent 能力未就绪：
- 现象：选项页显示“Agent 能力未就绪”，并就地展示安装引导。
- 处理：点击“一键安装”或复制命令手动安装依赖。
安装失败：
- 现象：toast 提示安装失败，展示错误与日志尾部。
- 处理：点击“重新检测”或再次尝试安装。
知识库操作失败：
- 现象：toast 提示操作失败，包含错误消息。
- 处理：检查知识库是否存在、是否处于进行中任务、网络是否可达。

章节来源

结论

RAG 工具在扩展端采用动态注册机制，仅在总开关开启且 Agent 支持 RAG 时生效；Agent 端通过能力检测与按需路由确保 RAG 作为可选依赖不阻塞主流程。知识库管理面板提供完整的生命周期操作，侧边栏 @ 选择器支持多选与禁用库手动引用。配置项涵盖向量模型、相似度阈值、分块策略，并提供连通性测试与进度轮询。扩展端与 Agent 端通过 HTTP 接口通信，具备完善的错误处理与安装引导。

附录：扩展知识库源与检索参数示例

添加新的知识库源：
- 在选项页点击“新建知识库”，填写名称、描述，选择向量模型（本地或远端），必要时测试连通性并回填维度。
- 如需外接 RAG 服务，可通过 MCP 服务器接入，无需开发适配器。
配置检索参数：
- 在导入弹窗中调整分块大小与重叠值；注意中文 512 token 上限，建议保持默认或略调。
- 在搜索时调整 topK 与 threshold；注意 topK 上界为 50，threshold 范围 [-1,1]。
优化查询性能：
- 合理设置 topK，避免过大导致候选集膨胀。
- 使用关键词命中增强，但注意高频词可能被剔除。
- 对于超大知识库（>10 万分块），考虑迁移至外接方案（如 Qdrant）。

章节来源

消息流与工具调用

RAG 数据处理管道

工具面板集成

聊天管理系统

主题与国际化系统

UI 组件库

Markdown 渲染引擎

RAG 工具配置

目录

引言

项目结构

核心组件

架构总览

详细组件分析

1. RAG 工具动态注册与缓存同步

2. 知识库选择界面

3. RAG 工具状态管理

4. RAG 工具配置选项

5. RAG 工具与 Agent 服务的通信协议

依赖关系分析

性能与容量特性

故障排查指南

结论

附录：扩展知识库源与检索参数示例

Markdown 渲染引擎

RAG 工具配置 ​

目录 ​

引言 ​

项目结构 ​

核心组件 ​

架构总览 ​

详细组件分析 ​

1. RAG 工具动态注册与缓存同步 ​

2. 知识库选择界面 ​

3. RAG 工具状态管理 ​

4. RAG 工具配置选项 ​

5. RAG 工具与 Agent 服务的通信协议 ​

依赖关系分析 ​

性能与容量特性 ​

故障排查指南 ​

结论 ​

附录：扩展知识库源与检索参数示例 ​

RAG 工具配置

目录

引言

项目结构

核心组件

架构总览

详细组件分析

1. RAG 工具动态注册与缓存同步

2. 知识库选择界面

3. RAG 工具状态管理

4. RAG 工具配置选项

5. RAG 工具与 Agent 服务的通信协议

依赖关系分析

性能与容量特性

故障排查指南

结论

附录：扩展知识库源与检索参数示例