AI Helper 文档中心

主题

消息生命周期管理 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与内存优化
  8. 故障诊断与监控
  9. 安全与隐私
  10. 结论

引言 ​

本文围绕“从用户输入到最终响应”的完整消息生命周期，系统性梳理扩展端（Chrome 侧边栏/Service Worker）与本地 Agent 之间的协作机制。重点覆盖：消息创建、路由分发、ReAct 推理循环、状态跟踪、持久化、会话上下文压缩、去重与缓存、优先级调度、队列管理、消息格式与版本兼容、统计与调试、以及安全与隐私保护。

项目结构 ​

本项目采用双进程架构：

  • Chrome 扩展端（Manifest V3 Service Worker + Side Panel）：负责 UI、消息编排、流式渲染、会话与 Token 预算、任务恢复、与 Agent 通信。
  • 独立本地 Agent（Node.js）：提供文件读写、命令执行、长期记忆与 RAG、MCP 工具注册等能力。
graph TB
subgraph "浏览器扩展端"
SP["Side Panel<br/>chat-manager / chat-streaming"]
BG["Background Service Worker<br/>index / react-loop"]
DB["IndexedDB<br/>会话/Checkpoint"]
end
subgraph "本地Agent端"
AG_HTTP["HTTP API<br/>fs/exec/mcp/skill/rag"]
AG_WS["WebSocket<br/>命令实时输出"]
end
SP --> |chrome.runtime.sendMessage| BG
BG --> |HTTP/WebSocket| AG_HTTP
BG --> |SSE/流式| SP
BG --> DB
SP --> DB

图表来源

章节来源

核心组件 ​

  • 消息入口与路由：Side Panel 发起 CALL_API，Background 接收并进入 ReAct 循环；支持 RESUME_REACT 恢复中断任务。
  • ReAct 推理循环：工具选择、调用、结果聚合、反思评估、循环检测、超时控制、子任务拆分与并行策略。
  • 流式输出：SSE 流式分片、思考过程可视化、工具卡片、滚动与交互控制。
  • 会话与持久化：会话 CRUD、归档、分叉、滚动位置、上下文压缩记录、生成态标记。
  • Token 预算与上下文压缩：模型上下文窗口推断、消息预算分配、历史裁剪、引用内容压缩、自动压缩决策。
  • Agent 客户端：配对认证、HTTP/WebSocket 封装、可达性缓存、多代理切换、敏感操作分级。

章节来源

架构总览 ​

下图展示一次典型请求的消息流转：用户输入 → Side Panel 构建上下文 → Background 路由 → ReAct 循环 → Agent 工具执行 → 流式返回 → Side Panel 渲染与持久化。

sequenceDiagram
participant U as "用户"
participant SP as "Side Panel<br/>chat-manager"
participant BG as "Background<br/>react-loop"
participant AG as "Agent<br/>HTTP/WebSocket"
participant DB as "IndexedDB"
U->>SP : 输入消息/附件/上下文
SP->>BG : 发送 CALL_API含 sessionId、模型参数
BG->>BG : 工具预筛选/记忆注入/预算计算
BG->>AG : 调用 LLM/MCP/RAG/文件/命令
AG-->>BG : 流式 SSE 数据块
BG-->>SP : STREAM_START/STREAM_CHUNK/STREAM_TOOL_RESULT
SP->>SP : 增量渲染/滚动/交互
BG->>DB : 写入 Checkpoint/执行日志
SP->>DB : 保存会话/消息历史
BG-->>SP : API_COMPLETE最终结果/反思评分

图表来源

详细组件分析 ​

消息创建与路由分发 ​

  • Side Panel 在发送前进行上下文组装：系统提示词、工具定义、历史消息选择、知识库检索注入、引用/选中内容压缩。
  • Background 接收后进入 reactLoop，维护 activeReactLoops 以检测 SW 重启；通过 keepalive port 定向下发确认弹窗与状态更新。
  • 支持 RESUME_REACT：从 IndexedDB 恢复 checkpoint，清理不完整 tool_calls/tool 配对，注入恢复提示，继续执行。
