AgentCore-Light 二次开发 API

版本：v1.1.2

适用程序：AgentCore-Light.exe、AgentCore-Light.app、Linux AgentCore-Light

简单介绍：AgentCore-Light 是一套“软件 + 状态指示设备”的本地控制产品。它可以将 AI Agent、客户业务程序或监控系统的运行状态，实时反映到状态指示设备上。产品支持两种设备连接模式：USB 有线模式和蓝牙无线模式。客户可以通过本文档的 API 和命令行接口，将产品集成到自己的应用中。

本文档适用于将 AgentCore-Light 集成到客户软件、自动化脚本、监控系统或 AI Agent 的开发者。

1. 工作方式

AgentCore-Light 是一个本机程序，包含控制台、后台设备服务和命令行入口：

客户程序 / AI Agent
    |
    | HTTP 或命令行
    v
AgentCore-Light
    |
    | USB 有线或蓝牙无线连接
    v
状态指示设备

启动桌面程序后，控制中心 API 默认监听：

http://127.0.0.1:18793

底层设备服务默认监听：

http://127.0.0.1:18792

客户程序优先调用 18793。18792 是底层服务接口，字段更接近设备层，只有在需要极低延迟或自行管理 UI 时才使用。

重要安全边界

• 两个端口都只绑定 127.0.0.1，默认不能从局域网或公网访问。
• 当前 API 没有账号密码、Token 或 HTTPS。它的安全边界是“只有本机进程可访问”。
• 不要把端口映射到公网，也不要在路由器上做端口转发。
• 如果客户需要跨机器控制，应在客户自己的服务器上增加认证代理，由代理调用本机 AgentCore-Light。
• 请求使用 UTF-8 JSON；响应的 Content-Type 为 application/json; charset=utf-8。

2. 安装和启动

客户可以让用户手动双击 EXE，也可以由安装程序或客户软件调用：

AgentCore-Light.exe install
AgentCore-Light.exe start
AgentCore-Light.exe status

直接打开控制台：

AgentCore-Light.exe
AgentCore-Light.exe ui --no-browser

Linux/macOS 将命令替换为对应的可执行文件。start 会启动后台服务；第一次运行或设备未连接时，服务可能返回 scanning、reconnecting，客户程序应继续轮询，而不是立即判定失败。

3. 通用 HTTP 约定

请求

POST /api/light/state HTTP/1.1
Host: 127.0.0.1:18793
Content-Type: application/json

{"state":"THINKING"}

成功响应

{
  "ok": true,
  "accepted_state": "THINKING",
  "source": "agentcore"
}

错误响应

{
  "ok": false,
  "error": "unsupported state: UNKNOWN"
}

客户程序必须同时检查 HTTP 状态码和 JSON 的 ok 字段。服务未运行时通常返回：

{"ok":false,"error":"service not running"}

建议：连接失败时等待 1 秒后重试，连续重试 3-5 次；不要在每次失败时重复启动多个 AgentCore-Light 进程。

4. API 总览（18793）

5. 设备选择与绑定

当当前工作模式扫描到多个可用设备时，程序不会自动猜测目标设备，而是返回 selection_required=true 并列出 device_candidates。客户程序应展示列表，让用户选择后调用选择接口。绑定成功后，后续启动只优先连接该设备。

GET /api/devices

响应示例：

{
  "ok": true,
  "transport_mode": "ble",
  "selection_required": true,
  "candidates": [
    {"kind":"ble", "id":"AA:BB:CC:DD:EE:01", "address":"AA:BB:CC:DD:EE:01", "name":"AgentCore-Light", "rssi":-48},
    {"kind":"ble", "id":"AA:BB:CC:DD:EE:02", "address":"AA:BB:CC:DD:EE:02", "name":"AgentCore-Light", "rssi":-61}
  ]
}

POST /api/device/select

串口模式请求：{"mode":"serial","port":"COM7"}；蓝牙模式请求：{"mode":"ble","address":"AA:BB:CC:DD:EE:01","name":"AgentCore-Light"}。成功响应包含 binding，例如：

