企业官网建设流程全解析

CodexBar 的 Kiro 用量采集方案：kiro-cli 命令探测与 GetUsageLimits 超额额度增强

【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar

本指南基于 CodexBar 开源仓库中 docs/kiro.md 及 Kiro Provider 的完整实现，系统讲解 CodexBar 如何在不借助浏览器 Cookie 与 OAuth 流程的前提下采集 Kiro（AWS 旗下基于 Builder ID 认证的编码助手）的用量数据。读者将掌握：Kiro 主数据源kiro-cli的命令式探测机制与超时/回退策略、GetUsageLimitsAPI 对超额（overage）额度的尽力而为增强、三类用量窗口（计划积分、Bonus 积分、超额额度）的快照映射，以及"计划用量 vs 超额用量"拆分中防止双重计数的数据校验原则。

Kiro Provider 概览：无 Cookie、无 OAuth 的 CLI 优先架构

CodexBar 是一款菜单栏用量统计应用，对绝大多数 Provider 依赖浏览器 Cookie 或 OAuth 换取会话凭证。Kiro 是一个例外：它使用 AWS 官方kiro-cli工具直接抓取用量数据，认证完全由 CLI 内置的 AWS Builder ID 流程负责，CodexBar 自身不接触任何 Cookie 或 OAuth 令牌。

这一点可以从 Provider 描述符 Sources/CodexBarCore/Providers/Kiro/KiroProviderDescriptor.swift 中得到印证：

• cliName: "kiro"，aliases: ["kiro-cli"]，fetchPlan.sourceModes仅包含.auto与.cli（没有任何.cookies/.oauth模式），取数管线resolveStrategies直接返回[KiroCLIFetchStrategy()]；
• KiroCLIFetchStrategy.isAvailable通过TTYCommandRunner.which("kiro-cli")检查二进制是否存在，fetch则构造KiroStatusProbe并执行探测；
• dashboardURL指向 Kiro 官方用量页（https://app.kiro.dev/account/usage），defaultEnabled: false，意味着用户需要在设置中显式开启"Show Kiro usage"；
• 品牌色为 Kiro 标识性的橙色调（ProviderColor(red: 255/255, green: 153/255, blue: 0/255)），并配有专属聚彩（confetti）配色。

数据源一：kiro-cli 命令行探测（主数据源）

核心命令与超时语义

主数据源是单条 CLI 命令：

kiro-cli chat --no-interactive "/usage"

对应源码位于 Sources/CodexBarCore/Providers/Kiro/KiroStatusProbe.swift 的runUsageCommand()：

• 整体超时 20 秒（usageProbeTimeout: TimeInterval = 20.0）；
• 空闲截断 4 秒：CLI 一旦开始输出，若连续 4 秒无新输出则主动终止进程并采信已收到的内容（idleTimeout: 4.0）；
• 配套探测：whoami（3 秒超时、1.5 秒空闲截断）用于登录态校验与账号信息（邮箱、认证方式）提取；chat --no-interactive "/context"（8 秒超时）用于上下文窗口（Context window）占用解析，该探测失败仅记日志、不阻断主流程。

stdout/stderr 管道优先，PTY 伪终端兜底

新版 Kiro CLI 在管道下能正常输出，但部分旧版本在普通管道下不产出任何内容；反过来，新版本在 PTY 下即使加了--no-interactive也可能让 TUI 无限期存活。因此 CodexBar 采用双通道竞速 + 回退策略（见runCommand）：

1. 先以普通stdout/stderr管道启动命令，管道数据到达即记录活动时间戳；
2. 若管道在pipeTimeoutCap（5 秒）内仍无输出，且尚未收到可接受的管道结果，则在同一命令总截止时间（20 秒）内启动 PTY 伪终端通道兜底；
3. 管道结果需要经过shouldAcceptPipeResult校验（如 usage 输出必须能被解析器识别）才被采纳；不完整或不可用的管道输出会被丢弃，转而等待 PTY 结果；
4. 任一通道产生合格结果即取消另一通道并返回，保证总耗时仍受 20 秒 deadline 约束。

