系统管理 API

本文引用的源码文件

本文引用的文件

简介

本文件是 AI Helper Agent（本地代理服务）的系统管理 API 参考文档。Agent 是 Chrome 扩展的独立 Node.js 进程，提供健康检查、心跳检测、服务控制、配置管理、日志查询等能力。所有需要变更状态的接口均受认证保护；部分只读或本机调用接口具有额外来源限制。

版本：Agent 包 ai-helper-agent 当前版本为 2.3.1，与扩展端保持同步。
默认监听地址：127.0.0.1:18910。
安全模型：
- /api/status、/api/pair 无需 Bearer Token，但仅返回必要信息，并限制跨域响应头。
- /api/heartbeat、/api/agent/restart、/api/agent/update、/api/shutdown、/api/status/detail 等需要 Authorization: Bearer <token>。
- /api/shutdown 允许本机来源免认证，远程来源仍需 Token。
运行时约束：修改 Agent 源码后必须重启进程，新接口才生效。

章节来源

项目结构

Agent 的 HTTP 路由、WebSocket、配置加载、认证、日志、命令执行、RAG、记忆、MCP、技能等子系统集中在服务端入口中组织，并通过 CLI 启动器暴露命令行能力。

graph TB
subgraph "Chrome 扩展"
BG["background/index.js<br/>心跳与健康检查"]
end
subgraph "Agent 进程"
CLI["bin/agent.js<br/>CLI 启动/停止/重启/更新"]
Server["src/server.js<br/>HTTP 路由 + WebSocket"]
Logger["src/logger.js<br/>审计日志模块"]
Config["src/config.js<br/>配置文件读写"]
Auth["src/auth.js<br/>配对码与 Token"]
Security["src/security.js<br/>路径/命令安全检查"]
Executor["src/executor.js<br/>命令执行"]
Memory["memory/routes.js<br/>长期记忆路由"]
RAG["rag/*<br/>可选知识库能力"]
MCP["mcp/registry.js<br/>MCP 工具注册"]
Skill["skill/*<br/>技能系统"]
end
BG --> Server
CLI --> Server
Server --> Logger
Server --> Config
Server --> Auth
Server --> Security
Server --> Executor
Server --> Memory
Server --> RAG
Server --> MCP
Server --> Skill

图表来源

章节来源

核心组件

HTTP 路由器：统一解析请求、CORS、国际化语言、认证、业务路由和错误响应。
认证模块：校验 Bearer Token，记录认证失败日志。
日志模块：按天写入 JSON Lines 审计日志，支持分类过滤、分页查询和日期列表。
配置模块：工作目录、允许路径、端口、主机、超时、文件大小限制等。
命令执行模块：同步/异步执行系统命令，支持 WebSocket 输出、超时、终止、守护模式。
生命周期控制：优雅关闭、防重入、冷却时间、两阶段重启包装器。

章节来源

架构总览

系统管理 API 的请求流程如下：

sequenceDiagram
participant Client as "客户端"
participant Server as "Agent HTTP 服务器"
participant Auth as "认证模块"
participant Logger as "日志模块"
participant OS as "操作系统"
Client->>Server : "HTTP 请求"
Server->>Server : "解析 URL / CORS / i18n"
alt "无需认证的接口"
Server-->>Client : "直接返回状态或本机操作结果"
else "需要认证的接口"
Server->>Auth : "验证 Bearer Token"
Auth-->>Server : "extId 或失败"
Server->>Logger : "记录认证/操作日志"
Server->>OS : "执行文件/命令/重启/更新"
OS-->>Server : "结果"
Server-->>Client : "JSON 响应"
end

图表来源

详细接口参考

系统状态端点

GET /api/status

用途：健康检查。用于判断 Agent 是否存活、版本、平台信息和搜索工具可用性。
认证：不需要 Bearer Token。
CORS：仅对 chrome-extension:// 来源设置 Access-Control-Allow-Origin。
成功响应字段：
- success: boolean
- version: string，Agent 版本号
- running: boolean
- platform: string，如 darwin、linux、win32
- platformName: string，如 macOS、Linux、Windows
- arch: string，CPU 架构
- nodeVersion: string
- searchTools: object，包含搜索引擎可用性
- ragAvailable: boolean，RAG 可选依赖是否可用
错误响应：
- 网络不可达时由客户端判定连接失败。
- 内部异常会返回 500 且 success: false。

章节来源

GET /api/status/detail

