安装问题排查

本文引用的源码文件

本文引用的文件

更新摘要

已完成的变更

将所有版本引用从 v2.3.1 更新为 v2.4.0
更新了扩展端与 Agent 端版本同步要求
修正了 GitHub Releases 官方构建产物验证中的版本号
保持了文档结构和内容的一致性

文档目标与适用范围
双进程架构与版本约束
Chrome 扩展安装步骤
Chrome 扩展常见安装失败原因
Agent 本地代理服务安装流程
Node.js 环境与依赖冲突排查
npm 安装错误修复方法
扩展端与 Agent 端版本同步要求
GitHub Releases 官方构建产物验证
浏览器兼容性检查
系统权限配置
网络代理与下载源设置
常见问题排查清单
结论与建议

文档目标与适用范围

本文面向首次安装 AI Helper 的用户和需要定位安装问题的技术支持人员，覆盖以下范围：

Chrome、Edge 等 Chromium 内核浏览器的扩展安装。
GitHub Releases 自动构建产物的手动加载。
Agent 本地代理服务的 Node.js 环境安装、CLI 启动、配对连接。
Manifest V3 兼容性问题、权限配置错误、扩展商店安装失败。
npm 安装错误、依赖包冲突、RAG 可选依赖缺失。
双进程架构的安装顺序要求，以及扩展端与 Agent 端版本号必须保持为 2.4.0。

双进程架构与版本约束

AI Helper 采用双进程架构：

Chrome 扩展端：基于 Manifest V3，位于仓库根目录的 src/，扩展版本为 2.4.0。
Agent 本地代理端：独立 Node.js 服务，入口为 agent/src/server.js，npm 包名为 ai-helper-agent，版本也为 2.4.0。

两端通过本地 HTTP/WebSocket 通信：扩展端调用 Agent 的文件读写、命令执行、长期记忆、RAG、MCP 和 Skill 能力。Agent 源码修改后必须重启进程，新接口才生效；仅刷新页面或重载扩展不会让 Agent 端生效。

graph TB
Extension["Chrome 扩展端<br/>Manifest V3 · 版本 2.4.0"] --> HTTP["本地 HTTP 接口<br/>http://127.0.0.1:18910"]
Extension --> WS["本地 WebSocket 接口<br/>ws://127.0.0.1:18910/ws/exec/:execId"]
HTTP --> Agent["Agent 本地代理服务<br/>Node.js · ai-helper-agent · 版本 2.4.0"]
WS --> Agent
Agent --> FS["文件系统沙箱"]
Agent --> Exec["命令执行与安全分级"]
Agent --> Memory["长期记忆与 RAG"]
Agent --> MCP["MCP 工具注册"]
Agent --> Skill["Skill 系统"]

图表来源

章节来源

Chrome 扩展安装步骤

推荐按以下顺序安装：

优先使用 Chrome Web Store 或 Microsoft Edge Add-ons 商店安装。
如果没有商店账号，可从 GitHub Releases 下载自动构建的 ai-helper-*.zip，解压后在开发者模式下加载文件夹。
开发者可运行 npm install && npm run build，然后加载 dist/ 目录。
打开侧边栏： 按下快捷键 Ctrl+Shift+Y（Windows/Linux）或 Cmd+Shift+Y（macOS），或点击扩展图标。
添加 LLM API Key： 在 Options → Basic Settings 中添加 OpenAI 兼容端点。
可选启用本地能力： 安装 Agent 后，在 Options → Agent 中完成配对。

