easy-codex 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UnionSchool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# easy-codex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+显示当前本机 Codex 登录账号的剩余额度百分比和重置时间。第三方辅助工具，与 OpenAI 无官方隶属关系。
+
+## 安装与使用
+
+安装一次：
+
+```sh
+npm i -g easy-codex
+```
+
+查看额度：
+
+```sh
+easy-codex
+```
+
+显示透明圆环（macOS）：
+
+```sh
+easy-codex overlay
+```
+
+需要 Node.js 22+ 和已登录的官方 Codex CLI。安装包自带浮窗，使用者无需下载源码、安装依赖或编译。
+
+输出每个额度桶的主、次窗口。窗口时长采用服务端数据，重置时间使用本机时区。剩余比例为 `100 - usedPercent`，限制在 0–100%；未返回的字段显示“未知”。额度属于账号，不是当前会话的 Token 数，也不是 API 账单余额。即使有剩余百分比，也不代表其他服务端限制已解除。
+
+## 数据与限制
+
+通过官方 [App Server 协议](https://developers.openai.com/codex/app-server) 启动 `codex app-server --listen stdio://`，完成握手后调用 `account/rateLimits/read`，随后关闭本工具启动的进程。优先读取多额度桶，兼容单额度桶。
+
+本工具不读取或保存凭据，不创建聊天、不发送模型请求、不购买额度、不消耗额度重置券。认证及必要的登录状态刷新由官方 CLI 处理，CLI 本身可能写入其运行日志。为避免敏感信息外泄，本工具不直接输出子进程日志及原始服务端错误。
+
+查询总超时为 20 秒；失败返回非零退出码。找不到 CLI 时检查安装及 PATH；读取失败时检查 `codex login`、网络和 CLI 版本。仅安装桌面应用但没有可执行的 `codex` CLI 时无法使用。不同 CLI 版本的协议兼容性需实测。
+
+## 开发
+
+```sh
+node bin/easy-codex.js
+npm test
+```
+
+使用 Node.js 内置测试工具，覆盖格式化和模拟 App Server 通信，不依赖真实账号或网络。真实账号查询需单独执行上述命令。浮窗使用同一数据源；暂不提供多账号管理或自动安装官方 CLI。
+
+## macOS 额度浮窗
+
+macOS 14+ 安装后运行：
+
+```sh
+easy-codex overlay
+```
+
+独立 AppKit 浮窗在 Codex 位于前台时显示，切到其他应用、最小化或关闭 Codex 窗口后隐藏。默认位于 Codex 窗口右下角上方；拖动可校准位置，偏移量保存在本机。它按窗口边界跟随，不自动识别头像；侧栏布局变化后可再次拖动。首版跟随最前面的一个 Codex 普通窗口。
+
+- 圆环长度表示剩余百分比：大于 50% 绿色，20%–50% 橙色，低于 20% 红色。
+- 浮窗为小尺寸（16×16），背景透明，无底板和阴影。圆环只显示百分比，无数据时显示 `—`，不显示窗口时长或状态文字；时长与状态见悬停提示和菜单。
+- 未知或过期数据为灰色；失败后的过期说明见悬停提示。已到重置时间时也先标为过期，等待重新查询，不擅自恢复满额。
+- 浮窗可见时每 60 秒刷新，查询不会重叠；回到前台且距离上次查询超过 60 秒会刷新。
+- 默认优先 codex 额度桶，显示其中剩余比例最低的窗口；右键可切换其他窗口，不把各窗口相加。
+- 悬停查看额度详情与更新时间；双击刷新；右键或菜单栏 **EC** 可立即刷新、恢复默认位置、退出。
+- 这是 **CLI 登录账号** 的额度，不自动确认桌面端正在使用同一账号。切换账号后请核对并手动刷新。
+
+浮窗不修改官方应用，不读取界面文字、不截图、不请求辅助功能权限，不自动开机启动。位置与选择保存在 `com.unionschool.easy-codex.overlay` 的用户偏好中，不保存额度历史或凭据。系统窗口接口只用于查询窗口边界及前台状态。
+
+本地构建需要 Xcode Command Line Tools 与 Swift 6；构建包含 Apple Silicon 和 Intel 的通用应用：
+
+```sh
+npm run build:overlay
+node bin/easy-codex.js overlay
+```
+
+构建输出为 `native/build/EasyCodexOverlay.app`，使用本地 ad-hoc 签名，尚未做开发者签名或公证。全局安装的是快照，源码修改后需重建、打包并重新安装；升级前通过 EC 菜单退出旧浮窗。浮窗仅支持 macOS 14+；未做开发者签名或公证，系统策略可能阻止启动。
+
+## 发布
+
+GitHub Actions 在 `v*` 标签上测试、构建通用 macOS 浮窗，并发布 npm 包。标签必须与 package.json 版本一致；预发布版本使用 `next`，正式版本使用 `latest`。发布任务使用 GitHub `npm` Environment，部署记录链接到 npm 包。
+
+首次发布需配置仓库 Secret `NPM_TOKEN`（具有该包发布权限、允许自动化发布的 npm Token）。不要把凭据写入源码。修改版本后创建对应标签触发发布；失败可在 Actions 中重新运行任务。

package/bin/easy-codex.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+import { readUsage, formatUsage } from '../src/usage.js';
+
+const args = process.argv.slice(2);
+if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+  console.log('用法：easy-codex [usage|overlay]\n显示已登录 Codex 账号的剩余百分比和重置时间。需要官方 Codex CLI。');
+} else if (args.length === 1 && ['--version', '-v'].includes(args[0])) {
+  console.log(version);
+} else if (args.length === 1 && args[0] === 'overlay') {
+  try { const { launchOverlay } = await import('../src/overlay.js'); await launchOverlay(); }
+  catch (error) { console.error(`easy-codex: ${error.message}`); process.exitCode = 1; }
+} else if (args.length === 0 || (args.length === 1 && args[0] === 'usage')) {
+  try { console.log(formatUsage(await readUsage())); }
+  catch (error) { console.error(`easy-codex: ${error.message}`); process.exitCode = 1; }
+} else {
+  console.error('未知参数。用法：easy-codex [usage|overlay]，或 easy-codex --help');
+  process.exitCode = 1;
+}