用途：详细状态。面向已认证客户端，返回工作目录、资源使用、运行进程、平台信息等。
认证：需要 Bearer Token。
成功响应关键字段：
- success: boolean
- version: string
- pairCodeTTL: number
- workdir: string
- allowedPaths: array<string>
- commandTimeout: number
- fileMaxSize: number
- uploadMaxSize: number
- runningProcesses: array
- resourceUsage.memoryUsedMB: number
- resourceUsage.memoryTotalMB: number
- resourceUsage.memoryRssMB: number
- resourceUsage.uptimeSeconds: number
- resourceUsage.cpuUser: number
- resourceUsage.cpuSystem: number
- platform、platformName、arch、hostname、shell、homeDir、nodeVersion
- searchTools
- ragAvailable
说明：该接口不返回敏感配对码，避免横向泄露。

章节来源

agent/src/server.js#L724-L749

GET /api/heartbeat

用途：心跳检测。刷新代理端“插件在线”状态，防止频繁刷新配对码。
认证：需要 Bearer Token。
成功响应：
- success: boolean
- time: number，当前时间戳
扩展端行为：每 60 秒向当前活跃代理发送一次轻量心跳。

sequenceDiagram
participant SW as "扩展 Service Worker"
participant Agent as "Agent 服务器"
SW->>Agent : "GET /api/heartbeat (带 Authorization)"
Agent->>Agent : "刷新 lastAuthTime"
Agent-->>SW : "{ success : true, time }"

图表来源

章节来源

系统控制端点

POST /api/agent/restart

用途：重启 Agent 服务。
认证：需要 Bearer Token。
防重入与限流：
- 若已有操作进行中，返回 409。
- 10 秒内重复调用返回 429，并提示等待秒数。
成功响应：
- success: boolean
- message: string，表示正在重启
行为：
- 记录系统日志。
- 启动两阶段重启包装器，等待旧进程退出并释放端口后拉起新进程。
- 延迟关闭当前进程。

flowchart TD
Start["收到 POST /api/agent/restart"] --> CheckBusy{"是否有其他操作进行中？"}
CheckBusy --> |是| Return409["返回 409 操作进行中"]
CheckBusy --> |否| CheckCooldown{"是否在 10 秒冷却期内？"}
CheckCooldown --> |是| Return429["返回 429 太频繁"]
CheckCooldown --> |否| MarkInProgress["标记操作进行中"]
MarkInProgress --> LogRestart["记录重启日志"]
LogRestart --> SpawnHelper["spawn 两阶段重启包装器"]
SpawnHelper --> Respond["返回 200 正在重启"]
Respond --> ShutdownOld["延迟关闭旧进程"]

图表来源

agent/src/server.js#L555-L603

章节来源

agent/src/server.js#L555-L603

POST /api/agent/update

用途：更新 Agent 到最新版本并重启。
认证：需要 Bearer Token。
互斥规则：
- 不能与 RAG 依赖安装并发执行。
- 不能与其他 agent 操作并发执行。
- 10 秒内重复调用返回 429。
成功响应：
- success: boolean
- message: string，表示更新成功或失败原因
行为：
- 执行 npm install -g ai-helper-agent@latest。
- 更新失败时保留老进程，返回失败消息。
- 更新成功后触发两阶段重启。

sequenceDiagram
participant Client as "客户端"
participant Server as "Agent 服务器"
participant NPM as "npm 进程"
participant Helper as "重启包装器"
Client->>Server : "POST /api/agent/update"
Server->>Server : "检查操作互斥与冷却时间"
Server->>NPM : "npm install -g ai-helper-agent@latest"
alt "npm 成功"
NPM-->>Server : "退出码 0"
Server-->>Client : "{ success : true, message }"
Server->>Helper : "spawn 两阶段重启"
Server->>Server : "延迟关闭旧进程"
else "npm 失败或超时"
NPM-->>Server : "错误或超时"
Server-->>Client : "{ success : false, error }"
end

图表来源

agent/src/server.js#L605-L720

章节来源

agent/src/server.js#L605-L720

POST /api/shutdown

用途：关闭 Agent 服务。
认证策略：
- 本机来源（127.0.0.1、::1、localhost）免认证。
- 远程来源需要 Bearer Token。
防重入与限流：同其他 agent 操作。
成功响应：
- success: boolean
- message: string，表示正在关闭
行为：
- 写入 .stopped 标记阻止 autostart 自动拉起。
- 延迟 200ms 后执行优雅关闭。

章节来源

agent/src/server.js#L502-L535

配置管理端点

Agent 的配置管理主要通过以下接口实现：

POST /api/config/workdir

用途：切换工作目录。
认证：需要 Bearer Token。
请求体：
- workdir: string，支持 ~ 展开、MSYS 路径规整、绝对路径校验。
成功响应：
- success: boolean
- workdir: string，最终工作目录
- allowedPaths: array<string>
- message: string
安全规则：
- 禁止设置为 Agent 系统目录本身。
- 自动创建目录。
- 将新 workdir 加入 allowedPaths（只增不减）。

