Skip to content

CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息

17.3 KB
Raw Blame

Repository guidelines

语言要求

始终使用简体中文回答,代码、命令、专有名词和用户明确要求保留的原文除外。

实现原则

目标和约束明确后,优先选择全生命周期综合成本最低的方案,兼顾实现和维护成本、扩展能力及未来调整空间。

  • 评估技术债务、路径依赖、维护复杂度和未来重构成本,必要时承担合理的一次性结构调整成本
  • 用尽可能少的概念、状态、依赖和特殊规则解决问题,保持实现清晰、实用
  • 保持核心逻辑易于理解和验证,模块边界明确、职责合理,优先复用已有能力
  • 处理必要的边界条件和异常场景,为可预见的变化保留空间
  • 对生命周期短、影响范围小或需求高度不确定的问题控制前期投入,不为假设中的需求设计复杂架构
  • 让实现和维护成本与业务价值相匹配;长期收益与当前简洁性难以兼顾时,结合生命周期、变更概率、影响范围、可逆性和未来修正成本说明取舍

判断与行动原则

从目标和事实出发

从目标、约束和因果关系分析问题,用事实检验经验、惯例和既有做法。

  • 识别用户真正的目标、问题的事实依据、已知约束、未知信息、隐含前提和验收标准,不默认用户已完整定义问题
  • 能从现有代码、文档、工具或环境取得的信息,先自行验证
  • 区分已确认事实、基于事实的推断、尚待验证的假设和无法确定的部分,不把推测表达为事实
  • 关键前提不成立时,先指出事实依据及其对结论的影响,再给出可落地的替代方案
  • 证据不足时,明确缺失信息、不确定性及验证方式

根据清晰度和影响决定行动

情况 行动
目标清晰、路径合理 直接执行
目标清晰、当前路径明显不是最优 完成合理范围内的任务,同时指出更简单、成本更低或风险更低的替代方案
目标模糊,但可通过低风险、可逆的假设推进 明确假设后执行
目标模糊,且不同选择会显著影响结果 暂停实施,确认关键问题

涉及兼容性问题时,遵守下文代码修改原则中的确认要求。

给出可验证的判断

能量化时使用数字,有明确结论时直接说明,不用模糊措辞或表面中立代替判断。按问题需要,说明结论的适用范围、事实依据和推导过程、主要风险与失败条件,以及实施步骤、验证方法和验收标准。

沟通原则

优先直接回答当前问题,给出结果、方案、代码、命令或操作步骤,再按需补充分析。简单、明确的问题直接处理,避免长篇铺垫,不重复确认已经明确的信息。

  • 仅在手段偏离目标、关键前提或约束缺失、存在隐藏的长期成本、有明显更优的替代方案,或涉及安全、合规、数据损失及不可逆后果时,审慎挑战原始需求
  • 挑战时说明事实依据、推导和实际影响,并给出可执行的替代方案;不机械质疑,不揣测用户动机
  • 根据事实和可验证的推理作出判断,不因用户预期或表面中立改变结论;讨论具体分歧,避免立场对抗
  • 保持尊重、直接和坚定;用户提供更可靠的事实或推导后,及时修正结论并说明依据,不作无意义的辩护

项目结构与模块组织

CodexBar 是面向 macOS 的 LSUIElement 菜单栏应用,使用 Swift 6, SwiftUI, AppKit 和 MVVM。工程只有 CodexBar scheme,包含主 App、CodexBarPowerHelperManager、CodexBarPowerHelper、CodexBarTests 和 CodexBarPowerHelperTests 五个 target。

CodexBar/ 按 App/ Views/ Controllers/ Models/ Services/ 和 Resources/ 分层。CodexBarHelper/ 按职责组织 Helper。其中,Power/Daemon/ 提供电源管理的 root LaunchDaemon,主 App 直接与其通信;Power/Manager/ 提供嵌入主 App 的管理 App,负责该 daemon 的注册,系统授权也归属于它;Power/Shared/ 存放跨 target 协议与身份定义。通用跨 target 工具位于 Shared/。测试统一放在 Tests/,按被测模块划分为 App/ 和 Helpers/。Scripts/ 提供发布和 Helper 清理工具,Images/ 存放 README 资源,Design/ 统一存放主 App 和 Helper 的原始设计图、图标工程等设计素材。