{"ok":true,"binding":{"mode":"ble","address":"AA:BB:CC:DD:EE:01","name":"AgentCore-Light"}}

POST /api/device/unbind

清除已保存的设备绑定。清除后重新扫描时，如果发现多个设备，会再次要求用户选择。

6. 状态控制

POST /api/light/state

请求字段：

推荐状态：

说明：颜色和闪烁效果由 ESP32 固件执行；电脑端设置的整体亮度会同时缩放所有状态的亮度。SUCCESS 显示 5 秒后会自动恢复为绿色常亮的 IDLE 状态。

兼容别名：AI、CONFIRM、WAITING、WAIT、WRITING、RUNNING、DONE。其中 WRITING 映射为 AI，RUNNING 映射为 BUSY，DONE 映射为 SUCCESS。

可选的来源字段可以帮助客户在日志中区分不同系统：

{"state":"BUSY","source":"workbuddy"}

支持来源：agentcore、control_panel、claude_code、codex、cursor、qoder、codebuddy、workbuddy、gemini_antigravity、github_copilot、trae、opencode、hermes。

响应：

{"ok":true,"accepted_state":"BUSY","source":"workbuddy"}

Python 示例

import json
import urllib.request

def set_state(state, source="agentcore"):
    body = json.dumps({"state": state, "source": source}).encode("utf-8")
    request = urllib.request.Request(
        "http://127.0.0.1:18793/api/light/state",
        data=body,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=5) as response:
        result = json.load(response)
    if not result.get("ok"):
        raise RuntimeError(result.get("error", "state request failed"))
    return result

set_state("THINKING", "agentcore")

JavaScript 示例

async function setState(state, source = "agentcore") {
  const response = await fetch("http://127.0.0.1:18793/api/light/state", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ state, source }),
  });
  const result = await response.json();
  if (!response.ok || !result.ok) {
    throw new Error(result.error || `HTTP ${response.status}`);
  }
  return result;
}

7. 亮度、蜂鸣器和音效

POST /api/light/brightness

brightness 必须是 0 到 100 的整数：

{"brightness":75}

成功响应：

{"ok":true,"brightness":75}

POST /api/buzzer/settings

至少提供一个字段：

{"enabled":true,"volume":40}

• enabled：布尔值，也接受 true/false、on/off、1/0。
• volume：0 到 100 的整数。

响应：

{"ok":true,"buzzer_enabled":true,"buzzer_volume":40}

GET /api/sound-settings

返回每种状态当前绑定的声音和播放模式：

{
  "ok": true,
  "bindings": {
    "SUCCESS": {"sound":"UP","mode":"once"},
    "BUSY": {"sound":"OFF","mode":"once"}
  }
}

POST /api/sound-settings

提交 bindings 对象。未提交的状态保留默认值；mode 只能是 once 或 loop。

{
  "bindings": {
    "THINKING": {"sound":"MELODY_CALM","mode":"loop"},
    "SUCCESS": {"sound":"DONE","mode":"once"},
    "ERROR": {"sound":"ALERT","mode":"once"}
  }
}

声音名称包括：OFF、CLASSIC、UP、DOWN、OK、ALERT、SOFT、CHIME、POP、DONE，以及 MELODY_RISE、MELODY_HAPPY、MELODY_CALM、MELODY_READY、MELODY_ODE、MELODY_FRERE、MELODY_ARCADE、MELODY_LEVELUP、MELODY_COIN、MELODY_FANFARE、MELODY_TWINKLE、MELODY_SCALE、MELODY_MINUET、MELODY_TURKISH、MELODY_FUR_ELISE、MELODY_ARCADE2、MELODY_JUMP、MELODY_STAGE、MELODY_BONUS、MELODY_GAMEOVER、MELODY_PUZZLE、MELODY_CHIPTUNE。

8. 设备连接和服务控制

GET /api/status

这是客户监控最重要的接口。返回结构如下：

