lijianfei.com

在 2026 年的今天，每一个重度依赖 AI 编程的开发者，日常工作流几乎都演变成了多智能体并行作业（Multi-Agent Parallelism）：

• 终端里跑着 Claude Code 进行大规模架构重构与跨模块重写；
• 窗口里开着 Cursor 进行微观代码补全与内联行级 Diff；
• 后台挂着 OpenAI Codex 或 Google Antigravity 自治执行复杂的深层测试与长任务调研。

然而，这套梦幻流水线背后藏着一个极其抓狂的心智黑洞：各大厂商无一例外都采用基于“滑动窗口（Rolling Session Windows）”的动态限额机制（例如 Claude 的 5 小时会话窗口与每周额度、Cursor 的 Pro 用量上限、Antigravity 的云端配额）。

你在键盘上思路泉涌，AI 却突然在代码写到一半时暴毙抛出 429 Rate Limit Exceeded；或者后台并行挂了三个终端任务，你根本不知道哪个正在疯狂思考、哪个任务已经完成、哪个任务正因为一条等待确认的权限请求卡在屏幕角落……

近期在 GitHub 开源的 vinzdg/codenotch，以近乎偏执的 Apple 原生工业美学与黑客级逆向工程，给出了近乎完美的终极答案：它把一个极简暗黑的微型“侧边刘海（Side Notch）”直接焊在 macOS 屏幕边缘，零登录、零配置，实时把 Claude Code、Cursor、Codex、Antigravity 的真实燃烧额度与存活状态投射在视线边缘。

🧭 一眼看穿全景：Codenotch 解决了什么？

在传统工作流中，想要查看各个工具的额度，你必须在不同软件里来回翻找；而排查后台 Agent 是否卡死，更需要不断切换终端窗口。

flowchart TD
    subgraph PainPoints["传统多 Agent 协同的痛苦现状"]
        P1["Claude Code: 必须手动输入 /usage 才能看剩余时间与百分比"]
        P2["Cursor: 需要进入 Settings -> Account 才能查看当前周期额度"]
        P3["后台 Agent 盲盒: 不知道后台终端是卡死、思考中、还是在等待输入"]
        P4["多账号切换混乱: 个人账号与公司账号配置目录割裂，无法全局兼顾"]
    end

    PainPoints ==>|一站式降维解决| CodenotchCore

    subgraph CodenotchCore["Codenotch 屏幕边缘实时中枢"]
        C1["<b>屏幕边缘极简暗黑刘海</b><br/>纯黑微型胶囊，1:1 贴合硬件 Bezel，支持四向边缘停靠"]
        C2["<b>零登录凭据借用 (Zero-Login)</b><br/>不要求输入账号密码，直接借用本地 Keychain 与 SQLite 凭据"]
        C3["<b>保真度状态机 (Fidelity & Status)</b><br/>官方接口直连，拒绝瞎编数字，状态透明降级"]
        C4["<b>实时会话心跳感知 (Is it working?)</b><br/>推理中旋转光弧，等待确认跳动琥珀环，完成即静默"]
    end

一、 工业级原生美学：把“刘海”焊在屏幕边缘

Codenotch 不是那种套壳浏览器（Electron）动辄吃掉几百兆内存的臃肿工具，而是一个采用 Swift 6 + AppKit / SwiftUI 构建的原生轻量级后台常驻守护程序（LSUIElement，无独立 Dock 栏占位，内存底噪仅数兆）。

它的 UI 哲学可以用四个字概括：克制、融合。

1. 硬件级反向圆角（Inverse Rounded Corners）

苹果硬件设计中最精妙之处在于曲线的连续性。Codenotch 借鉴了 MacBook 顶部刘海的几何数学曲线，在微型胶囊与屏幕物理边框衔接处绘制了反向圆角：

• 它支持停靠在屏幕的左、右、上、下四个边缘；
• 在顶部放置时，它能与带刘海的 MacBook 物理摄像头刘海做到像素级轮廓吻合，完全融入硬件黑边，毫无“悬浮窗”的割裂突兀感；
• 底部停靠时能智能识别 Dock 栏高度与隐藏状态，自动紧贴可用工作区。

2. 状态驱动的进度光环（Provider Ring）

在收起（Collapsed）的静默状态下，刘海仅仅是一条极细的黑色条块，垂直（或水平）堆叠各个已启用的模型光环：