flowchart TD
Start(["收到 CALL_API"]) --> BuildCtx["构建上下文<br/>系统提示/工具/历史/知识"]
BuildCtx --> Budget["Token 预算与压力评估"]
Budget --> Loop["进入 ReAct 循环"]
Loop --> ToolSel["工具预筛选/选择"]
ToolSel --> Exec["执行工具Agent HTTP/WebSocket"]
Exec --> Stream["流式回传SSE"]
Stream --> Persist["持久化 Checkpoint/日志"]
Persist --> End(["完成/反思/反馈"])

图表来源

章节来源

状态跟踪与持久化存储 ​

  • Checkpoint：按 sessionId 保存 currentMessages、iteration、taskState、subtaskPlan、subtaskProgress、notesState 等，失败时自动续跑。
  • 会话存储：会话列表、活跃会话、消息历史、上下文压缩记录、滚动位置、生成态标记；删除会话时同步清理 checkpoint 与收藏。
  • 恢复流程：页面加载或用户点击“继续执行”，复用 callApi 基础设施，传入 resumeFromCheckpoint=true，走相同流式渲染路径。
classDiagram
class Session {
+string id
+string title
+Array messageHistory
+object contextCompaction
+boolean isGenerating
+timestamp updatedAt
}
class Checkpoint {
+string sessionId
+number iteration
+Array currentMessages
+object taskState
+object subtaskPlan
+object subtaskProgress
+timestamp updatedAt
}
Session --> Checkpoint : "删除会话时清理"

图表来源

章节来源

会话状态管理与上下文压缩 ​

  • 会话级上下文压缩记录（activeCompaction）包含摘要、压缩范围、节省 token、模型、时间戳与 revision。
  • 自动压缩：基于使用率阈值（默认 85%）、最小待处理消息数、是否正在生成、是否启用隔离聊天等条件触发。
  • 压缩时机：发送前尝试自动压缩；手动压缩可撤销（若未发送新消息）。
  • 压缩效果：将旧轮次替换为结构化摘要，保留关键信息，降低后续请求上下文占用。
flowchart TD
A["发送前计算上下文使用率"] --> B{"超过阈值？"}
B -- 否 --> C["直接发送"]
B -- 是 --> D{"满足自动压缩条件？"}
D -- 否 --> C
D -- 是 --> E["执行压缩LLM 生成摘要"]
E --> F["更新 activeCompaction 并持久化"]
F --> C

图表来源

章节来源

消息去重、重复请求检测与缓存 ​

  • 工具结果缓存：单次 ReAct 循环内缓存工具结果，TTL 60s，上限 30 条，避免重复工具调用。
  • 确认弹窗去重：Side Panel 对可见/排队中的确认项做同请求去重，防止 port 与广播重复投递导致吞掉后续请求。
  • 关联键唯一：后台为每次确认生成唯一关联键，即使模型复用 tool_call.id 也能区分不同命令。
  • MCP 工具查询缓存：Background 缓存 MCP 工具列表，减少网络请求。

章节来源

优先级调度、队列管理与资源分配 ​

  • 子任务拆分与策略：plan_task 可将复杂任务拆分为多个子任务，支持顺序/并行/依赖策略；同一轮中 plan_task 后其他工具调用被跳过。
  • 循环检测：多模式检测器识别重复无效操作、枚举循环、振荡、无进展滚动、预算耗尽等，达到阈值暂停任务并提示补充指导。
  • 超时控制：ReAct 循环总超时、工具执行超时、流式空闲超时；子任务继承父任务剩余时间预算。
  • 资源分配：执行日志内存窗口限制（1000 条），仅保留终态条目，避免长任务内存失控。

章节来源

消息格式规范、元数据结构与版本兼容 ​

  • 消息字段白名单：role、content、tool_calls、tool_call_id、reasoning_content 等；过滤内部字段，清洗非法 Unicode。
  • assistant(tool_calls)/tool 配对校验：确保 tool_call_id 与 tool_calls[].id 严格匹配，缺失则清理或丢弃。
  • 图片 content：移除 original_url/Base64，保留 width/height 用于 token 估算；发送前进一步清理非标准字段。
  • 迁移兼容：Agent 配置从旧格式迁移到新 pairedAgents 结构；会话导入/复制时重新生成 messageId，避免冲突。

章节来源

流式输出与交互体验 ​

  • 流式元素隔离：按 sessionId 隔离 DOM 与累积内容，避免多会话串台。
  • 智能滚动：区分程序滚动与用户上滚，支持“滚动到底部”按钮与 badge 提醒。
  • 思考过程可视化：每轮思考指示器、思考结果 badge、工具卡片、执行日志节点筛选。
  • 脱落后重连：STREAM_CHUNK 在元素脱落期间跳过 DOM 更新，重连时补全累积内容并修复残留指示器。

章节来源

依赖关系分析 ​

  • Background 依赖 Shared Token Counter 进行预算与裁剪；依赖 Stream Controller 管理 SSE 空闲超时；依赖 Local Agent Client 访问 Agent HTTP/WebSocket。
  • Side Panel 依赖 Chat Streaming 管理流式渲染；依赖 Session Store 持久化会话；依赖 Context Indicator 展示上下文使用详情。
  • Agent 客户端维护可达性缓存，已知不可达时快速失败，避免阻塞等待超时。
graph LR
BG["Background"] --> TC["Token Counter"]
BG --> SC["Stream Controller"]
BG --> AC["Agent Client"]
SP["Side Panel"] --> CS["Chat Streaming"]
SP --> SS["Session Store"]
SP --> CI["Context Indicator"]

图表来源

章节来源

性能与内存优化 ​

  • Token 估算校准：基于实际 prompt_tokens 与估算值对比，EWMA 平滑因子动态调整，提升估算准确性。
  • 图片 Token 估算：按分辨率 tile 公式计算，避免 Base64 字符串高估约 20 倍。
  • 历史裁剪优化：一次性预计算每条消息贡献值，增量扣减，替代 O(n²) 全量重估。
  • 执行日志内存窗口：仅保留最近 1000 条终态条目，释放进行中条目之外的旧数据，防止 SW 内存泄漏。
  • 流式滚动优化：requestAnimationFrame 补滚，避免内容高度变化导致的底部遮挡。

章节来源

故障诊断与监控 ​

  • SW 保活与自动续跑：keepalive port 维持 SW 存活；SW 重启检测并通过闹钟唤醒后扫描 checkpoint 自动续跑，耗尽次数后通知人工介入。
  • 面板断开延迟复核：端口断开后延迟判断，避免误判“仍在执行”；结合 activeReactLoops 与 isCancelled 综合判定。
  • 流式空闲超时：SSE 空闲超时自动中断，提示网络或服务提供商不稳定。
  • 调试信息：checkpoint 列表诊断、IndexedDB 自检、日志截断保留 subtask_plan 条目，便于历史视图还原计划。

章节来源

安全与隐私 ​

  • Agent 配对与认证：所有需认证请求携带 Bearer Token；配对码认证成功后存储加密 token，支持多代理切换。
  • 敏感操作确认：工具执行前弹出确认对话框，5 分钟超时默认拒绝；支持“当前任务放行”批量授权，但会清理以避免跨任务泄露。
  • 文件沙箱与命令分级：Agent 端安全模块对文件操作与命令执行进行分级管控；黑名单拦截、灰名单确认。
  • 数据脱敏：消息过滤移除 internal 字段，清洗非法 Unicode；图片 content 剥离 Base64，仅保留必要元数据。

章节来源

结论 ​

本方案通过 Side Panel 与 Background 的紧密协作，结合 Agent 端的强大能力，实现了从用户输入到最终响应的完整消息生命周期管理。系统在状态跟踪、持久化、上下文压缩、去重与缓存、优先级调度、流式渲染等方面提供了完善的实现，同时兼顾性能优化与安全隐私保护。未来可进一步扩展监控指标采集、自动化故障自愈与更细粒度的权限控制。