AI Helper 文档中心

主题

扩展相关问题 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构与排查边界
  3. 扩展更新失败：常见原因与解决方法
  4. 配置重置：用户设置备份、恢复与缓存清理
  5. 数据恢复流程：会话导出导入、历史恢复与知识库重建
  6. 扩展卸载与完整清理步骤
  7. 扩展权限管理与安全最佳实践
  8. 崩溃保护与灾难恢复方案
  9. 依赖关系与架构总览
  10. 故障排查清单
  11. 结论

引言 ​

本文件面向“AI Helper”扩展（Chrome 扩展端，Manifest V3，版本 2.3.1）与其独立本地代理端 Agent（Node.js，包名 ai-helper-agent，版本 2.3.1）的扩展相关问题排查。文档重点覆盖以下目标：

  • 扩展更新失败的常见原因与修复路径；
  • 配置重置的具体步骤，包括用户设置备份、默认配置重置和缓存清理；
  • 数据恢复流程，包括 IndexedDB 数据导出导入、会话历史恢复和知识库重建；
  • 扩展卸载后的完整清理步骤，包括文件残留、注册表/系统状态和服务进程终止；
  • 扩展权限管理最佳实践；
  • 扩展崩溃后的数据保护机制与灾难恢复方案。

需要特别强调：扩展端与 Agent 端通过本地 HTTP/WebSocket 通信，Agent 源码修改后必须重启进程，新接口才生效。因此任何涉及 Agent 行为变更的修复，都应包含“重启 Agent 进程”这一动作。

章节来源

项目结构与排查边界 ​

本项目采用双进程架构：

  • Chrome 扩展端位于 src/，入口为 Service Worker src/background/index.js，负责侧边栏、消息路由、ReAct 任务调度、IndexedDB 持久化、与 Agent 的本地通信。
  • Agent 端位于 agent/src/server.js，提供 HTTP + WebSocket 接口，暴露文件读写、命令执行、长期记忆、RAG、MCP、技能等能力。
graph TB
Browser["浏览器扩展环境<br/>Manifest V3"]
Background["Background Service Worker<br/>src/background/index.js"]
SidePanel["Side Panel 界面<br/>会话/工具/知识面板"]
Storage["IndexedDB<br/>ai-helper-db"]
LocalStorage["chrome.storage.local<br/>配置/后备 checkpoint"]
AgentServer["Agent 本地服务器<br/>agent/src/server.js"]
FileSystem["工作目录与系统文件"]
RAG["RAG 知识库与向量索引"]
Browser --> Background
Browser --> SidePanel
Background --> Storage
Background --> LocalStorage
Background --> AgentServer
AgentServer --> FileSystem
AgentServer --> RAG

图表来源

章节来源

扩展更新失败：常见原因与解决方法 ​

1. 版本冲突 ​

扩展端与 Agent 端版本号应保持同步。当前仓库中扩展端版本为 2.3.1，Agent 端也应以 2.3.1 为准。若出现“扩展可用但 Agent 功能异常”，应优先检查两端版本是否一致。

排查建议：

  • 查看扩展版本：在 Chrome 扩展管理页面确认扩展版本是否为 2.3.1。
  • 查看 Agent 版本：调用 Agent 健康接口 /api/status，返回字段中包含 version。
  • 若版本不一致，先升级 Agent 端，再刷新扩展。

章节来源

2. npm 全局安装失败或超时 ​

Agent 更新通过服务端 /api/agent/update 触发 npm install -g ai-helper-agent@latest。该过程存在以下风险：

  • 网络不可用或镜像源不可达；
  • npm 被其他进程占用；
  • 安装超时（默认 90 秒保护）；
  • 与 RAG 依赖安装并发写 node_modules，导致互相破坏。

修复步骤：

  1. 停止正在进行的 RAG 安装或更新操作。
  2. 手动执行 npm install -g ai-helper-agent@latest，观察输出日志。
  3. 若提示权限问题，使用管理员权限或调整 npm 全局目录权限。
  4. 更新成功后重启 Agent 进程。

章节来源

3. 端口占用或服务未启动 ​

Agent 监听本地端口，若端口被占用或进程未启动，扩展无法连接。

排查建议：

  • 检查 Agent 是否运行：访问 /api/status。
  • 检查端口是否被占用：根据配置中的 host 与 port 判断。
  • 若服务已启动但无响应，执行 /api/shutdown 或手动终止进程后重新启动。

章节来源

4. 内嵌模式与 npm 全局模式路径差异 ​

