CodexBar 工程开发规范指南Swift 6 菜单栏应用的构建、测试、发布与 Agent 协作全流程【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar本文基于 CLAUDE.md 仓库开发指南整理覆盖 CodexBar开源 macOS 菜单栏应用用于展示 OpenAI Codex 与 Claude Code 用量统计的模块结构、编译运行、格式检查、测试策略、发布流程以及面向 AI Agent 的协作红线帮助开发者在保证代码质量与安全边界的前提下高效参与迭代。一、文档定位与适用范围CLAUDE.md是 CodexBar 仓库面向人类开发者和 AI Agent 双方的工程协作规范内容分为六个板块项目结构与模块、构建/测试/运行、编码风格与命名、测试准则、提交与 PR 规范、Agent 注意事项。它不讲解具体的 Provider 实现细节而是定义了如何在这个仓库里安全、合规、高质量地改动代码。适用前提CodexBar 采用SwiftPM 驱动、无 Xcode 工程的开发方式主应用是 macOS 菜单栏程序同时附带 CLISources/CodexBarCLI、核心库Sources/CodexBarCore与 Widget 扩展Sources/CodexBarWidget。这意味着构建、测试、打包、签名、发布均通过仓库根目录下的脚本完成。二、项目结构与模块划分文档明确给出了四个核心目录的职责边界改动时Keep changes small and reuse existing helpers保持改动小、复用既有工具目录职责Sources/CodexBarSwift 6 菜单栏应用主体用量/额度探测usage/credits probes、图标渲染器icon renderer、设置界面settingsTests/CodexBarTests覆盖用量解析、状态探测、图标模式的 XCTest 用例新逻辑必须镜像补充聚焦测试Scripts构建/打包辅助脚本如 package_app.sh、sign-and-notarize.sh、make_appcast.sh、build_icon.sh、compile_and_run.shdocs发布说明与流程文档docs/RELEASING.md、screenshots根目录 zip/appcast 是生成产物非发布期不要手动编辑发布相关脚本统一通过 Scripts/mac-release 间接调用它会解析MAC_RELEASE_TOOL环境变量或回退到共享的agent-scriptscheckout 目录。此外从仓库结构看Sources/CodexBarCore 承载了大量与 UI 无关的可复用逻辑Keychain、Cookie 导入、Provider 探测、用量模型等是 CLI 与应用共享的公共层。三、构建、测试、运行全流程3.1 首选开发循环compile_and_run.sh文档规定的主开发循环是./Scripts/compile_and_run.sh该脚本Scripts/compile_and_run.sh执行一条完整链路杀死旧实例 → 构建 → 打包 → 重新启动CodexBar.app→ 确认应用持续运行。它内部实现了多项防护单实例锁以仓库根目录哈希为 key 创建锁目录${TMPDIR}/codexbar-compile-and-run-hash防止多个 Agent 同时编译另一个实例正在编译时默认直接退出--wait可等待其完成分级杀进程先pkill请求优雅退出最多 25 次探测再对残留进程pkill -9强杀覆盖三种进程形态打包后的.app二进制、.build/debug、.build/release避免open -n产生多实例孤儿探测清理应用可能在探测期间启动claude /status、claude /usage子进程脚本会pkill -f claude (/status|/usage) --allowed-tools兜底清理签名模式自动解析优先使用Developer ID Application: Peter Steinberger (Y5PE65HELJ)其次CodexBar Development再尝试自动探测本机证书最后回退 adhoc 签名adhoc 签名每次构建都会变导致旧 Keychain 条目失效可用--clear-adhoc-keychain显式重置启动验证open之后轮询检测进程 10 次每次 0.4 秒若应用秒退则报错并提示查看 Console.app 崩溃日志。支持的参数./Scripts/compile_and_run.sh --test # 先跑分片全量测试再打包 ./Scripts/compile_and_run.sh --wait # 等待其他编译任务完成 ./Scripts/compile_and_run.sh --debug-lldb # 以 debug 配置打包允许 LLDB 附加 ./Scripts/compile_and_run.sh --release-universal # 打包 arm64 x86_64 ./Scripts/compile_and_run.sh --release-archesarm64 x86_64 ./Scripts/compile_and_run.sh --clear-adhoc-keychain脚本还强制校验 Swift 版本 5.5支持swift build --archPATH 上版本不足时自动切换 Xcode 工具链。3.2 快速构建与全量测试文档给出的快捷路径swift build # debug 构建 swift build -c release # release 构建 make test # 分片全量测试make test实际调用 Scripts/test.sh其要点Makefile 中test目标默认按12 个测试为一组CODEXBAR_TEST_GROUP_SIZE分片单套件超时 180 秒CODEXBAR_TEST_SUITE_TIMEOUT非超时失败默认重试 1 次支持CODEXBAR_TEST_SHARD_INDEX/CODEXBAR_TEST_SHARD_COUNT环境变量做 CI 分片默认强制隔离 Keychain除非显式设置CODEXBAR_ALLOW_TEST_KEYCHAIN_ACCESS1否则导出CODEXBAR_SUPPRESS_TEST_KEYCHAIN_ACCESS1测试进程不得访问用户登录钥匙串同时导出CODEXBAR_TEST_CODEX_FILE_ISOLATION1、CODEXBAR_TEST_SESSION_FILE_ISOLATION1隔离 Codex 文件与会话文件访问。Makefile 还提供了 restart重新编译运行、make lint/make check格式与静态检查、make format自动格式化、make docs-list等目标。3.3 本地打包与重启./Scripts/package_app.sh # 刷新 CodexBar.app pkill -x CodexBar || pkill -f CodexBar.app || true cd /Users/steipete/Projects/codexbar open -n /Users/steipete/Projects/codexbar/CodexBar.app注意文档中/Users/steipete/Projects/codexbar是维护者的本地开发机路径示例读者需替换为自己的克隆目录open -n保证即使已有实例也强制新开一份从而验证刚打包出来的最新 bundle。Scripts/package_app.sh 内部会校验 SwiftPM 产物、处理 KeyboardShortcuts 资源 bundle 的安全加载避免Bundle.module的 fatal trap、按ARCHES选择架构默认宿主架构、可选CODEXBAR_FORCE_CLEAN1触发无缓存重构建并做codesign --verify --deep --strict与 quarantine 属性校验。3.4 格式与静态检查make check / make lint文档要求每次代码改动后运行make check并在交回前修复全部格式/lint 问题。其背后是 Scripts/lint.sh 的lint命令由 Makefile 的check/lint目标触发Swift 侧swiftformat Sources Tests --lintswiftlint --strict --no-cache工具由 install_lint_tools.sh 安装到.build/lint-tools/binJS/TS 侧oxfmt --check、oxlint --deny-warnings、tsc --project tsconfig.plugins.json针对 Sources/CodexBarCore/Resources/Plugins 下的插件脚本与 docs/site.js可移植性检查Codex parser hash、Provider manifests、插件 JS 再生成、包产物路径/strip/签名/Info.plist、release dSYM 路径、release checksum、Sparkle 签名路径、Swift 测试分片、CI 路径门禁、Homebrew tap 等待、仓库体积、Shell 脚本bash -n语法、文档链接、站点多语言等提供lint-linux跳过 macOS 专属项与lint-macos两种平台变体以及format命令自动改写。四、编码风格与命名规范格式化红线4 空格缩进、单行 120 字符显式self是有意为之不得移除维护既有MARK分组注释类型设计偏好小而类型化的 struct/enum语义清晰的符号命名与当前提交风格保持一致Swift 并发Agent Notes 部分进一步细化当async let兄弟任务中一个必需、另一个可选/best-effort时视为审查红旗——应改为顺序 await或用会汇合必需失败、显式包含可选失败的withThrowingTaskGroup崩溃栈中出现swift_task_dealloc或asyncLet_finish_after_task_completion时需审计附近的async let用法现代化 API优先 SwiftUI Observation 宏Observable模型 State持有 视图内Bindable避免ObservableObject/ObservedObject/StateObject重构时优先 macOS 15 新 APIObservation、新 display link API、更新的菜单项样式等而非遗留/废弃 API。五、测试准则从用例命名到安全隔离5.1 测试组织与命名新测试放在 Tests/CodexBarTests 下FeatureNameTests.swift方法采用test_caseDescription驼峰风格若使用 Swift Testing 框架则偏好反引号句子式名称如backticked sentence name不强制驼峰测试/代码中的模型名称只能使用已发布模型或明确虚构的名称绝不暴露未发布的模型名防止泄露未发布产品信息交回前必须make test通过针对 parser/provider 修复优先补充聚焦测试swift test --filter ...行为可在不重启 CodexBar 时验证的优先 CLI 或聚焦测试而非 app bundle 级 live 测试。5.2 Keychain 安全测试不得弹出系统弹窗文档明确禁止运行任何会触发 macOS Keychain 弹窗的测试/校验。红线包括live provider 探测、浏览器 cookie 导入、针对真实账号的codexbar usage、真实SecItem读取——这些操作必须显式请求才可执行否则一律使用 parser 测试、stub、测试 store或KeychainNoUIQuery。仓库源码印证了这一机制Sources/CodexBarCore/KeychainNoUIQuery.swift构造LAContext()并设置interactionNotAllowed true写入查询的kSecUseAuthenticationContext为避免仅在interactionNotAllowed下某些 macOS 仍弹出 Allow/Deny 弹窗还通过dlopen在运行时解析kSecUseAuthenticationUIFail常量写入kSecUseAuthenticationUI编译期不直接引用已废弃 APISources/CodexBarCore/KeychainAccessPreflight.swift 进一步提供无 UI 预检只读取 item 引用与属性不请求kSecReturnData检查解密 ACL 是否信任当前可执行文件返回allowed / interactionRequired / temporarilyUnavailable / notFound / failure五态并带同操作内记忆化与KeychainAccessGate.isDisabled总开关。测试侧Scripts/test.sh 默认导出CODEXBAR_SUPPRESS_TEST_KEYCHAIN_ACCESS1作为纵深防御只有刻意测试隔离 Keychain 的用例才允许通过CODEXBAR_ALLOW_TEST_KEYCHAIN_ACCESS1显式放行。Makefile 中test-liveLIVE_TEST1 CODEXBAR_ALLOW_TEST_KEYCHAIN_ACCESS1 swift test --filter LiveAccountTests与test-tty目标正体现了这种默认禁、显式开的取舍。5.3 App-group 迁移测试的隔离要求文档要求 app-group 迁移测试必须注入字典支撑的 defaults、两个快照 URL、合成 home 目录、受控的录音型 FileManager。特别提醒UUID 默认值套件与 Keychain 隔离标志并不能隔离 defaults 搜索域或文件系统访问普通 SettingsStore 测试不得发现共享 defaults也不得触发 app-group 迁移。5.4 macOS CI 的脆弱性规避无头 CI 环境下 AppKit 状态栏/菜单测试容易失败。文档建议优先通过稳定的状态/模型接缝如MenuDescriptor、ProvidersPane、CodexAccountsSectionState等见 Sources/CodexBar 下对应文件覆盖菜单行为而不是构造真实的NSStatusBar/NSMenu流程——除非被测对象本身就是 AppKit 接线逻辑。六、提交与 PR 规范提交信息短促的祈使句如 Improve usage probe、Fix icon dimming提交保持单一范围PR/补丁列出摘要、运行过的命令UI 改动附截图/GIF相关时附 issue/引用链接。七、面向 AI Agent 的协作要点CLAUDE.md 专为 Agent 定义了额外的操作红线使用现有脚本与 SwiftPM未经确认不得引入新依赖或工具菜单栏自动化验证先截取目标屏幕确认 CodexBar 图标确实在屏拒绝坐标落在显示边界外的click-extra成功判定隐藏的菜单栏扩展不算已点击证据验证新鲜构建UI/运行时行为必须针对刚打包的 bundle 验证通过上文 pkillopen 命令重启避免运行过期二进制CLI 可测逻辑provider/parser/settings 行为用 CLI 或聚焦测试验证避免动用package_app.sh/compile_and_run.sh后者仅在需要 bundle 级 UI/运行时验证时使用Widget/Tahoe UI 问题在 Parallels macOS VM 中配合截图/点击做自主验证发布脚本必须前台运行Scripts/release.sh不得后台化等它跑完Sparkle 密钥使用.mac-release.env中的MAC_RELEASE_SIGNING_KEY_FILE即旧版共享密钥AGCY8w5vHirVfGGDGc8Szc5iuOqupZSh9pMj/Qs67XI不要使用sparkle-private-key-KEEP-SECURE.txt那是 VibeTunnel 的不匹配密钥Provider 数据隔离渲染某 ProviderClaude vs Codex的用量/账号信息时绝不展示来自其他 Provider 的 identity/plan 字段对应源码中的 ProviderAccountSnapshot/ProviderIdentitySnapshot 等数据模型Claude 状态行Claude CLI 状态行是用户自定义的默认不得依赖其解析用量只有用户显式开启的 statusLine JSON 数据源才被允许owner 裁定 #2733且必须默认关闭、明确标注来源、格式漂移时软失败Cookie 导入默认仅 Chrome避免其他浏览器弹窗需要时通过浏览器列表覆盖。八、发布流程要点结合 docs/RELEASING.mdCLAUDE.md 将发布细节指向 docs/RELEASING.md。发布由 Scripts/release.sh 触发内部转调Scripts/mac-release要求先加载 shell 环境变量如~/.profile。核心流程与前置条件前置Xcode 26、Developer ID 证书、ASC API 凭据APP_STORE_CONNECT_API_KEY_P8/APP_STORE_CONNECT_KEY_ID/APP_STORE_CONNECT_ISSUER_ID图标./Scripts/build_icon.sh Icon.icon CodexBar用 Xcode 的ictool 透明 padding 生成Icon.icns签名与公证Scripts/sign-and-notarize.sh 依次做 arm64/x86_64 双架构 release 构建、打包CodexBar.app、嵌入 Sparkle.framework 及 Updater/Autoupdate/XPC、深度 codesign--timestamp--deep rpath、zip、notarytool 提交与 stapling经验教训Sparkle 的 framework/Autoupdate/Updater/XPC 都必须签名否则公证失败解压用ditto -x -k而不要用unzip后者会引入 AppleDouble._*文件破坏密封签名触发app is damagediCloud/CloudKitrelease 构建嵌入 Scripts/profiles/CodexBar-DeveloperID.provisionprofile2044-07-29 到期任何 Sync schema 变更必须先更新 Scripts/cloudkit/schema.ckdb 并部署deploy_schema.sh development/production否则 Developer ID 构建的同步全部报 unknown record typeAppcastScripts/make_appcast.sh 从CHANGELOG.md生成 HTML 发布说明并嵌入 appcast 条目SPARKLE_CHANNELbeta可标记 beta 通道发布后用 Scripts/verify_appcast.sh 校验签名与尺寸Homebrew发布后由.github/workflows/release-cli.yml构建 macOS/glibc Linux/musl Linux 的 CLI tarball并派发../homebrew-tap的 CLI formula 与 app cask 更新发布完成后用 Scripts/check-release-assets.sh 验证 zip、dSYM、CLI tarball 与 checksum 齐全。发布完成的定义appcast/enclosure 链接可解析、Homebrew cask 可安装、旧公开版本能通过 Sparkle 更新到新版本。文档还给出常见故障排查表白底图标重跑build_icon.sh、公证失败检查 deeptimestamp 签名与 Sparkle 组件、app 打不开Sparkle.framework 嵌入与 rpath、解压后 app damaged改用ditto重解、更新下载 404核对 release asset 与 enclosure URL。九、总结仓库协作的黄金法则CodexBar 的CLAUDE.md将工程纪律总结为可执行的四条主线流程工具化构建、测试、打包、签名、发布全部脚本化Agent 与人类共用同一套入口compile_and_run.sh/make test/make check/release.sh减少环境差异安全默认隔离测试默认不得触碰用户 Keychain、共享 defaults、真实账号与浏览器数据所有敏感能力必须显式放行CODEXBAR_ALLOW_TEST_KEYCHAIN_ACCESS1等质量门禁前置每次改动过make check、全量make test新逻辑必须镜像聚焦测试模型名称不得泄露未发布信息Agent 行为可验证菜单栏自动化必须先截图确认图标在屏UI 行为必须针对新鲜 bundle 验证Provider 数据严格隔离避免运行过期二进制。对参与本仓库的开发者而言遵循以上规范即可在保持 CodexBar 稳定、安全、可发布的前提下以最小风险完成从改一行代码到发布一个新版本的完整闭环。【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考