AI Helper 文档中心

主题

数据流设计 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构与数据边界
  3. 端到端数据流总览
  4. 核心组件与职责
  5. 架构视图
  6. 详细数据流分析
  7. 依赖关系分析
  8. 性能与容量特征
  9. 故障排查指南
  10. 结论与建议
  11. 附录：关键状态与配置表

引言 ​

本文件面向“从用户输入到 LLM 响应”的完整数据流转，覆盖消息序列化、工具调用结果聚合、上下文压缩、会话状态管理、持久化存储、RAG 知识检索、Token 统计与上下文窗口管理。系统采用双进程架构：Chrome 扩展端（Manifest V3，Service Worker + Side Panel）与独立本地 Agent 进程；两端通过 HTTP/WebSocket 通信契约协作。Agent 负责文件系统、命令执行、长期记忆与 RAG 索引；扩展端负责 ReAct 推理循环、工具调度、界面交互、会话与 Token 统计。

项目结构与数据边界 ​

  • 扩展端 background 是 Service Worker 入口，承担任务编排、保活、自动续跑、ReAct 循环、工具注册、Token 统计和 IndexedDB 访问。
  • side panel 负责聊天 UI、知识库引用注入、流式渲染、会话加载与保存。
  • agent 进程提供 HTTP API 与 WebSocket，暴露文件、命令、MCP、Skill、RAG、日志等能力。
  • 持久化层以 IndexedDB 为主，checkpoint 使用 IndexedDB + chrome.storage.local 双写降级。
graph TB
subgraph "扩展端"
SP["侧边栏<br/>聊天与知识库注入"]
BG["后台服务<br/>ReAct/工具/保活"]
IDB["IndexedDB<br/>会话/Checkpoint/Token"]
end
subgraph "Agent 进程"
HTTP["HTTP 路由<br/>认证/文件/命令/MCP/Skill/RAG"]
WS["WebSocket<br/>命令输出流"]
FS["文件系统/工作目录"]
RAG["RAG 索引/向量存储"]
end
SP --> |消息/配置/操作| BG
BG --> |HTTP/WebSocket| HTTP
BG --> IDB
HTTP --> FS
HTTP --> RAG
HTTP --> WS

图表来源

章节来源

端到端数据流总览 ​

用户输入在侧边栏组装后进入后台 ReAct 循环；后台根据模型能力与工具集选择工具，必要时调用 Agent 的 MCP/Skill/RAG/文件/命令接口；LLM 返回流式内容，后台聚合工具结果、维护执行日志、进行上下文预算评估与压缩；最终将消息写入会话并持久化，同时记录 Token 使用。

sequenceDiagram
participant U as "用户"
participant SP as "侧边栏"
participant BG as "后台 ReAct"
participant AG as "Agent HTTP/WSS"
participant DB as "IndexedDB"
participant LLM as "LLM 提供商"
U->>SP : "输入问题/附件/知识库引用"
SP->>BG : "发送 CALL_API / 构建知识库上下文"
BG->>LLM : "构造消息+工具定义，发起流式请求"
LLM-->>BG : "assistant(tool_calls)/文本片段"
BG->>AG : "调用工具MCP/Skill/RAG/FS/Exec"
AG-->>BG : "工具结果/流式输出"
BG->>BG : "聚合结果/上下文预算/压缩摘要"
BG->>DB : "保存会话/Checkpoint/Token 统计"
BG-->>SP : "流式消息/执行日志/完成态"
SP-->>U : "渲染结果/可恢复提示"

图表来源

章节来源

核心组件与职责 ​

  • 侧边栏聊天管理：组装用户输入、知识库引用、流式渲染、会话加载与保存、上下文指标。
  • 后台 ReAct 循环：推理迭代、工具预筛选与执行、流式控制、循环检测、确认交互、检查点持久化。
  • 工具执行器：动态注册 MCP/RAG 工具、参数压缩、执行代理、审计与活动记录。
  • Agent 客户端：配对、认证、HTTP/WebSocket 封装、可达性缓存、多代理支持。
  • Agent 服务器：HTTP 路由、认证、CORS、文件上传/下载、命令执行、MCP/Skill/RAG 集成。
  • 上下文压缩：批量摘要生成、结构化历史摘要、手动压缩摘要。
  • Token 统计与估算：消息 token 估算、上下文窗口预算、校准因子、统计持久化。
  • 存储层：会话、归档、UI 原型、Token 统计、ReAct Checkpoint、迁移与升级。

章节来源

架构视图 ​

扩展端与 Agent 端的通信契约是数据流的核心：所有需认证的请求携带 Bearer Token，GET/POST 统一由 local-agent-client 封装；文件上传走 multipart/form-data 或流式上传；命令执行通过 WebSocket 推送实时输出。

