红绿灯状态灯 eustace030616-hub/traffic-light

traffic light

一个 DSH 插件，外加一个 macOS 指示灯守护进程。 插件把每个会话正在做什么写进一个小 JSON 文件；守护进程读这个文件，在每个窗口上方画出一盏红绿灯。两个进程，一份文档，中间没有 socket。

- 插件。 lib/ —— 一个 DSH 插件，从插件页面安装。
- 守护进程。 mac/ —— DSHLight.app，通用架构，ad-hoc 签名。它只读，从不写。

安装

插件 —— 把下面这行粘进 DSH 的插件页面（侧边栏 → Plugins），然后重启 DSH：

github:eustace030616-hub/traffic-light

守护进程 —— 不用装：它就在同一个包里，插件会把它启动。想单独运行，克隆仓库并打开随附的 bundle：

git clone https://github.com/eustace030616-hub/traffic-light.git ~/traffic-light
open ~/traffic-light/bin/DSHLight.app

用法

| 你看到 | 它表示 |
| 暗的 | 休息（idle）：没有待处理的事，这不是故障 |
| 黄色，常亮 | 有会话正在干活（working） |
| 黄色，脉动 | 有会话卡在你这里（asking）—— 1.3 s 内从 30% 到 100% |
| 绿色 | 一轮结束了，你还没看（waiting） |
| 红色 | 数据源本身不可信 —— 丢了、读不了或过期了 |
| 红色，脉动 | 余额低于阈值，或者服务商不肯接这次调用 |

| 你做什么 | 它做什么 |
| 双击 | 在 DSH 和你来时的应用之间切换 |
| 单击 | 在灯旁边立刻说明这盏灯什么意思 —— 它往上飘，一秒左右后消失，句子越长留得越久 |
| 右键 | 打开列表：Appearance、Account、Quit the light |
| 拖动 | 吸附到更近的那条屏幕边缘，高度随你放下的位置 |

DSH 在前台时，绿色会自己消掉，因为待在这里正是这条提醒想要的结果。

Appearance ▸ Account ▸
Size ●━━━━━━━━━━ 20 pt CNY 12.62
Gap ●━━━━━━━━━━ 8 pt ─────────────
Rest ●━━━━━━━━━━ 28% Top up now
Lit ●━━━━━━━━━━ 85% updated 2m ago
─────────────
Reset to default

滑块拖动时即时生效，并且会被记住；Reset to default 恢复 20 / 8 / 28% / 85%。账户部分每种有余额的货币占一行，下面跟着平台自己的充值页面。点一下货币那一行 —— ↻ 就是提示 —— 去要一份最新余额。列表保持打开，答案回来时数字就地改写。

数据怎么流动

一个文件，一个方向：

DSH Desktop the daemon (DSHLight)
agent/pre-step a prompt was accepted reads the document every 0.25 s
agent/turn-stopping the ordinary turn end never fetches, holds no credential
agent/status idle | running
approval/request blocked on you
user-questions/… blocked on you │ ▲ ▼ │ lib/index.js — 每次变更写一份文档，每 2 秒重新打一次时间戳（心跳）│ │ │ ▼ │ ~/Library/Application Support/dsh-status/state.json ┘ 先写入临时文件，再重命名到位

守护进程唯一的写入，用于按需获取余额：点击某条货币行 → touch <statePath>.refresh → 下一次心跳时返回

- 多个会话，一盏灯。 每个根会话都在 meta.sessions 里；守护进程按 blocked > unread finish > working > rest 聚合。
- 多个 harness：暂不支持。 每个发布者都会写整份文档，所以两个发布者会互相覆盖，而守护进程是单例（flock），只读一个路径。要改的话，得先改成每个路径一把锁。
- 其他任何遵守契约的东西： 你自己写文档，保持 updatedAt 新鲜，用 --state-file PATH 让守护进程指向它。守护进程里不用改任何代码。

文档

~/Library/Application Support/dsh-status/state.json —— cat 它，或者用 DSHLight --print 跟踪它。

{ "version": 1, "state": "working", "sessionId": "session-1a2b3c4d", "title": null,
"updatedAt": 1790000000000, "changedAt": 1790000000000, "heartbeatMs": 2000,
"reason": "prompt", "meta": { "cwd": "/Users/you/project" } }

| 字段 | 含义 |
| version | 契约版本。只有破坏性变更才会升。 |
| state | idle \| working \| waiting \| asking。 |
| sessionId | 正在上报的会话，或 null。 |
| title | 会话标题 —— 目前始终是 null（见 Known gaps）。 |
| updatedAt | 最后一次收到发布者消息的时间。即使什么都没变，也会每 heartbeatMs 重新打一次时间戳 —— 这正是过期判断能生效的原因，也是它绝不能当成变更时间读取的原因。 |
| changedAt | 最后一次确认此状态的时间。心跳不会动它，所以确认时该比对的是它，而不是 updatedAt。 |
| heartbeatMs | 发布者的节奏，这样守护进程就不必硬编码过期规则。 |
| reason | 哪个事件写了这份文档：init、session-start、prompt、turn-end、agent-idle、agent-running、approval、question、answered、dispose。仅用于调试。 |
| meta | 扩展通道：只增不改，未知键必须忽略。 |
| meta.sessions | 发布者监视的每个会话：{ id, state, reason, changedAt }。 |
| meta.account | { fetchedAt, intervalMs, isAvailable, balances: [{ currency, total, granted, toppedUp }] }，查询失败时则是一个 reason。数字都是字符串；绝不含凭据。 |