┌──────────┐
│   ◯ ✳    │   ← 44pt 环形槽，深灰底色 (#2A2A2A)，中心浮现品牌矢量 Icon
│   73%     │   ← 消耗百分比（Used 燃烧值），随额度动态变色
│           │
│   ◯ ⌾    │
│   21%     │
│           │
│   ◯ ✦    │
│   52%     │
└──────────┘

光环颜色遵循直觉级的交通信号逻辑：

• 0% – 49%（安全区）：鲜艳翠绿 #28E07B，余量充足，随意挥霍；
• 50% – 79%（警告区）：警示亮黄 #F5E400，会话消耗过半；
• 80% – 99%（临界区）：熔断鲜橙 #FF4500，即将触碰配额天花板；
• 100%（熔断冷却）：整环高亮锁定，中心 Logo 渐隐变暗，明确提示等待 Reset。

3. “它还在干活吗？”—— 动态会话活跃度指示

在多 Agent 场景中，最让人焦虑的莫过于不知道终端里的 Agent 到底处于什么状态。Codenotch 为每个环注入了生命体征：

• 正在推理/执行（Busy）：环内部会有一圈纤细的动态旋转光弧（Spinning Arc），表明底层进程正在思考或运行命令；
• 阻塞等待输入（Waiting on you）：当 Agent 弹出了工具授权、输入追问或单步确认时，整个圆环会切换为跳动的呼吸琥珀环（Pulsing Amber Ring），瞬间抓取你的余光注意力；
• 任务结束（Done）：自动恢复为静态百分比环。

4. 悬停抽屉卡片（Hover Tooltip）与多 Profile 矩阵

当鼠标划过某个圆环时，系统会在 180ms 内向屏幕内侧展开一张带有精准三角尾巴的暗黑卡片：

• 显示当前滚动会话窗口（如 Current session - 73% Used, Resets in 51 min）；
• 显示长周期全局窗口（如 All models - 7% Used, Resets Thu 12:00 AM）；
• 天然支持多 Profile 隔离：如果你在公司用 CLAUDE_CONFIG_DIR=~/.claude-work 隔离企业账号，Codenotch 在启动时会自动扫描所有 ~/.claude-* 配置，并在界面上并排渲染 Claude 与 Claude (work) 两个独立圆环，各自拥有独立的配额与会话监听！

二、 黑客级硬核底层：零登录的“凭据借用”黑科技

市面上绝大多数聚合看板最让人头疼的是：安装完后，你得把每个厂商的账号密码、Cookie 或私有 Token 手工拷贝一遍。

Codenotch 坚决不设任何登录界面，它的一切数据，全靠向本地已安装工具“合法借用”！

sequenceDiagram
    autonumber
    actor Dev as 开发者 / Mac 环境
    participant App as Codenotch 守护进程
    participant Keychain as macOS 登录钥匙串
    participant SQLite as Cursor 状态库 (WAL)
    participant FS as 终端会话文件 (DispatchSource)
    participant Vendor as 各大厂商官方 Usage 接口

    Note over App: 启动自检，探测本机已安装工具
    rect rgb(240, 248, 255)
    Note over App,Keychain: 【Claude Code 凭据获取】
    App->>Keychain: 检索 service: com.anthropic.claudecode 最优凭据
    Keychain-->>App: 返回最新 OAuth Access Token
    App->>Vendor: 请求 GET api.anthropic.com/api/oauth/usage
    Vendor-->>App: 拿到与官方 /usage 完全同源的百分比与重置时间
    end

    rect rgb(255, 250, 240)
    Note over App,SQLite: 【Cursor 凭据获取】
    App->>SQLite: 只读打开 state.vscdb (正确解析 WAL 模式)
    SQLite-->>App: 提取 accessToken + accountId
    App->>Vendor: 组装 Cookie 请求 cursor.com/api/usage-summary
    Vendor-->>App: 拿到 Pro/Fast Requests 官方额度
    end

    rect rgb(240, 255, 240)
    Note over App,FS: 【活跃状态感知】
    App->>FS: open(sessions_dir, O_EVTONLY) 注册内核文件变更源
    FS-->>App: 触发防抖回调 -> 捕获模型运行/等待状态
    end

为了做到这一点，作者在各个厂商的本地实现中趟过了无数深坑。

1. Claude Code：绕过 Keychain 历史污染与 429 惩罚陷阱

Codenotch 对 Claude Code 的适配展现了教科书级的系统级工程水平：

钥匙串“旋转冗余”陷阱

Claude Code 在做 OAuth Token 刷新时，并不是原地覆写原有的 Keychain 条目，而是在同一个 Service 名称下不断追加新的条目。
如果直接用常规的 SecItemCopyMatching（配合 kSecMatchLimitOne），系统会无序返回一条历史记录，往往是几个月前过期的废弃 Token，导致界面永久卡死在 Waiting for the first reading...。

Codenotch 在 KeychainItem.swift 中实现了一套极其精巧的筛选逻辑：

1. 先以只读属性方式枚举该 Service 下所有条目的修改时间戳（Modification Date）与持久引用（Persistent Ref）；
2. 比较时间戳，精准锁定最新的有效记录；
3. 关键优势：读取元数据属性不需要触发系统的密码弹窗！只有对最终胜出的一条有效记录读取 Payload 时，才消耗一次授权。搭配稳定的 Developer ID 签名，用户只需在初次安装时点击一次“始终允许”，后续无论重启多少次都不会再弹窗骚扰。

429 Rate Limit 指数退避防雪崩

Claude 的 Usage 接口如果被高频轮询，会返回 HTTP 429 Too Many Requests，并且携带一个极不友好的响应头 Retry-After: 0。
如果客户端轻信这个 0，继续发起请求，就会陷入死循环甚至被封禁。Codenotch 在代码中构建了专属退避机制：

• 遭遇 429 时，强制设立 60 秒 的惩罚底线；
• 连续 429 则按指数级翻倍（120s -> 240s...），最高封顶 15 分钟；
• 这一惩罚截止时间（Deadline）会被本地持久化，哪怕你强行重启 Codenotch，未到冷却期也绝不浪费请求配额。当后台没有任何活动会话时，轮询周期自动降频至 5 分钟一次。

2. Cursor：正确驾驭 SQLite WAL 模式

Cursor 在改版后，网页端登录与本地编辑器会话存在差异，直接在 WebView 里登录往往会关联到一个空白账号。最真实的数据源，正是 Cursor 编辑器自己正在使用的本地全局状态库：
~/Library/Application Support/Cursor/User/globalStorage/state.vscdb

必须避开的 immutable=1 天坑

很多 macOS 工具在读取其他软件的 SQLite 数据库时，为了防止锁库，喜欢带上 immutable=1 只读参数。
但 Cursor 的数据库工作在 WAL（Write-Ahead Log，预写式日志）模式。如果在打开连接时声明了 immutable，SQLite 就会彻底忽略磁盘上的 -wal 文件，只读取主库文件上一次 Checkpoint 时的数据——这意味着你读取到的永远是早已过期的陈旧 Token！

Codenotch 采用纯只读模式打开，不加 immutable，安全读取 WAL 缓冲：

// CursorCredentials.swift 核心片段
guard let token = value(forKey: "cursorAuth/accessToken", in: db),
      let account = value(forKey: "cursorAuth/stripeMembershipAuthId", in: db)
else { throw UsageProviderError.needsAuth }

// 组装官方 Session Cookie
var sessionCookie: String { 
    "WorkosCursorSessionToken=\(account)::\(token)" 
}

拿着这个活体 Token 去敲 https://cursor.com/api/usage-summary，返回的数据与 Cursor 设置面板中显示的 Pro 额度、快速请求用量 100% 吻合！

3. OpenAI Codex：Live App Server 与 Rollout 日志回退

针对 OpenAI Codex，Codenotch 实现了双层容灾策略：

1. 活跃状态：如果 Codex 正在运行，直接通过本地 IPC 进程管道询问 Codex 本地 App Server 的实时 Rate Limit 接口；
2. 离线状态：若 Codex 未启动，Codenotch 不会发起远程网络嗅探，而是查阅 Codex 的线程索引数据库，找到最后一次运行的 Rollout 日志文件，只读取其尾部 256KB 内容（Tail Bytes），解析上次会话关闭前记录的 Rate-limit 快照，展示为 .stale 历史值。

4. Google Antigravity：Keychain Base64 解码与 Transcript 活跃监听

在适配 Google 的 Antigravity（也就是我们当前所处的 Agent 环境） 时，作者同样展现了极强的逆向功底：

• 凭据获取：Antigravity 借助 Go 语言的 keyring 模块将 OAuth Token 写入系统钥匙串，服务名为 gemini，账户名为 antigravity。Go 语言存储时对内容添加了特定前缀 go-keyring-base64:。Codenotch 自动剥离前缀并完成 Base64 反序列化，直连 Google Cloud Code 内部网关（loadCodeAssist 与 retrieveUserQuotaSummary）；
• 会话活跃度感知（Transcript Heartbeat）：由于 Google 的生成接口采用流式传输，会话状态不会即时写回远程，Codenotch 另辟蹊径，在本地实时监听：
  ~/.gemini/antigravity/brain/**/.system_generated/logs/transcript.jsonl
  只要发现该文件最新记录包含 source == "MODEL" 且时间戳在 45 秒以内，圆环立即激活旋转光弧，真实展现 Antigravity 正在推理的存活状态！

5. 零开销的内核级会话文件监听（DispatchSource）

为了做到在 Agent 结束工作的第一时间更新 UI，同时不消耗 CPU 资源，Codenotch 彻底摒弃了每秒扫盘的低级做法。

它直接使用 BSD 系统的底层内核系统调用 open(path, O_EVTONLY)，并构建 DispatchSourceFileSystemObject：

let source = DispatchSource.makeFileSystemObjectSource(
    fileDescriptor: descriptor,
    eventMask: [.write, .extend, .attrib, .delete, .rename, .revoke],
    queue: .main
)
source.setEventHandler { [weak self] in
    MainActor.assumeIsolated { self?.scheduleRescan() }
}

当 Claude Code 在终端中输出一个字符、变更一次状态时，操作系统内核会在几微秒内通过 VFS 事件直接唤醒 Codenotch 的防抖事件处理器，日常待机 CPU 占用率绝对为 0.0%。

三、 保真度哲学：宁可留白，绝不伪造

在开源工具界，很多软件为了让界面“好看”，在没有拿到准确数据时喜欢硬编一个“0%”或者虚拟一个百分比。

Codenotch 在架构层设计了严格的 Fidelity（保真度）与 Status（状态）模型：

enum Fidelity {
    case official  // 厂商官方直出数据，权威准确
    case derived   // 本地会话计算/推断数据，Tooltip 中以 '~' 标明
    case manual    // 用户自定义保底数据
}

enum Status {
    case ok
    case stale(since: Date)  // 凭据有效但离线，暗色标明历史数据
    case needsAuth           // 本地工具未登录，提示启动应用
    case unsupported         // 账号类型不支持计量
    case error(String)       // 异常降级
}

以 Antigravity 的个人版账号为例：由于 Google 官方并没有对外公开基于百分比的滑动窗口配额，Codenotch 断然拒绝伪造一个虚假的百分比圆环。相反，它诚实地展示 ~31 requests today（今日调用请求数），并将状态清晰标注。

这种工程上的诚实，让每一次亮起的警报都具备 100% 的参考价值。

四、 极速安装与实战体验

1. 本地源码编译运行（极简 3 步）

Codenotch 采用纯 Swift 编写，使用 XcodeGen 管理工程，无需安装任何复杂的依赖包：

# 1. 安装 XcodeGen（如果未安装）
brew install xcodegen

# 2. 克隆项目
git clone https://github.com/vinzdg/codenotch.git
cd codenotch

# 3. 自动生成 Xcode 工程、编译并启动调试运行
make run

编译完成后，一个精巧的暗黑侧边刘海就会自动贴合在你的 Mac 屏幕右侧（或顶部），自动嗅探出你已登录的 AI 编程工具。

2. 体验 Demo 演示模式

如果你想在不依赖本地真实凭据的情况下，快速查看全套 UI 的满载表现，只需带上环境变量启动：

CODENOTCH_DEMO=1 make run

系统会立即加载内置的预设数据，呈现出 73%（Claude 橙）、21%（Cursor 绿）、52%（Codex 黄）等多种活跃与报警状态。

3. 查看系统级统一日志

由于应用属于无主窗口的 Agent 常驻形态，所有的凭据读取、网络诊断均输出至 macOS 统一日志系统（Unified Logging）：

/usr/bin/log stream --predicate 'subsystem == "com.vinz.codenotch"' --level debug

五、 总结与思考：Agent 时代的“仪表盘革命”

如果说两年前的大模型开发还是“问答式的单次对话”，那么在 2026 年，以 Claude Code、Cursor、Antigravity、Codex 为代表的 Autonomous Coding Agent（自主编程智能体） 已经正式成为主力生产力。

当 Agent 在后台替我们重构工程、跑测试、修 Bug 时，算力配额与会话窗口已经变成了开发者在这个时代的“剩余电量与汽油”。

Codenotch 没有做大而全的复杂功能，而是将精力倾注在两件事情上：

1. 把系统级交互做到极致：硬件刘海融合、反向圆角、旋转光弧、零 CPU 唤醒；
2. 把底层工程做到底：钥匙串去重、WAL 模式穿透、Tail 缓存读取、指数退避防护。

它不仅是一款惊艳的 macOS 效率神器，更为未来“人机协同开发时代”的系统级仪表盘设计，树立了一座教科书级的标杆。

🔗 关联资源与开源地址

• 官方 GitHub 仓库：https://github.com/vinzdg/codenotch
• 软件架构设计规范：docs/specs/2026-08-28-usage-notch-design.md
• 许可证：MIT License