构建、测试与开发命令

  • xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'generic/platform=macOS' build 执行代码变更后的构建验证
  • env -u CC -u CXX xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'platform=macOS' -testPlan Unit test 执行日常快速单元测试,也是 scheme 的默认测试计划
  • env -u CC -u CXX xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'platform=macOS' -testPlan Integration test 执行协议、存储、进程及跨模块生命周期集成测试
  • env -u CC -u CXX xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'platform=macOS' -testPlan Standard test 执行全部单元测试和集成测试
  • env -u CC -u CXX xcodebuild -project CodexBar.xcodeproj -scheme CodexBar -destination 'platform=macOS' -testPlan Sanitizers test 分别运行 TSan 和 ASan 诊断;使用 -only-test-configuration ThreadSanitizer 或 -only-test-configuration AddressSanitizer 可单独运行对应配置
  • swiftformat . 按 .swiftformat 格式化全部 Swift,使用 Swift 6 和 4 空格缩进
  • swiftlint 按 .swiftlint.yml 检查
  • /usr/bin/log stream --predicate 'subsystem == "app.zabrian.codexbar"' --style compact 查看系统日志,Debug 版 subsystem 带 .debug 后缀

测试命令中的 env -u CC -u CXX 用于清除终端的编译器覆盖,确保使用 Xcode 工具链,避免 Homebrew LLVM 干扰 Sanitizer。

Scripts/build.sh dmg.sh 和 appcast.sh 需要 Developer ID 与公证凭据,不用于日常验证。

写作风格

代码、代码注释和项目文档使用彼此独立的规则,不得把一类内容的标点约定直接套用到另一类内容。提交信息由 Git 规范单独约束。

代码和注释

代码和注释统一遵守:

  • 禁止使用中文标点,一律使用半角标点
  • 句中停顿和并列项使用空格或者逗号,顿号的位置也用空格或者逗号
  • 分号只用来断开完整句子,相当于句号;拿不准就把它换成句号读一遍,两边都能独立成句才保留
  • 行末禁止使用标点
  • 行内标点后如果还有文字,间隔一个英文空格
  • 注释中引用类型、成员、参数或命令后尽量不要紧跟标点,需要断句时补一个词或者使用空格再断
  • 注释清晰简洁、通俗易懂,优先说明代码中不明显的原因和约束,避免复述实现
  • 一个注释段只解释一件事,长注释按主题分段;需要列出独立条件或步骤时使用简短列表
  • 按职责边界适当使用 // MARK: - 名称,帮助浏览较长文件;不为每个属性或短函数单独添加标记
  • 不在注释中重复容易变化的展示数量、尺寸或动画参数;涉及数据处理时说明具体字段和操作

项目文档

项目文档统一遵守:

  • 代码标识符、命令、路径、配置键、原始字段值和需要精确复制的版本号使用行内代码
  • 中文正文使用全角中文标点,包括 , 。 ; : ! ? “” 和 ()
  • 中文短词或短语的并列使用 、;能独立表达语义的分句使用 ,,两边都能独立成句时才考虑 ;
  • 中文标点前后不加空格;中文与英文、数字或行内代码之间按词语边界保留一个半角空格
  • 不机械替换特殊内容中的英文标点。数字序列、行内代码序列或英文术语并列时,如果英文标点观感更好,使用英文标点并在其后保留一个半角空格
  • 普通正文行末使用与语义匹配的中文标点;引出列表、表格或代码块的正文使用 :
  • 标题、独立列表项、编号项和表格单元格行末不加标点
  • 如果一行以 Markdown 格式的链接或行内代码结尾,后面不加任何标点;链接或行内代码位于句中时仍按句子结构使用中文标点
  • Markdown 语法、代码块、命令、路径、URL、版本号和程序标识符内部的符号保持原样
  • 如果某句话的作用只是防止被质疑,而不是推进论证,请删除这句话
  • 文档只描述当前行为,不记录变更过程,删除没有实质信息的辩解

架构与编码约定

