PromLight 高级教程

本教程面向已按《开箱教程》完成配对与接入的用户，专业、完整地介绍 PromLight 的全部能力。加入默认灯控效果满意，则无需阅读本文本。 下列功能均按需开启，非必选项。

接入配置（setup 子命令）

setup 子命令把 PromLight 的状态灯 hook 一键合并安装进各 AI 的配置文件。支持的 AI：claude / codex / cursor / copilot / qoder，或用 all 一次配好本机已装的全部。

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

三种安装位置（互斥，缺省为 --global）：

合并是幂等的：重复执行不会重复追加，挪动 PromLight 位置后重装会自动更正配置里的路径，也会保留你原有的其它配置；目标文件不是合法 JSON 时会报错并保持原样、绝不破坏。

一次配好多个（all）：

显式点名单个 AI（如 setup claude）始终安装、不做检测；检测只作用于 all。 Copilot 仅支持全局安装；对它用 --project 会自动降级为全局并打印提示。 配置改动均在新开对话后生效；Codex 还需在 设置 → 钩子 里手动点击信任一次（桌面版无法用 /hooks 命令信任）。

各 Agent 的状态覆盖

六种状态灯效（含义见《开箱教程》「默认灯效」）并非每个 AI 都齐全——能点亮哪些，取决于该 AI 对外提供的事件。✓=支持，—=该 AI 无对应事件：

• Claude Code：六种状态全支持。
• Codex：不显示「出错」红灯与「对话结束」呼吸（每轮答完即「完成空闲」）。
• Cursor：不显示「出错」红灯，其余均支持。
• GitHub Copilot：不显示「等待确认」黄闪（其确认为系统弹窗）。
• Qoder：只显示「正在处理」「出错」「完成空闲」，无「开始 / 等待确认 / 对话结束」。

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

Hook 脚本

agent_hook.py 是用于被 Claude/Codex 运行期间调用执行的 Hook 脚本文件，位于 PromLight 程序 同级目录。

该脚本通过TCP端口47800（默认端口，可修改，见「端口与 web 控制台」节），与 PromLight PC端程序通信，为了保证 Agent 正常运行，该脚本执行后立刻释放资源，不会报错，也不会阻塞 Agent 运行。

配置文件

以下配置文件都在 PromLight 程序所在的文件夹里（与 PromLight.exe / PromLight.app 同目录），任意文本编辑器即可打开修改：

• events.json——HOOK事件 与 状态灯效映射表，用户可以自定义灯控状态（改完即时生效，无需重启）。
• devices.json——设备别名 / 多设备路由配置，用户为项目或Agent关联固定的设备（改完需重启 PromLight PC程序）。

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

events.json 有两段：

• macros——常用灯效的简称（如 work = 黄灯常亮），便于复用；
• events——"状态 → 灯效"对照表，值可写简称，也可直接写整条命令。

保存后下一次状态变化即生效，无需重启。

例：把"正在处理"从黄灯改成绿灯——

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

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

把"对话结束"配成全灭，容易让人误以为设备断电或损坏。用 --fade 给一段2秒长周期呼吸最为合适——平滑起伏、醒目又柔和。把 events.json 里 macros 的 end 改成：

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

• --freq 2000：闪烁周期 2 秒，即"长周期"；
• --fade 1000：渐变 1 秒（=周期的一半）→ 满呼吸（灭↔亮平滑过渡）。

--fade 只作用于本条命令、对应的那几盏灯，不写设备全局参数、也不影响其他状态的灯效——可放心写进事件。 （与之相对，write led.fadetime（见 §3）改的是全局持久参数，请勿放进事件命令。）

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

程序会自动连上所有已配对的 PromLight 指示灯。在 devices.json 的 aliases 里给每台起个好记的名字 （右侧编号印在设备包装标签上，也可在 PromLight web 控制台输入 devices 查到）：

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

按项目关联PromLight（routes）

让某个项目始终用固定的PromLight，在 devices.json 的 routes 里把项目文件夹映射到设备：

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

