AI Helper 文档中心

主题

故障排除与常见问题 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能注意事项
  8. 故障排除指南
  9. 结论
  10. 附录

简介 ​

本文件面向 AI Helper（扩展端）与本地 Agent 服务（代理端）的故障排除与常见问题。文档覆盖安装问题、运行问题、扩展相关问题、Agent 服务问题、调试工具与技巧，以及常见错误信息的含义和解决方案，并给出社区支持与反馈渠道。

本项目采用双进程架构：

  • Chrome 扩展端：Manifest V3，Service Worker 作为 background，侧边栏为 side panel，版本 2.3.1。
  • 独立本地 Agent 服务：Node.js 进程，npm 包名 ai-helper-agent，版本 2.3.1。

两端通过本地 HTTP/WebSocket 通信；Agent 源码修改后必须重启进程，新接口才生效。

章节来源

项目结构 ​

  • 扩展端入口：src/background/index.js（Service Worker）。
  • 侧边栏界面：side_panel.html，由 manifest.json 的 side_panel.default_path 指向。
  • 选项页：options.html，用于配置 API Key、Agent 配对、知识库等。
  • Agent 服务端：agent/src/server.js，提供文件读写、命令执行、记忆、RAG、MCP、Skill 等能力。
  • 安装引导：src/options/install-guide.js 生成与当前扩展版本一致的 Agent 安装命令。
  • 日志系统：扩展端使用 src/shared/logger.js；Agent 端将审计日志写入 ~/.ai-helper-agent/logs/。
graph TB
A["浏览器"] --> B["Chrome 扩展<br/>Service Worker"]
B --> C["侧边栏面板"]
B --> D["工具执行器"]
D --> E["本地 Agent 客户端"]
E --> F["Agent 服务<br/>HTTP + WebSocket"]
F --> G["文件系统 / 命令执行 / 记忆 / RAG / MCP / Skill"]

图表来源

章节来源

核心组件 ​

  • Service Worker 生命周期管理：keepalive 端口、自动续跑闹钟、SW 重启检测、侧边栏可见性。
  • ReAct 推理循环：任务拆解、工具调用、超时、循环检测、完成度校验。
  • Agent 客户端：配对、认证、HTTP/WebSocket 封装、可达性缓存、多代理支持。
  • Agent 服务器：请求路由、CORS、认证、文件沙箱、命令分级安全、日志、更新与重启。
  • 存储层：IndexedDB 会话、checkpoint、定时任务、书签、Token 统计。

章节来源

架构总览 ​

扩展端通过 local-agent-client.js 向 Agent 发起认证后的 HTTP 请求；命令执行还建立 WebSocket 流式输出。Agent 端对每个请求进行语言设置、CORS、URL 解析、认证、业务处理，并把异常统一捕获返回 500，避免单点错误拖垮整个服务。

