AI Helper 文档中心

主题

服务生命周期管理 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构与职责边界
  3. 核心组件与生命周期阶段
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与资源特性
  8. 故障排查与恢复指南
  9. 结论
  10. 附录：部署与运维要点

引言 ​

本文件面向“AI Helper”双进程架构的服务生命周期管理，覆盖 Chrome 扩展端（Manifest V3，Service Worker）与独立本地代理端 Agent（Node.js）。文档重点说明：

  • 服务启动流程、依赖初始化与环境适配；
  • 运行模式检测、安装模式切换；
  • 健康检查、监控、自动重启与优雅关闭；
  • 日志轮转、指标收集与诊断信息；
  • 信号处理、进程守护与服务注册；
  • 部署、运维与故障恢复策略。

本项目版本以 2.3.1 为准，Agent 包入口为 agent/src/server.js，CLI 入口为 agent/bin/agent.js。两端通过本地 HTTP/WebSocket 通信，Agent 源码修改后必须重启进程才生效。

章节来源

项目结构与职责边界 ​

  • 扩展端 background Service Worker：负责 UI 交互、任务编排、SW 保活、侧边栏状态、Agent 可达性检测与心跳。
  • Agent 端 Node.js 服务：提供 HTTP API 与 WebSocket，实现文件操作、命令执行、MCP/Skill/RAG 能力、认证与安全控制。
  • CLI 工具：负责后台守护、PID 管理、健康检查、在线更新与自启管理。
graph TB
subgraph "Chrome 扩展端"
BG["background/index.js<br/>Service Worker 主逻辑"]
Client["local-agent-client.js<br/>HTTP/WebSocket 客户端"]
State["state.js<br/>keepalive 端口与实例身份"]
end
subgraph "Agent 端"
CLI["bin/agent.js<br/>CLI 守护/健康检查/更新"]
Server["src/server.js<br/>HTTP 路由 + WS 服务器"]
Logger["src/logger.js<br/>审计日志"]
ProcTree["src/process-tree.js<br/>进程树终止"]
InstallMode["src/install-mode.js<br/>内嵌/npm 模式"]
end
BG --> Client
Client --> Server
CLI --> Server
Server --> Logger
Server --> ProcTree
Server --> InstallMode

图表来源

章节来源

核心组件与生命周期阶段 ​

  • 启动阶段
    • CLI 解析参数、创建必要目录、写入 PID 文件、启动前台或后台进程。
    • Agent 加载配置、开启终端日志、异步探测搜索工具与 RAG 能力、启动 HTTP 服务。
  • 运行阶段
    • 扩展端周期性健康检查与心跳；Agent 端提供 /api/status、/api/heartbeat 等接口。
    • keepalive 长连接维持 SW 存活，支持 SW 静默重启检测与任务续跑。
  • 维护阶段
    • 在线重启、在线更新、RAG 依赖安装互斥保护、冷却时间防抖。
  • 关闭阶段
    • 优雅关闭：写停止标记、延迟关闭、清理 PID、整棵进程树终止。
flowchart TD
Start(["进程启动"]) --> ParseArgs["CLI 解析参数<br/>读取配置/语言/工作目录"]
ParseArgs --> EnsureDir["确保 .ai-helper-agent 目录存在"]
EnsureDir --> Mode{"前台还是后台？"}
Mode --> |前台| Foreground["写入 PID → 导入 server.js → startServer()"]
Mode --> |后台| Spawn["spawn 子进程 → 健康检查 → 写入 PID"]
Foreground --> InitDeps["初始化日志/搜索工具/RAG 探测"]
Spawn --> HealthCheck["轮询 /api/status 直到就绪"]
HealthCheck --> Running["进入运行期"]
InitDeps --> Running

图表来源

章节来源

架构总览 ​

扩展端通过 local-agent-client 封装 HTTP/WebSocket 调用，background/index.js 负责 SW 保活、侧边栏可见性、通知与消息路由；Agent 端 server.js 统一路由所有业务接口，并集成认证、安全、日志、进程树管理、RAG/MCP/Skill 子系统。