进程管理方面，管道启动时会向TTYCommandRunner注册进程组（PipeProcessRegistry），确保应用退出时能随主进程一起终止残留子进程，避免kiro-cli僵尸进程。

前置条件与登录态

• 本机需已安装kiro-cli（未找到时报cliNotFound：kiro-cli not found. Install it from https://kiro.dev）；
• 需已通过 AWS Builder ID 完成登录（未登录时whoami/usage 输出会命中not logged in、login required、failed to initialize auth portal、kiro-cli login、oauth error等关键词，被判定为notLoggedIn并提示用户先运行kiro-cli login）；
• 输出带有 ANSI 装饰符，CodexBar 在解析前先用正则\x1B\[[0-9;?]*[A-Za-z]|\x1B\].*?\x07剥离全部转义序列（stripANSI）。

plan-only 报告的特殊处理

kiro-cli 2.20 及更新版本会输出类似Plan: KIRO PRO MAX | 1 usage breakdowns的摘要行。解析器（parsePlanName）识别到该行时标记matchedNewFormat + isSummary：此时若没有可用的条形图百分比与积分数字，则生成一个hasUsageMetrics = false的只含计划名的快照——摘要中的 breakdown 数量既不等于零用量，也不代表还有可用额度，CodexBar 不会据此推断任何积分余量。

数据源二：GetUsageLimits API（超额额度增强，尽力而为）

为什么需要第二个数据源

Kiro CLI 的/usage报告只把积分对照计划本身陈述，对组织（organization）账户会整段省略 overage（超额）部分，因此它永远无法给出超额上限。而账号实际可花费的天花板是"计划 + 超额额度"。GetUsageLimitsAPI 恰好携带超额额度，CodexBar 用它把缺失的账本补全。相关实现位于 Sources/CodexBarCore/Providers/Kiro/KiroUsageLimitsAPI.swift。

请求协议与区域路由

• HTTP 方法POST，Content-Type: application/x-amz-json-1.0，头部X-Amz-Target: AmazonCodeWhispererService.GetUsageLimits，请求体为{"profileArn": ...}，鉴权使用Authorization: Bearer <access_token>；
• 端点为区域化的，依据 CLI profile ARN 中的 region 段路由：

• ARN 会被严格拆解校验：必须是arn:aws:codewhisperer:<region>:...:profile/xxx六段结构、不含空白与控制字符，且区域必须命中上面两个端点之一，否则抛出credentialsUnavailable("unsupported profile ARN")并跳过增强；
• 请求超时 10 秒，使用隔离的临时 URLSession（不共享 Cookie、无缓存、reloadIgnoringLocalCacheData、防重定向），避免污染与主应用的状态。

凭证来源：只读打开 CLI 状态库

API 凭证完全取自 CLI 自身的状态文件，且以SQLite 只读模式（sqlite3_open_v2(..., SQLITE_OPEN_READONLY, ...)，busy_timeout 250ms）打开——令牌与其刷新周期由 CLI 独占，CodexBar 绝不写入：

• macOS：~/Library/Application Support/kiro-cli/data.sqlite3
• Linux（无 XDG）：~/.local/share/kiro-cli/data.sqlite3
• Linux（有XDG_DATA_HOME）：$XDG_DATA_HOME/kiro-cli/data.sqlite3
• 任意平台可用环境变量KIRO_DATA_DIR整体覆盖目录（追加data.sqlite3）

两张表两个键：

值得注意的执行顺序设计：API 增强在 CLI 探测之后运行（fetch()中先跑 CLI，最后fetchUsageLimits()），因此 CLI 在探测过程中若刷新了令牌，增强请求读取到的必然是最新的。此外该路径依赖 CLI 私有令牌库的位置，而 Kiro 某个版本可能移动它；CLI 报告则只读取 CLI 自己发布的输出，因此增强被设计为非致命——失败时保留 CLI 已产出的计划相对数值，或维持 plan-only 报告（用量不可得）；只有当 API 返回明确的正向额度时，才用它补上缺失的计划指标。