{
  "ok": true,
  "app_version": "v1.1.2",
  "service": {
    "service_running": true,
    "service_health": {
      "ok": true,
      "connected": true,
      "device_status": "connected",
      "desired_state": "BUSY",
      "current_state": "BUSY",
      "brightness_percent": 75,
      "buzzer_enabled": true,
      "buzzer_volume_percent": 40,
      "transport_mode": "serial",
      "port_name": "COM5",
      "last_error": "",
      "updated_at": 1788743720.2
    }
  },
  "recent_logs": "[AI:workbuddy] ...",
  "sound_settings": {"ok":true,"bindings":{}}
}

device_status 可能为 scanning、connected、reconnecting 或 disconnected。connected=true 才表示当前设备链路已经建立；transport_mode 为 serial 时使用 USB，为 ble 时使用蓝牙。desired_state 是客户最后要求的状态，current_state 是服务当前状态。

POST /api/device/rescan

POST /api/device/rescan
Content-Length: 0

成功响应：{"ok":true}。调用后立即返回，设备扫描在后台进行，客户应随后轮询 /api/status。

POST /api/transport

{"mode":"serial"}

mode 支持 serial 和 ble：serial 表示 USB 有线模式，ble 表示蓝牙无线模式。建议客户程序将工作模式作为配置项，需要换连接方式时调用此接口。成功响应：

{"ok":true,"transport_mode":"ble"}

模式选择建议：USB 适合固定部署、持续运行和对连接稳定性要求较高的场景；蓝牙适合减少线缆、需要灵活摆放设备的场景。切换模式后服务会重新扫描设备，客户程序应等待 /api/status 中的 device_status 变为 connected。

服务控制

POST /api/service/start
POST /api/service/stop
POST /api/service/restart

服务控制操作可能需要数秒。start 或 restart 返回成功只代表启动请求已接受，最终连接状态以 /api/status 为准。

9. 实时监控

当前版本没有 WebSocket 或 Server-Sent Events（SSE）接口。推荐客户使用 1 秒到 2 秒间隔轮询：

let lastState = "";
let lastUpdatedAt = 0;

async function monitor() {
  try {
    const response = await fetch("http://127.0.0.1:18793/api/status", {
      cache: "no-store",
    });
    const data = await response.json();
    const health = data.service?.service_health || {};
    if (health.current_state !== lastState || health.updated_at !== lastUpdatedAt) {
      console.log("AgentCore update", {
        state: health.current_state,
        connected: health.connected,
        deviceStatus: health.device_status,
        updatedAt: health.updated_at,
      });
      lastState = health.current_state;
      lastUpdatedAt = health.updated_at;
    }
  } catch (error) {
    console.warn("AgentCore unavailable", error.message);
  }
}

setInterval(monitor, 1500);
monitor();

如果只关心 AI Agent 事件，使用 GET /api/logs/recent。返回的 logs 是换行分隔的客户事件文本，示例：

{
  "ok": true,
  "logs": "[AI:workbuddy] 2026-09-07 09:05:45,561 触发状态：THINKING\n[AI:workbuddy] 2026-09-07 09:05:47,002 触发状态：SUCCESS"
}

客户应保存上次已处理的完整行或时间戳，避免重复处理。该接口只返回 AgentCore-Light 识别到的状态事件，不会把设备传输原始数据或内部调试日志当作业务事件。

10. 原始兼容命令

POST /api/light/command

{"command":"PING"}

客户也可以通过这个接口直接控制某一盏灯，而不使用预设状态：

{"command":"RED_ON"}

接口会把 command 原样发送给当前连接的 ESP32 设备。成功响应示例：

{"ok":true,"command":"RED_ON"}

常用命令：

例如，客户可以按以下顺序实现“红灯闪烁 3 秒后关闭”：

POST /api/light/command  {"command":"RED_BLINK"}
等待 3 秒
POST /api/light/command  {"command":"OFF"}

当前固件的 *_BLINK 命令会持续闪烁，直到收到新的灯光命令；闪烁周期和自动停止时长暂不能通过命令参数设置。整体亮度请使用 /api/light/brightness 或 BRIGHTNESS:0~100 设置。

