AI Helper 文档中心

主题

Agent 服务问题 ​

本文引用的源码文件

本文引用的文件

目录 ​

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

引言 ​

本文件面向 Agent 服务的运维与排障，覆盖启动失败、连接异常、权限拒绝、资源占用过高、MCP 协议问题以及 RAG 索引构建失败等典型场景。Agent 为独立 Node.js 进程（默认监听 127.0.0.1:18910），Chrome 扩展通过 HTTP/WebSocket 调用其文件系统、命令执行、长期记忆与 RAG 能力；修改 Agent 源码后必须重启进程，新接口才生效。

项目结构 ​

Agent 端以 server.js 为 HTTP + WebSocket 入口，按功能拆分为配置、安全、命令执行、MCP、RAG、长期记忆等模块；扩展端 background/local-agent-client.js 封装所有远程调用。

graph TB
subgraph "Chrome 扩展"
LAC["background/local-agent-client.js"]
end
subgraph "Agent 进程"
S["server.js<br/>HTTP+WebSocket 路由"]
CFG["config.js<br/>配置读写"]
SEC["security.js<br/>路径/命令安全"]
EXE["executor.js<br/>命令执行器"]
MCP["mcp/client.js<br/>MCP 客户端"]
RAG["rag/manager.js<br/>知识库生命周期"]
MEM["memory/service.js<br/>长期记忆"]
end
LAC --> |HTTP / WebSocket| S
S --> CFG
S --> SEC
S --> EXE
S --> MCP
S --> RAG
S --> MEM

图示来源

章节来源

核心组件 ​

  • 服务器与路由：负责端口监听、CORS、认证、健康检查、重启/更新、文件上传、状态详情等。
  • 配置管理：默认端口 18910、工作目录、allowedPaths、pairCodeTTL、commandTimeout、fileMaxSize、RAG URL 内网策略、记忆 embedding 配置。
  • 安全管控：路径白名单 + 硬阻止清单 + 符号链接校验；命令黑名单/灰名单分级。
  • 命令执行：跨平台 shell 选择、流式输出、超时预算与延长策略、进程树终止。
  • MCP 客户端：支持 stdio/SSE/streamable-http/websocket 传输，工具发现与调用。
  • RAG 管理器：知识库注册表、文档导入、分块、向量化、向量存储、检索参数上限、重建与崩溃恢复。
  • 长期记忆：关键词通道 + 可选向量通道，召回锁外嵌入、冷却与降级。
  • 扩展端客户端：配对、认证、HTTP/WebSocket 封装、可达性缓存、错误提示。

章节来源

架构总览 ​

扩展端通过 local-agent-client.js 发起带 Bearer Token 的 HTTP 请求或 WebSocket 连接；Agent server.js 在请求入口处设置各子模块语言、校验 CORS、鉴权，再分发到文件、命令、MCP、RAG、记忆等子系统。

sequenceDiagram
participant Ext as "扩展端<br/>local-agent-client.js"
participant Srv as "Agent 服务器<br/>server.js"
participant Sec as "安全模块<br/>security.js"
participant Exe as "命令执行器<br/>executor.js"
participant Rag as "RAG 管理器<br/>rag/manager.js"
participant Mem as "长期记忆<br/>memory/service.js"
Ext->>Srv : "POST /api/exec (Bearer Token)"
Srv->>Srv : "解析语言/CORS/鉴权"
Srv->>Sec : "checkCommand(command, force)"
Sec-->>Srv : "{safe, level}"
alt 允许
Srv->>Exe : "executeCommand(command, cwd, wsClient)"
Exe-->>Ext : "stdout/stderr/exit 流式消息"
else 拒绝/确认
Srv-->>Ext : "{success : false, error}"
end
Note over Ext,Rag : "RAG 导入/检索走 /api/rag/* 路由"
Note over Ext,Mem : "记忆 recall/store 走 /api/memory/* 路由"

图示来源

详细组件分析 ​

启动失败诊断 ​