sequenceDiagram
participant UI as "Side Panel"
participant BG as "background/index.js"
participant Client as "local-agent-client.js"
participant Server as "agent/src/server.js"
UI->>BG : CALL_API / 其他业务消息
BG->>Client : agentRequest(path, body)
Client->>Server : HTTP GET/POST (Bearer Token)
Server-->>Client : JSON 响应
Client-->>BG : 返回结果
BG-->>UI : API_COMPLETE / STREAM_* / API_ERROR

图表来源

章节来源

详细组件分析 ​

启动流程与依赖初始化 ​

  • CLI 启动
    • 前台模式：写入 PID，动态导入 server.js 并调用 startServer。
    • 后台模式：spawn 子进程，轮询 /api/status 最多 8 秒，成功后写入 PID。
  • Agent 启动
    • 设置控制台输出、记录系统日志、异步初始化搜索工具与 RAG 可用性检测。
    • 启动 HTTP 服务，CORS 仅放行 chrome-extension 来源。
sequenceDiagram
participant CLI as "bin/agent.js"
participant OS as "操作系统"
participant AG as "server.js"
CLI->>OS : spawn(node, agent.js start [-b])
AG->>AG : setConsoleOutput(true)
AG->>AG : initSearchTools()
AG->>AG : detectRagAvailable()
AG->>OS : http.createServer(...)
CLI->>CLI : healthCheck(/api/status)
CLI-->>CLI : 成功则写入 PID

图表来源

章节来源

运行模式检测与安装模式切换 ​

  • 安装模式
    • 内嵌模式：由 install.sh/ps1 安装，runtime+app 位于 ~/.ai-helper-agent。
    • npm 全局模式：传统 npm -g 路径。
    • 判断依据：agent 包入口是否在 ~/.ai-helper-agent/app/ 下。
  • 运行时工具
    • getNodePath/getNpmPath：根据模式选择 Node/npm 可执行路径。
    • getRegistryUrl/getHfEndpoint：按 mirrors.json 切换 npm registry 与 HuggingFace 端点。
    • readInstallManifest/getStoppedFlagPath：读取安装清单与主动停止标记。
flowchart TD
A["isEmbedded()"] --> B{"是否内嵌模式？"}
B --> |是| C["getNodePath -> ~/.ai-helper-agent/runtime/bin/node"]
B --> |否| D["process.execPath"]
C --> E["getNpmPath -> runtime/bin/npm 或 npm.cmd"]
D --> E
E --> F["readMirrors() -> getRegistryUrl()/getHfEndpoint()"]

图表来源

章节来源

健康检查、监控与自动重启 ​

  • 扩展端健康检查
    • 每 30 秒对活跃代理发起 /api/status，失败时触发指数退避重连。
    • 每 60 秒发送 /api/heartbeat 刷新 Agent 端 lastAuthTime，保持“插件在线”。
  • Agent 端健康与心跳
    • /api/status：返回版本、平台、searchTools、ragAvailable。
    • /api/heartbeat：轻量刷新认证时间，不返回敏感信息。
  • 自动重启
    • /api/agent/restart：两阶段重启（spawn helper → 等待旧进程退出 → 启动新进程），带 10s 冷却。
    • /api/agent/update：npm 全局安装最新版本，超时 90s，失败不回滚老进程。
sequenceDiagram
participant BG as "background/index.js"
participant Client as "local-agent-client.js"
participant Server as "agent/src/server.js"
BG->>Client : performAgentHealthCheck()
Client->>Server : GET /api/status
Server-->>Client : {version, platform, searchTools, ragAvailable}
BG->>Client : performAgentHeartbeat()
Client->>Server : GET /api/heartbeat
Server-->>Client : {success, time}

图表来源

章节来源

优雅关闭与进程守护 ​

  • 优雅关闭
    • /api/shutdown：本机来源免认证，远程需认证；写 .stopped 阻止 autostart；延迟 200ms 关闭。
    • CLI stop：优先调用 /api/shutdown，失败回退到 PID kill。
  • 进程守护
    • PID 文件：~/.ai-helper-agent/agent.pid。
    • 后台启动：spawn detached，健康检查通过后写入 PID。
    • 进程树终止：POSIX 对进程组发信号，Windows 使用 taskkill /T。