package/native/Overlay.swift

@@ -0,0 +1,338 @@
+import AppKit
+import CoreGraphics
+
+struct UsageWindow: Decodable {
+    let id: String
+    let label: String
+    let name: String
+    let remaining: Double?
+    let resetsAt: Double?
+}
+struct Snapshot: Decodable {
+    var windows: [UsageWindow] = []
+    var detail: String = ""
+    var fetchedAt: Double = 0
+    var restricted: Bool = false
+    var error: String?
+
+    enum CodingKeys: CodingKey { case windows, detail, fetchedAt, restricted, error }
+    init(from decoder: any Decoder) throws {
+        let c = try decoder.container(keyedBy: CodingKeys.self)
+        windows = try c.decodeIfPresent([UsageWindow].self, forKey: .windows) ?? []
+        detail = try c.decodeIfPresent(String.self, forKey: .detail) ?? ""
+        fetchedAt = try c.decodeIfPresent(Double.self, forKey: .fetchedAt) ?? 0
+        restricted = try c.decodeIfPresent(Bool.self, forKey: .restricted) ?? false
+        error = try c.decodeIfPresent(String.self, forKey: .error)
+    }
+}
+
+enum RingState: Equatable {
+    case green, orange, red, unknown
+    static func resolve(_ remaining: Double?, stale: Bool) -> RingState {
+        guard !stale, let remaining, remaining.isFinite else { return .unknown }
+        return remaining > 50 ? .green : remaining >= 20 ? .orange : .red
+    }
+    var color: NSColor {
+        switch self {
+        case .green: .systemGreen
+        case .orange: .systemOrange
+        case .red: .systemRed
+        case .unknown: .secondaryLabelColor
+        }
+    }
+}
+
+func appKitRect(_ rect: CGRect, primaryHeight: CGFloat) -> CGRect {
+    CGRect(x: rect.minX, y: primaryHeight - rect.maxY, width: rect.width, height: rect.height)
+}
+func ringOrigin(in rect: CGRect, inset: CGPoint) -> CGPoint {
+    CGPoint(x: max(rect.minX, min(rect.maxX - 16, rect.maxX - 16 - inset.x)),
+            y: max(rect.minY, min(rect.maxY - 16, rect.minY + inset.y)))
+}
+
+@MainActor
+func targetWindow() -> CGRect? {
+    guard let app = NSWorkspace.shared.frontmostApplication,
+          app.bundleIdentifier == "com.openai.codex" else { return nil }
+    let windows = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] ?? []
+    for window in windows {
+        guard (window[kCGWindowOwnerPID as String] as? Int) == Int(app.processIdentifier),
+              (window[kCGWindowLayer as String] as? Int) == 0,
+              let bounds = window[kCGWindowBounds as String] as? [String: Any],
+              let rect = CGRect(dictionaryRepresentation: bounds as CFDictionary),
+              rect.width >= 300, rect.height >= 200 else { continue }
+        // CG 坐标原点在主屏左上；AppKit 使用主屏左下，多屏位置也按同一基准转换。
+        return appKitRect(rect, primaryHeight: NSScreen.screens.first?.frame.height ?? 0)
+    }
+    return nil
+}
+
+@MainActor
+final class RingView: NSView {
+    var remaining: Double?
+    var stale = true
+    var caption = "等待额度"
+    var makeMenu: (() -> NSMenu)?
+    var moved: ((CGPoint) -> Void)?
+    var refresh: (() -> Void)?
+    var dragging = false
+    private var dragStart = CGPoint.zero
+    private var originStart = CGPoint.zero
+
+    override func draw(_ dirtyRect: NSRect) {
+        let center = CGPoint(x: bounds.midX, y: bounds.midY)
+        let track = NSBezierPath(ovalIn: CGRect(x: center.x - 7, y: center.y - 7, width: 14, height: 14))
+        track.lineWidth = 1
+        NSColor.labelColor.withAlphaComponent(0.12).setStroke()
+        track.stroke()
+        let state = RingState.resolve(remaining, stale: stale)
+        if let remaining, remaining > 0, !stale {
+            let arc = NSBezierPath()
+            arc.lineWidth = 1
+            arc.lineCapStyle = .round
+            arc.appendArc(withCenter: center, radius: 7, startAngle: 90,
+                          endAngle: 90 - CGFloat(min(100, max(0, remaining))) * 3.6, clockwise: true)
+            state.color.setStroke()
+            arc.stroke()
+        }
+        let text = remaining.map { "\(Int($0.rounded()))%" } ?? "—"
+        drawText(text, y: 5, font: .monospacedDigitSystemFont(ofSize: 4.5, weight: .semibold), color: state.color)
+    }
+    private func drawText(_ text: String, y: CGFloat, font: NSFont, color: NSColor) {
+        let style = NSMutableParagraphStyle()
+        style.alignment = .center
+        style.lineBreakMode = .byTruncatingTail
+        (text as NSString).draw(in: CGRect(x: 1, y: y, width: bounds.width - 2, height: 6),
+                               withAttributes: [.font: font, .foregroundColor: color, .paragraphStyle: style])
+    }
+    override func mouseDown(with event: NSEvent) {
+        if event.clickCount == 2 { refresh?(); return }
+        dragging = true
+        dragStart = NSEvent.mouseLocation
+        originStart = window?.frame.origin ?? .zero
+    }
+    override func mouseDragged(with event: NSEvent) {
+        guard dragging else { return }
+        let point = NSEvent.mouseLocation
+        window?.setFrameOrigin(CGPoint(x: originStart.x + point.x - dragStart.x, y: originStart.y + point.y - dragStart.y))
+    }
+    override func mouseUp(with event: NSEvent) {
+        if dragging, let origin = window?.frame.origin { moved?(origin) }
+        dragging = false
+    }
+    override func rightMouseDown(with event: NSEvent) {
+        if let menu = makeMenu?() { NSMenu.popUpContextMenu(menu, with: event, for: self) }
+    }
+}
+
+@MainActor
+final class Overlay: NSObject, NSApplicationDelegate, NSMenuDelegate {
+    let panel = NSPanel(contentRect: CGRect(x: 0, y: 0, width: 16, height: 16),
+                        styleMask: [.borderless, .nonactivatingPanel], backing: .buffered, defer: false)
+    let ring = RingView(frame: CGRect(x: 0, y: 0, width: 16, height: 16))
+    var status: NSStatusItem?
+    var timer: Timer?
+    var query: Process?
+    var snapshot: Snapshot?
+    var error: String?
+    var selectedID: String?
+    var lastAttempt = Date.distantPast
+    var lastRect: CGRect?
+    var inset = CGPoint(x: 10, y: 74)
+    var node = ""
+    var script = ""
+    var searchPath = ""
+    var codexHome = ""
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        let args = CommandLine.arguments
+        guard args.count >= 4 else { NSApp.terminate(nil); return }
+        node = args[1]; script = args[2]; searchPath = args[3]
+        codexHome = args.count > 4 ? args[4] : ""
+        let prefs = UserDefaults.standard
+        if prefs.object(forKey: "rightInset") != nil {
+            inset = CGPoint(x: prefs.double(forKey: "rightInset"), y: prefs.double(forKey: "bottomInset"))
+        }
+        selectedID = prefs.string(forKey: "selectedWindow")
+        panel.isOpaque = false
+        panel.backgroundColor = .clear
+        panel.hasShadow = false
+        panel.level = .floating
+        panel.hidesOnDeactivate = false
+        panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
+        panel.contentView = ring
+        ring.makeMenu = { [weak self] in self?.makeMenu() ?? NSMenu() }
+        ring.refresh = { [weak self] in self?.refresh() }
+        ring.moved = { [weak self] point in
+            guard let self, let rect = self.lastRect else { return }
+            self.inset = CGPoint(x: rect.maxX - point.x - 16, y: point.y - rect.minY)
+            prefs.set(self.inset.x, forKey: "rightInset")
+            prefs.set(self.inset.y, forKey: "bottomInset")
+        }
+        ring.setAccessibilityElement(true)
+        ring.setAccessibilityRole(.button)
+        status = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
+        status?.button?.title = "EC"
+        status?.button?.toolTip = "Easy Codex 额度浮窗"
+        let menu = NSMenu(); menu.delegate = self; status?.menu = menu
+        timer = Timer.scheduledTimer(timeInterval: 0.4, target: self, selector: #selector(tick), userInfo: nil, repeats: true)
+        NSWorkspace.shared.notificationCenter.addObserver(self, selector: #selector(hide), name: NSWorkspace.didDeactivateApplicationNotification, object: nil)
+        tick()
+    }
+    @objc func hide() { panel.orderOut(nil) }
+    @objc func tick() {
+        guard let rect = targetWindow() else { panel.orderOut(nil); lastRect = nil; return }
+        lastRect = rect
+        if !ring.dragging { panel.setFrameOrigin(ringOrigin(in: rect, inset: inset)) }
+        if !panel.isVisible { panel.orderFrontRegardless() }
+        if Date().timeIntervalSince(lastAttempt) >= 60 { refresh() }
+        updateRing()
+    }
+    var chosen: UsageWindow? {
+        guard let windows = snapshot?.windows else { return nil }
+        if let selectedID { return windows.first { $0.id == selectedID } }
+        // 默认优先 codex 桶，取其中最紧张的窗口，不把不同窗口相加。
+        let codex = windows.filter { $0.id.hasPrefix("codex:") }
+        return (codex.isEmpty ? windows : codex).filter { $0.remaining != nil }.min { $0.remaining! < $1.remaining! }
+            ?? windows.first
+    }
+    func updateRing() {
+        let stale = error != nil || snapshot == nil || Date().timeIntervalSince1970 - (snapshot?.fetchedAt ?? 0) > 120
+            || (chosen?.resetsAt.map { $0 <= Date().timeIntervalSince1970 } ?? false)
+        ring.remaining = chosen?.remaining
+        ring.stale = stale
+        ring.caption = stale ? (snapshot == nil ? "等待额度" : "数据过期") : chosen?.label ?? "额度未知"
+        let fetched = snapshot.map { Date(timeIntervalSince1970: $0.fetchedAt).formatted(date: .omitted, time: .standard) } ?? "尚未更新"
+        ring.toolTip = "本机 Codex CLI 账号额度\n\(chosen?.name ?? "未选择窗口")\n\(error ?? snapshot?.detail ?? "正在读取")\n状态：\(stale ? "数据未知或已过期" : "已更新")\n更新时间：\(fetched)\n拖动校准位置；双击刷新；右键打开菜单"
+        ring.setAccessibilityLabel("Codex \(chosen?.name ?? "") 剩余 \(chosen?.remaining.map { "\(Int($0.rounded()))%" } ?? "未知")，\(ring.caption)")
+        ring.needsDisplay = true
+    }
+    @objc func refresh() {
+        guard query == nil else { return }
+        lastAttempt = Date()
+        let process = Process(), pipe = Pipe()
+        process.executableURL = URL(fileURLWithPath: node)
+        process.arguments = [script]
+        var env = ProcessInfo.processInfo.environment
+        env["PATH"] = searchPath
+        if !codexHome.isEmpty { env["CODEX_HOME"] = codexHome }
+        process.environment = env
+        process.standardOutput = pipe
+        process.standardError = FileHandle.nullDevice
+        process.terminationHandler = { [weak self] process in
+            let data = pipe.fileHandleForReading.readDataToEndOfFile()
+            Task { @MainActor in
+                guard let self else { return }
+                self.query = nil
+                do {
+                    let value = try JSONDecoder().decode(Snapshot.self, from: data)
+                    if let message = value.error { self.error = message }
+                    else if process.terminationStatus == 0, value.fetchedAt > 0 {
+                        self.snapshot = value; self.error = nil
+                    } else { self.error = "额度查询失败" }
+                } catch { self.error = "无法读取额度响应，请检查 CLI 和网络" }
+                self.updateRing()
+            }
+        }
+        query = process
+        do { try process.run() }
+        catch { query = nil; self.error = "无法启动额度查询，请重新运行 easy-codex overlay"; updateRing() }
+    }
+    func item(_ title: String, _ action: Selector?) -> NSMenuItem {
+        let item = NSMenuItem(title: title, action: action, keyEquivalent: "")
+        item.target = self
+        return item
+    }
+    func makeMenu() -> NSMenu {
+        let menu = NSMenu()
+        menu.addItem(item("Easy Codex · CLI 账号额度", nil))
+        menu.addItem(item(lastRect == nil ? "等待 Codex 前台窗口" : "拖动圆环可调整位置", nil))
+        if let error { menu.addItem(item(error, nil)) }
+        if snapshot?.restricted == true { menu.addItem(item("服务端提示：当前使用受限", nil)) }
+        menu.addItem(.separator())
+        for window in snapshot?.windows ?? [] {
+            let remaining = window.remaining.map { "\(Int($0.rounded()))%" } ?? "未知"
+            let option = item("\(window.name) · \(remaining)", #selector(selectWindow(_:)))
+            option.representedObject = window.id
+            option.state = chosen?.id == window.id ? .on : .off
+            menu.addItem(option)
+        }
+        menu.addItem(item(query == nil ? "立即刷新" : "正在刷新…", query == nil ? #selector(refresh) : nil))
+        menu.addItem(item("恢复默认位置", #selector(resetPosition)))
+        menu.addItem(.separator())
+        menu.addItem(item("退出浮窗", #selector(quit)))
+        return menu
+    }
+    func menuNeedsUpdate(_ menu: NSMenu) {
+        menu.removeAllItems()
+        let fresh = makeMenu()
+        for item in fresh.items { fresh.removeItem(item); menu.addItem(item) }
+    }
+    @objc func selectWindow(_ sender: NSMenuItem) {
+        selectedID = sender.representedObject as? String
+        UserDefaults.standard.set(selectedID, forKey: "selectedWindow")
+        updateRing()
+    }
+    @objc func resetPosition() {
+        inset = CGPoint(x: 10, y: 74)
+        UserDefaults.standard.removeObject(forKey: "rightInset")
+        UserDefaults.standard.removeObject(forKey: "bottomInset")
+        tick()
+    }
+    @objc func quit() { NSApp.terminate(nil) }
+    func applicationWillTerminate(_ notification: Notification) {
+        timer?.invalidate()
+        query?.terminate()
+        NSWorkspace.shared.notificationCenter.removeObserver(self)
+    }
+}
+
+@main
+struct Main {
+    @MainActor static func main() {
+        if CommandLine.arguments.contains("--self-test") {
+            assert(RingState.resolve(51, stale: false) == .green)
+            assert(RingState.resolve(50, stale: false) == .orange)
+            assert(RingState.resolve(20, stale: false) == .orange)
+            assert(RingState.resolve(19, stale: false) == .red)
+            assert(RingState.resolve(nil, stale: false) == .unknown)
+            assert(RingState.resolve(99, stale: true) == .unknown)
+            assert(appKitRect(CGRect(x: -900, y: 100, width: 800, height: 600), primaryHeight: 900).origin == CGPoint(x: -900, y: 200))
+            let bounds = CGRect(x: 100, y: 100, width: 800, height: 600)
+            assert(ringOrigin(in: bounds, inset: CGPoint(x: 10, y: 74)) == CGPoint(x: 874, y: 174))
+            assert(ringOrigin(in: bounds, inset: CGPoint(x: -100, y: -100)) == CGPoint(x: 884, y: 100))
+            print("Swift 圆环颜色与窗口坐标检查通过")
+            return
+        }
+        let app = NSApplication.shared
+        app.setActivationPolicy(.accessory)
+        if CommandLine.arguments.contains("--diagnose") {
+            print("targetFrontmost=\(NSWorkspace.shared.frontmostApplication?.bundleIdentifier == "com.openai.codex")")
+            print("targetWindow=\(targetWindow().map { NSStringFromRect($0) } ?? "unavailable")")
+            return
+        }
+        if let i = CommandLine.arguments.firstIndex(of: "--render-preview"), CommandLine.arguments.count > i + 1 {
+            let image = NSImage(size: NSSize(width: 340, height: 100))
+            image.lockFocus()
+            for (index, value) in [75.0, 35.0, 10.0, -1.0].enumerated() {
+                NSGraphicsContext.saveGraphicsState()
+                let transform = AffineTransform(translationByX: CGFloat(index * 84 + 4), byY: 8)
+                (transform as NSAffineTransform).concat()
+                let view = RingView(frame: CGRect(x: 0, y: 0, width: 16, height: 16))
+                view.remaining = value < 0 ? nil : value; view.stale = value < 0
+                view.caption = value < 0 ? "额度未知" : "7天"
+                view.draw(view.bounds)
+                NSGraphicsContext.restoreGraphicsState()
+            }
+            image.unlockFocus()
+            if let tiff = image.tiffRepresentation, let bitmap = NSBitmapImageRep(data: tiff), let png = bitmap.representation(using: .png, properties: [:]) {
+                do { try png.write(to: URL(fileURLWithPath: CommandLine.arguments[i+1])) }
+                catch { fputs("预览写入失败\n", stderr); exit(1) }
+            }
+            return
+        }
+        let delegate = Overlay()
+        app.delegate = delegate
+        withExtendedLifetime(delegate) { app.run() }
+    }
+}

package/native/build/EasyCodexOverlay.app/Contents/Info.plist

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>CFBundleExecutable</key><string>EasyCodexOverlay</string>
+<key>CFBundleIdentifier</key><string>com.unionschool.easy-codex.overlay</string>
+<key>CFBundleName</key><string>Easy Codex Overlay</string>
+<key>CFBundlePackageType</key><string>APPL</string>
+<key>CFBundleShortVersionString</key><string>0.1.1</string>
+<key>LSMinimumSystemVersion</key><string>14.0</string>
+<key>LSUIElement</key><true/>
+<key>NSHighResolutionCapable</key><true/>
+</dict></plist>

package/native/build/EasyCodexOverlay.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict/>
+	<key>files2</key>
+	<dict/>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "easy-codex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Display remaining Codex account usage limits",
+  "type": "module",
+  "bin": {
+    "easy-codex": "bin/easy-codex.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "native/Overlay.swift",
+    "native/build/EasyCodexOverlay.app",
+    "scripts/build-overlay.mjs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/easy-codex.js",
+    "build:overlay": "node scripts/build-overlay.mjs"
+  },
+  "license": "MIT",
+  "author": "UnionSchool",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UnionSchool/easy-codex.git"
+  },
+  "homepage": "https://github.com/UnionSchool/easy-codex#readme",
+  "bugs": {
+    "url": "https://github.com/UnionSchool/easy-codex/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/scripts/build-overlay.mjs

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+import { mkdir, writeFile, mkdtemp, rm } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const root = fileURLToPath(new URL('../', import.meta.url));
+if (process.platform !== 'darwin') throw new Error('浮窗只能在 macOS 构建。');
+const app = `${root}native/build/EasyCodexOverlay.app/Contents`;
+await mkdir(`${app}/MacOS`, { recursive: true });
+const temporary = await mkdtemp('/tmp/easy-codex-build-');
+try {
+  for (const architecture of ['arm64', 'x86_64']) {
+    execFileSync('xcrun', ['swiftc', '-swift-version', '6', '-parse-as-library',
+      '-target', `${architecture}-apple-macosx14.0`, '-module-cache-path', `${temporary}/cache`,
+      `${root}native/Overlay.swift`, '-o', `${temporary}/${architecture}`, '-framework', 'AppKit'], { stdio: 'inherit' });
+  }
+  execFileSync('lipo', ['-create', `${temporary}/arm64`, `${temporary}/x86_64`, '-output', `${app}/MacOS/EasyCodexOverlay`], { stdio: 'inherit' });
+} finally {
+  await rm(temporary, { recursive: true, force: true });
+}
+await writeFile(`${app}/Info.plist`, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>CFBundleExecutable</key><string>EasyCodexOverlay</string>
+<key>CFBundleIdentifier</key><string>com.unionschool.easy-codex.overlay</string>
+<key>CFBundleName</key><string>Easy Codex Overlay</string>
+<key>CFBundlePackageType</key><string>APPL</string>
+<key>CFBundleShortVersionString</key><string>${version}</string>
+<key>LSMinimumSystemVersion</key><string>14.0</string>
+<key>LSUIElement</key><true/>
+<key>NSHighResolutionCapable</key><true/>
+</dict></plist>`);
+execFileSync('/usr/bin/codesign', ['--force', '--sign', '-', `${root}native/build/EasyCodexOverlay.app`], { stdio: 'inherit' });
+execFileSync(`${app}/MacOS/EasyCodexOverlay`, ['--self-test'], { stdio: 'inherit' });

package/src/overlay-data.js

@@ -0,0 +1,25 @@
+import { formatUsage } from './usage.js';
+
+export function overlayData(result, now = Date.now()) {
+  const detail = formatUsage(result);
+  const map = result.rateLimitsByLimitId;
+  const entries = map && typeof map === 'object' && !Array.isArray(map)
+    ? Object.entries(map).filter(([, b]) => b && typeof b === 'object') : [];
+  if (!entries.length) entries.push([result.rateLimits.limitId ?? 'codex', result.rateLimits]);
+  const windows = [];
+  for (const [id, bucket] of entries) {
+    for (const key of ['primary', 'secondary']) {
+      const w = bucket[key];
+      if (!w) continue;
+      const mins = w.windowDurationMins;
+      const label = Number.isFinite(mins) && mins > 0
+        ? mins % 1440 === 0 ? `${mins / 1440}天` : mins % 60 === 0 ? `${mins / 60}小时` : `${mins}分钟`
+        : key === 'primary' ? '主窗口' : '次窗口';
+      windows.push({ id: `${id}:${key}`, label,
+        name: `${String(bucket.limitName || id).replace(/[\x00-\x1f\x7f-\x9f]/g, '')} · ${label}`,
+        remaining: Number.isFinite(w.usedPercent) ? Math.max(0, Math.min(100, 100 - w.usedPercent)) : null,
+        resetsAt: Number.isFinite(w.resetsAt) && Math.abs(w.resetsAt) < 8.64e12 ? w.resetsAt : null });
+    }
+  }
+  return { windows, detail, fetchedAt: now / 1000, restricted: result.ordinaryUsageAllowed === false };
+}

package/src/overlay-query.js

@@ -0,0 +1,14 @@
+import { readUsage } from './usage.js';
+import { overlayData } from './overlay-data.js';
+const controller = new AbortController();
+process.once('SIGTERM', () => controller.abort());
+process.once('SIGINT', () => controller.abort());
+try {
+  const text = JSON.stringify(overlayData(await readUsage({ signal: controller.signal })));
+  // 原生端在进程结束后读取管道；限制体积以免写端等待管道空间。
+  if (Buffer.byteLength(text) > 12000) throw new Error('额度响应过大，请使用 easy-codex 查看完整数据。');
+  console.log(text);
+} catch (error) {
+  console.log(JSON.stringify({ error: error.message }));
+  process.exitCode = 1;
+}

package/src/overlay.js

@@ -0,0 +1,15 @@
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+export async function launchOverlay() {
+  if (process.platform !== 'darwin') throw new Error('浮窗首版仅支持 macOS。');
+  const app = fileURLToPath(new URL('../native/build/EasyCodexOverlay.app', import.meta.url));
+  try { await access(`${app}/Contents/MacOS/EasyCodexOverlay`, constants.X_OK); }
+  catch { throw new Error('尚未构建浮窗，请在项目目录执行 npm run build:overlay。'); }
+  await promisify(execFile)('/usr/bin/open', ['-g', '-a', app, '--args',
+    process.execPath, fileURLToPath(new URL('./overlay-query.js', import.meta.url)), process.env.PATH ?? '', process.env.CODEX_HOME ?? '']);
+  console.log('额度浮窗已启动；Codex 在前台时显示。拖动调整位置，右键或菜单栏 EC 可刷新、切换额度和退出。');
+}

package/src/usage.js

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+// 认证交给官方 CLI；不读取凭据文件，也不转发可能含敏感信息的服务端日志。
+export function readUsage({ command = 'codex', args = ['app-server', '--listen', 'stdio://'], timeoutMs = 20000, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(new Error('查询已取消。')); return; }
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'ignore'], shell: false });
+    const lines = createInterface({ input: child.stdout });
+    let done = false;
+    let expectedId = 1;
+    let killTimer;
+    const timer = setTimeout(() => finish(new Error('查询超时，请检查网络和 Codex 登录状态。')), timeoutMs);
+    function finish(error, result) {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      lines.close();
+      child.stdin.end();
+      child.kill();
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 1000);
+      killTimer.unref();
+      if (error) reject(error);
+      else resolve(result);
+    }
+    function onAbort() { finish(new Error('查询已取消。')); }
+    signal?.addEventListener('abort', onAbort, { once: true });
+    function send(message) {
+      child.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+    child.on('error', (error) => finish(new Error(error.code === 'ENOENT'
+      ? '找不到 codex，请先安装官方 Codex CLI 并确保它位于 PATH 中。'
+      : '无法启动 Codex CLI，请检查安装和执行权限。')));
+    child.stdin.on('error', () => finish(new Error('Codex 通信中断，请检查 CLI 是否正常。')));
+    child.on('close', () => {
+      clearTimeout(killTimer);
+      finish(new Error('Codex 在返回额度前退出，请检查 CLI 版本、配置和登录状态。'));
+    });
+    lines.on('line', (line) => {
+      if (done) return;
+      let message;
+      try { message = JSON.parse(line); }
+      catch { finish(new Error('Codex 返回了无效的协议数据，请检查 CLI 版本。')); return; }
+      if (message?.id !== expectedId) return;
+      if (message.error) {
+        finish(new Error(expectedId === 1
+          ? 'Codex 初始化失败，请检查 CLI 版本和配置。'
+          : '无法读取额度，请确认已通过 codex login 登录 ChatGPT，并检查网络；API Key 余额不在本工具范围内。'));
+        return;
+      }
+      if (!message.result || typeof message.result !== 'object') {
+        finish(new Error('Codex 返回了无效的结果。'));
+        return;
+      }
+      if (expectedId === 1) {
+        expectedId = 2;
+        send({ method: 'initialized' });
+        send({ id: 2, method: 'account/rateLimits/read' });
+      } else finish(null, message.result);
+    });
+    send({ id: 1, method: 'initialize', params: {
+      clientInfo: { name: 'easy_codex', title: 'Easy Codex', version },
+      capabilities: null,
+    } });
+  });
+}
+
+function duration(minutes, fallback) {
+  if (!Number.isFinite(minutes) || minutes <= 0) return fallback;
+  if (minutes % 1440 === 0) return `${minutes / 1440} 天`;
+  if (minutes % 60 === 0) return `${minutes / 60} 小时`;
+  return `${minutes} 分钟`;
+}
+
+function windowText(window, label) {
+  if (!window || typeof window !== 'object') return `  ${label}：未知（未提供数据）`;
+  const remaining = Number.isFinite(window.usedPercent)
+    ? `${Number(Math.max(0, Math.min(100, 100 - window.usedPercent)).toFixed(1))}%`
+    : '未知';
+  const date = Number.isFinite(window.resetsAt) ? new Date(window.resetsAt * 1000) : null;
+  const reset = date && Number.isFinite(date.getTime()) ? date.toLocaleString('zh-CN', { hour12: false }) : '未知';
+  return `  ${duration(window.windowDurationMins, label)}：剩余 ${remaining}；重置 ${reset}`;
+}
+
+export function formatUsage(result) {
+  if (!result || typeof result !== 'object') throw new Error('额度响应格式无效。');
+  const buckets = result.rateLimitsByLimitId;
+  const entries = buckets && typeof buckets === 'object' && !Array.isArray(buckets)
+    ? Object.entries(buckets).filter(([, value]) => value && typeof value === 'object') : [];
+  if (!entries.length && result.rateLimits && typeof result.rateLimits === 'object') {
+    entries.push([result.rateLimits.limitId ?? 'codex', result.rateLimits]);
+  }
+  if (!entries.length) throw new Error('服务端未提供额度数据，无法判断剩余额度。');
+  const output = ['Codex 剩余额度（账号共享，非当前会话）'];
+  for (const [id, bucket] of entries) {
+    // 限制服务端标签中的控制字符，避免终端转义序列影响显示。
+    const label = String(bucket.limitName || bucket.limitId || id).replace(/[\x00-\x1f\x7f-\x9f]/g, '');
+    output.push(label, windowText(bucket.primary, '主窗口'), windowText(bucket.secondary, '次窗口'));
+  }
+  if (result.ordinaryUsageAllowed === false) output.push('服务端提示：当前普通额度使用受限。');
+  output.push(`重置时间使用本机时区：${Intl.DateTimeFormat().resolvedOptions().timeZone}`);
+  return output.join('\n');
+}