POST /api/config/allowed-paths/remove

用途：从允许访问路径列表中移除某个目录。
认证：需要 Bearer Token。
请求体：
- path: string，需为绝对路径。
成功响应：
- success: boolean
- allowedPaths: array<string>
- message: string
安全规则：
- 禁止移除当前工作目录。
- 跨平台路径比较。

关于 /api/config/get、/api/config/set、/api/config/lang

在 Agent HTTP 路由中未定义这三个精确路径。
实际配置读取通过 loadConfig() 获取，配置持久化通过 saveConfig() 写入。
语言设置通过各子模块的 set*Lang 方法同步，CLI 层支持 --lang 与环境变量 AI_HELPER_LANG。
若需要统一配置接口，建议以现有 /api/config/workdir 和 /api/config/allowed-paths/remove 为基础扩展，而不是假设已有 /api/config/get、/api/config/set、/api/config/lang。

章节来源

日志查询端点

GET /api/logs/query

用途：查询审计日志。
认证：需要 Bearer Token。
请求参数：
- limit: number，单次最多 500 条。
- category: string，可选分类过滤。
行为：
- 默认查询最近 7 天的日志。
- 合并多日结果并按时间倒序排序。
成功响应：
- success: boolean
- entries: array，日志条目数组
- total: number，匹配总数
- dates: array<string>，查询涉及的日期列表

GET /api/logs/dates

用途：获取可用日志日期列表。
认证：需要 Bearer Token。
成功响应：
- success: boolean
- dates: array<string>，按日期命名的日志文件名对应的日期列表

flowchart TD
Start["收到 /api/logs/query"] --> ParseParams["解析 limit 与 category"]
ParseParams --> BuildDates["构建最近 7 天日期列表"]
BuildDates --> LoopDays["遍历日期查询日志"]
LoopDays --> Merge["合并 entries 并截断到 limit"]
Merge --> Sort["按 timestamp 倒序排序"]
Sort --> Return["返回 { success, entries, total, dates }"]

图表来源

章节来源

通用错误响应格式

除明确说明外，多数接口遵循以下结构：

成功：
- success: boolean
- 业务字段随接口不同而变化
失败：
- success: boolean
- error: string，人类可读错误消息
HTTP 状态码常见含义：
- 200：成功
- 400：参数无效或业务校验失败
- 401：缺少 Token
- 403：Token 无效或权限不足
- 409：操作进行中或冲突
- 429：频率过高
- 500：内部错误
- 503：RAG 依赖不可用

章节来源

依赖关系分析

graph LR
Status["/api/status"] --> Platform["PLATFORM_INFO"]
Status --> SearchTools["getSearchToolsAvailable()"]
Status --> RAGDetect["isRagAvailable()"]
Heartbeat["/api/heartbeat"] --> Auth["verifyToken()"]
Heartbeat --> Response["{ success, time }"]
Restart["/api/agent/restart"] --> Cooldown["OPERATION_COOLDOWN_MS"]
Restart --> Spawn["spawn _restart-helper"]
Restart --> Shutdown["shutdown()"]
Update["/api/agent/update"] --> NPM["npm install -g"]
Update --> Spawn
Update --> Shutdown
ShutdownAPI["/api/shutdown"] --> LocalCheck["remoteIp 检查"]
ShutdownAPI --> WriteStopped["写入 .stopped"]
ShutdownAPI --> Shutdown
LogsQuery["/api/logs/query"] --> Logger["queryLogs()"]
LogsDates["/api/logs/dates"] --> GetDates["getLogDates()"]

图表来源

章节来源

性能与监控指标

关键性能约束

请求体大小限制：200MB，防止超大 JSON 导致内存压力。
上传大小限制：
- 普通上传：200MB。
- 流式上传：同样 200MB，但走流式写入，不一次性占满内存。
搜索结果上限：单次搜索最多 5000 条。
日志查询上限：单次最多 500 条。
操作冷却时间：10 秒，防止 DoS 与重复重启/更新。
npm 更新超时：90 秒，超时后终止 npm 进程树。

系统监控指标

从 /api/status/detail 可获取以下指标：

resourceUsage.memoryUsedMB
resourceUsage.memoryTotalMB
resourceUsage.memoryRssMB
resourceUsage.uptimeSeconds
resourceUsage.cpuUser
resourceUsage.cpuSystem
runningProcesses
searchTools
ragAvailable

这些指标适合接入外部监控系统，用于观察 Agent 进程稳定性、内存泄漏趋势、CPU 占用和 RAG 依赖状态。

章节来源

运维脚本与自动化集成

常用 CLI 命令

