高级教程

本教程面向已按《开箱教程》完成配对与接入的用户，完整介绍 PromLight 的高级能力。

如果默认灯控效果已经满足使用需求，可以不必阅读本页。

下列功能均按需开启，不是必选项。

接入配置（setup 子命令）

setup 子命令会把 PromLight 的状态灯 Hook 一键合并安装进各 AI 的配置文件。

支持的 AI：

• claude
• codex
• cursor
• copilot
• qoder
• codebuddy
• antigravity
• all：一次配置当前机器已安装的全部

setup <agent|all> [--global | --local | --project [<路径>]] [--force]

三种安装位置，互斥，默认是 --global：

注意：合并是幂等的。重复执行不会重复追加；PromLight 路径变化后重新安装会自动修正配置；已有其他配置会被保留。

注意：如果目标文件不是合法 JSON，会报错并保持原样。

一次配置多个 AI：

注意：显式指定单个 AI，如 setup claude，始终会安装，不做检测。

注意：检测只作用于 all。

注意：Copilot 仅支持全局安装，对它使用 --project 会自动降级并提示。

注意：配置改动在新开对话后生效；Codex 还需要在设置里的 Hook 面板手动点一次信任。

各 Agent 的状态覆盖

六种状态灯效并不是每个 AI 都完整支持，是否能点亮取决于该 AI 对外提供的事件能力。

• Claude Code：六种状态全支持。
• Codex：不显示“出错”红灯和“对话结束”呼吸，每轮完成后直接进入“完成空闲”。
• Cursor：不显示“出错”红灯，其余支持。
• GitHub Copilot：不显示“等待确认”黄闪，因为确认通常是系统弹窗。
• Qoder：只显示“正在处理”“出错”“完成空闲”。
• CodeBuddy：六种状态全支持。
• Antigravity：只显示“新对话开始”“正在处理”“完成空闲”。

注意：未覆盖的状态只是不会单独点灯，这是各 AI 的事件能力差异，不是 PromLight 故障。

配置文件

以下文件都位于 PromLight 程序所在目录，也就是与 PromLight.exe 或 PromLight.app 同级的位置：

• events.json：Hook 事件到灯效的映射，改完即时生效，无需重启
• devices.json：设备别名和多设备路由，改完后需要重启 PromLight 程序

自定义灯控效果（events.json）

events.json 主要包含两段：

• macros：常用灯效的简称，便于复用
• events：状态到灯效命令的映射，值可以是简称，也可以直接写完整命令

保存后，下一次状态变化就会生效。

例：把“正在处理”从黄灯改成绿灯：

"UserPromptSubmit": "led green on --only"

让“对话结束”变成长周期呼吸

如果把“对话结束”配置成全灭，容易误以为设备断电或损坏。更推荐使用长周期呼吸：

"end": "led green blink --freq 2000 --fade 1000"

• --freq 2000：闪烁周期 2 秒
• --fade 1000：渐变 1 秒，形成平滑呼吸

注意：--fade 只作用于当前命令，不会写入设备全局参数，也不会影响其他状态。

注意：与之相对，write led.fadetime 修改的是全局持久参数，不应该放进事件命令里。

多台 PromLight：命名与切换（devices.json）

程序会自动连接所有已配对的 PromLight。你可以先在 aliases 中给每台设备起别名：

"aliases": {
  "1号": "D46C50377A40",
  "2号": "D46C50377A43"
}

设备编号通常能在包装标签上看到，也可以在 Web 控制台输入 devices 查看。

按项目关联 PromLight（routes）

让某个项目始终使用固定设备：

"routes": {
  "D:/我的项目/网站": "1号",
  "D:/我的项目/App": "2号"
}

这样多个项目并行时不会串灯。匹配规则按最长前缀处理，子目录也会继承对应设备。

按 AI 来源关联设备（agents）

如果希望 Claude 和 Codex 使用不同设备：

"agents": {
  "claude": "1号",
  "codex": "2号"
}

路由优先级：

1. routes：按项目
2. agents：按 AI 来源
3. 自动分配

一份更完整的 devices.json 示例：

{
  "aliases": { "1号": "D46C50377A40", "2号": "D46C50377A43" },
  "routes": { "D:/我的项目/网站": "1号" },
  "agents": { "claude": "1号", "codex": "2号" },
  "default": "1号"
}

• default：没有命中任何路由时的兜底设备，可省略；省略时默认使用枚举到的第一台

