# CodexNotch 产品文档

> CodexNotch 源代码采用 [GNU GPL v3.0](../LICENSE) 开源；CodexNotch 名称与官方图标仍归 49Labs 管理。详见 [品牌政策](../TRADEMARKS.md)。

CodexNotch 是一款位于 MacBook 刘海区域的轻量 Codex 状态工具。它让用户在浏览网页、写文档或切换应用时，仍能看到任务是否运行、是否等待确认以及何时完成。

## 1. 产品定位

- **目标用户**：在 macOS 上频繁使用 Codex、多任务运行且不希望持续停留在 Codex 窗口的用户。
- **核心价值**：减少来回切换窗口确认进度的成本。
- **设计原则**：默认克制、状态优先、点击可返回、数据留在本机。
- **界面语言**：默认跟随 macOS，也可在设置中选择中文或 English。

## 2. 系统要求

- macOS 14 或更高版本。
- 已安装并登录 Codex 桌面应用。
- MacBook 刘海屏获得完整体验；普通显示器显示较薄的顶部胶囊。

## 3. 安装

可以从 [GitHub Releases](https://github.com/VibeDough/CodexNotch/releases/latest) 下载 Apple 芯片版 DMG，将应用拖入“应用程序”文件夹；也可以从源码构建：

```sh
git clone https://github.com/VibeDough/CodexNotch.git
cd CodexNotch
sh build-app.sh
open "dist/CodexNotch.app"
```

当前预览版尚未经过 Apple 公证。首次打开如果 macOS 阻止应用，请右键应用选择“打开”，或在“系统设置 → 隐私与安全性”中确认打开。正式版本将改用 Developer ID 签名与公证。

## 4. 状态说明

| 状态 | 顶部表现 | 操作 |
| --- | --- | --- |
| 空闲 | 剩余用量、空闲与任务数 0 | 悬停查看今日 Token、重置时间与版本 |
| 运行 | 绿色状态点、任务标题、耗时、模型 | 点击任务返回对应 Codex 对话 |
| 分析 | 绿色状态点与“分析”状态 | 多任务时点击 `+N` 展开全部 |
| 等待确认 | 优先展示确认卡片 | 点击返回 Codex 完成确认 |
| 已完成 | 绿色完成按钮或待查看数量徽标 | 点击打开对应对话并清除提醒 |
| 正在重连 | 红色连接图标和状态 | 等待 Codex 产生新的桌面活动后恢复 |
| 已断开 | 红色断开图标 | 点击可打开 Codex |

## 5. 主要功能

### 5.1 任务状态

- 自动读取本机 Codex 会话记录。
- 展示运行、分析、等待确认、完成和异常。
- 展示任务名称、最近结果摘要、模型、推理强度、单任务 Token 和运行时间；长时间无新事件时给出克制的健康提示。

### 5.2 多任务

- 默认只显示优先级最高的一项任务。
- 多任务时显示 `+N`。
- 点击当前任务展开全部，再次点击收回。
- 已完成待查看任务显示在运行任务下方，不遮挡仍在执行的任务。

### 5.3 用量

- 顶部显示当前剩余百分比。
- 低于 50% 变为橙色，低于 20% 变为红色。
- 空闲悬停显示今日 Token 增量、主要模型用量、重置倒计时、方案类型和 Codex 版本。

### 5.4 拖入分析

1. 将文件、网址或文字拖到刘海区域。
2. 检查待处理名称。
3. 点击“在 Codex 新建对话”。
4. 应用通过 `codex://threads/new` 打开带分析指令的新任务。

拖入本地文件时传递的是文件路径和分析提示，不会由 CodexNotch 上传文件。

### 5.5 屏幕与共存

- 默认优先显示在内建刘海屏。
- 可在设置中切换目标屏幕。
- 无刘海屏采用薄顶部胶囊。
- 检测到 BoringNotch 或 NotchNook 时询问是否暂时隐藏 CodexNotch，不会擅自关闭其他应用。

## 6. 隐私

应用仅在本机读取：

- `~/.codex/sessions/` 下的会话事件。
- `~/Library/Logs/com.openai.codex/` 下的桌面状态日志。
- Codex 应用进程、版本与本机网络可用状态。

应用不包含服务器、不上传对话内容，也不收集遥测数据。

## 7. 当前限制

- Codex 会话和未读同步依赖当前版本的本地日志格式；Codex 更新后可能需要适配。
- 当前为 arm64 本机构建和临时签名，不是正式分发包。
- 拖入文件通过本地路径传递，Codex 是否能读取取决于其权限与路径可用性。
- 今日 Token 是从本机会话事件计算的增量，不代表账单金额。

## 8. 故障排查

### 不显示任务

- 确认 Codex 正在运行。
- 确认当前任务产生了新的会话事件。
- 重启 CodexNotch 后再运行一个简短任务。

### 完成提醒没有消失

- 点击绿色确认按钮返回对应任务。
- 在 Codex 中打开相应对话后等待一次状态刷新。

### 位置不正确

- 悬停后打开设置。
- 在“屏幕”中切换到内建刘海屏或目标外接显示器。

## 9. 发布前路线

1. Developer ID 签名与公证。
2. 针对 Codex 日志格式变化增加版本兼容层。
3. 增加安装后引导与诊断页面。
4. 补充更多 MacBook 和外接显示器实机验证。
5. 发布公开演示视频与版本说明。