classDiagram
class ChatManager {
+buildKnowledgeContextText()
+loadChatHistory()
+saveChatHistory()
}
class ReactLoop {
+reactLoop()
+resumeReactLoopFromCheckpoint()
+requestToolConfirmation()
}
class ToolExecutor {
+loadMcpTools()
+executeKnowledgeSearch()
+mergeForcedMcpTools()
}
class LocalAgentClient {
+agentRequest()
+createExecWebSocket()
+getMcpTools()
+callMcpTool()
}
class AgentServer {
+startServer()
+handleRequest()
+parseBody()
+parseMultipartBody()
}
class Storage {
+withStore()
+saveReactCheckpoint()
+recordTokenCall()
}
ChatManager --> ReactLoop : "触发推理"
ReactLoop --> ToolExecutor : "工具调度"
ToolExecutor --> LocalAgentClient : "远程工具调用"
LocalAgentClient --> AgentServer : "HTTP/WebSocket"
ReactLoop --> Storage : "持久化"
ToolExecutor --> Storage : "审计/统计"

图表来源

章节来源

详细数据流分析 ​

消息序列化与工具调用结果聚合 ​

  • 侧边栏将用户输入与知识库引用组合为消息，必要时注入固定标记的知识库上下文文本。
  • 后台 ReAct 循环对 assistant(tool_calls) 与 tool 消息进行配对校验，过滤非法字段，修复缺失 tool_call_id 的情况。
  • 工具执行器动态注册 MCP/RAG 工具，压缩 schema 描述，合并强制下发的 MCP 服务工具，避免被预筛选丢弃。
  • Agent 客户端统一封装认证、超时、错误映射，附加 httpStatus 区分网络错误与业务错误。
flowchart TD
Start(["消息进入"]) --> BuildMsg["组装消息/知识库上下文"]
BuildMsg --> Validate["过滤内部字段/修复 tool_calls-tool 配对"]
Validate --> Preselect["工具预筛选/强制 MCP 补回"]
Preselect --> ExecTool["执行工具MCP/RAG/FS/Exec"]
ExecTool --> Aggregate["聚合结果/执行日志"]
Aggregate --> Budget["上下文预算评估"]
Budget --> End(["返回 LLM/持久化"])

图表来源

章节来源

上下文压缩算法 ​

  • 增量对话摘要：当 ReAct 上下文 token 超阈值时，批量提取最旧一轮轮次，构建 transcript，调用 LLM 生成结构化摘要（任务目标/已完成/关键事实/未决问题）。
  • 手动压缩摘要：用户显式触发，按 UI 语言生成摘要，失败不静默降级。
  • 预算裁剪：基于模型上下文窗口减去系统提示词、工具定义、输出预留，计算消息历史预算；从旧到新移除消息，保持 tool_calls/tool 配对。
flowchart TD
Enter(["上下文超限"]) --> Extract["提取最旧轮次/全部轮次"]
Extract --> Transcript["构建 transcript截断输入上限"]
Transcript --> Summarize["LLM 批量摘要结构化模板"]
Summarize --> Inject["注入摘要/保留最近消息"]
Inject --> BudgetCheck{"是否仍超限？"}
BudgetCheck --> |是| Trim["按预算裁剪历史保留 system/配对"]
BudgetCheck --> |否| Done(["完成"])
Trim --> Done

图表来源

章节来源

会话状态管理与持久化 ​

  • 会话状态保存在 IndexedDB，包含 messageHistory、model、temperature、topP、enabledTools、agentId、contextCompaction 等。
  • ReAct Checkpoint 双写策略：先写 chrome.storage.local（可靠），再尝试 IndexedDB（性能优化）；读取优先 IndexedDB，失败降级到 storage.local。
  • 自动清理过期 checkpoint（TTL 7 天），SW 启动时重建定时任务闹钟并从 DB 恢复。
stateDiagram-v2
[*] --> 活跃
活跃 --> 已归档 : "归档当前会话"
已归档 --> 活跃 : "恢复归档会话"
活跃 --> 分叉 : "复制会话/消息级分叉"
分叉 --> 活跃 : "切换至新会话"
活跃 --> 删除 : "删除会话"
删除 --> [*]

图表来源

章节来源

RAG 知识检索数据管道 ​

  • 侧边栏通过 chrome.runtime.sendMessage 触发 RAG_SEARCH，后端查询 Agent 的 RAG 集合，返回命中结果。
  • 命中内容按 collectionId 分组统计，注入固定中文标记的知识库上下文文本，单条命中最大字符数限制。
  • Agent 端暴露 /api/rag/collections 与检索接口，供工具执行器调用。