常见问题包括端口占用、配置文件损坏、依赖库加载失败、Node 版本不兼容。

  • 端口占用检查
    • 默认监听 host=127.0.0.1、port=18910；若被占用，server 无法启动。
    • 建议先查看系统端口占用情况，再调整 config.json 中的 port/host。
  • 配置文件验证
    • 配置文件位于用户目录下 .ai-helper-agent/config.json；若 JSON 解析失败，loadConfig 会回退默认值并记录日志。
    • 注意 memoryEmbedding.apiKey 落盘前混淆，读取时解密；若加密字段损坏，可能影响后续 RAG/记忆链路。
  • 依赖库加载错误
    • server.js 启动时会异步检测 RAG 能力；若 Node 环境缺失原生依赖或子进程探测失败，RAG 不可用但服务仍可启动。
    • 若 npm 全局安装 ai-helper-agent 失败，应优先检查网络代理、npm registry、权限与磁盘空间。
flowchart TD
Start(["启动 Agent"]) --> LoadCfg["加载 config.json"]
LoadCfg --> CfgOk{"JSON 有效？"}
CfgOk -- "否" --> Fallback["使用默认配置并记录错误"]
CfgOk -- "是" --> DetectRAG["异步检测 RAG 能力"]
DetectRAG --> Listen["监听 HTTP/WebSocket"]
Fallback --> Listen
Listen --> Ready(["服务就绪"])

图示来源

章节来源

连接异常处理流程 ​

涵盖 HTTP/WebSocket 超时、认证失败、跨域访问问题。

  • HTTP/WebSocket 超时
    • 扩展端 agentRequest/agentGet/createExecWebSocket 均使用 AbortController 控制超时；AbortError 会返回“请求超时”提示。
    • 对于长任务（如 exec wait），可传入 timeoutMs 协商受管模式；Agent 端 executor.js 会根据输出心跳决定是否延长或终止。
  • 认证失败
    • 未携带 Authorization: Bearer token 的请求会被拒绝；token 无效也会返回 401/403。
    • 配对流程通过 /api/pair 完成，成功后扩展端保存 token 并在后续请求中附带。
  • 跨域访问
    • server.js 仅放行 chrome-extension:// 来源的 Origin；普通网页无法读取无认证端点响应，避免信息泄露。
    • 预检 OPTIONS 与 JSON 响应都会根据 allowedOrigin 设置 Access-Control-Allow-Origin。
sequenceDiagram
participant Ext as "扩展端"
participant Srv as "Agent 服务器"
Ext->>Srv : "GET /api/status/detail (无 Token)"
Srv-->>Ext : "401 {success : false, error : noToken}"
Ext->>Srv : "POST /api/pair (code, extensionId)"
Srv-->>Ext : "{success : true, token}"
Ext->>Srv : "GET /api/status/detail (Authorization : Bearer token)"
Srv-->>Ext : "200 {version, workdir, resourceUsage...}"

图示来源

章节来源

权限拒绝错误排查 ​

包括文件系统访问权限、命令执行白名单和安全策略配置。

  • 文件系统访问
    • checkPath 对路径进行规范化、白名单前缀匹配、realpath 符号链接校验，并命中 HARD_BLOCKED_PATHS 直接拒绝。
    • workdir 始终放行；allowedPaths 为空时回退为 workdir。
    • 若路径不在 allowedPaths 或命中硬阻止，会返回“路径不在允许目录”或“禁止访问 Agent 敏感文件”。
  • 命令执行白名单
    • checkCommand 将命令拆分为多个子段，逐段匹配黑名单（deny）和灰名单（confirm）。
    • 黑名单包含 rm -rf /、格式化、fork bomb、shebang 直执、管道注入 sh 等高危模式；灰名单包含 sudo、rm -rf、chmod 777、kill、systemctl、脚本解释器执行外部文件等。
    • force=true 可跳过灰名单，但黑名单仍生效。
  • 安全策略配置
    • 可通过 config.allowedPaths 限制文件访问范围；RAG URL 导入支持 allowPrivateNetwork + allowedPrivateHosts 双闸策略。
flowchart TD
A["输入 path/command"] --> N["规范化路径/命令"]
N --> H["硬阻止检查"]
H -- "命中" --> Deny["拒绝：禁止访问 Agent 敏感文件"]
H -- "未命中" --> W["白名单前缀匹配"]
W -- "不在 allowedPaths" --> PathErr["拒绝：路径不在允许目录"]
W -- "在 allowedPaths" --> Real["realpath 校验"]
Real --> OK["允许"]
N --> Cmd["命令分级：黑名单/灰名单"]
Cmd --> Level{"level=deny/confirm/allow"}
Level --> Deny
Level --> Confirm["需要用户确认"]
Level --> Allow["允许执行"]