sequenceDiagram
participant UI as "侧边栏"
participant BG as "Service Worker"
participant TE as "工具执行器"
participant AC as "Agent 客户端"
participant AG as "Agent 服务"
UI->>BG : 发送用户指令
BG->>TE : 选择工具并准备参数
TE->>AC : 调用 Agent API
AC->>AG : POST /api/* (Bearer Token)
AG-->>AC : JSON 响应
AC-->>TE : 结果或错误
TE-->>BG : 工具执行结果
BG-->>UI : 渲染消息/状态

图表来源

章节来源

详细组件分析 ​

Service Worker 生命周期与保活 ​

  • keepalive 端口：侧边栏通过 chrome.runtime.connect 建立长连接，防止 SW 空闲被杀。
  • SW 重启检测：重连时若 sessionId 不在活跃集合中，说明 SW 已重启，会下发 SW_RESTARTED 并携带可恢复 checkpoint。
  • 自动续跑：主任务期间注册 30 秒周期闹钟；SW 被回收后由闹钟唤醒，扫描残留 checkpoint 自动续跑，最多尝试固定次数，耗尽后提示人工介入。
  • 侧边栏开关与分组：全局模式与标签页绑定模式分别处理，避免“能开不能关”“面板泄露到新 tab”等问题。
flowchart TD
Start(["SW 启动"]) --> Keepalive["注册 keepalive 端口"]
Keepalive --> DetectRestart{"是否重连且会话不在活跃集合？"}
DetectRestart --> |是| SendRestart["发送 SW_RESTARTED 并附带 checkpoint"]
DetectRestart --> |否| Normal["正常处理消息"]
Normal --> WatchAlarm["注册自动续跑闹钟"]
SendRestart --> WatchAlarm
WatchAlarm --> AlarmTick{"闹钟触发"}
AlarmTick --> Decide["决策：是否应续跑"]
Decide --> |是| Resume["从 checkpoint 恢复执行"]
Decide --> |否| Idle["等待下一次闹钟"]
Resume --> CheckAttempts{"是否已达最大尝试次数？"}
CheckAttempts --> |是| NotifyExhausted["通知人工介入"]
CheckAttempts --> |否| Continue["继续执行"]

图表来源

章节来源

ReAct 推理循环与完成度校验 ​

  • 工具预筛选减少 token 消耗。
  • 子任务计划与完成度校验：基于 DOM/命令证据验证子任务目标，未满足时可自动重试或跳过。
  • 循环检测：重复无效操作、页面元素枚举循环、操作振荡、连续失败、无进展滚动、预算耗尽等场景会暂停任务并提示补充指导。
  • 流式响应空闲超时：长时间无数据则中断，提示网络或服务提供商不稳定。
flowchart TD
Enter(["进入 ReAct 循环"]) --> Preselect["工具预筛选"]
Preselect --> Plan["规划子任务"]
Plan --> Execute["执行工具"]
Execute --> Verify{"完成度校验通过？"}
Verify --> |是| NextRound["下一轮"]
Verify --> |否| RetryOrSkip["重试或跳过"]
NextRound --> LoopCheck{"是否检测到循环？"}
LoopCheck --> |是| Pause["暂停并提示补充指导"]
LoopCheck --> |否| Execute
RetryOrSkip --> LoopCheck

图表来源

章节来源

Agent 客户端与服务端通信 ​

  • 配对流程：扩展端 POST /api/pair，成功后保存 token 并设为活跃代理。
  • 认证请求：所有需认证的请求带 Bearer Token，GET/POST 均封装在 agentGet/agentRequest。
  • 可达性缓存：已知不可达时直接返回错误，避免阻塞等待超时。
  • WebSocket：命令执行实时输出，token 通过查询参数附加。
sequenceDiagram
participant Ext as "扩展端"
participant AC as "Agent 客户端"
participant AG as "Agent 服务"
Ext->>AC : pairWithAgent(url, code)
AC->>AG : POST /api/pair
AG-->>AC : {success, token}
AC->>Ext : 保存 token 并标记活跃
Ext->>AC : agentRequest(path, body)
AC->>AG : POST /api/* (Authorization : Bearer token)
AG-->>AC : JSON 响应
AC-->>Ext : 结果或错误

图表来源

章节来源

Agent 服务启动、认证与安全 ​

  • 启动：加载配置、初始化搜索工具、检测 RAG 能力、启动 HTTP 与 WebSocket。
  • CORS：仅放行 chrome-extension:// 来源，保护无认证端点。
  • 认证：Bearer Token 校验，缺失或无效返回 401/403。
  • 安全：文件路径白名单、命令黑名单/灰名单、进程树终止、审计日志。
flowchart TD
Start(["startServer"]) --> LoadConfig["加载配置"]
LoadConfig --> InitSearch["初始化搜索工具"]
InitSearch --> DetectRAG["检测 RAG 可用性"]
DetectRAG --> Listen["监听 HTTP/WebSocket"]
Listen --> HandleReq["处理请求"]
HandleReq --> ParseURL["解析 URL"]
ParseURL --> Auth{"是否需要认证？"}
Auth --> |否| Public["公开接口：/api/pair, /api/status"]
Auth --> |是| Verify["验证 Bearer Token"]
Verify --> Route["路由到具体功能"]
Public --> Route
Route --> Log["记录审计日志"]

图表来源

章节来源

数据存储与恢复 ​

  • IndexedDB：会话、归档、原型、Token 统计、ReAct checkpoint、书签、定时任务。
  • checkpoint TTL：7 天，过期清理。
  • 连接恢复：store 不存在时关闭旧连接并重试，避免升级阻塞导致 checkpoint 静默失败。
flowchart TD
OpenDB["打开数据库"] --> Upgrade{"版本变更？"}
Upgrade --> |是| CloseOld["关闭旧连接"]
CloseOld --> ResetCache["重置连接缓存"]
ResetCache --> Reopen["重新打开数据库"]
Upgrade --> |否| UseDB["使用现有连接"]
UseDB --> WithStore["withStore 事务包装"]
WithStore --> StoreExists{"store 是否存在？"}
StoreExists --> |否| CloseAndRetry["关闭并延迟重试"]
StoreExists --> |是| ExecTx["执行事务"]

图表来源

章节来源

依赖关系分析 ​

  • 扩展端依赖 Manifest V3 能力：sidePanel、scripting、storage、alarms、debugger 等。
  • Agent 端依赖 Node.js >= 18，可选 fd/rg 加速搜索，RAG 可选依赖 vectra、transformers、pdf-parse 等。
  • 构建脚本：扩展端使用 vite，Agent 端发布脚本复制 dist。
graph LR
MV3["Manifest V3 权限"] --> BG["Service Worker"]
BG --> Tools["工具执行器"]
Tools --> AgentClient["Agent 客户端"]
AgentClient --> AgentServer["Agent 服务"]
AgentServer --> FS["文件系统"]
AgentServer --> Exec["命令执行"]
AgentServer --> Memory["长期记忆"]
AgentServer --> RAG["知识库"]
AgentServer --> MCP["MCP 协议"]
AgentServer --> Skill["技能系统"]

图表来源

章节来源

性能注意事项 ​

  • ReAct 循环 token 预算按 token 计数而非消息数，避免 tool_calls/tool 消息对被截断。
  • 大页面选择内容会被摘要压缩，减少上下文占用。
  • Agent 端命令执行支持进程树终止，避免孤儿进程持续写盘。
  • 向量索引重建与模型指纹变化会触发缓存失效，避免维度不匹配比较。

[本节为通用性能建议，不直接分析具体文件]

故障排除指南 ​

安装问题 ​

  • 权限配置
    • 确保以官方渠道安装扩展：Chrome Web Store 或 Edge Add-ons，或从 GitHub Releases 下载 zip 并在开发者模式下加载。
    • Agent 一键安装脚本会自动检测网络环境并安装 Node.js 运行时；Windows 使用 PowerShell 管道执行。
    • 若手动 npm 安装，需 Node.js >= 18；RAG 功能推荐 Node.js >= 22.13.0。
  • 依赖冲突
    • RAG 依赖缺失时，Agent 启动时会检测并提供自动恢复；npm -g 升级可能清空包目录内依赖，Agent 会重新安装。
    • 更新 Agent 与 RAG 依赖安装互斥，避免并发写 node_modules 破坏依赖。
  • 浏览器兼容性
    • 需要 Chrome / Edge / Chromium 114+，因为使用 Side Panel API。
    • Manifest V3 要求 Service Worker 作为 background，注意 SW 生命周期硬约束。
  • 网络问题
    • 扩展端与 Agent 通信使用本地 HTTP/WebSocket；若代理地址为 0.0.0.0，客户端会替换为 127.0.0.1 或配置的 hostname。
    • 内网访问受网络范围控制，需在扩展设置中开启“内网地址访问”并将主机加入允许列表。

章节来源

运行问题 ​

  • Service Worker 生命周期
    • 现象：任务中途消失、侧边栏断开、API 调用中断。
    • 排查：检查 keepalive 端口是否建立，SW 是否重启；查看后台日志中的 SW_RESTARTED 与 checkpoint 相关条目。
    • 解决：确认侧边栏保持打开；必要时点击“继续执行”恢复；检查自动续跑是否达到最大尝试次数。
  • 内存泄漏排查
    • 现象：Agent 内存持续增长、命令执行后进程残留。
    • 排查：查看 Agent /api/status/detail 的 resourceUsage；检查命令执行是否被正确终止；查看审计日志中的 exec 类别。
    • 解决：停止命令执行；重启 Agent；确认进程树终止逻辑生效。
  • 性能瓶颈分析
    • 现象：工具调用慢、流式响应卡顿。
    • 排查：检查工具预筛选是否生效；查看 ReAct 循环迭代次数；检查网络范围限制是否频繁拒绝。
    • 解决：缩小任务范围；调整 timeout；确认服务提供商可用。
  • 日志分析方法
    • 扩展端：使用 src/shared/logger.js，控制台输出 [AIH] 前缀。
    • Agent 端：终端前台模式实时输出；文件日志位于 ~/.ai-helper-agent/logs/，JSON Lines 格式，支持按日期/类别查询。

章节来源

扩展相关问题 ​

  • 更新失败处理
    • 现象：Agent 更新失败，前端提示更新失败。
    • 原因：npm 安装超时或退出码非 0；与 RAG 依赖安装并发被拒绝。
    • 解决：稍后重试；检查网络代理配置；手动执行 npm install -g ai-helper-agent@latest。
  • 配置重置方法
    • 现象：Agent 配置异常、工作目录错误。
    • 解决：编辑 ~/.ai-helper-agent/config.json；或通过扩展设置页重置 Agent 配置。
  • 数据恢复步骤
    • 现象：任务中断后无法恢复。
    • 原因：checkpoint 过期或被清理；IndexedDB store 缺失。
    • 解决：检查 reactCheckpoints store 是否存在；必要时清理过期 checkpoint 后重试；确认自动续跑未耗尽。
  • 卸载清理
    • 现象：卸载后仍有残留进程或文件。
    • 解决：使用 Agent CLI uninstall；手动删除 ~/.ai-helper-agent/ 下数据；确认 PID 文件已清理。

章节来源

Agent 服务问题 ​

  • 启动失败
    • 现象：Agent 无法启动，端口冲突。
    • 排查：检查端口配置；查看启动日志；确认 Node.js 版本。
    • 解决：更换端口；重启服务；检查防火墙或代理设置。
  • 连接异常
    • 现象：扩展端提示“无法连接到 Agent”。
    • 排查：检查配对是否成功；Token 是否有效；代理地址是否正确。
    • 解决：重新配对；确认代理在线；检查可达性缓存。
  • 权限拒绝
    • 现象：命令执行被拒绝，文件操作受限。
    • 排查：查看安全日志；确认命令是否在黑名单；检查文件路径是否在白名单。
    • 解决：调整 allowedPaths；确认命令无需高危操作；必要时用户确认。
  • 资源占用过高
    • 现象：CPU/内存飙升。
    • 排查：查看 /api/status/detail 的资源使用；检查是否有长时间运行的命令。
    • 解决：停止命令；重启 Agent；优化 RAG 索引重建频率。

章节来源

调试工具与技巧 ​

  • 日志查看
    • 扩展端：控制台过滤 [AIH]；后台日志关注 checkpoint、SW 重启、自动续跑。
    • Agent 端：前台模式实时输出；文件日志按日期分类；支持 /api/logs 查询。
  • 性能监控
    • 扩展端：观察 ReAct 循环迭代次数、工具调用耗时。
    • Agent 端：查看 /api/status/detail 的 memoryUsedMB、uptimeSeconds、cpuUser/System。
  • 网络抓包
    • 使用浏览器开发者工具的 Network 面板查看扩展端与 Agent 的 HTTP 请求。
    • 使用 WebSocket 面板查看命令执行实时输出。
  • 内存分析
    • 使用 Chrome DevTools 的 Memory 面板分析 Service Worker 内存。
    • 使用 Node.js 的 process.memoryUsage() 或 Agent 提供的资源信息分析 Agent 内存。

章节来源

常见错误信息与解决方案 ​

  • “无法连接到 Agent”
    • 含义：扩展端无法与 Agent 建立连接。
    • 解决：确认 Agent 已启动；检查配对状态；验证代理地址。
  • “代理服务未连接”
    • 含义：Agent 客户端已知代理不可达。
    • 解决：重启 Agent；检查网络；清除可达性缓存。
  • “请求超时”
    • 含义：HTTP 请求超过设定时间。
    • 解决：增大 timeout；检查网络稳定性；确认服务提供商可用。
  • “命令执行被拒绝”
    • 含义：命令命中黑名单或灰名单未确认。
    • 解决：调整命令策略；用户确认；避免高危操作。
  • “更新失败”
    • 含义：Agent 更新过程中 npm 安装失败。
    • 解决：检查网络代理；手动执行更新命令；稍后重试。

章节来源

社区支持与问题反馈 ​

  • GitHub Discussions：提问与讨论。
  • Issues：提交 bug 或功能请求。
  • 承诺：每个 issue 会在 24 小时内回复。

章节来源

结论 ​

AI Helper 的双进程架构提供了强大的网页自动化与本地能力，但也引入了 Service Worker 生命周期、Agent 通信、权限安全等复杂问题。通过本文的故障排除指南，用户可以快速定位安装、运行、扩展、Agent 相关的问题，并使用日志、性能监控、网络抓包等工具进行诊断。遇到问题时，优先检查配置、日志、权限和网络，再考虑社区支持。

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

附录 ​

  • 快速参考：
    • 扩展版本：2.3.1
    • Agent 版本：2.3.1
    • 最低浏览器版本：Chrome / Edge / Chromium 114+
    • 最低 Node.js 版本：18（RAG 推荐 22.13.0+）

[本节为补充信息，不直接分析具体文件]