新信息都放进 meta，键只增不改，读取方遇到从未见过的状态时保持静默而不是报警 —— 所以新增状态或键不会让旧版本虚惊一场。

什么会让灯变化

| 转换 | 触发条件 |
| → idle | 插件加载、会话即将开始、dispose |
| → working | 带消息的 agent/pre-step，或 agent/status: running |
| → waiting | agent/turn-stopping，或 agent/status: idle |
| → asking | approval/request 或 user-questions/request，一直计数到最后一个得到答复 |
| ignored | 子代理上的上述任何一项；提问计入其父会话 |

只有智能体的状态能覆盖所有结束方式：你停止的一轮会被中止，turn-stopping 永远不会为它派发——这就是为什么以前停止的会话会一直亮黄灯，直到 DSH 重启。

配置

每个键都是可选的，且手工校验；不可用的值会回退到默认值（lib/config.js）。

| 键 | 默认值 | 说明 |
| statePath | ~/Library/Application Support/dsh-status/state.json | 必须是绝对路径 |
| heartbeatMs | 2000 | 下限为 250 |
| launch | true | 挂载时启动守护进程，dispose 时停止 |
| lightArgs | [] | 额外的守护进程参数，例如浏览器托管的 DSH 用 --open / --ack-app |
| balance | true | 本包发出的唯一请求 |
| balanceMs | 300000 | 下限为 60000 |

守护进程

npm test # 65 checks — no DSH, no network, no key
npm run ship # rebuild bin/ from the Swift (npm test fails if it drifts)
./mac/build.sh --run # follow the light in a terminal
open build/DSHLight.app # draw it by hand
pkill -f DSHLight # stop it

| 参数 | 作用 |
| --state-file PATH | 读取哪个文档（默认：已发布的路径） |
| --print | 在终端里跟随，而不是绘制窗口 |
| --interval SECONDS | 轮询间隔，默认 0.25 |
| --open PATH | 双击打开什么，默认 /Applications/DSH Desktop.app |
| --ack-app BUNDLE-ID | 另一个应用，它返回即视为绿灯结束；可重复 |
| --no-ack | 保持绿灯直到下一个提示词，而不是返回时结束 |
| --level floating\|status\|screensaver | 窗口层级，默认 screensaver |
| --size POINTS | 本次运行的透镜尺寸，覆盖尺寸滑块 |
| --low-balance POINTS | 余额降到多少时灯变红并呼吸，默认 8，以金额最大的币种计；0 表示关闭 |

值得了解：

- 主体是菜单自身材质的一半强度，加一层 0.15 的黑色蒙版，圆角取自其窄边；透镜周围的环是浅灰色，绝不是黑色。
- 菜单栏的 22 点始终预留，从不跟随：visibleFrame 在两种栏状态下都报告整个屏幕，而贴着菜单栏会产生一个迟滞的灯，与菜单栏重叠。
- 红色从不表示智能体。 不可信的订阅源是红色常亮；余额耗尽是红色呼吸；完全读不到的账户是列表里一行暗色，绝不是透镜。
- 守护进程不持有密钥，也不抓取任何东西；每个账户数字都来自发布者，而它只写一个刷新请求。
- 每个用户一盏灯 —— 进程存活期间独占一个 flock。
- 双击恢复的是应用，不是窗口或标签页 —— 公开 API 能触及的范围就到这里。
- 不需要 Apple 账号：临时签名，包管理器安装不会设置隔离标志。

密钥

- API key 在请求时通过 harness 的凭据接缝解析 —— inject 是唯一可行的路径 —— 并在一次请求期间存活于一个局部变量。没有任何地方存储它，轮换后的 key 无需重启即可抵达下一个请求。
- 失败时返回的是错误码，绝不是服务商的消息：DeepSeek 自己的 401 会回显被拒 key 的一部分，所以只有在应答正常时才读取响应体。
- key 绝不会进入已发布的文档、日志行或子进程的参数，守护进程则完全没有凭据。测试注入一个金丝雀值，并断言它不出现在任何地方。
- 开发时也是同一条规则：绝不打印凭据。描述凭据时只说它存在、来源和长度；万一泄露，用 ctx.credentials.set(ref, …) 轮换。

已知缺口

- title 始终是 null：会话标题明明存在，但哪个访问器能暴露它尚未确认，猜错比 null 更糟。

MIT —— 见 LICENSE。