sequenceDiagram
participant SP as "侧边栏"
participant BG as "后台"
participant AG as "Agent RAG"
participant VS as "向量索引"
SP->>BG : "RAG_SEARCH(query, refs)"
BG->>AG : "检索知识库collectionIds/topK"
AG->>VS : "语义检索/相似度排序"
VS-->>AG : "chunks/scores"
AG-->>BG : "results"
BG-->>SP : "构建知识库上下文文本"

图表来源

章节来源

Token 计数统计与上下文窗口管理 ​

  • Token 估算：中文约 1.5 字符/token，英文约 4 字符/token；图片按分辨率 tile 公式估算，避免 Base64 高估。
  • 上下文窗口：内置模型映射 + 自定义模型配置 + 全局覆盖；计算消息预算 = 窗口 - 系统提示词 - 工具定义 - 输出预留。
  • 校准因子：基于 API 返回 prompt_tokens 与估算值对比，EWMA 平滑修正估算偏差。
  • 统计持久化：每次 API 调用后记录 sessionId/model/usage/callType，存入 IndexedDB。
flowchart TD
Estimate["估算消息 token"] --> Calibrate["校准因子更新EWMA"]
Calibrate --> Budget["计算消息预算"]
Budget --> Trim["按需裁剪历史"]
Trim --> Record["记录 Token 统计"]
Record --> Persist["IndexedDB 持久化"]

图表来源

章节来源

依赖关系分析 ​

  • 扩展端依赖 Agent 提供的 HTTP/WebSocket 接口，所有认证请求携带 Bearer Token。
  • 工具执行器依赖 MCP/Skill/RAG 的动态注册与元信息，支持会话级强制下发。
  • ReAct 循环依赖 token-counter 的估算与裁剪、stream-controller 的流式控制、notifier 的交互提醒。
  • 存储层依赖 IndexedDB 事务包装 withStore，具备连接恢复重试与 store 不存在时的自动重建。
graph LR
BG["后台 ReAct"] --> TC["Token 估算/裁剪"]
BG --> SC["流式控制器"]
BG --> ST["存储层"]
BG --> AGC["Agent 客户端"]
AGC --> AS["Agent 服务器"]
TE["工具执行器"] --> MC["MCP/Skill/RAG"]
TE --> ST

图表来源

章节来源

性能与容量特征 ​

  • 消息日志内存窗口：执行日志仅保留最近 1000 条，防止长任务期间 SW 内存失控。
  • MCP schema 压缩：description 截断、properties 嵌套深度限制、参数数量上限，防止上下文膨胀。
  • RAG 命中内容截断：单条命中最大字符数限制，避免注入过大上下文。
  • Token 估算校准：EWMA 平滑因子，样本不足时不校准，避免单次异常波动。
  • 文件上传大小限制：JSON body 解析上限 200MB，流式上传支持原文件 200MB。

章节来源

故障排查指南 ​

  • Service Worker 生命周期：keepalive port 重连检测 SW 重启，若存在 checkpoint 则自动续跑；面板断开延迟复核避免误报。
  • IndexedDB 升级阻塞：onversionchange 主动关闭连接，withStore 检测 store 不存在时重置连接并重试。
  • Checkpoint 双写降级：IndexedDB 不可用时 fallback 到 chrome.storage.local，读取优先 IndexedDB。
  • 工具确认通道：关联键唯一性保证并发安全，面板关闭或超时默认拒绝（fail-closed）。
  • Agent 可达性缓存：已知不可达时直接返回错误，避免阻塞等待超时。

章节来源

结论与建议 ​

  • 数据流设计围绕“扩展端编排 + Agent 能力 + 持久化保障”展开，强调认证、安全、可恢复性与性能。
  • 建议在生产环境中监控 IndexedDB 升级事件、Checkpoint 双写成功率、Token 估算校准因子变化。
  • 对于大规模 RAG 场景，建议关注向量索引构建耗时、检索命中率与注入上下文大小。
  • 对于长任务，建议启用自动续跑与执行日志内存裁剪，避免 SW 终止导致任务丢失。

[本节为总结性内容，不直接分析具体文件]

附录：关键状态与配置表 ​

关键状态字段 ​

  • 会话状态：activeSessionId、messageHistory、model、temperature、topP、enabledTools、agentId、contextCompaction。
  • ReAct Checkpoint：sessionId、currentMessages、executionLog、iteration、globalIteration、subtaskPlan、model、apiParams、tabId、callId、interruptedReason、createdAt、updatedAt。
  • Token 统计：sessionId、model、promptTokens、completionTokens、totalTokens、contextWindow、contextUsageRate、callType。

章节来源

配置选项 ​

  • 模型上下文窗口：内置映射 + 自定义模型配置 + 全局覆盖。
  • 消息预算：窗口 - 系统提示词 - 工具定义 - 输出预留。
  • RAG 开关：ragEnabled 控制知识库检索是否启用。
  • MCP 开关：mcpEnabled 控制 MCP 工具动态注册。

章节来源