输出格式示例与解析要点

kiro-cli chat --no-interactive "/usage"的典型输出如下（已剥离 ANSI）：

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ | KIRO FREE ┃ ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ Monthly credits: ┃ ┃ ████████████████████████████████████████████████████████ 100% (resets on 01/01) ┃ ┃ (0.00 of 50 covered in plan) ┃ ┃ Bonus credits: ┃ ┃ 0.00/100 credits used, expires in 88 days ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

解析器在 KiroStatusProbe.swift 中通过多条正则兼容不同 CLI 版本：

• 计划名：兼容三种格式——旧版| KIRO FREE徽标行、2.x 的Estimated Usage | resets on 2026-06-01 | KIRO FREE尾部字段、1.24+ 的Plan: <name>新格式；
• 用量百分比：█+\s*(\d+)%条形图提取；若无条形图则回退用(X.XX of Y covered in plan)计算used/total（creditsTotal默认兜底 50，即免费档）；
• 重置时间：resets on MM/DD（假定当前或次年）或resets on yyyy-MM-dd（ISO 格式）两种写法均可解析；
• Bonus 积分：Bonus credits: X.XX/Y credits used与expires in N days；
• overage 行：Overages: ...、Credits used: X、Est. cost: $X USD（仅当 API 不可用且币种为 USD 时才采信后两者）。

快照映射：计划、Bonus 与超额三个独立窗口

KiroUsageSnapshot.toUsageSnapshot()（KiroStatusProbe.swift）将上述信息映射为 CodexBar 统一的UsageSnapshot：

• Primary window（主窗口）：月度计划积分百分比（条形图）。当托管报告或摘要输出扣留指标、且 API 增强不可用时，该窗口连同数字积分行一起省略，但计划名仍可见；包含 Bonus 的 API 总量与零额度不会顶替 CLI 计划指标或凭空造出缺失的计划仪表。usedPercent取自███...█ X%，或 API 应答时的planUsed / planLimit；resetsAt解析自resets on MM/DD或 API 的nextDateReset；
• Secondary window（次窗口）：Bonus 积分（存在时）。始终来自 CLI。当GetUsageLimits返回非空bonuses[]数组时，CodexBar 保留 CLI 的计划仪表，不把 Bonus 花费当作计划用量，overage 增强照常生效；resetsAt由expires in N days换算为到期日；
• Extra windowkiro-overage：已花费的超额额度对照overageCapWithPrecision（仅 API 提供）。这是第二层积分上限，而非可选的额外用量——计划仪表保持 plan-only，使"计划已花完但仍有超额余量"的账户依旧能看到剩余超额空间；该窗口复用 Credits 剩余的文案（N of M credits left）；
• Provider cost（费用快照）：overageCharges对照overageCap × overageRate（仅 API），展示超额产生的实际费用与费用上限；
• Identity：accountOrganization取计划名（如KIRO FREE），loginMethod也取计划名用于菜单展示。

详情面板（details）还会按需渲染：Credits left/used/total、Bonus credits left、Overages 状态、Overage usage、Overage credits left、Overage cost、Context window 及其细分（Context files / Tools / Kiro responses / Your prompts）、Manage 链接。

Plan 与 Overage 拆分：杜绝双重计数

API 响应中的currentUsageWithPrecision是包含 overage 的总量，因此计划用量必须按planUsed = currentUsage - currentOverages计算。若把总量直接喂给计划仪表，已花完计划的账户会显示超过 100%，且同一笔花费会在两个仪表中被重复计数。

源码通过 KiroUsageLimitsAPI.parse 施加多条防御性校验：