flowchart TD
Start["开始安装"] --> Store{"是否已有 Chrome/Edge 商店账号"}
Store --> |是| StoreInstall["从商店安装扩展"]
Store --> |否| ReleaseInstall["从 GitHub Releases 下载 zip 并解压"]
StoreInstall --> DevMode["打开 chrome://extensions/ 并启用开发者模式"]
ReleaseInstall --> DevMode
DevMode --> LoadExt["加载扩展或已安装的扩展"]
LoadExt --> SidePanel["打开侧边栏"]
SidePanel --> ApiKey["配置 LLM API Key"]
ApiKey --> OptionalAgent{"是否需要本地文件/命令/RAG"}
OptionalAgent --> |不需要| Done["基础功能可用"]
OptionalAgent --> |需要| InstallAgent["安装 Agent 本地代理服务"]
InstallAgent --> Pairing["在扩展设置中粘贴配对码"]
Pairing --> Done

图表来源

章节来源

Chrome 扩展常见安装失败原因

1. Manifest V3 不兼容

扩展声明 manifest_version: 3，因此旧版 Chromium 内核可能无法安装或运行。当前项目要求 Chrome / Edge / Chromium 114+，因为需要使用 Side Panel API。

排查建议：

确认浏览器版本不低于 114。
如果浏览器过旧，请升级浏览器或使用新版 Chromium。
不要尝试降级到 Manifest V2，否则扩展核心功能会失效。

2. 权限配置错误

扩展需要大量权限，包括 sidePanel、scripting、offscreen、cookies、tabs、notifications、clipboardRead、clipboardWrite、commands、alarms、debugger、webNavigation 等。如果权限被企业策略、安全软件或第三方扩展拦截，可能导致扩展部分功能不可用。

排查建议：

检查浏览器扩展权限列表，确认扩展未被禁用。
检查企业策略是否限制 sidePanel、offscreen、scripting 等权限。
临时关闭其他强管控型扩展，观察是否恢复。

3. 远程代码与 CSP 限制

扩展的 Content Security Policy 为 script-src 'self'，禁止远程脚本。所有第三方库应打包进扩展内，不能动态从远端加载 JS。

排查建议：

如果使用自定义构建，确保没有引入远程脚本。
不要直接替换 libs/jspdf.min.js 等静态库，除非确认未引入远程 URL。
审核相关说明指出，构建脚本会对已知风险路径做补丁处理，避免商店拒审。

4. 开发者模式加载失败

从 GitHub Releases 解压后加载失败，通常是因为：

没有启用开发者模式。
加载的是 zip 文件而不是解压后的目录。
构建产物不完整，缺少 dist/ 下的 background、content、side_panel、options 入口。

排查建议：

重新解压 zip。
在 chrome://extensions/ 中点击"加载已解压的扩展程序"，选择解压后的根目录。
开发者构建时运行 npm run build，再加载 dist/。

章节来源

Agent 本地代理服务安装流程

Agent 提供本地文件读写、命令执行、Skill、MCP 和本地知识库（RAG）能力。安装方式分为一键安装和 npm 手动安装。

一键安装（推荐）

macOS / Linux：

bash

curl -fsSL https://raw.githubusercontent.com/xiweicheng/ai-helper/main/install.sh | bash

Windows（PowerShell）：

powershell

irm https://raw.githubusercontent.com/xiweicheng/ai-helper/main/install.ps1 | iex

一键脚本会自动检测网络环境、下载 Node.js 运行时、安装 Agent、配置 CLI 和开机自启，无需用户具备 Node.js 知识。

npm 手动安装

bash

npm install -g ai-helper-agent

该方式要求 Node.js >= 18.0.0；若启用知识库/RAG 功能，建议使用 Node.js >= 22.13.0。

启动与配对

bash

ai-helper-agent start
ai-helper-agent start --background
ai-helper-agent start -b
ai-helper-agent start --workdir /path/to/your/project --port 18910

启动后终端会显示 6 位配对码，将其粘贴到 Chrome 扩展设置的 Agent 面板即可完成配对。默认监听地址为 127.0.0.1:18910。