图示来源

章节来源

资源占用过高分析方法 ​

包括进程树监控、内存使用分析和 CPU 负载优化。

  • 进程树监控
    • executor.js 维护 runningProcesses 与 completedProcesses，提供 getRunningProcesses 列出运行中命令的 execId、pid、command、duration。
    • killProcess 在 Unix 下尝试进程组 SIGTERM/SIGKILL，Windows 下使用 taskkill /T /PID 递归终止。
  • 内存使用分析
    • /api/status/detail 返回 memoryUsedMB、memoryTotalMB、memoryRssMB、uptimeSeconds、cpuUser、cpuSystem。
    • executor.js 对 stdout/stderr 缓冲区设置 MAX_OUTPUT_BUFFER（5MB），超限后截断并广播 truncated 事件。
  • CPU 负载优化
    • RAG 导入/重建后台执行，进度经 _reportProgress 轮询；搜索 topK 有上限 SEARCH_TOPK_MAX=50，防止候选集放大。
    • 命令执行采用超时预算与延长策略：若无输出则尽快杀进程，避免静默挂起。
classDiagram
class Executor {
+runningProcesses Map
+completedProcesses Map
+executeCommand()
+killProcess()
+getRunningProcesses()
}
class Server {
+"/api/status/detail"
}
class RAGManager {
+_startRebuild()
+_ingestText()
+normalizeSearchOptions()
}
Server --> Executor : "查询运行进程/资源"
Server --> RAGManager : "触发导入/重建"

图示来源

章节来源

MCP 协议连接问题调试技巧 ​

包括工具发现失败、远程服务不可用和协议版本不兼容。

  • 工具发现失败
    • McpClient.connect 会创建 transport、连接服务端、获取 serverInfo/capabilities，并调用 listTools 拉取工具列表。
    • 若 toolsResult.tools 为空，tools 数组置空；前端需检查远端是否实现 MCP 工具注册。
  • 远程服务不可用
    • SSE/streamable-http/websocket 传输需要 url；stdio 传输需要 command/args/env/cwd。
    • connect 失败会 disconnect 并返回 error 消息；建议检查网络、鉴权头、URL 可达性与远端日志。
  • 协议版本不兼容
    • client 声明自身 version；若远端不支持该版本或 capabilities 不匹配，listTools/callTool 可能失败。
    • 建议升级远端 MCP 服务或调整客户端 SDK 版本。
sequenceDiagram
participant Reg as "MCP 注册中心"
participant Cli as "McpClient"
participant Trans as "Transport(Stdio/SSE/WS)"
participant Svr as "远端 MCP 服务"
Reg->>Cli : "connect(serverConfig)"
Cli->>Trans : "_createTransport()"
Trans-->>Cli : "transport 实例"
Cli->>Svr : "client.connect(transport)"
Svr-->>Cli : "serverInfo/capabilities"
Cli->>Svr : "listTools({})"
Svr-->>Cli : "{tools : [...]}"
Cli-->>Reg : "{success : true, toolCount}"

图示来源

章节来源

RAG 索引构建失败与向量数据库异常修复指南 ​

  • 索引构建失败
    • updateCollection 检测到 embedding/chunk 配置变更会触发 _startRebuild；重建过程在临时目录完成，原子换入后再提交注册表。
    • 若中途进程被杀，recoverInterruptedRebuilds 会扫描 .rebuild_* 目录，依据 rebuild_manifest.json 判断是补提交还是回滚旧索引。
  • 向量数据库异常
    • VectraStore 负责向量写入；若远端向量服务不可用，embedding provider 调用失败会抛出 RagError。
    • 建议检查 embeddingConfig.mode（local/openai-compat）、endpoint、modelName、dimensions、apiKey 是否正确。
  • 导入体积与检索参数保护
    • INGEST_MAX_TEXT_BYTES=10MB、INGEST_MAX_FILE_BYTES=50MB；topK 上限 SEARCH_TOPK_MAX=50，防止 OOM 与性能退化。
