# 三色灯

**Repository Path**: aeizzz/three-color-light

## Basic Information

- **Project Name**: 三色灯
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 三色灯 Three Color Light

三色灯是一个原生 macOS 桌面状态指示器，用来在不切回终端的情况下观察 Codex 和 Claude Code 的工作状态。

它会在桌面右上角显示一个常驻小窗，并在菜单栏显示当前状态：

- 绿色：空闲，没有检测到正在工作的 Codex 或 Claude Code 任务。
- 黄色：工作中，检测到 Codex 或 Claude Code 正在执行任务。
- 红色：需要关注，检测到异常状态或近期错误信号。

## 功能特性

- 原生 Swift/AppKit 实现，无第三方运行时依赖。
- 桌面浮窗默认置顶，可拖动、取消置顶、重置位置、退出。
- 菜单栏显示当前状态和状态详情。
- 支持读取全局 hook 写入的状态文件。
- 支持读取当前工作区的结构化状态文件。
- 支持扫描当前工作区近期日志中的错误关键字。
- 支持进程兜底检测 Codex、Claude、Claude Code 活动。
- 提供核心状态分类回归测试。

## 状态来源优先级

三色灯会按以下顺序判断状态。

### 1. 全局 hook 状态

如果 Codex 或 Claude Code 的全局 hook 写入了：

```text
~/.three-color-light-status.json
```

三色灯会优先使用这个状态。状态文件格式为：

```json
{"status":"working","timestamp":1780144363}
```

支持的状态值：

- `working`：工作中，显示黄灯。
- `idle`：空闲，显示绿灯。
- `attention`：需要关注，显示红灯。

`idle` 会一直有效，直到下一次 hook 写入 `working` 或 `attention`。这样可以避免 Codex 桌面进程仍然打开时，任务结束后又被进程兜底检测误判为黄灯。

### 2. 当前工作区结构化状态

如果没有有效的 hook 状态，三色灯会读取当前工作区中的状态文件：

```text
.omx/state
.codex
.claude
```

活跃会话会显示黄灯；包含 `error`、`failed`、`panic`、`crash` 等异常阶段的会话会显示红灯。

### 3. 当前工作区日志

三色灯会扫描当前工作区近期日志：

```text
.omx/logs
.codex/logs
.claude/logs
```

支持的日志格式包括 `.log`、`.jsonl`、`.txt`。常见异常关键字包括：

```text
error
fatal
exception
panic
failed
failure
permission denied
rate limit
timed out
timeout
crash
```

### 4. 进程兜底检测

如果没有 hook 状态和结构化状态，三色灯会检测命令行中包含以下关键字的进程：

```text
codex
claude
claude-code
```

只有当进程 CPU 时间在轮询间隔内增长时，才会判定为工作中。

## 运行环境

- macOS 13 或更高版本。
- Swift 6 或兼容 Swift Package Manager 的 Xcode Command Line Tools。

检查 Swift：

```sh
swift --version
```

## 从源码运行

```sh
swift run ThreeColorLight
```

运行后会出现：

- 桌面右上角浮窗。
- 菜单栏圆点图标。

## 构建

调试构建：

```sh
swift build
```

Release 构建：

```sh
swift build -c release
```

生成 `.app`：

```sh
scripts/build-app.sh
```

生成结果：

```text
build/ThreeColorLight.app
```

## 测试

```sh
swift test
swift run ThreeColorLightCoreRegressionTests
```

`swift test` 用于 SwiftPM 包级检查；`ThreeColorLightCoreRegressionTests` 用于验证核心状态分类逻辑。

## Hook 配置

为了让三色灯准确知道 Codex 或 Claude Code 什么时候开始和结束任务，建议配置全局 hook。

详细配置见：

- [Codex 和 Claude Code Hook 配置](docs/hooks.md)

## 提交到 Gitee

这个目录当前不是 Git 仓库。提交前建议先初始化仓库，并确认 `.build/`、`build/`、`.omx/`、`.claude/` 等本地产物不会提交。

详细步骤见：

- [Gitee 提交说明](docs/gitee.md)

## 项目结构

```text
Package.swift
Sources/
  ThreeColorLight/                  macOS AppKit 应用
  ThreeColorLightCore/              状态模型、日志信号、分类器
  ThreeColorLightCoreRegressionTests/ 核心分类回归测试入口
Tests/
  PackageSmokeTests/                SwiftPM smoke test
scripts/
  build-app.sh                      生成 macOS .app 包
docs/
  hooks.md                          hook 配置说明
  gitee.md                          Gitee 提交说明
```

## 设计边界

Codex 和 Claude Code 目前没有统一的桌面状态 API，所以三色灯采用本地信号组合判断：

- 优先使用 hook 写入的明确状态。
- 其次读取工作区结构化状态。
- 再扫描近期日志。
- 最后用进程活动做兜底。

如果后续 Codex 或 Claude Code 的状态文件、进程名称或 hook 机制变化，需要对应调整：

- `HookStatusReader`
- `WorkspaceStateMonitor`
- `AgentProcessMonitor`
- `LogMonitor`