sequenceDiagram
participant User as "用户"
participant Shell as "终端"
participant Script as "安装脚本"
participant Node as "Node.js 运行时"
participant Agent as "ai-helper-agent"
participant Browser as "Chrome 扩展"
User->>Shell : 运行安装命令
Shell->>Script : 下载并执行 install.sh 或 install.ps1
Script->>Node : 安装或复用 Node.js 运行时
Script->>Agent : 安装 ai-helper-agent 包
Script->>Agent : 启动服务
Agent-->>Shell : 输出 6 位配对码
User->>Browser : 打开扩展设置并粘贴配对码
Browser->>Agent : 发起 /api/pair 配对请求
Agent-->>Browser : 返回 token 并建立会话

图表来源

章节来源

Node.js 环境与依赖冲突排查

Node.js 版本要求

Agent 包声明引擎要求 Node.js >= 18.0.0。
一键脚本固定使用 Node.js 22.13.0，用于保证 RAG 和相关原生依赖的稳定安装。
知识库/RAG 功能对 Node.js 版本更敏感，建议优先使用 22.13.0 或更高版本。

常见冲突场景

系统全局 Node.js 版本过低： 使用 npm install -g ai-helper-agent 时报错，提示引擎不满足。
多 Node.js 管理器共存： nvm、fnm、npx、系统 PATH 中的 node 指向不一致，导致 CLI 找不到正确版本。
RAG 原生依赖编译失败： @huggingface/transformers、vectra、onnxruntime-node 等依赖可能需要原生编译环境。
全局 npm 权限不足： 在非管理员环境下执行 npm install -g 失败。

排查建议：

使用 node --version 和 npm --version 确认当前环境。
如果一键脚本已安装内置 Node.js，优先使用 aha 或 ai-helper-agent 命令，而不是依赖系统全局 node。
遇到原生模块编译失败时，优先使用一键脚本，因为它会安装匹配的 Node.js 二进制。
如果必须使用全局 npm，请确认当前用户有写入全局 node_modules 的权限。

章节来源

npm 安装错误修复方法

1. 网络超时或镜像源不可达

一键脚本会探测 Node.js 官方源、npm 官方 registry、HuggingFace 源，并在不可用时切换到国内镜像。如果仍然失败，通常是防火墙、公司代理或 DNS 问题。

修复建议：

检查是否能访问 https://registry.npmjs.org 和 https://cdn.npmmirror.com。
在公司网络中配置 npm 代理或切换镜像源。
使用 aha status 查看脚本记录的镜像检测结果。

2. 权限错误

Windows 下可能出现权限不足；Linux/macOS 下全局安装可能提示无权限。

修复建议：

优先使用一键脚本，它会在用户目录下安装 Node.js 和 Agent，避免 sudo/administrator。
如果必须全局安装，先解决 npm 全局目录权限，而不是反复重试。

3. 依赖版本冲突

Agent 包包含核心依赖和 RAG 可选依赖。RAG 依赖由 ragDependencies 字段管理，并在 Agent 启动时检测可用性；缺失时 RAG 接口返回 503，扩展端会提示安装。

修复建议：

使用 ai-helper-agent rag status 检查 RAG 依赖状态。
使用 ai-helper-agent rag install 安装白名单内的 RAG 依赖。
如果之前成功安装过但升级后丢失，Agent 支持自动恢复：启动时会尝试重新安装 RAG 依赖。

4. 更新失败

Agent 内部提供 /api/agent/update，但该接口会执行 npm install -g ai-helper-agent@latest，存在超时、网络失败、权限失败等风险。

修复建议：

优先使用 aha update 或安装脚本的更新逻辑。
如果前端触发更新失败，不要重复点击，先检查网络和 npm 环境。
更新失败时保留老进程，避免服务中断。

章节来源

扩展端与 Agent 端版本同步要求

扩展端和 Agent 端都必须使用 2.4.0。

扩展端版本来自 manifest.json 和 package.json，均为 2.4.0。
Agent 端 npm 包 ai-helper-agent 版本也应为 2.4.0。
扩展设置中的安装指引会根据扩展版本生成对应 Agent 安装命令，并通过 AGENT_VERSION 环境变量传递版本标识。

如果 Agent 版本低于 2.4.0，可能出现：

