AI Helper 文档中心

主题

常见错误与解决方案 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构与错误边界总览
  3. 核心错误分类与处理机制
  4. 架构总览与错误流转图
  5. 详细错误类别与解决方案
  6. 依赖关系与耦合分析
  7. 性能与稳定性考量
  8. 故障排查指南
  9. 结论
  10. 附录：错误复现模板与调试报告格式

引言 ​

本文件面向用户、测试人员与开发者，系统化整理 AI Helper 扩展端（Chrome 扩展）与 Agent 本地代理端之间的常见错误。文档按错误类型组织，覆盖网络连接错误、权限拒绝错误、参数验证错误和内部服务器错误四类；每类包含错误码说明、发生原因、正则匹配模式、解决步骤、预防策略、上报与反馈方式，以及社区已知案例与官方修复建议。

本项目为双进程架构：

  • Chrome 扩展端（Manifest V3，版本 2.3.1）。
  • 独立本地 Agent 代理端（Node.js，入口 agent/src/server.js，npm 包 ai-helper-agent，版本 2.3.1）。 两端通过 HTTP/WebSocket 通信，Agent 修改源码后必须重启进程，新接口才生效。

项目结构与错误边界总览 ​

错误在以下边界产生并被捕获：

  • 扩展侧工具执行层：网络访问、浏览器能力、工具参数校验。
  • 扩展侧 Agent 客户端：配对、HTTP 请求、WebSocket 连接、上传下载。
  • Agent 服务端：路由解析、认证鉴权、文件/命令/MCP/Skill/RAG 等子系统。
  • 日志系统：Agent 审计日志 JSON Lines 文件与扩展侧控制台日志。
graph TB
UI["用户界面<br/>side_panel / options"] --> ToolExec["工具执行器<br/>tool-executor.js"]
ToolExec --> AgentClient["Agent 客户端<br/>local-agent-client.js"]
AgentClient --> Server["Agent 服务端<br/>server.js"]
Server --> FS["文件系统与安全校验"]
Server --> Exec["命令执行"]
Server --> MCP["MCP 工具注册与调用"]
Server --> Skill["技能系统"]
Server --> RAG["知识库检索"]
Server --> Logger["审计日志<br/>logger.js"]

图表来源

章节来源

核心错误分类与处理机制 ​

  • 网络连接错误：包括 Agent 不可达、超时、CORS、协议限制、内网访问拦截、URL 非法、响应读取失败等。
  • 权限拒绝错误：包括未提供 token、token 无效、路径不在允许列表、高危命令被拦截、RAG 依赖缺失、端口占用等。
  • 参数验证错误：包括缺少 path/url/command/name 等参数、非绝对路径、Windows 非法字符、空数组、大小超限、JSON 解析失败等。
  • 内部服务器错误：包括 server.js 顶层异常兜底、RAG 模块加载失败、ZIP/URL 导入失败、打包/解析失败等。

Agent 服务端统一使用 i18n 文案键 error.* 返回结构化错误；扩展侧对网络异常进行降级与友好提示，并保留原始错误用于诊断。

章节来源

架构总览与错误流转图 ​

sequenceDiagram
participant User as "用户"
participant Panel as "侧边栏/选项页"
participant Tool as "工具执行器<br/>tool-executor.js"
participant Client as "Agent 客户端<br/>local-agent-client.js"
participant Server as "Agent 服务端<br/>server.js"
participant Log as "审计日志<br/>logger.js"
User->>Panel : 发起任务
Panel->>Tool : 调用工具如 fetch_url
Tool->>Tool : 参数校验与网络范围判定
Tool->>Client : 发送 HTTP/WebSocket 请求
Client->>Server : 携带 Bearer Token 的请求
Server->>Server : 认证、路由、业务校验
Server-->>Client : 返回 success/error + httpStatus
Client-->>Tool : 翻译后的错误信息
Tool-->>Panel : 展示用户友好提示
Server->>Log : 记录安全/系统/文件/命令日志

图表来源

详细错误类别与解决方案 ​

一、网络连接错误 ​

典型场景：

  • Agent 服务未启动或不可达。
  • 请求超时（AbortError）。
  • CORS 跨域限制。
  • fetch_url 工具被网络范围策略拦截（非 http/https、内网地址、白名单未命中）。
  • URL 非法或缺失。
  • 响应内容读取失败。

常见错误码与文案键：

  • agentClient.cannotConnectAgent / agentClient.requestTimeout / agentClient.agentRequestFailed
  • toolExec.missingUrlParam / toolExec.invalidUrlFormat / toolExec.schemeBlocked / toolExec.networkGateClosed / toolExec.networkNoAllowlist / toolExec.networkHostNotAllowed / toolExec.readResponseFailed / toolExec.requestFailed
  • server.js 顶层异常兜底返回 error.internal

正则匹配模式（便于自动化处理与日志分析）：

  • 连接失败：/无法连接到 Agent|Cannot connect to Agent/
  • 请求超时：/请求超时|Request timeout/
  • 请求失败：/Agent 请求失败|Agent request failed/
  • URL 缺失：/缺少 url 参数|Missing url parameter/
  • URL 非法：/无效的 URL|Invalid URL|not a url/
  • 协议受限：/仅支持 http/https|Only http/https protocols are supported/
  • 内网拦截：/本机/内网地址|private network|localhost|127.0.0.1/
  • 响应读取失败：/读取响应内容失败|Failed to read response content/

解决步骤：

  1. 确认 Agent 已启动且可访问：检查 /api/status 健康检查是否返回成功。
  2. 若提示“代理服务未连接”，先确认 Agent 进程运行状态，再重试。
  3. 若出现超时，适当增大超时时间或检查目标服务可用性。
  4. 若 fetch_url 被拦截：
    • 确保 URL 为 http/https。
    • 打开“推理”标签的“内网地址访问”总开关。
    • 将目标主机加入允许列表（例如 127.0.0.1 或 intranet.example.com）。
    • 不要建议用户放开整个内网。
  5. 若出现 CORS 错误，确认目标服务器允许跨域访问。
  6. 若响应读取失败，检查响应体是否为有效文本或过大导致截断。

预防最佳实践：

  • 在工具入口处严格校验 URL 是否存在、是否合法。
  • 在网络范围判定处优先拒绝非 http/https 与非白名单内网地址。
  • 对 AbortError 明确区分“超时”与“其他网络错误”。
  • 避免把敏感请求头写入控制台日志。

错误上报与反馈：

  • 用户侧显示：使用 i18n 文案键（如 toolExec.、agentClient.），给出可操作指引。
  • 开发者侧记录：保留 originalError、url、httpStatus，便于定位。

社区已知案例与官方修复建议：

  • 审计指出 fetch_url 存在 SSRF 风险，需纳入确认流程、增加目标校验、屏蔽敏感请求头日志。
  • 参考修复建议见审计报告中关于 fetch_url 的安全修复条目。

章节来源

二、权限拒绝错误 ​

典型场景：

  • 未提供认证 token。
  • token 无效。
  • 路径不在允许列表。
  • 高危命令被拦截（sudo、rm -rf、chmod 777、systemd 修改等）。
  • RAG 依赖未安装或环境不满足要求。
  • 端口已被占用。

常见错误码与文案键：

  • error.noToken / error.invalidToken
  • security.pathNotInAllowedDir / security.commandBlocked / security.cmd*
  • error.ragNotAvailable / error.portInUse

正则匹配模式：

  • 认证缺失：/未提供认证 token|No authentication token provided/
  • 认证无效：/认证 token 无效|Invalid authentication token/
  • 路径不允许：/路径不在允许的目录范围内|Path is not within allowed directories/
  • 命令被拦截：/高危命令被拦截|High-risk command blocked/
  • RAG 不可用：/RAG 功能依赖未安装|RAG dependencies are not installed/
  • 端口占用：/端口已被占用|Port already in use/

解决步骤：

  1. 若提示未提供 token，重新完成 Agent 配对流程。
  2. 若 token 无效，检查配对是否过期或被篡改，必要时重新配对。
  3. 若路径不在允许列表，调整 workdir 或 allowedPaths，确保目标路径在允许范围内。
  4. 若命令被拦截，评估命令风险，必要时改用受控命令或通过确认流程。
  5. 若 RAG 不可用，按扩展页面引导安装 RAG 依赖，或运行 aha rag install。
  6. 若端口占用，停止已有 Agent 进程后再启动。

预防最佳实践：

  • 所有需要认证的接口统一校验 Authorization 头。
  • 路径与命令在进入业务逻辑前做安全检查。
  • RAG 相关功能在检测失败时给出明确安装指引。
  • 启动前检查端口占用情况，避免重复监听。

错误上报与反馈：

  • 用户侧：显示具体错误原因与操作指引（如“请在设置中打开内网访问并添加主机到白名单”）。
  • 开发者侧：记录 security 类别日志，包含 path、command、remote 等信息。

章节来源

三、参数验证错误 ​

典型场景：

  • 缺少 path/url/command/name/steps 等必需参数。
  • path/workdir 不是绝对路径。
  • Windows 非法字符。
  • paths 为空数组。
  • 请求体过大、JSON 解析失败、multipart 数据格式不正确。
  • RAG 导入内容过大、URL 重定向过多、向量维度不匹配。

常见错误码与文案键：

  • error.missingPath / error.missingWorkdir / error.missingCommand / error.missingName / error.missingNameAndSteps
  • error.workdirNotAbsolute / error.pathNotAbsolute / error.newNameInvalidChars
  • error.bodyTooLarge / error.invalidJson / error.invalidMultipart / error.malformedMultipart
  • rag.err_contentTooLarge / rag.err_urlTooManyRedirects / rag.err_embeddingDimensionMismatch

正则匹配模式：

  • 缺少参数：/缺少 .* 参数|Missing .* parameter/
  • 非绝对路径：/必须是绝对路径|must be an absolute path/
  • Windows 非法字符：/Windows 非法字符|Windows invalid characters/
  • 请求体过大：/请求体过大|Request body too large/
  • JSON 解析失败：/请求体不是有效的 JSON|Request body is not valid JSON/
  • multipart 格式错误：/multipart 数据格式不正确|Malformed multipart data format/
  • RAG 内容过大：/导入内容超过大小限制|Import content exceeds the size limit/
  • 向量维度不匹配：/向量维度不匹配|Embedding dimension mismatch/

解决步骤：

  1. 补全缺失参数，确保类型正确（字符串、数组、对象）。
  2. 将 path/workdir 改为绝对路径。
  3. 清理文件名中的 Windows 非法字符。
  4. 检查请求体大小与 JSON 格式，避免超大 payload。
  5. 对于 multipart 上传，确保 boundary、headers、file data 完整。
  6. RAG 导入时控制文件大小、URL 重定向次数，并确保向量模型维度与配置一致。

预防最佳实践：

  • 在路由与工具入口处集中校验参数，尽早返回错误。
  • 对超大请求体与文件流式上传设置上限。
  • 对 RAG 导入与检索参数进行白名单与范围校验。
  • 对向量维度、embedding endpoint 进行预检。

错误上报与反馈：

  • 用户侧：提示具体缺失字段或非法值，并给出修正建议。
  • 开发者侧：记录 error.* 与 rag.err_* 错误码及 params，便于统计与优化。

章节来源

四、内部服务器错误 ​

典型场景：

  • server.js 顶层异常兜底返回 internal。
  • RAG 模块加载失败。
  • ZIP/URL 导入失败。
  • 打包/解析失败。
  • npm 更新超时或退出码异常。

常见错误码与文案键：

  • error.internal
  • error.ragLoadFailed
  • error.zipImportFailed / error.urlImportFailed
  • error.packFailed / error.parseFailed
  • error.npmInstallTimeout / error.npmInstallExitCode / error.updateFailed

正则匹配模式：

  • 内部错误：/服务器内部错误|Internal server error/
  • RAG 加载失败：/知识库模块加载失败|Failed to load knowledge base module/
  • 导入失败：/Zip 导入失败|URL 导入失败|Zip import failed|URL import failed/
  • 打包/解析失败：/打包失败|解析失败|Pack failed|Parse failed/
  • npm 更新失败：/npm install 超时|npm install exit code|Update failed/

解决步骤：

  1. 若出现 internal 错误，查看 Agent 终端输出与审计日志，定位异常堆栈。
  2. 若 RAG 加载失败，尝试重启 Agent 后重试；必要时重装 RAG 依赖。
  3. 若 ZIP/URL 导入失败，检查压缩包结构或 URL 可达性。
  4. 若打包/解析失败，检查输入数据完整性与格式。
  5. 若 npm 更新失败，手动执行 npm install -g ai-helper-agent@latest，并检查网络与镜像源。

预防最佳实践：

  • 对异步初始化与外部依赖加载增加 try/catch 与降级策略。
  • 对 npm 子进程增加超时与进程树终止保护。
  • 对 ZIP/URL 导入增加结构校验与大小限制。
  • 对打包/解析过程增加错误码与详细 message。

错误上报与反馈：

  • 用户侧：提示“请重启代理端后重试”或“请手动执行更新命令”。
  • 开发者侧：记录 system/security/fs/exec 类别日志，附带错误 message 与上下文。

章节来源

依赖关系与耦合分析 ​

  • 工具执行器依赖网络范围策略与 i18n 文案，负责前端侧的参数校验与错误翻译。
  • Agent 客户端封装 HTTP/WebSocket 请求，统一处理超时、不可达、配对状态。
  • Agent 服务端承担认证、路由、业务逻辑与日志记录。
  • RAG 错误采用 RagError 类与 translateRagError 函数，保证错误码与参数可翻译。
classDiagram
class ToolExecutor {
+executeFetchUrl(args, toolCallId)
+参数校验()
+网络范围判定()
}
class AgentClient {
+agentRequest(path, body, method, timeoutMs)
+agentGet(path, timeoutMs)
+createExecWebSocket(wsUrl, onMessage, onClose, onError)
}
class Server {
+handleRequest(req, res)
+parseBody(req)
+parseMultipartBody(req)
+jsonResponse(res, status, data)
}
class RagError {
+code
+params
+translateRagError(err, t)
}
ToolExecutor --> AgentClient : "调用"
AgentClient --> Server : "HTTP/WebSocket"
Server --> RagError : "RAG 错误转换"

图表来源

章节来源

性能与稳定性考量 ​

  • 请求体与文件上传大小限制：MAX_BODY_SIZE、MAX_UPLOAD_SIZE，防止内存溢出。
  • npm 更新超时保护：90 秒超时，终止整棵进程树防孤儿。
  • 日志清理：保留最近 MAX_LOG_FILES 个日志文件，单文件最大 MAX_LOG_SIZE。
  • WebSocket 空闲超时由调用方统一管理，避免双重超时冲突。
  • Service Worker 生命周期硬约束：保活与消息传递是常见故障点，需在扩展侧做降级与重试。

章节来源

故障排查指南 ​

快速定位步骤：

  1. 确认 Agent 是否在线：访问 /api/status，观察 version、running、platform 等字段。
  2. 检查认证：Authorization 头是否携带有效 Bearer token。
  3. 检查网络范围：fetch_url 是否被 scheme/gate/allowlist 拦截。
  4. 检查参数：path/url/command/name 是否齐全且类型正确。
  5. 查看 Agent 审计日志：~/.ai-helper-agent/logs/agent-YYYY-MM-DD.log，过滤 category 与 action。
  6. 查看扩展侧控制台日志：[AIH] 前缀日志，关注 warn/error。
  7. 若为 RAG 问题，检查 Node 版本、可选依赖、向量模型维度与 endpoint。

常见错误对照：

  • 401/403：认证缺失或 token 无效。
  • 400：参数错误或请求体格式错误。
  • 404：文件不存在或 API 路径未知。
  • 429：操作过于频繁。
  • 500：内部服务器错误。

章节来源

结论 ​

通过对扩展端与 Agent 端的错误边界进行系统化梳理，可将常见错误归并为网络连接、权限拒绝、参数验证与内部服务器四类。每类均具备明确的错误码、正则匹配模式与解决步骤。结合 i18n 文案、审计日志与单元测试，可实现用户友好的错误提示与开发者友好的详细日志。建议在工具入口与网络访问处加强参数校验与安全策略，在 Agent 端完善依赖检测与降级处理，以提升整体稳定性与可维护性。

附录：错误复现模板与调试报告格式 ​

错误复现步骤模板：

  • 环境信息：操作系统、Node 版本、Agent 版本、扩展版本。
  • 触发条件：操作步骤、输入参数、网络环境。
  • 预期结果：期望的成功响应或错误提示。
  • 实际结果：实际错误码、错误文案、HTTP 状态码。
  • 日志附件：Agent 审计日志片段、扩展控制台日志。
  • 截图/录屏：关键界面与错误弹窗。

调试报告格式建议：

  • 标题：错误类别 + 简要描述。
  • 复现步骤：编号步骤，尽量最小化。
  • 错误信息：复制粘贴错误文案与原始错误。
  • 日志摘要：category、action、timestamp、details。
  • 根因分析：参数校验失败、网络范围拦截、认证失败、依赖缺失等。
  • 解决方案：用户操作指引与开发者修复建议。
  • 回归测试：对应单元测试或集成测试用例链接。

章节来源