flowchart TD
S(["收到 shutdown 请求"]) --> L["校验来源/认证"]
L --> Mark["写入 .stopped 标记"]
Mark --> Delay["延迟 200ms 响应"]
Delay --> Close["shutdown() 关闭服务"]
Close --> Cleanup["清理 PID 文件"]

图表来源

章节来源

服务状态机图 ​

stateDiagram-v2
[*] --> 未启动
未启动 --> 启动中 : "CLI start / _restart-helper"
启动中 --> 运行中 : "/api/status 健康检查通过"
运行中 --> 关闭中 : "/api/shutdown 或 CLI stop"
关闭中 --> 已停止 : "PID 清理完成"
运行中 --> 重启中 : "/api/agent/restart 或 update"
重启中 --> 启动中 : "_restart-helper 接管"
已停止 --> 未启动 : "用户再次启动"

图表来源

启动时序图（含两阶段重启） ​

sequenceDiagram
participant Caller as "调用方"
participant Server as "server.js"
participant Helper as "_restart-helper"
participant NewProc as "新进程"
Caller->>Server : POST /api/agent/restart
Server-->>Caller : {success : true, message : "restarting"}
Server->>Helper : spawn(process.execPath, ["_restart-helper", ...])
Server->>Server : setTimeout(shutdown, 500)
Helper->>Helper : waitForOldExit(oldPid)
Helper->>Helper : waitForPortRelease(host,port)
Helper->>NewProc : spawn(agent.js start --port/--host/--workdir)
Helper->>Helper : 健康检查新进程

图表来源

章节来源

日志轮转、指标与诊断 ​

  • 日志
    • JSON Lines 格式，按日切分，保留最近 30 个文件，单文件上限 10MB，每分钟清理一次。
    • 分类标签：auth/fs/exec/security/system，支持中英文。
    • 查询接口：/api/logs（由 logger.queryLogs 提供）。
  • 指标
    • /api/status/detail 返回内存占用、CPU user/system、uptime、runningProcesses 等。
  • 诊断
    • 错误日志统一 logError，包含 action 与 details。
    • 扩展端 SW 重启检测通过 keepalive port 上报 HOST_TAB_RESOLVED 与 SW_RESTARTED。
flowchart TD
A["log(level, category, action, details)"] --> B["stderr 输出前台模式"]
A --> C["appendFileSync(当日日志)"]
C --> D["cleanOldLogs() 定期清理"]

图表来源

章节来源

信号处理、进程守护与服务注册 ​

  • 信号处理
    • CLI stop：优先 /api/shutdown，失败则 killByPid（POSIX SIGTERM，Windows taskkill /F /T）。
    • process-tree：POSIX 负 PID 向进程组发信号，Windows 使用 taskkill /T。
  • 进程守护
    • PID 文件读写原子化，后台启动 spawn detached，健康检查通过后写入 PID。
  • 服务注册
    • 自启：macOS LaunchAgents、systemd user service、Windows Task Scheduler。
    • 卸载：移除 plist/service/task，删除 runtime/app/bin 目录（保留数据）。
flowchart TD
StopCmd["CLI stop"] --> TryAPI["尝试 /api/shutdown"]
TryAPI --> |成功| CleanPID["清理 PID 文件"]
TryAPI --> |失败| KillPID["killByPid(pid)"]
KillPID --> CleanPID
CleanPID --> Exit["进程退出"]

图表来源

章节来源

扩展端 SW 保活与侧边栏状态 ​

  • keepalive 长连接
    • side panel 建立 keepalive-<sessionId> 端口，SW 维护映射，用于定向消息（澄清弹框等）。
    • SW 重启检测：检测到 reconnection 且 activeReactLoops 缺失，发送 SW_RESTARTED。
  • 侧边栏可见性与分组
    • 全局模式 vs 标签页绑定模式，窗口焦点与活跃 tab 镜像同步。
    • 快捷键 toggle 必须在用户手势同步栈内调用 open/close。
sequenceDiagram
participant SP as "side_panel"
participant BG as "background/index.js"
participant State as "state.js"
SP->>BG : connect("keepalive-<sessionId>")
BG->>State : registerKeepalivePort(sessionId, port)
SP->>BG : KEEPALIVE_IDENTITY(windowId, hostTabId)
BG->>State : setKeepaliveIdentity(sessionId, identity)
BG-->>SP : HOST_TAB_RESOLVED
Note over BG,SP : SW 重启后重连 → SW_RESTARTED