缺少 /api/memory/* 接口。
缺少 RAG、MCP、Skill 等新能力。
扩展端提示版本不匹配或连接异常。

修复建议：

在扩展设置中复制带版本的安装命令。
使用 aha update 升级到最新稳定版本。
如果团队统一部署，应同时升级扩展和 Agent，并保持版本一致。

flowchart TD
ExtVersion["扩展端版本 2.4.0"] --> Guide["Options 安装指引生成命令"]
Guide --> EnvVar["AGENT_VERSION=2.4.0"]
EnvVar --> Installer["install.sh / install.ps1"]
Installer --> AgentPkg["安装 ai-helper-agent 2.4.0"]
AgentPkg --> Status["/api/status 返回版本"]
ExtVersion --> Status
Status --> Match{"版本是否匹配"}
Match --> |是| Connected["扩展与 Agent 正常通信"]
Match --> |否| Mismatch["可能出现接口缺失或连接失败"]

图表来源

章节来源

GitHub Releases 官方构建产物验证

唯一官方渠道是 GitHub Releases 自动构建产物。不要将手动 clone 源码构建作为推荐安装路径。

验证要点

来源可信： 从 GitHub Releases 页面下载，不要从第三方站点获取 zip。
文件名特征： 扩展包名通常为 ai-helper-*.zip。
解压后结构： 应包含 manifest.json、src/、dist/、icons/、_locales/、styles/、libs/ 等目录。
版本一致性： manifest.json 中 version 应为 2.4.0。
开发者构建产物： 开发者运行 npm run build 后，dist/ 应包含 background、content、side_panel、options 四个入口。

手动加载步骤

下载 ai-helper-*.zip。
解压到任意目录。
打开 chrome://extensions/。
启用"开发者模式"。
点击"加载已解压的扩展程序"，选择解压后的根目录。
确认扩展图标出现，并可打开侧边栏。

构建产物注意事项

构建输出目录为 dist/。
构建关闭 sourcemap，避免发布产物中包含源码映射。
静态资源如 libs、styles、icons、_locales 会通过构建插件复制到输出目录。

章节来源

浏览器兼容性检查

最低版本要求

项目明确要求 Chrome / Edge / Chromium 114+，原因是使用了 Side Panel API。

检查方法

打开浏览器关于页面，查看版本号。
确认内核为 Chromium 114 或更高。
如果浏览器提示扩展不兼容，优先升级浏览器。
在企业环境中，确认 IT 策略未锁定浏览器版本。

常见兼容症状

扩展可以安装，但侧边栏打不开。
某些页面注入失败。
offscreen 文档或 background Service Worker 行为异常。
快捷键无效。

章节来源

系统权限配置

Chrome 扩展权限

扩展声明了广泛权限，用于网页操作、存储、通知、调试、剪贴板、标签页管理等。这些权限是扩展实现自动化能力的必要前提。

关键权限说明：

activeTab、tabs、tabGroups：读取和操作标签页。
storage、unlimitedStorage：保存配置、会话、记忆数据。
sidePanel：打开侧边栏。
scripting、content_scripts：向网页注入脚本。
offscreen：配合 MV3 Service Worker 生命周期使用。
cookies、history、downloads、bookmarks：辅助网页操作。
notifications：任务完成或失败提醒。
clipboardRead、clipboardWrite：剪贴板交互。
commands：快捷键控制。
alarms：定时任务。
debugger、webNavigation：调试与导航能力。

Agent 系统权限

Agent 的命令执行具有黑灰名单机制：

黑名单命令直接拒绝。
灰名单命令需要用户确认。
高危命令如 rm -rf /、系统文件覆盖、管道执行、fork bomb 等会被拦截。
文件操作受 allowedPaths 白名单和工作目录限制。

排查建议：

如果命令执行被拒绝，查看 Agent 终端日志或审计日志。
如果需要执行特定命令，先在扩展或 Agent 配置中确认是否属于灰名单。
不要随意扩大 allowedPaths，应限定到项目工作目录。

章节来源

网络代理与下载源设置

一键脚本的网络探测

install.sh 和 install.ps1 都会探测：

Node.js 下载源：官方 vs npmmirror。
npm registry：官方 vs npmmirror。
HuggingFace：官方 vs hf-mirror。

探测结果保存在 ~/.ai-helper-agent/mirrors.json。

常见问题

Node.js 下载失败： 可能是国家网络限制或代理未配置。
npm registry 不可达： 公司内网可能只允许访问私有 registry。
RAG 模型下载失败： HuggingFace 可能被墙，需使用 hf-mirror 或配置代理。
安装脚本中途退出： 检查 curl/wget、tar、PowerShell TLS 设置。

修复建议：

使用 aha status 查看镜像检测结果。
在公司网络中配置 npm 代理或私有 registry。
如果 RAG 依赖安装失败，先确认网络可达性，再执行 ai-helper-agent rag install。
Windows 下 PowerShell 5.1 可能需要显式启用 TLS12，安装脚本已在命令生成时处理。

章节来源

常见问题排查清单

1. 扩展商店安装失败

现象：

Chrome Web Store 或 Edge Add-ons 显示无法安装。
提示扩展不兼容。

可能原因：

浏览器版本低于 114。
企业策略阻止商店安装。
浏览器内核不是 Chromium。

解决方法：

升级浏览器至 114+。
改用 GitHub Releases 手动加载。
联系企业 IT 确认扩展安装策略。

2. 开发者模式加载扩展失败

现象：

加载后扩展立即消失。
控制台报 manifest 错误或 CSP 错误。

可能原因：

加载的不是解压目录。
构建产物不完整。
自定义构建引入了远程脚本。

解决方法：

重新解压 zip。
开发者构建后加载 dist/。
检查构建脚本是否引入远程 JS。

3. 侧边栏打不开

现象：

快捷键无效。
扩展图标点击无响应。
侧边栏空白或崩溃。

可能原因：

浏览器不支持 Side Panel API。
Service Worker 被终止且未保活。
side panel 与 background 消息传递失败。

解决方法：

确认浏览器版本 >= 114。
打开任意页面激活扩展。
检查 background 和 side panel 日志。

4. Agent 未启动或端口占用

现象：

扩展提示"代理服务未连接"。
aha status 显示未运行。
端口 18910 被占用。

可能原因：

Agent 进程未启动。
上次异常退出残留 PID 文件。
端口被其他服务占用。

解决方法：

运行 aha stop 清理状态。
运行 aha start 重新启动。
如需更换端口，使用 --port 参数。
检查 ~/.ai-helper-agent/agent.pid 是否存在异常。

5. 配对失败

现象：

扩展提示"配对失败"或"无法连接到 Agent"。
Agent 终端没有收到配对请求。

可能原因：

Agent 未启动。
扩展配置的 Agent URL 不正确。
配对码过期（默认 30 秒）。
浏览器无法访问 http://127.0.0.1:18910。

解决方法：

确认 Agent 正在运行。
在浏览器访问 http://127.0.0.1:18910/api/status 测试连通性。
重新获取配对码并快速粘贴。
检查防火墙或代理是否拦截本地回环地址。

6. 命令执行被拒绝

现象：

命令执行返回安全拒绝。
终端日志显示"高风险命令被阻止"。

可能原因：

命令命中黑名单。
命令命中灰名单但未确认。
路径不在 allowedPaths 白名单。

解决方法：

查看 Agent 审计日志。
调整命令或工作目录。
谨慎扩大白名单。

7. RAG 功能不可用

现象：

RAG 接口返回 503。
扩展提示依赖缺失。
向量索引重建失败。

可能原因：

Node.js 版本过低。
RAG 依赖未安装。
HuggingFace 或 embedding 端点不可达。
向量缓存损坏。

解决方法：

使用 Node.js >= 22.13.0。
执行 ai-helper-agent rag status。
执行 ai-helper-agent rag install。
删除 memory-vectors.json 后重建索引。

章节来源

结论与建议

安装 AI Helper 时，最关键的判断标准是：扩展端与 Agent 端都必须是 2.4.0，并且 Agent 必须先于扩展功能使用。

推荐安装顺序：

从 Chrome Web Store、Edge Add-ons 或 GitHub Releases 安装扩展。
确认浏览器版本 >= 114。
安装 Agent 本地代理服务。
在扩展设置中完成配对。
如需本地文件、命令、MCP、Skill 或 RAG，再按需配置 Agent。

常见失败集中在三类：

浏览器版本或 Manifest V3 不兼容。
Agent 未启动、端口不可达或配对码过期。
npm 环境、Node.js 版本或 RAG 依赖缺失。

遇到问题时，优先检查：

浏览器版本和扩展权限。
aha status 和 Agent 终端日志。
http://127.0.0.1:18910/api/status 是否可访问。
扩展端与 Agent 端版本是否一致。

Markdown 渲染引擎

安装问题排查 ​

更新摘要 ​

目录 ​

文档目标与适用范围 ​

双进程架构与版本约束 ​

Chrome 扩展安装步骤 ​

Chrome 扩展常见安装失败原因 ​

1. Manifest V3 不兼容 ​

2. 权限配置错误 ​

3. 远程代码与 CSP 限制 ​

4. 开发者模式加载失败 ​

Agent 本地代理服务安装流程 ​

一键安装（推荐） ​

npm 手动安装 ​

启动与配对 ​

Node.js 环境与依赖冲突排查 ​

Node.js 版本要求 ​

常见冲突场景 ​

npm 安装错误修复方法 ​

1. 网络超时或镜像源不可达 ​

2. 权限错误 ​

3. 依赖版本冲突 ​

4. 更新失败 ​

扩展端与 Agent 端版本同步要求 ​

GitHub Releases 官方构建产物验证 ​

验证要点 ​

手动加载步骤 ​

构建产物注意事项 ​

浏览器兼容性检查 ​

最低版本要求 ​

检查方法 ​

常见兼容症状 ​

系统权限配置 ​

Chrome 扩展权限 ​

Agent 系统权限 ​

网络代理与下载源设置 ​

一键脚本的网络探测 ​

常见问题 ​

常见问题排查清单 ​

1. 扩展商店安装失败 ​

2. 开发者模式加载扩展失败 ​

3. 侧边栏打不开 ​

4. Agent 未启动或端口占用 ​

5. 配对失败 ​

6. 命令执行被拒绝 ​

7. RAG 功能不可用 ​

结论与建议 ​

安装问题排查

更新摘要

目录

文档目标与适用范围

双进程架构与版本约束

Chrome 扩展安装步骤

Chrome 扩展常见安装失败原因

1. Manifest V3 不兼容

2. 权限配置错误

3. 远程代码与 CSP 限制

4. 开发者模式加载失败

Agent 本地代理服务安装流程

一键安装（推荐）

npm 手动安装

启动与配对

Node.js 环境与依赖冲突排查

Node.js 版本要求

常见冲突场景

npm 安装错误修复方法

1. 网络超时或镜像源不可达

2. 权限错误

3. 依赖版本冲突

4. 更新失败

扩展端与 Agent 端版本同步要求

GitHub Releases 官方构建产物验证

验证要点

手动加载步骤

构建产物注意事项

浏览器兼容性检查

最低版本要求

检查方法

常见兼容症状

系统权限配置

Chrome 扩展权限

Agent 系统权限

网络代理与下载源设置

一键脚本的网络探测

常见问题

常见问题排查清单

1. 扩展商店安装失败

2. 开发者模式加载扩展失败

3. 侧边栏打不开

4. Agent 未启动或端口占用

5. 配对失败

6. 命令执行被拒绝

7. RAG 功能不可用

结论与建议