启动与并发边界

  • Codex 后台服务采集由独立 actor 拥有连接和解析状态,不在主 actor 执行阻塞 I/O
  • 采集消息和读取时间必须有界,共享数据写入必须加锁
  • 普通模式由 App 的统一入口装配长期服务
  • 工程默认采用 MainActor 隔离,共享可变状态放入 actor,跨 actor 值类型按需声明 nonisolated,禁止在主 actor 执行阻塞 I/O
  • 类型命名使用 UpperCamelCase,成员命名使用 lowerCamelCase
  • 设置持久化 key 使用 UpperCamelCase.lowerCamelCase,模块名按职责命名,不跟随界面文案变化;总开关使用 isEnabled,子开关使用 is…Enabled 或 are…Enabled,行为布尔值可使用 keeps… 等自然谓词;时长以秒保存并带 Seconds 后缀,百分比带 Percent 后缀

数据链路与权限边界

  • 保持 app-server 额度与用量、活动历史聚合、实时任务三条数据链路独立
  • 账户主链路、活动连接启用与校验必须分别检查当前 app-server 的实际版本是否满足各自最低要求
  • 活动连接只订阅已加载线程,不创建用户轮次、不回答审批、不修改 Codex 配置或管理 Codex 后台服务生命周期
  • App 启动入口允许在 Codex 后台服务缺失时通过官方 codex app-server daemon start 命令确保服务启动,能力检测、等待和重试必须有界;禁止停止、重启、更新 Codex 后台服务或修改 Codex 配置
  • helper 只能执行固定的睡眠控制和自动重置唤醒计划,不得增加网络、任意命令执行或额外文件访问
  • 新增网络访问、日志数据或 CloudKit 字段前先核对隐私边界
  • 开启自动重置或防睡眠前必须取得用户确认,打开 helper 授权系统设置必须由用户显式操作触发

生命周期与资源清理

  • 自动重置只处理新鲜响应中明确可用且具备用量和有效期信息的凭证,重试必须有界
  • helper 只接受有限时间戳,维护单一的系统唤醒计划;目标变化、功能关闭、App 退出、对应连接断开或 helper 启动时必须收敛并清理计划
  • 修改唤醒事件的归属或类型时,必须考虑旧版本遗留事件的清理兼容性
  • 异常会话保护跟随防睡眠开关,只判定运行中任务,等待批准任务不参与判定
  • 活动连接初始化、系统睡眠、唤醒恢复或数据源不可用期间暂停异常会话判定,数据恢复后执行无通知核对
  • 主动排空活动读取是屏障,每个调用方必须等待一轮在本次请求之后开始的读取;唤醒后只有该轮读取成功,才能执行生命周期核对并恢复保护判定
  • reader 更换时丢弃旧结果,数据源不可用或任务取消时不得使用旧快照继续判定

数据语义与兼容性

  • 实时任务必须具备会话标识和轮次标识,身份不完整的事件不创建任务;子任务归属未确认时等待关联,开始时间缺失时保留未知耗时
  • 异常会话保护记录只保存哈希任务标识和必要时间戳,保留时间必须有界;Debug 与 Release 共用的数据必须跨进程加锁,修改存储格式或身份计算属于兼容性问题
  • 聚合算法、输出字段、字段含义或去重规则变化,需要重新计算历史数据时,必须递增聚合 schema,从保留期内的原始事件完整重建,不新增字段级历史迁移
  • 活动计数字段缺失表示历史来源不可用,不能解释为明确的零值

测试规范

