xinyang920/dsh-caps-beacon

English | 简体中文

把 MacBook 的 Caps Lock 指示灯变成 DeepSeek Harness 的状态灯——Mac-Agent-Beacon 的 DSH 原生版。

常亮 = 工作中 · 快闪 = 需要你 · 熄灭 = 空闲

让 DSH 在后台干活时，你不用再切回来盯屏幕：扫一眼键盘就知道状态。

灯光含义

宿主状态	LED
根 agent 正在运行（工具调用、模型请求、重试）	常亮
有审批请求在等你	快闪
ask_user_question 提问或计划审批在等你回答	快闪
根任务以 error / blocked 结束（锁存到下一个任务开始）	快闪
空闲	熄灭

"需要注意"永远压过"工作中"：审批一解决，灯立刻回到常亮。默认只盯根 agent（rootsOnly），子 agent 扇出不会让你的键盘狂闪。

插件是纯观察者：approval/request 和 tools/execute 监听器一律通过 next() 转发，绝不替你做任何决定。它只写 LED——不按键、不改键位映射、 不改审批策略。退出时助手会把物理灯恢复成当前逻辑大写状态。

工作原理

DSH 宿主事件 ──▶ 插件状态机 ──▶ beacon-led (C) ──▶ Caps Lock LED

• 插件监听 DSH 的公开宿主事件——agent/status、approval/request、 tools/execute、session/event。不逆向任何内部接口，agent 栈升级不会 悄悄弄坏它。
• 一个小 C 助手（native/led.c，经 Mac-Agent-Beacon 改编自 CapsPulse，均为 MIT）通过 macOS IOKit/IOHID 输出元素驱动内置键盘的 Caps Lock LED。插件保活一个 beacon-led serve 子进程，往它的 stdin 写 1/0 字节；快闪由插件内 定时器驱动。
• 助手绝不注入按键。写 LED 期间若逻辑大写状态发生变化，立即停止。
• 助手仍可能因环境原因死亡——系统睡眠重置 HID 设备、信号波及它的进程 组等。插件会自动重启它（指数退避，1 秒到 30 秒）并重新应用当前灯态， 信标自愈，而不是黑到下次重启 dsh。

环境要求

• 带内置 Apple 键盘的 MacBook（外接键盘和 Magic Keyboard 不支持）。
• macOS + Xcode Command Line Tools（xcode-select --install，用于一步 make 编译）。
• 装好 DeepSeek Harness （dsh）并有一个 profile——以 web 为例测试。

安装

# 1. 把插件加入 profile（任意 profile 均可，此处以 web 为例）。
dsh plugin --profile web add github:xinyang920/dsh-caps-beacon

# 2. 在 pnpm 放置包的位置编译 LED 助手。
cd ~/.dsh/profiles/web/node_modules/dsh-caps-beacon && make

# 3. 重启 dsh web——bundle 成员在启动时读取。

第 1 步会自动把 bundle 注册进 dsh.profile.bundles。第 2 步编译 build/beacon-led（约一秒；安装器刻意不替你执行编译产物）。第 3 步必需， 因为插件在启动时加载。

如被系统拦截，授予 LED 访问权限

多数机器上助手无需额外授权即可写 LED。如果你的机器拦了：

1. 运行 ./build/beacon-led inspect——访问被拒时它会说明原因。
2. 打开 系统设置 → 隐私与安全性 → 输入监控，点 +，按 Cmd-Shift-G 输入 profile node_modules 里 dsh-caps-beacon/build/beacon-led 的绝对路径。
3. 重启 dsh web。

验证

# 助手能找到键盘和 LED 元素：
./build/beacon-led inspect
# {"keyboard":"Apple Internal Keyboard / Trackpad","led_output":true,...}

# dsh 运行期间助手进程存活：
pgrep -fl beacon-led

然后给任意会话派个任务：运行期间 LED 常亮。最简单的快闪测试：让 agent 调用 ask_user_question 向你提问——提示等待期间 LED 快闪。

助手失败和异常退出会以 [dsh-caps-beacon] 前缀记录在 dsh 日志里。

配置

在 profile 的 cordis.patch.yml 里按 id dsh-caps-beacon 覆盖（patch 会 替换整行 config，需要什么就重述什么）：

- id: dsh-caps-beacon
  config:
    enabled: true
    ledPath: ""            # beacon-led 绝对路径；默认：包内 build/beacon-led
    blinkIntervalMs: 250
    rootsOnly: true        # 忽略子 agent 和后台子进程
    verbose: false         # 记录每次模式切换
    triggers:
      approval: true       # approval/request 等待中
      question: true       # ask_user_question / exit_plan_mode 等待中
      error: true          # 任务以 error/blocked 结束

排查

• 灯从不亮——dsh 运行时查 pgrep -fl beacon-led。没有进程说明插件 没加载：确认 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 里有 dsh-caps-beacon，然后重启。有进程但灯不亮，通常是外接键盘或 Karabiner 的问题：Karabiner-Elements 独占抓取内置键盘时会挡住 LED。
• 灯在会话中途变黑——助手死了（系统睡眠、终端 Ctrl+C 是常见诱因）。 v0.1.1 起插件会在几秒内自动复活它；dsh 日志里可见 [dsh-caps-beacon] helper restarted after failure。若超过一分钟仍是黑的， 重启 dsh web。
• make 失败——安装 Xcode Command Line Tools （xcode-select --install）后重试。
• 升级了插件——重跑安装第 2 步（包目录里 make）让二进制跟上，然后 重启。

卸载

dsh plugin --profile web remove dsh-caps-beacon

如果你的 dsh 版本没有自动移除，把 ~/.dsh/profiles/web/package.json 里 dsh.profile.bundles 中的 dsh-caps-beacon 删掉，然后重启。

致谢

• Mac-Agent-Beacon（MIT）—— 原版 Codex 状态灯，LED 助手的 stdin 协议与安全检查直接源自它。本项目 用 DSH 公开宿主事件替换了它最难的部分（逆向 Codex Desktop IPC 流）。
• CapsPulse（MIT）——IOKit/IOHID 控制 Caps Lock LED 的原始技术来源。

见 THIRD_PARTY_NOTICES.md。

许可

MIT