Agent 支持两种运行模式：

  • 内嵌模式：由安装脚本安装到 ~/.ai-helper-agent/；
  • npm 全局模式：传统 npm install -g 路径。

若更新后路径解析异常，应检查当前是否为内嵌模式，并确认 Node/npm 可执行文件路径是否正确。

章节来源

5. 权限变更导致 Agent 无法写入 ​

Agent 对核心敏感路径有硬阻止策略，例如配置文件、配对记录、日志目录、回收站等。若更新过程中尝试写入这些路径，会被安全模块拦截。

修复建议：

  • 不要将工作目录设置为 Agent 内部目录；
  • 使用用户可控的工作目录；
  • 避免直接修改 config.json、pairings.json、mcp_servers.json 等核心文件。

章节来源

配置重置：用户设置备份、恢复与缓存清理 ​

1. 用户设置的备份 ​

扩展端主要配置存储在 chrome.storage.local，包括模型列表、API Base URL、图片识别模型、自定义 API Base、删除过的预设项等。

推荐备份方式：

  • 打开选项页，进入模型与 API Base 管理界面；
  • 记录自定义模型名称、上下文窗口大小、API Base URL 及标签；
  • 如需完整备份，可使用浏览器开发者工具读取 chrome.storage.local 内容并保存 JSON。

章节来源

2. 默认配置的重置 ​

若配置损坏或行为异常，可按以下步骤重置：

  1. 打开 Chrome 扩展设置页；
  2. 找到 AI Helper 扩展；
  3. 点击“清除数据”或“重置设置”；
  4. 重新打开选项页，加载默认模型与 API Base；
  5. 重新输入必要的密钥或 API Base。

注意：重置会清空 chrome.storage.local 中的扩展配置，但不会自动删除 IndexedDB 中的会话数据。

章节来源

3. 缓存数据的清理 ​

扩展端涉及两类缓存：

  • chrome.storage.local：轻量配置、临时状态；
  • IndexedDB ai-helper-db：会话、归档会话、UI 原型、Token 统计、ReAct checkpoint、书签、定时任务等。

清理建议：

  • 仅清理配置：清除扩展数据；
  • 仅清理会话：通过侧边栏导出重要会话后，再删除 IndexedDB 中的 sessions 与 archivedSessions；
  • 完全重置：清除扩展数据 + 删除 IndexedDB + 重启 Agent。

章节来源

数据恢复流程：会话导出导入、历史恢复与知识库重建 ​

1. 会话导出与导入 ​

侧边栏提供会话导出/导入功能，导出格式为 .aihelper.json，包含会话标题、模型、工具配置、温度、TopP、消息历史等。

导出流程：

  1. 打开侧边栏；
  2. 进入会话导出界面；
  3. 选择要导出的会话；
  4. 点击导出，生成 JSON 文件；
  5. 将文件保存到安全位置。

导入流程：

  1. 准备 .aihelper.json 文件或兼容旧格式的消息数组；
  2. 在侧边栏导入界面选择文件；
  3. 系统校验格式并导入会话；
  4. 刷新会话标签栏。

章节来源

2. IndexedDB 数据迁移与自检 ​

扩展启动时会检查 IndexedDB 是否已有会话数据；若无，则尝试从 chrome.storage.local 迁移旧数据。迁移完成后会清理旧的会话 key。

此外，数据库封装层对 reactCheckpoints store 缺失做了防御性处理：若 store 不存在，会关闭连接并重试，以应对 SW 重启或 DB 升级导致的连接陈旧问题。

章节来源

3. ReAct Checkpoint 的双写后备机制 ​

当长任务被 Service Worker 回收时，扩展会保存 ReAct checkpoint，以便后续自动续跑。checkpoint 同时写入：

  • chrome.storage.local（可靠后备）；
  • IndexedDB reactCheckpoints（性能优化）。

若 IndexedDB 不可用，checkpoint 仍可保留在 storage.local 中，避免中断任务丢失。

章节来源

4. 知识库重建方法 ​

Agent 端的 RAG 能力依赖本地依赖与环境检测。若 RAG 不可用，可能表现为知识库无法检索或重建失败。

重建建议：

  1. 检查 Agent 健康接口 /api/status 中的 ragAvailable；
  2. 若不可用，查看 RAG 安装日志；
  3. 若曾成功安装但依赖被清（例如 npm 全局更新），Agent 会自动尝试恢复 RAG 依赖；
  4. 若仍失败，手动安装 RAG 相关依赖；
  5. 重建知识库索引。

章节来源

扩展卸载与完整清理步骤 ​

