在 AI 编码工具大行其道的今天，像 Claude Code 或 OpenAI Codex 这样的 CLI（命令行）工具已经成为了不少开发者的生产力标配。但随之而来的是一个体验上的小痛点：终端盲盒效应。

当你在后台运行一个复杂的重构任务、或者让 AI 执行一系列工具调用时，你必须时刻把终端窗口留在一边，盯着那几行闪烁的提示符，确认它是在“思考”、“等待授权”还是“报错挂起”。一旦切换到 IDE 专心看代码，你就彻底失去了对 AI 状态的感知。

为了解决这个痛点，我顺手写了一个小工具：Code Light AI。它是一个常驻系统托盘的“状态灯”，能让你在不看终端的情况下，一眼看穿后台 AI 代理（Agent）的当前一举一动。

---

核心设计：为什么是托盘灯？

在设计这个工具时，我的核心目标是无感、轻量、高确定性。

最终的形式非常简单：系统托盘区一个会呼吸、会变色的小圆点。通过颜色的状态映射，把原本属于终端的反馈“降维”到系统的全局视觉边缘：

• 灰色（Idle）： 岁月静好，没有活跃的 AI 会话。

• 绿色闪烁（Working）： AI 正在不知疲倦地调用工具或执行代码。

• 黄色闪烁（Waiting）： 划重点！这是最实用的状态。当 AI 需要你输入密码、确认写入权限（Permission Prompt）时，它会立刻变黄闪烁，提醒你切回终端“捞”它一把。

• 红色闪烁（Error）： 报错挂了，及时止损。

• 蓝色（Completed）： 任务搞定，保持 10 秒让你安心，随后自动归于灰色。

为了保证对视觉的有效捕捉，所有活跃状态（工作、等待、错误）都会以 500ms 的频率进行呼吸闪烁。

---

技术架构：极其克制的“零成本”设计

很多同类工具喜欢动辄起一个本地 HTTP 服务器，或者在后台挂一个 WebSocket 搞通信。但这对于一个纯粹的本地辅助工具来说，太重了。不仅占用端口、增加功耗，还平添了安全风险。

Code Light AI 采用了一种极其复古但极其可靠的架构：基于文件的生命周期钩子（Shell Hooks）与文件轮询。

1. 寄生于 CLI 的生命周期

现代 AI CLI 工具通常都预留了生命周期钩子（Lifecycle Hooks）。例如，Claude Code 会读取 ~/.claude/settings.json，而 Codex 会读取 ~/.codex/hooks.json。

通过一行命令，Code Light AI 会把一组轻量级的 Shell 脚本注册到这些钩子中。每当 AI Agent 发生状态迁移（比如准备调用工具、遇到权限阻碍、退出会话），就会触发对应的脚本。

2. 状态的原子化落盘

触发的 Shell 脚本不会做任何复杂的逻辑，它们只干一件事：往本地特定目录（~/.code-light/sessions/）下写入一个以当前会话 ID 命名的 JSON 状态文件。

AI 事件触发 → 执行 Hook 脚本 → 原子写入本地 JSON → 托盘应用消费文件

这里有一个工程细节：为了防止高频读写导致的文件损坏或锁死，脚本采用了原子化写入（先写临时文件，再通过 mv 覆盖），确保托盘应用在读取时数据永远是完整的。

3. Tauri v2 后端的高效消费

应用后端基于 Tauri v2 + Rust 构建。

Rust 后端只做一件纯粹的事：开启一个每秒执行一次的轮询定时器，扫描 ~/.code-light/sessions/ 目录下的所有 JSON 文件，通过多线程解析状态，并在内存中进行状态竞争与合并，最后直接修改系统托盘的图标。由于没有前端渲染进程（纯 Menu Bar 无窗口模式），内存占用极低，常年保持在个位数兆字节（MB）。

---

边界工程：如何处理“脏数据”与复杂场景？

在实际开发中，单会话的理想状态是很少见的。写这个项目时，我花了一大半精力去解决各种“脏状态”和多场景兼容：

多会话状态竞争（Priority Matrix）

如果你在终端里同时开了三个窗口，一个在用 Claude 重构，另一个在用 Codex 跑测试，托盘应该听谁的？

项目引入了状态优先级矩阵：

$$\text{Error} > \text{Waiting} > \text{Working} > \text{Completed} > \text{Idle}$$

Rust 后端在轮询时会遍历所有未过期的会话文件，提取所有状态，并强行吐出当前优先级最高的那个。比如只要有一个会话卡在“等待确认（Waiting）”，哪怕其他会话都在“正常工作”，托盘也会显示黄色，确保关键阻塞信息不被淹没。

异常行为的兜底与自动清理（Self-Healing）

CLI 工具由于各种原因（如用户直接强杀终端、网络突发断开）可能无法触发 stop 钩子。这会导致过期的 JSON 状态文件残留在盘上，引发“状态死锁”。

为此，后端设计了一套自动清理与状态推演机制：

• 僵尸会话清理： 超过 5 分钟没有任何时间戳更新的会话，直接判定为死亡，文件强行抹除。

• 卡死推演：

  • 如果一个会话被标记为 waiting（等待用户确认）超过 30 秒无响应，系统会降级推演其为 working，避免托盘长时间假死。

  • 如果一个会话保持 working 状态超过 60 秒且没有任何增量更新，系统会自动将其平滑过渡到完成或闲置。

---

总结

Code Light AI 并不是一个技术堆砌的大作，而是一个典型的工程创口贴。它用最轻量、最不打扰的方式，缝合了“本地命令行工具”与“开发者视觉焦点”之间的断层。

如果你也在频繁使用 Claude Code 这类工具，厌倦了在各个桌面和终端窗口之间反复横跳，不妨来体验一下。工具完全开源，你也可以基于它开放的 JSON 协议，轻松定制属于你自己的 AI 状态追踪器。