注意：修改 devices.json 后需要重启 PromLight 程序；events.json 则无需重启。

端口与 Web 控制台

PromLight 程序在后台运行，控制和调试主要通过 Web 控制台完成：

• 打开 http://127.0.0.1:7800

程序默认使用两个本机端口，都可以在 config.json 里修改：

如果端口冲突，可以改成其他值后重启程序：

{ "web_port": 7801, "port": 47801 }

手动操控 PromLight 指示灯

PromLight 程序在后台运行，没有可见窗口。以下命令都在 Web 控制台的输入框里执行。

先看几个常用调试命令：

注意：use 只影响当前调试会话，不会修改 devices.json 的路由配置。

灯光控制命令语法：

led 颜色 动作 [--only] [--count 次数] [--freq 周期] [--fade 渐变]

• 颜色：green、yellow、red、all，也支持组合，如 green+red
• 动作：on、off、blink
• --only：先熄灭其他灯，保证只显示当前状态
• --count N：闪烁次数，0 表示持续
• --freq：闪烁周期，支持 1000ms 或 1s
• --fade：本次命令的渐变时长

关于 --fade：

• 对 on / off：表示亮起或熄灭时的平滑过渡
• 对 blink：表现为呼吸效果，最大只会取闪烁周期的一半

注意：--count、--freq、--fade 只作用于当前命令，不会保存到设备。

示例：

注意：命令写错只会提示“命令有误”，不会影响 AI 正常运行。

读写设备默认参数（设备持久保存）

除了临时控制命令，还可以读写设备级的持久参数：

支持的主要参数：

• led.brightness：亮度，范围 1~100
• led.frequency：闪烁周期，范围 200~5000ms
• led.fadetime：渐变时间，范围 0~5000ms
• ble.advtimeout：蓝牙广播超时，范围 30~240s

注意：不要在 events.json 的事件命令中使用 write。这些参数是全局持久参数，频繁写入会改变其他状态的灯效，也会带来额外的写入负担。

注意：如果你只想针对某条命令做呼吸或渐变，请用 led ... --fade。

Hook 脚本

agent_hook.py 位于 PromLight 程序同级目录，用于被 Claude、Codex 等工具在运行期间调用。

它通过 TCP 端口 47800 与 PromLight PC 程序通信。默认执行策略是：

• 调用后快速返回
• 不阻塞 Agent 运行
• 失败时不影响主流程

如果你想自己写脚本或程序主动上报事件，可以直接使用下一节的通信协议。

通信协议

PromLight 运行后会监听一个本机 TCP 端口，接收事件并控制灯光。Hook 脚本走的就是这个协议。

怎么发

• 传输方式：TCP
• 数据格式：一行 UTF-8 JSON，结尾带 \n
• 地址：127.0.0.1
• 端口：默认 47800，可在 config.json 的 port 修改
• 发完即可关闭连接；PromLight 会返回一行 JSON，应答可读可不读

发什么

常见消息格式：

{
  "cmd": "led green on --only",
  "message": "build finished",
  "session": "my-task-1",
  "cwd": "/path/to/project",
  "release_session": false
}

注意：选灯顺序是：cwd 命中 routes，否则按 session 自动分配空闲设备，再否则走默认设备。

应答

PromLight 每条消息都会返回一行 JSON：

{"ok": true, "detail": "0x84"}

• ok：是否成功送达设备
• detail：成功时是设备确认码，失败时会返回错误原因

例子

命令行示例：

printf '{"cmd":"led green on --only","message":"hello"}\n' | nc 127.0.0.1 47800

Python 示例：

import socket, json

msg = json.dumps({
    "cmd": "led red blink --only --count 5",
    "cwd": "/path/to/project"
}) + "\n"

with socket.create_connection(("127.0.0.1", 47800), timeout=0.3) as s:
    s.sendall(msg.encode("utf-8"))

更新升级

本节所说的自动更新只针对 PC 端 PromLight 程序，不包含蓝牙指示灯硬件固件升级。

PromLight 程序会自动检查并下载新版本，下次重启时完成更新。即使更新失败，也不会影响当前设备使用。

如果需要手动触发更新，也可以在 Web 控制台输入：

update

常见问题

高频问题与排查方法请查看：常见问题

命令速查

以下命令都在 PromLight Web 控制台中执行。

接入配置总命令：

setup <claude|codex|cursor|copilot|qoder|codebuddy|antigravity|all> [--global|--project [路径]|--local]

PromLight 出厂默认参数