ai-helper-agent start：前台启动。
ai-helper-agent start --background：后台启动。
ai-helper-agent stop：停止服务。
ai-helper-agent restart：重启服务。
ai-helper-agent status：查看运行状态。
ai-helper-agent update：检查并更新到最新版本。
ai-helper-agent config：查看当前配置。

健康检查脚本示例

bash

#!/usr/bin/env bash
HOST="127.0.0.1"
PORT=18910
ENDPOINT="http://${HOST}:${PORT}/api/status"

for i in $(seq 1 16); do
  if curl -sf "$ENDPOINT" > /dev/null; then
    echo "Agent is healthy."
    exit 0
  fi
  sleep 0.5
done

echo "Agent health check timed out."
exit 1

停止服务脚本示例

bash

#!/usr/bin/env bash
HOST="127.0.0.1"
PORT=18910
curl -s -X POST "http://${HOST}:${PORT}/api/shutdown" || true
sleep 1
ai-helper-agent status

自动化部署集成建议

CI 中可使用 GitHub Actions 或类似流水线启动 Agent，轮询 /api/status 直到健康。
发布新版本时，先调用 /api/agent/update，再轮询 /api/status 确认新版本就绪。
若更新失败，应回滚到上一个稳定版本并告警。
对于容器化部署，建议使用进程管理器（systemd、Docker、Kubernetes）管理 Agent 生命周期，并结合 /api/shutdown 优雅退出。

章节来源

故障排除指南

常见问题与定位方式

Agent 无法启动
- 检查端口是否被占用。
- 查看 CLI 输出与 PID 文件。
- 使用 ai-helper-agent status 确认是否运行。
健康检查超时
- 确认 /api/status 可达。
- 检查防火墙、代理、浏览器扩展来源限制。
心跳失效
- 确认扩展端是否持有有效 Token。
- 检查 /api/heartbeat 是否返回 200。
重启或更新失败
- 检查 10 秒冷却时间。
- 查看 npm 更新日志与超时错误。
- 确认没有 RAG 安装任务并发。
日志查不到
- 确认认证 Token。
- 检查日志目录是否存在。
- 使用 /api/logs/dates 查看可用日期。
配置切换失败
- 确认 workdir 是绝对路径。
- 确认不是 Agent 系统目录。
- 检查 allowedPaths 是否正确更新。

日志定位

审计日志位于用户目录下，按天分割。
可通过 /api/logs/query 查询最近 7 天日志。
分类包括：认证、文件、命令、安全、系统。
控制台输出在前台模式下可见。

章节来源

结论

本参考文档覆盖了系统管理 API 的核心能力：健康检查、心跳检测、服务重启、版本更新、服务关闭、配置管理、日志查询。Agent 的安全模型强调最小权限、本机豁免、Token 认证、操作冷却与互斥。运维侧应结合 CLI、HTTP 接口和审计日志建立完整的监控、部署与排障流程。

Markdown 渲染引擎

系统管理 API ​

目录 ​

简介 ​

项目结构 ​

核心组件 ​

架构总览 ​

详细接口参考 ​

系统状态端点 ​

GET /api/status ​

GET /api/status/detail ​

GET /api/heartbeat ​

系统控制端点 ​

POST /api/agent/restart ​

POST /api/agent/update ​

POST /api/shutdown ​

配置管理端点 ​

POST /api/config/workdir ​

POST /api/config/allowed-paths/remove ​

关于 /api/config/get、/api/config/set、/api/config/lang ​

日志查询端点 ​

GET /api/logs/query ​

GET /api/logs/dates ​

通用错误响应格式 ​

依赖关系分析 ​

性能与监控指标 ​

关键性能约束 ​

系统监控指标 ​

运维脚本与自动化集成 ​

常用 CLI 命令 ​

健康检查脚本示例 ​

停止服务脚本示例 ​

自动化部署集成建议 ​

故障排除指南 ​

常见问题与定位方式 ​

日志定位 ​

结论 ​

系统管理 API

目录

简介

项目结构

核心组件

架构总览

详细接口参考

系统状态端点

GET /api/status

GET /api/status/detail

GET /api/heartbeat

系统控制端点

POST /api/agent/restart

POST /api/agent/update

POST /api/shutdown

配置管理端点

POST /api/config/workdir

POST /api/config/allowed-paths/remove

关于 /api/config/get、/api/config/set、/api/config/lang

日志查询端点

GET /api/logs/query

GET /api/logs/dates

通用错误响应格式

依赖关系分析

性能与监控指标

关键性能约束

系统监控指标

运维脚本与自动化集成

常用 CLI 命令

健康检查脚本示例

停止服务脚本示例

自动化部署集成建议

故障排除指南

常见问题与定位方式

日志定位

结论