这样"网站"项目的 AI 状态永远显示在 1号灯上，多个项目并行也不串。匹配按最长前缀：配了某目录，其所有子目录都会路由到指定的PromLight上。

按 AI 来源关联设备（agents）

想让 Claude 和 Codex 各用一台PromLight？在 devices.json 加一个 agents 段：

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

于是 Claude 的状态走 1号PromLight、Codex 走 2号PromLight，一眼区分谁在干活。

路由优先级：routes（按项目）> agents（按来源）> 自动分配。即同一项目用 routes 钉死时仍以项目为准；没被项目命中的会话，才按 AI 来源分灯。

一份较完整的 devices.json：

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

• default：没命中任何路由、也无可分配时的兜底设备（可省，省略=枚举到的第一台）。

改 devices.json 后需重启 PromLight 程序才生效（改 events.json 则即时生效）。

手动操控 PromLight 指示灯

PromLight 程序在后台运行、无可见窗口；下列命令都在 web 控制台（浏览器打开 http://127.0.0.1:7800）的输入框中输入。

在 PromLight web 控制台中可使用提供的命令快速调试设备：

注意，use 命令，仅用于选择待调试的设备，不会修改 devices.json 中的关联配置。

以下命令直接控制 PromLight 指示灯，便于调试或演示。语法如下：

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

• 颜色：green 绿 / yellow 黄 / red 红 / all 全部（也可组合，如 green+red）
• 动作：on 亮 / off 灭 / blink 闪
• --only：点亮前先关掉其他灯，保证同一时刻只显示一种状态
• --count N：闪几次（仅 blink，0=持续）
• --freq：闪烁周期（仅 blink，支持单位 1000ms / 1s，越大越慢；范围 200~5000ms）
• --fade：本次渐变时长（on/off/blink 均可，范围 0~5000ms）。
  • on/off：亮起/熄灭带一段平滑过渡，按设定整段渐变（只受 0~5000ms 限制）；
  • blink：配上它即"呼吸"，但渐变上限会被自动裁到闪烁周期的一半（设更大也按周期/2 起伏）。

Note: 这里的参数 --count N，--freq，--fade 仅针对本次命令，不会保存到设备中。

示例：

命令打错只会提示"命令有误"，不报错、也不影响 AI 运行。

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

还可读/写设备参数。这些是设备级全局参数：写入后对所有灯生效、并持久保存：

• led.brightness 亮度 1~100（%）
• led.frequency 闪烁周期 200~5000（ms）
• led.fadetime 渐变时间 0~5000ms（注意 0=无渐变）
• ble.advtimeout 蓝牙广播超时 30..240（秒）

请勿在 events.json 的事件命令里 write 这些参数——它们全局且持久，在事件中反复写入会改变其他状态的灯效、并频繁写入存储。需要"逐灯"渐变/呼吸（只影响某条命令的那几盏灯、不写全局）请改用 led … --fade（见 §2）。

更新升级

本节所述自动更新仅指 PC 端 PromLight 程序（后台软件），不涉及 PromLight 蓝牙指示灯硬件的固件升级。蓝牙灯固件升级功能可能在未来版本中提供。

PromLight 程序会自动检查并下载新版本，下次重启程序时无感完成更新，无需手动操作；即使更新失败也不影响 PromLight 指示灯正常使用。

也可以在 web 控制台输入命令 update 手动更新。

端口与 web 控制台

PromLight 程序在后台运行，控制与调试都通过 web 控制台完成：在浏览器打开 http://127.0.0.1:7800 即可。

程序使用两个本机端口，均可在程序目录的 config.json 中配置（端口冲突时程序会引导生成该文件）：

若某端口被其他程序占用（会导致程序启动失败或对应功能失效），编辑 config.json 改用其他端口、保存后重启 PromLight 生效，例如：

复制

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

通信协议

暂无

常见问题

使用中的高频问题与排查方法见 常见问题。

命令速查

在 PromLight web 控制台（浏览器打开 http://127.0.0.1:7800）的输入框中输入。

PromLight出厂默认参数