flowchart TD
U["updateCollection(collectionId, input)"] --> Check["解析 embedding/chunk 配置"]
Check --> Rebuild{"是否需要重建？"}
Rebuild -- "否" --> Save["直接更新名称/描述/配置"]
Rebuild -- "是" --> Build["后台 _startRebuild -> _rebuildIndex"]
Build --> Temp["临时目录构建新索引"]
Temp --> Swap["原子 rename 换入"]
Swap --> Commit["_updateRegistry 提交新配置"]
Commit --> Done["清理临时目录/清单"]
Swap --> |失败| Rollback["回滚旧索引"]

图示来源

章节来源

依赖关系分析 ​

  • server.js 依赖 config.js、auth.js、security.js、executor.js、logger.js、search.js、rag/detect.js、rag/install.js、memory/routes.js、process-tree.js、mcp/registry.js、skill/registry.js、skill/loader.js、i18n.js。
  • security.js 依赖 config.js 与 i18n.js。
  • executor.js 依赖 config.js 与 i18n.js。
  • mcp/client.js 依赖 @modelcontextprotocol/sdk 与 i18n.js。
  • rag/manager.js 依赖 embedding/index.js、store/vectra.js、document/chunker.js、document/loader.js、searcher.js、security.js、url-guard.js、config.js、crypto-lite.js。
  • memory/service.js 依赖 vectors、embedding-config、tier、fusion、tags、rag/detect、rag/embedding/index。
  • local-agent-client.js 依赖 shared/logger/i18n/secret。
graph LR
Server["server.js"] --> Config["config.js"]
Server --> Security["security.js"]
Server --> Executor["executor.js"]
Server --> MCP["mcp/client.js"]
Server --> RAG["rag/manager.js"]
Server --> Memory["memory/service.js"]
Security --> Config
Executor --> Config
RAG --> Security
Memory --> RAG
LocalClient["local-agent-client.js"] --> Server

图示来源

章节来源

性能注意事项 ​

  • 命令输出缓冲上限 5MB，避免长时间命令撑爆内存；超长输出会触发 truncated 事件。
  • RAG 导入/重建后台执行，避免阻塞主线程；检索 topK 上限 50，防止候选集过大。
  • 记忆召回将外部嵌入调用移出互斥锁，并使用 embedWithTimeout 与 backfillFail 冷却，避免一次慢请求拖垮全进程。
  • 配置读写加写锁，防止并发覆盖；pairings/token 落盘前混淆，提升安全性。

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

故障排查指南 ​

  • 启动失败
    • 检查端口占用与 config.json 中 port/host。
    • 校验 config.json JSON 格式与 memoryEmbedding.apiKey 密文。
    • 查看 RAG 依赖检测日志；必要时重新安装 ai-helper-agent。
  • 连接异常
    • 确认扩展端已配对并持有有效 token。
    • 检查浏览器控制台是否有 CORS 错误或 AbortError。
    • 对远程 Agent，确认 ws/wss 与 http/https 协议一致。
  • 权限拒绝
    • 核对 allowedPaths 是否包含目标目录；workdir 始终放行。
    • 对危险命令，查看黑名单/灰名单命中原因；必要时使用“本次任务放行”。
  • 资源占用过高
    • 通过 /api/status/detail 观察 memoryRssMB、cpuUser/System。
    • 使用 getRunningProcesses 定位长耗时命令；必要时 killProcess。
  • MCP 问题
    • 检查 transport 类型与必填字段（url/command）。
    • 确认远端 MCP 服务可连通且实现 listTools/callTool。
  • RAG 异常
    • 检查 embeddingConfig.mode/endpoint/modelName/dimensions/apiKey。
    • 关注重建清单 .rebuild_* 与 rebuild_manifest.json，必要时手动收敛中断重建。
    • 控制导入文件大小与检索 topK，避免 OOM。

章节来源

结论 ​

Agent 服务的问题排查应以“启动—连接—权限—资源—协议—数据”为主线：先确认服务可用与端口正常，再验证认证与跨域，随后聚焦安全策略与命令分级，最后结合 RAG/MCP/记忆子系统的日志与状态接口定位根因。修改 Agent 源码后务必重启进程，确保新逻辑生效。