1. 扩展本身卸载 ​

在 Chrome 扩展管理页面移除 AI Helper 扩展。这会删除扩展代码和部分扩展数据，但不会自动清理：

  • Agent 本地服务进程；
  • Agent 工作目录；
  • ~/.ai-helper-agent/ 下的内嵌运行时；
  • 系统级 npm 全局包（如果是 npm 全局安装）。

2. Agent 服务进程终止 ​

Agent 是独立 Node.js 进程，卸载扩展不会自动终止它。

终止方式：

  • 使用 Agent 提供的 /api/shutdown 接口；
  • 或通过系统任务管理器查找并终止 Node 进程；
  • 内嵌模式下，检查 ~/.ai-helper-agent/ 下是否有残留进程。

章节来源

3. 文件残留清理 ​

内嵌模式 ​

内嵌模式会将运行时和应用安装在 ~/.ai-helper-agent/。卸载时应检查：

  • ~/.ai-helper-agent/runtime/；
  • ~/.ai-helper-agent/app/；
  • ~/.ai-helper-agent/config.json；
  • ~/.ai-helper-agent/logs/；
  • ~/.ai-helper-agent/.trash/；
  • ~/.ai-helper-agent/mirrors.json；
  • ~/.ai-helper-agent/INSTALL_MANIFEST.json。

npm 全局模式 ​

npm 全局安装的 Agent 包通常位于 Node 全局包目录，例如：

  • macOS/Linux：/usr/local/lib/node_modules/ai-helper-agent 或用户 npm prefix；
  • Windows：Node 全局模块目录。

工作目录 ​

Agent 的 workdir 由配置决定，默认可能是用户当前工作目录。卸载前应先确认工作目录中是否有用户数据，不要误删。

章节来源

4. 注册表与系统状态清理 ​

Agent 的安全模块对命令执行进行分级管控，其中包含 Windows 注册表相关命令的灰名单。但扩展本身不直接维护 Windows 注册表条目；若用户通过 Agent 命令修改过系统状态，需按系统常规方式清理。

注意：

  • 不应盲目删除系统注册表；
  • 只清理明确由用户创建的条目；
  • 若不确定，请先导出注册表备份。

章节来源

扩展权限管理与安全最佳实践 ​

1. Manifest 权限说明 ​

扩展声明了较多权限，包括 activeTab、storage、unlimitedStorage、sidePanel、scripting、bookmarks、history、downloads、notifications、tabs、tabGroups、cookies、offscreen、clipboardRead、clipboardWrite、commands、alarms、debugger、webNavigation，以及主机权限 <all_urls>、http://*/*、https://*/*。

最小权限原则建议：

  • 仅在确实需要时启用对应功能；
  • 避免将扩展分发给不需要全部能力的用户；
  • 定期审计权限使用情况；
  • 对敏感权限（如 cookies、history、debugger）做额外风险评估。

章节来源

2. Agent 端安全控制 ​

Agent 端实现了两层关键安全控制：

  • 文件路径沙箱：白名单 + 硬阻止目录 + 符号链接校验；
  • 命令分级管控：黑名单绝对禁止，灰名单需用户确认。

最佳实践：

  • 将工作目录限制在用户可控目录；
  • 不在 allowedPaths 中添加系统目录；
  • 谨慎授权高风险命令；
  • 开启确认弹窗，不要长期关闭安全提示；
  • 定期检查 Agent 日志。

章节来源

3. CORS 与来源限制 ​

Agent 服务器仅允许来自 chrome-extension:// 的请求跨域读取响应，防止恶意网页直接调用无认证接口。

建议：

  • 不要将 Agent 绑定到 0.0.0.0 且对外暴露；
  • 生产环境建议使用本机回环地址；
  • 若需远程访问，必须启用认证并通过安全网关。

章节来源

崩溃保护与灾难恢复方案 ​

1. Service Worker 生命周期与保活 ​

Chrome MV3 的 Service Worker 可能被系统回收。扩展通过 keepalive port 机制保持活跃，并在 SW 重启后检测断连，向面板发送 SW_RESTARTED 消息，附带可恢复的 checkpoint 元数据。

章节来源

2. ReAct 任务自动续跑 ​

扩展在后台注册闹钟处理器，扫描残留 checkpoint 并尝试自动续跑。续跑次数超过上限后会通知用户人工介入。

章节来源

3. IndexedDB 连接恢复与 store 重建 ​

数据库封装层对事务错误、连接关闭、store 缺失等情况进行重试与连接重置，确保 SW 重启后仍能访问必要的数据结构。

章节来源