• 逐分量校验而非求和校验：planLimit、totalUsed、overageUsed各自必须是有限非负数——负数无法藏在正数总量里蒙混过关；
• 关系一致性：totalUsed >= overageUsed，否则抛overage exceeds total usage；
• 计划上限：无 Bonus 时要求planUsed <= planLimit，否则拒绝；
• ENABLED 无 cap 视为不完整而非禁用：overageEnabled在ENABLED但无 cap 时返回nil，保留 CLI 的 overage 行展示；未知状态（如未来新增的枚举值）同样不当作 disabled 处理；
• 重置时间合理性：nextDateReset必须是 Unix 秒落在2001-09-09 ~ 2100-01-01（1_000_000_000...4_102_444_800）区间内的值，毫秒/微秒单位会被判定为非法。

上述逻辑在 Tests/CodexBarTests/KiroUsageLimitsAPITests.swift 中有完整的真实响应级验证：一份 KIRO POWER 账户"计划已花完、超额正在使用"的录制响应（overageInUseResponse）展示了planLimit = 10000、planUsed = 10000、overageUsed = 3603.49、overageCap = 10000、overageRate = 0.04、overageCharges = 144.14、overageChargeLimit = 400（10000 × 0.04）的映射结果，并断言快照中计划仪表停留在 100% 而非 136%、kiro-overage窗口为 36.03%、费用窗口上限为 $400。测试同时覆盖：overage 超总量拒绝、DISABLED 不"撤销"已花超额、多个 CREDIT 余额拒绝、非 USD 币种不采信 CLI 的美元估算、Bonus 未分离时保留 CLI 计划仪表、以及测试环境强制拒绝访问开发者真实状态库（refuses the live state database under tests）。

状态页

Kiro 没有独立的状态页。CodexBar 中该 Provider 的statusLinkURL直接指向AWS Health Dashboard（对应StatusItemController的"View Status"入口，描述符见 KiroProviderDescriptor.swift），状态相关探测实现于 Sources/CodexBarCore/Providers/Kiro/KiroStatusProbe.swift 与 KiroStatusProbe.swift 配套的KiroStatusProbe之上。

应用侧集成：登录流程与菜单栏展示

应用层实现位于 Sources/CodexBar/Providers/Kiro/KiroProviderImplementation.swift：

• 提供kiro-cli-login设置动作，允许用户在设置面板一键触发"Re-authenticate"重认证（实际执行kiro-cli login）；
• 提供kiroMenuBarDisplay下拉选择器，控制菜单栏图标旁是否显示 Kiro 积分、百分比或两者（KiroMenuBarDisplayMode三态）。

关键源码与测试文件索引

• 文档与描述：docs/kiro.md
• Provider 描述符与取数策略：Sources/CodexBarCore/Providers/Kiro/KiroProviderDescriptor.swift
• CLI 探测（whoami/usage/context、pipe/PTY 回退、ANSI 剥离、解析）：Sources/CodexBarCore/Providers/Kiro/KiroStatusProbe.swift
• GetUsageLimits 增强（SQLite 只读凭证、区域端点、解析校验）：Sources/CodexBarCore/Providers/Kiro/KiroUsageLimitsAPI.swift
• 应用层集成（登录动作、菜单栏选择器）：Sources/CodexBar/Providers/Kiro/KiroProviderImplementation.swift
• 测试： Tests/CodexBarTests/KiroUsageLimitsAPITests.swift、Tests/CodexBarTests/KiroStatusProbeTests.swift、Tests/CodexBarTests/KiroStatusProbeTTYHardStopTests.swift、Tests/CodexBarTests/KiroRegionalEnrichmentTests.swift、Tests/CodexBarTests/KiroSummaryTests.swift

综上，CodexBar 的 Kiro Provider 展示了一种"CLI 输出为主、底层 API 为辅"的健壮取数范式：主链路只依赖 CLI 公开输出（对 CLI 私有存储的变动免疫），增强链路尽力而为地补足超额账本，并通过逐分量校验与"计划/超额分离仪表"的设计，在不臆造数据的前提下给出准确、可审计的用量视图。

【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar