AI Helper 文档中心

主题

运行问题诊断 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能注意事项
  8. 故障排查指南
  9. 结论
  10. 附录：调试与日志清单

引言 ​

本文面向扩展端（Chrome MV3 Service Worker）与 Agent 端（Node.js）双进程架构的运行问题诊断，覆盖以下关键主题：

  • Service Worker 生命周期管理：空闲终止、保活、消息丢失与状态恢复。
  • 内存泄漏检测与分析：Chrome DevTools Memory 面板、堆快照对比、对象引用追踪。
  • 性能瓶颈识别：CPU 使用率、网络请求监控、渲染性能优化。
  • 日志收集与分析：扩展端日志、Agent 端审计日志、错误信息解读。
  • 调试工具使用：断点调试、变量检查、异步调用追踪。
  • 常见运行时错误与调优建议。

本项目为双进程架构：扩展端位于 src/，Agent 端位于 agent/src/server.js；两端版本号保持同步（当前以 2.3.1 为准）。扩展端通过本地 HTTP/WebSocket 调用 Agent 的文件读写、命令执行、长期记忆与 RAG 能力；Agent 源码修改后必须重启进程新接口才生效。

项目结构 ​

本仓库采用“功能域 + 进程边界”组织方式：

  • 扩展端 background：Service Worker 入口、任务调度、ReAct 循环、工具执行、Agent 客户端、持久化等。
  • 扩展端 side_panel：聊天界面、会话管理、流式输出、交互确认等。
  • 共享模块：logger、i18n、token 计数、主题等。
  • Agent 端 server：HTTP+WebSocket 路由、认证、安全、MCP/Skill/RAG、命令执行、日志等。
graph TB
subgraph "扩展端MV3 Service Worker"
BG["background/index.js<br/>SW 入口与保活"]
RL["react-loop.js<br/>ReAct 推理循环"]
TE["tool-executor.js<br/>工具定义与执行"]
LAC["local-agent-client.js<br/>Agent 通信客户端"]
DB["storage/db.js<br/>IndexedDB 封装"]
SP["side_panel/chat-manager.js<br/>聊天与交互"]
end
subgraph "Agent 端Node.js"
AS["server.js<br/>HTTP+WS 服务器"]
AE["executor.js<br/>命令执行器"]
AL["logger.js<br/>审计日志"]
end
BG --> RL
BG --> TE
BG --> LAC
BG --> DB
SP --> BG
LAC --> AS
AS --> AE
AS --> AL

图示来源

章节来源

核心组件 ​

  • Service Worker 入口与保活：负责 keepalive 端口注册、侧边栏可见性、自动续跑闹钟、过期 checkpoint 清理、SW 重启竞态防护。
  • ReAct 推理循环：心跳包装器、自动续跑开关、checkpoint 持久化与恢复、执行日志裁剪、多模式循环检测。
  • 工具执行与动态注册：内置工具、MCP 工具动态注入、RAG 工具、会话强制 MCP 服务合并。
  • Agent 通信客户端：配对、健康检查、HTTP/WebSocket 封装、可达性缓存、超时控制。
  • IndexedDB 持久化：会话、原型、Token 统计、ReAct checkpoint 双写策略（IndexedDB + chrome.storage.local）。
  • 聊天管理：会话加载、上下文气泡、知识库检索、子任务展示与过滤、恢复提示卡片。
  • Agent 服务端：HTTP 路由、认证、CORS、文件上传、命令执行、MCP/Skill/RAG、审计日志。
  • 命令执行器：跨平台 shell 选择、受管超时策略、输出缓冲截断、进程树终止。

章节来源

架构总览 ​

扩展端与 Agent 端的通信契约是系统核心：扩展端通过 local-agent-client 发起 HTTP/WebSocket 请求，Agent server 路由到具体子系统（fs/exec/mcp/skill/rag），并记录审计日志。Service Worker 的生命周期由 keepalive 长连接与 alarms 闹钟共同保障，ReAct 循环在 SW 被回收后可通过 auto-resume 机制从 checkpoint 恢复。

sequenceDiagram
participant UI as "Side Panel"
participant BG as "Background (SW)"
participant RL as "ReAct Loop"
participant LAC as "Agent Client"
participant AS as "Agent Server"
participant AE as "Executor"
UI->>BG : 发送任务CALL_API
BG->>RL : reactLoop()
RL->>LAC : agentRequest()/agentGet()
LAC->>AS : HTTP 请求Bearer Token
AS->>AE : 执行命令/文件操作/MCP/RAG
AE-->>AS : 结果/流式输出
AS-->>LAC : JSON 响应
LAC-->>RL : 返回数据
RL-->>BG : 更新执行日志/保存 checkpoint
BG-->>UI : 推送流式消息/完成通知

图示来源

详细组件分析 ​

Service Worker 生命周期与保活 ​

  • keepalive 端口：side panel 通过 chrome.runtime.connect 建立 keepalive-<sessionId> 长连接，防止 SW 空闲被杀；重连时检测 activeReactLoops 是否包含 sessionId，若缺失则判定 SW 静默重启并下发 SW_RESTARTED 消息。
  • 自动续跑：主任务期间注册 30s 周期闹钟（chrome.alarms），SW 被回收后由闹钟唤醒，扫描残留 checkpoint 自动续跑；对 user_cancelled/error 终态不自动续，超限次数后仅通知一次。
  • 侧边栏可见性与快捷键：维护 _openPanelsByWindow、_activeTabByWindow、_lastFocusedWindowId 等同步镜像，保证 open/close 在用户手势同步栈内调用。
flowchart TD
Start(["SW 启动"]) --> Keepalive["注册 keepalive 端口监听"]
Keepalive --> Reconnect{"重连且 sessionId 不在 activeReactLoops?"}
Reconnect --> |是| Detect["检测 checkpoint 并下发 SW_RESTARTED"]
Reconnect --> |否| Normal["正常处理"]
Start --> Alarm["注册 auto-resume 闹钟(30s)"]
Alarm --> Resume["扫描 checkpoint 并恢复执行"]
Resume --> End(["继续或人工介入"])

图示来源

章节来源

ReAct 循环与状态恢复 ​

  • 心跳包装器：reactLoop 开启 SW 保活心跳与自动续跑闹钟，finally 中停止；支持嵌套（子任务/子代理）。
  • Checkpoint 持久化：saveReactCheckpoint 先写 chrome.storage.local，再尝试 IndexedDB；失败降级但保证不丢数据；恢复时清理不完整 tool_calls/tool 消息对，注入恢复提示。
  • 执行日志裁剪：EXECUTION_LOG_MEMORY_LIMIT=1000，仅删除非 processing 的旧条目，保留 subtask_plan 以便历史视图展示未执行子任务。
flowchart TD
Enter(["进入 reactLoop"]) --> Heartbeat["启动 SW 心跳与自动续跑闹钟"]
Heartbeat --> Run["执行推理循环"]
Run --> Persist["保存 checkpoint双写策略"]
Persist --> Trim["裁剪执行日志窗口上限"]
Trim --> Exit(["退出并停止心跳/闹钟"])

图示来源

章节来源

工具执行与动态注册 ​

  • MCP 工具：loadMcpTools 并行获取工具列表与服务器状态，压缩 schema（限制嵌套深度、参数数量、description 长度），动态注入 RAW_TOOLS/BUILTIN_TOOLS/TOOL_HANDLERS，并重建 BG_HANDLERS。
  • 会话强制 MCP 服务：setSessionForcedMcpServers 与 mergeForcedMcpTools 确保预筛选不会丢弃用户显式指定的工具。
  • RAG 工具：knowledge_search 等工具按集合启用状态与禁用库进行门控。
classDiagram
class ToolExecutor {
+loadMcpTools()
+unloadMcpTools()
+mergeForcedMcpTools(selected, full, serverIds)
+getMcpToolMetaById(toolId)
}
class MCPRegistry {
+getMcpTools()
+callMcpTool(serverId, name, args)
}
ToolExecutor --> MCPRegistry : "调用"

图示来源

章节来源

Agent 通信客户端 ​

  • HTTP 封装：agentRequest/agentGet 统一添加 Bearer Token、Accept-Language，AbortController 超时控制，附加 httpStatus 区分 404 与离线。
  • WebSocket：createExecWebSocket 构造带 token 的 URL，onmessage 解析 JSON 或回退 raw；onclose/onerror 回调统一处理。
  • 可达性缓存：_agentReachability 按 agentId 缓存 true/false/null，不可达时直接返回错误避免阻塞。
sequenceDiagram
participant BG as "Background"
participant LAC as "Agent Client"
participant AS as "Agent Server"
BG->>LAC : agentRequest(path, body, method, timeoutMs)
LAC->>LAC : 校验配置/可达性缓存
LAC->>AS : fetch(url, {Authorization, Accept-Language})
AS-->>LAC : JSON 响应含 httpStatus
LAC-->>BG : 返回 data附加 httpStatus

图示来源

章节来源

聊天管理与交互 ​

  • 会话加载：loadChatHistory 恢复 activeSessionId、模型参数、MCP 关闭列表、上下文气泡、HTML 内容、滚动位置，并检查 abandoned checkpoint。
  • 知识库检索：buildKnowledgeContextText 通过 RAG_SEARCH 消息调用后端，构建注入文本与命中明细，failed=true 表示服务故障。
  • 子任务展示：extractSubtaskPlan 从 executionLog 提取最新 plan_task 清单，classifySubtaskOutcome 将部分成功标记为 partial。

章节来源

IndexedDB 持久化与 Checkpoint ​

  • 数据库升级：onversionchange 主动关闭当前连接，避免阻塞升级；withStore 检测 store 不存在时重置连接并重试。
  • Checkpoint 双写：saveReactCheckpoint 先写 chrome.storage.local，再尝试 IndexedDB；getReactCheckpoint 优先 IDB，失败降级 storage.local；getAllReactCheckpoints 合并去重。
  • TTL 清理：cleanupExpiredReactCheckpoints 清理超过 7 天的 checkpoint。

章节来源

Agent 服务端与命令执行 ​

  • HTTP 路由：startServer 创建 http.createServer，handleRequest 统一处理认证、CORS、路径解析、配置重载、健康检查、配对、重启/更新、文件上传、流式上传等。
  • 命令执行：executeCommand 使用 child_process.spawn，跨平台 shell 选择，受管超时策略（decideTimeoutAction），输出缓冲截断（MAX_OUTPUT_BUFFER=5MB），进程树终止（Windows taskkill /T /PID，Unix SIGTERM/SIGKILL）。
  • 审计日志：appendFileSync 写入 JSON Lines，每日轮转，最大 30 个文件或单文件 10MB，提供 queryLogs/getLogDates 查询接口。

章节来源

依赖关系分析 ​

  • background/index.js 依赖 state.js（keepalive/取消控制）、auto-resume.js（闹钟）、react-loop.js（ReAct 循环）、local-agent-client.js（Agent 通信）、storage/db.js（checkpoint 持久化）、notifier.js（通知）、panel-visibility.js（面板可见性）。
  • react-loop.js 依赖 state.js、tool-executor.js、stream-controller.js、db.js、logger.js、i18n.js、completion-verifier.js、subagent-depth.js、sw-heartbeat.js、auto-resume.js。
  • tool-executor.js 依赖 constants.js、config.js、db.js、local-agent-client.js、stream-controller.js、activity-store.js、network-scope.js、tool-memory.js、tool-debugger.js、state.js、logger.js、i18n.js、rag-tools.js、snapshot-orchestrator.js、notifier.js、react-loop.js。
  • local-agent-client.js 依赖 shared/logger.js、shared/i18n.js、shared/secret.js。
  • side_panel/chat-manager.js 依赖 state.js、clarify-dialog.js、confirm-dialog.js、utils.js、agent-manager.js、input-history.js、markdown-render.js、session-manager.js、context-indicator.js、auto-compaction.js、completion-feedback.js、panel-context.js、chat-streaming.js、chat-resume.js。
  • agent/src/server.js 依赖 config.js、auth.js、security.js、trash.js、executor.js、search.js、rag/detect.js、rag/install.js、memory/routes.js、process-tree.js、mcp/registry.js、skill/registry.js、skill/loader.js、skill/executor.js、mcp/client.js、i18n.js、logger.js。
graph LR
BG["background/index.js"] --> STATE["state.js"]
BG --> AR["auto-resume.js"]
BG --> RL["react-loop.js"]
BG --> LAC["local-agent-client.js"]
BG --> DB["storage/db.js"]
RL --> TE["tool-executor.js"]
RL --> SC["stream-controller.js"]
TE --> LAC
LAC --> AS["agent/src/server.js"]
AS --> EXE["agent/src/executor.js"]
AS --> LOG["agent/src/logger.js"]

图示来源

章节来源

性能注意事项 ​

  • Service Worker 保活：keepalive 端口与 sw-heartbeat 共同防止空闲终止；自动续跑闹钟（30s）确保 SW 被回收后可恢复。
  • 执行日志内存限制：EXECUTION_LOG_MEMORY_LIMIT=1000，避免长任务导致 SW 内存失控；同时保留 subtask_plan 以维持历史视图能力。
  • MCP Schema 压缩：限制 properties 嵌套深度（3）、参数数量（20）、description 长度（150），防止上下文膨胀。
  • Agent 命令输出缓冲：MAX_OUTPUT_BUFFER=5MB，超限时广播 truncated 事件，避免内存无限增长。
  • 网络请求超时：agentRequest/agentGet 默认 60s/30s，uploadFile 60s，downloadFile 120s；可调整 timeoutMs 参数。
  • 渲染性能：side_panel 懒加载大模块（docx 导出），避免首屏 chunk 过大；流式输出增量渲染，减少 DOM 压力。

[本节为通用指导，无需特定文件分析]

故障排查指南 ​

Service Worker 生命周期问题 ​

  • 症状：任务中断、API 调用丢失、侧边栏无响应。
  • 排查步骤：
    1. 检查 keepalive 端口是否建立：查看 Background 控制台是否有 keepalive port connected/reconnect 日志。
    2. 检查 SW 是否重启：若检测到 SW_RESTARTED，前端应显示“后台服务异常重启，API 调用已中断”。
    3. 检查自动续跑闹钟：确认 chrome.alarms 是否注册，auto-resume 是否触发。
    4. 检查 checkpoint 是否存在：查看 IndexedDB 中 reactCheckpoints store 是否可用，或 fallback 到 chrome.storage.local。

章节来源

消息丢失与状态恢复 ​

  • 症状：恢复后无流式输出、子任务计划丢失、消息对不完整。
  • 排查步骤：
    1. 检查 resumeReactLoopFromCheckpoint 是否注入恢复提示消息。
    2. 检查 cleanupIncompleteMessagePairs 是否清理了孤立 tool_calls/tool 消息。
    3. 检查 executionLog 是否裁剪了 subtask_plan 条目。
    4. 检查 IndexedDB 升级是否阻塞：onversionchange 是否主动关闭连接，withStore 是否重试。

章节来源

内存泄漏检测与分析 ​

  • 使用 Chrome DevTools Memory 面板：
    • 录制 Heap Snapshot，比较两次快照差异，查找持续增长的对象（如 Map/Set 未清理）。
    • 使用 Retainers 追踪对象引用链，定位未释放的 AbortController、WebSocket、定时器。
    • 关注 EXECUTION_LOG_MEMORY_LIMIT 是否生效，subtask_plan 是否被误删。
  • 常见问题：
    • keepalivePorts 未注销：unregisterKeepalivePort 应在 onDisconnect 中调用。
    • runningAgentCommands 未清理：tool-executor.js 需在取消时清理 Map。
    • completedProcesses 缓存未清理：executor.js 中 COMPLETED_CACHE_TTL=30s，需确保清理。

章节来源

性能瓶颈识别 ​

  • CPU 使用率：
    • 使用 Performance 面板录制，查看 Long Tasks 与 Scripting 时间。
    • 检查 ReAct 循环是否陷入重复工具调用（loopDetector 已检测 repeat/refEnum/oscillation/failureScope/noProgressScroll/budget）。
  • 网络请求监控：
    • 使用 Network 面板查看 Agent 请求耗时、失败率、httpStatus。
    • 检查 local-agent-client.js 的可达性缓存是否及时更新。
  • 渲染性能：
    • 使用 Rendering 面板查看 Layout/Paint/Composite 时间。
    • 检查 side_panel 是否频繁重绘（如流式输出增量更新）。

章节来源

日志收集与分析 ​

  • 扩展端日志：
    • 使用 console.debug/info/warn/error，前缀 [AIH]，可通过 logger.setLogLevel 调整级别。
    • 搜索关键字：checkpoint、SW_RESTARTED、auto-resume、keepalive。
  • Agent 端日志：
    • 审计日志位于 ~/.ai-helper-agent/logs/agent-YYYY-MM-DD.log，JSON Lines 格式。
    • 使用 /api/logs 查询，支持 date/category/limit/offset 过滤。
    • 分类标签：auth/fs/exec/security/system。

章节来源

调试工具使用指南 ​

  • 断点调试：
    • 在 background/index.js 的 keepalive 端口监听处设置断点，检查重连逻辑。
    • 在 react-loop.js 的 persistCheckpoint 处设置断点，验证 checkpoint 写入。
  • 变量检查：
    • 检查 activeReactLoops 是否包含 sessionId。
    • 检查 keepalivePorts 是否注册了对应 sessionId。
    • 检查 runningProcesses 是否清理了 execId。
  • 异步调用追踪：
    • 使用 Promise 调试器查看 reject 原因（如 AbortError、Network Error）。
    • 使用 Network 面板查看 WebSocket 连接状态与消息流。

章节来源

常见运行时错误与解决方案 ​

  • 错误：IndexedDB store 不存在导致 checkpoint 静默失败。
    • 解决：withStore 检测 store 不存在时重置连接并重试；确保 onversionchange 主动关闭连接。
  • 错误：Agent 未配对或不可达。
    • 解决：检查 pairWithAgent 是否成功，_agentReachability 缓存是否为 false。
  • 错误：命令执行超时或挂起。
    • 解决：调整 commandTimeout 或 timeoutMs，检查 decideTimeoutAction 策略是否合理。
  • 错误：侧边栏无法打开或关闭。
    • 解决：检查 sidePanel.open/close 是否在用户手势同步栈内调用，_openPanelsByWindow 镜像是否正确。

章节来源

结论 ​

本项目的运行稳定性依赖于 Service Worker 保活机制、ReAct 循环的状态恢复、Agent 端的健壮命令执行与审计日志。通过 keepalive 端口、自动续跑闹钟、checkpoint 双写策略，系统在 SW 被回收后仍能恢复执行；通过 MCP Schema 压缩、执行日志裁剪、输出缓冲限制，系统避免了内存与上下文膨胀。调试时应重点关注 keepalive 端口、checkpoint 持久化、Agent 可达性、命令执行超时等关键点。

[本节为总结，无需特定文件分析]

附录：调试与日志清单 ​

  • 扩展端日志关键字：
    • checkpoint、SW_RESTARTED、auto-resume、keepalive、reactLoop、toolExec。
  • Agent 端日志位置：
    • ~/.ai-helper-agent/logs/agent-YYYY-MM-DD.log。
  • 常用 API：
    • /api/status、/api/status/detail、/api/logs、/api/heartbeat。
  • 调试技巧：
    • 使用 Chrome DevTools 的 Console、Sources、Performance、Memory、Network 面板。
    • 在关键函数（persistCheckpoint、agentRequest、executeCommand）设置断点。
    • 检查 IndexedDB 中的 reactCheckpoints store 与 sessions 表。

[本节为通用指导，无需特定文件分析]