4. 灾难恢复流程 ​

若扩展或 Agent 发生严重异常，建议按以下顺序恢复：

  1. 导出所有重要会话；
  2. 检查 Agent 是否正常运行；
  3. 若 Agent 异常，重启 Agent；
  4. 若会话丢失，尝试从 .aihelper.json 导入；
  5. 若 IndexedDB 损坏，先导出备份，再考虑重置扩展数据；
  6. 若知识库失效，重建 RAG 索引；
  7. 最后恢复用户配置。
flowchart TD
Start["发现异常"] --> ExportSessions["导出重要会话"]
ExportSessions --> CheckAgent["检查 Agent 状态"]
CheckAgent --> AgentRunning{"Agent 正常?"}
AgentRunning --> |否| RestartAgent["重启 Agent"]
AgentRunning --> |是| CheckData["检查会话数据"]
RestartAgent --> CheckData
CheckData --> DataExists{"会话是否存在?"}
DataExists --> |是| RestoreKB["检查知识库可用性"]
DataExists --> |否| ImportBackup["导入 .aihelper.json 备份"]
ImportBackup --> RestoreKB
RestoreKB --> KBOk{"知识库可用?"}
KBOk --> |否| RebuildRAG["重建 RAG 索引"]
KBOk --> |是| RestoreConfig["恢复用户配置"]
RebuildRAG --> RestoreConfig
RestoreConfig --> End["完成恢复"]

图表来源

依赖关系与架构总览 ​

扩展端与 Agent 端的交互是故障排查的核心。下图展示关键组件之间的依赖关系。

graph LR
Manifest["manifest.json<br/>权限/入口/版本"]
Background["background/index.js<br/>Service Worker 主逻辑"]
DB["storage/db.js<br/>IndexedDB 封装"]
ExportImport["side_panel/export-import.js<br/>会话导出导入"]
ConfigManager["options/config-manager.js<br/>配置管理"]
AgentServer["agent/server.js<br/>HTTP/WebSocket 服务"]
InstallMode["agent/install-mode.js<br/>内嵌/npm 模式"]
Security["agent/security.js<br/>路径与命令安全"]
Manifest --> Background
Background --> DB
Background --> AgentServer
ExportImport --> DB
ConfigManager --> Background
AgentServer --> InstallMode
AgentServer --> Security

图表来源

故障排查清单 ​

更新失败 ​

  • [ ] 确认扩展版本与 Agent 版本一致；
  • [ ] 检查 npm 全局安装是否成功；
  • [ ] 查看 Agent 日志中是否有 update_npm_failed；
  • [ ] 确认没有 RAG 安装与更新并发；
  • [ ] 重启 Agent 后重试。

配置异常 ​

  • [ ] 备份 chrome.storage.local；
  • [ ] 重置扩展设置；
  • [ ] 重新配置模型与 API Base；
  • [ ] 检查是否误删内置预设；
  • [ ] 若仍异常，清理 IndexedDB 后重建。

数据丢失 ​

  • [ ] 检查是否有 .aihelper.json 备份；
  • [ ] 尝试导入会话；
  • [ ] 检查 IndexedDB 中 sessions 与 archivedSessions；
  • [ ] 检查 ReAct checkpoint 是否因 TTL 过期被清理；
  • [ ] 必要时重置扩展数据并重新导入。

权限与安全 ​

  • [ ] 检查工作目录是否在白名单；
  • [ ] 检查是否尝试访问 Agent 核心敏感文件；
  • [ ] 检查命令是否命中黑名单或灰名单；
  • [ ] 确认 Agent 未对外暴露；
  • [ ] 审查扩展权限是否超出实际需求。

崩溃与恢复 ​

  • [ ] 检查 Service Worker 是否被回收；
  • [ ] 查看是否有可恢复的 checkpoint；
  • [ ] 检查 IndexedDB 连接是否正常；
  • [ ] 重启扩展与 Agent；
  • [ ] 按灾难恢复流程逐步恢复数据。

章节来源

结论 ​

扩展相关问题的排查应以“扩展端 + Agent 端 + 本地存储”三位一体视角进行。更新失败多与 npm、端口、版本不一致有关；配置重置应优先备份用户设置；数据恢复应以会话导出文件为主、IndexedDB 为辅；卸载时必须清理 Agent 进程与文件残留；权限管理应遵循最小权限原则，并结合 Agent 的路径与命令安全策略。对于崩溃场景，扩展已提供 checkpoint 后备与自动续跑机制，但重大故障仍需人工介入并按灾难恢复流程处理。