根据改动的影响范围和风险选择验证方式。测试入口、源码归属、编译条件和工具配置以当前工程为准。

  • 测试围绕可观察行为、关键边界和失败恢复设计,优先复用现有测试;新增测试应能发现实际回归,避免只重复实现或为简单改名机械补测
  • 单元测试使用独立临时数据和可控依赖,测试结束后清理资源;不得读写真实用户数据、调用真实外部服务、启动特权服务或修改系统设置
  • 自动化测试(包括单元测试、集成测试和 Sanitizer 测试)不得显示窗口、面板、popover 或浏览器页面,也不得激活 App 或抢占焦点;透明窗口和屏幕外窗口同样不得显示
  • 布局使用不显示窗口的离屏宿主验证,交互逻辑使用可控依赖和状态断言验证;需要真实窗口或页面的场景只做手动验证。检查测试时同时核对辅助方法和被测入口,避免间接打开界面
  • 代码改动需完成受影响目标的构建、相关自动化测试及项目配置的格式和静态检查;涉及共享逻辑、构建配置或跨模块行为时,扩大验证范围;纯文档改动检查内容和格式即可
  • 日常代码改动默认运行 Unit 测试计划,并按影响范围补充相关 Integration 用例;涉及共享逻辑、构建配置或交付前运行完整 Standard 计划
  • 集成测试通过 .tags(.integration) 标记,按测试的主要依赖和职责归类,混合测试套件可以只标记对应函数;Unit 排除该标签,Integration 仅包含该标签,Standard 和 Sanitizers 均保留完整覆盖
  • 修改共享可变状态、锁或跨线程访问时,追加运行 Sanitizers 中的 ThreadSanitizer 配置;修改 SQLite、Darwin、C 接口或指针相关的内存访问与资源生命周期时,追加运行 AddressSanitizer 配置;同时涉及两类风险时,分别运行两种配置
  • 测试完成后同时检查失败用例和运行期警告,定位并处理新增的 Sanitizer、Main Thread Checker 和 Thread Performance Checker 报告
  • 自动化测试无法覆盖的交互、系统集成和生命周期行为,补充手动验证;验证前确认运行产物、构建配置和测试环境,避免混用不同版本
  • 交付时说明实际执行的验证、测试计划与配置、结果及运行期警告;未执行或受环境限制的项目应明确列出,并说明待验证场景,不以构建通过代替运行行为验证

Git 规范

不要主动 push,不要回滚、覆盖或丢弃他人的未提交修改。用户只要求提交时,不要顺带格式化或修改文件。

提交信息应根据完整代码差异,说明解决的问题及行为或能力变化:

  • 标题概括本次提交最主要的问题或目标,不用次要交互细节或局部实现代替核心目的
  • body 围绕核心目的解释必要的原因、关键行为变化和影响;实现细节仅在有助于理解目的或评估影响时保留
  • 只描述代码最终的行为和状态,不记录开发过程中的中间状态
  • 不把文件清单、函数改动清单或开发过程直接作为提交说明,也不为覆盖每一处 diff 而堆砌条目

提交标题使用 <type>: <中文描述> 格式:

  • 常用 type 包括 feat fix chore refactor docs
  • message 只描述改动,不写版本号、Release 标记或其他发布相关内容;版本信息写在 tag 中
  • 修复和发布提交需要 body
  • 标题与 body 之间空一行
  • body 中的 bullet 连续排列,每条缩进 4 个空格

Tag 名 v{MARKETING_VERSION} 里的版本号从 Config/Version.xcconfig 读取,使用附注 tag git tag -a v3.x.y -m "Release v3.x.y"

代码修改原则

  • 优先结合现有文件结构和类型职责,不为小改动新建抽象
  • 内部逻辑与界面需求分开处理:修复数据完整性、错误处理、重试或恢复等内部问题时,默认保持现有界面,包括内部新增成功、失败或部分恢复状态的情况。未经用户明确要求或同意,不新增提示、标签、状态文案或其他展示内容;确需调整界面时,先说明必要性和具体改动,取得同意后再实施
  • 改 shared controller、shared service、模型解析或持久化 key 时,要考虑旧数据和降级路径;用户设置要保持默认值;持久化 key 和旧版本迁移兼容
  • 任何兼容性问题都必须主动询问用户,不要自行决定;只要改动会影响新旧共存就适用,不限于旧数据迁移或丢弃、持久化 key 改名或改结构、老版本升上来的降级路径、最低系统版本与 API 可用性取舍、云端记录格式变更、内部版本变化;先说清影响面和几种做法的代价,等用户选定再动手
  • 处理窗口、菜单、快捷键、App 激活或事件监听时,特别注意 LSUIElement 应用特有的焦点行为
  • 不做辅助功能(Accessibility)适配,不新增辅助功能标签、特征或操作
  • 注释只解释代码中不明显的生命周期、焦点、actor 或系统 API 约束及其原因
  • 改动涉及菜单面板、窗口焦点、活动采集、同步、通知、自动重置唤醒或防睡眠时,构建通过之外还要说明应手动覆盖的交互场景;helper 相关改动额外要验证 App 包内 helper 与 plist 位置、签名、首次系统授权、运行/等待切换、唤醒计划替换与清理和异常退出后的恢复