优先使用结构化接口 /api/light/state、/api/light/brightness 和 /api/buzzer/settings。原始命令主要用于兼容旧客户程序；不应发送任意未经测试的字符串。

11. AI Hook 管理

GET /api/ai-tools/status

返回内置 Agent 适配器的检测和安装状态。当前支持：claude_code、codex、cursor、qoder、codebuddy、workbuddy、gemini_antigravity、github_copilot、trae、opencode、hermes。

GET /api/ai-tools/scan

扫描本机已安装或可识别的 Agent 平台，不会修改配置。

安装和卸载

POST /api/ai-tools/install
Content-Type: application/json

{"tool_id":"workbuddy"}

POST /api/ai-tools/uninstall
Content-Type: application/json

{"tool_id":"workbuddy"}

安装器会备份并合并配置，只处理 AgentCore-Light 自己的 Hook。WorkBuddy 安装后要彻底退出并重新打开 WorkBuddy，或新建 Agent 会话。

Hermes Agent 安装会创建 ~/.hermes/plugins/agentcore-light/ 插件，并将插件加入 ~/.hermes/config.yaml 的 plugins.enabled。安装后重启 Hermes；如 Hermes 提示插件尚未启用，请执行 hermes plugins enable agentcore-light。

12. 命令行 API

客户不想使用 HTTP 时，可以直接启动短命令：

AgentCore-Light.exe send THINKING --source agentcore
AgentCore-Light.exe send BUSY --source workbuddy
AgentCore-Light.exe send SUCCESS --source agentcore

send 会把状态请求交给后台服务，并输出 {} 供 Hook 调用方消费。客户程序可根据进程退出码判断命令是否成功，但如果服务尚未启动，建议先执行 start 并用 HTTP /api/status 确认设备连接。

诊断和管理命令：

AgentCore-Light.exe status
AgentCore-Light.exe doctor
AgentCore-Light.exe hook status
AgentCore-Light.exe hook scan
AgentCore-Light.exe hook install workbuddy
AgentCore-Light.exe hook uninstall workbuddy
AgentCore-Light.exe install
AgentCore-Light.exe uninstall

13. 在线更新 API

GET /api/version

{"ok":true,"version":"v1.1.2","update_available":false}

GET /api/update/check

返回当前版本、最新版本、平台、下载地址、文件大小和 SHA-256。客户自己的软件通常只需要展示结果，不要自行替换正在运行的 EXE。

POST /api/update/install

先调用 /api/update/check，确认 update_available=true 后再调用。程序会下载并校验安装包，退出当前 UI，替换固定安装位置并重启。更新过程中不要强制结束更新器进程。

14. 兼容性和错误处理建议

• 不要依赖 JSON 字段的顺序；未知字段必须忽略。
• 对状态、亮度、音量使用文档规定的枚举和范围。
• 读取监控数据时以 updated_at、current_state、device_status 的变化判断是否有新数据。
• 网络错误、HTTP 404、服务未运行和设备未连接应分别展示，不能都显示为“设备损坏”。
• 服务重启、设备重新连接或连接通道切换后，设置会从本机配置恢复；客户程序无需反复写入亮度和蜂鸣器参数。
• API 是本机同步 HTTP 服务，单次请求超时建议设置为 5 秒；监控轮询不要并发堆积。
• 设备连接不代表 AI Hook 已安装；Hook 状态请单独查询 /api/ai-tools/status。

15. 最小集成流程

1. 启动 AgentCore-Light.exe start
2. GET /api/status，等待 service_running=true 且 connected=true
3. 客户业务发生时 POST /api/light/state
4. 每 1-2 秒 GET /api/status 做实时监控
5. 需要审计 AI 事件时 GET /api/logs/recent
6. 程序退出时不要强制停止 AgentCore-Light；让后台服务继续运行或调用 service/stop

灯效与状态的详细说明见灯效说明；安装和 AI Hook 配置流程见快速安装和 Mac 安装教程。