图表来源

章节来源

依赖关系分析 ​

  • 模块耦合
    • server.js 聚合 auth、security、executor、logger、mcp、skill、memory/routes、process-tree、install-mode 等。
    • background/index.js 依赖 tool-executor、react-loop、notifier、panel-visibility、auto-resume、scheduler 等。
  • 外部依赖
    • ws、archiver、xlsx、zod 等；RAG 依赖在 package.json 的 ragDependencies 中声明。
  • 潜在循环依赖
    • server.js 内部模块化拆分避免直接循环；background 与 side_panel 通过 chrome.runtime 消息解耦。
graph LR
Server["server.js"] --> Auth["auth.js"]
Server --> Sec["security.js"]
Server --> Exec["executor.js"]
Server --> Log["logger.js"]
Server --> MCP["mcp/registry.js"]
Server --> Skill["skill/registry.js"]
Server --> Mem["memory/routes.js"]
Server --> PT["process-tree.js"]
Server --> IM["install-mode.js"]

图表来源

章节来源

性能与资源特性 ​

  • 文件上传/下载
    • multipart/form-data 与 raw binary stream 两种上传方式，流式传输避免大文件 OOM。
    • 目录下载打包为 zip，分块写入降低前端解码压力。
  • 搜索与预览
    • MAX_SEARCH_RESULTS=5000，XLSX 预览服务端裁剪空行列，限制行数。
  • 资源限制
    • MAX_BODY_SIZE=200MB，MAX_UPLOAD_SIZE=200MB，默认文件读取大小限制 50MB。
  • CPU/内存指标
    • /api/status/detail 暴露 heapUsed/heapTotal/rss、uptime、cpuUser/cpuSystem。

章节来源

故障排查与恢复指南 ​

  • 无法启动
    • 检查 PID 文件是否存在且有效；确认端口未被占用；查看后台健康检查日志。
    • 前台模式直接观察 stderr 日志；后台模式查看 ~/.ai-helper-agent/logs/agent-YYYY-MM-DD.log。
  • 无法连接 Agent
    • 确认已配对且 token 有效；检查 /api/status 可达性；关注扩展端可达性缓存与心跳。
  • 更新失败
    • /api/agent/update 失败不会回滚老进程；查看 npm 输出与超时日志；手动执行 npm install -g ai-helper-agent@latest。
  • 进程残留
    • 使用 CLI stop 或 /api/shutdown；必要时 killByPid（Windows taskkill /F /T）。
  • SW 崩溃重启
    • 关注 SW_RESTARTED 通知；side_panel 会拒绝当前 Promise 并提示继续执行（如有 checkpoint）。

章节来源

结论 ​

本项目的服务生命周期管理围绕“CLI 守护 + Agent HTTP 服务 + 扩展端健康检查/心跳”展开，具备：

  • 稳健的启动与依赖初始化流程；
  • 内嵌/npm 双模式自适应；
  • 完善的健康检查、心跳与自动重连；
  • 优雅关闭与进程树终止；
  • 日志轮转与指标暴露；
  • 在线重启与更新机制；
  • 针对 MV3 Service Worker 的保活与恢复策略。

这些机制共同保障了扩展端与 Agent 端的稳定协作与可观测性。

附录：部署与运维要点 ​

  • 官方安装渠道
    • 唯一推荐：GitHub Releases 自动构建产物下载；不要将 clone 源码构建作为推荐路径。
  • 启动与守护
    • 使用 ai-helper-agent start -b 后台启动；通过 status 查看健康状态；通过 stop 优雅关闭。
  • 自启管理
    • macOS：LaunchAgents plist；Linux：systemd user service；Windows：Task Scheduler。
    • 可通过 autostart on/off 管理。
  • 更新与卸载
    • update 在线更新并重启；uninstall 移除自启与运行时目录（保留数据）。
  • 运维监控
    • 定期巡检 /api/status/detail 指标；结合日志目录进行问题定位。
  • 故障恢复
    • 优先 /api/shutdown；失败再 killByPid；必要时清理 PID 与 .stopped 标记后重新启动。

章节来源