用途
add-report 是 ClaudeBar 项目中的一个技能,用于指导开发者添加新的报告卡片(Report Card)。这类卡片会读取并解析本地数据文件,聚合指标,与对比周期计算差值,并以项目现有的玻璃拟态卡片 UI 风格展示结果。
主要能力
该技能覆盖添加报告类功能的完整流程,报告卡片具备以下能力:
- 读取并解析本地数据文件(JSONL、JSON、CSV 等)
- 聚合指标(成本、Token、时间、计数等)
- 对比周期(今天对比昨天、本周对比上周等)
- 以匹配现有 UI 的玻璃拟态卡片展示结果
架构模式
每个报告功能遵循如下数据流:
数据源 → 解析器 → 分析器 → 报告模型 → UsageSnapshot → 卡片视图
对应到代码库分层:
- 领域层(Domain):Sources/Domain/{Feature}/,创建富模型 + @Mockable 协议
- 基础设施层(Infrastructure):Sources/Infrastructure/{Provider}/,创建解析器 + 分析器实现
- 应用层(App):Sources/App/Views/,创建卡片视图
- 集成(Integration):Provider 类 + statsGrid,将分析器 → 快照 → UI 串联
参考实现:references/daily-usage-pattern.md 中的 DailyUsage 功能是该模式的完整示例。
使用方式
工作流程分为五个阶段:
- 阶段 0:架构设计(必须获得用户批准)
- 阶段 1:领域模型 + 测试(TDD 红→绿)
- 阶段 2:基础设施解析器 + 分析器 + 测试
- 阶段 3:卡片视图 + 集成
- 阶段 4:验证所有测试通过
阶段 0:架构设计(强制)
在编写代码前先设计功能并获得用户批准。
步骤 1:定义报告,回答以下问题:
- 数据源是什么?(JSONL 会话、API 响应、本地数据库等)
- 指标是什么?(成本、Token、时间、计数等)
- 对比周期是什么?(今天对比昨天、本周对比上周等)
- 哪个 Provider?(Claude、Codex,还是跨所有 Provider 的通用型?)
- 需要多少张卡片?(每个指标一张,还是单张合并卡片?)
步骤 2:创建架构图。
步骤 3:记录组件,包括 {Name}Stat、{Name}Report、{Name}Analyzing 协议、{Name}Analyzer 实现、{Name}CardView 等,说明各自用途、输入与输出。
步骤 4:使用 AskUserQuestion 确认设计后再继续。
阶段 1:领域模型(TDD)
1a. 创建 Stat 模型:位于 Sources/Domain/{Feature}/{Name}Stat.swift,表示单个周期的聚合数据,包含格式化行为。关键规则:货币值使用 Decimal(而非 Double,避免浮点误差);时长使用 TimeInterval;货币格式化使用 Locale(identifier: "en_US")(而非 en_US_POSIX,后者会多出空格);所有格式化逻辑放在模型中,视图只读取格式化字符串;isEmpty 使用 &&(全为零才算空),而非 ||。
1b. 创建 Report 模型:位于 Sources/Domain/{Feature}/{Name}Report.swift,对比两个周期并计算差值。关键规则:当上一周期为零时变化百分比返回 nil(避免除零);格式化差值始终带符号(+ 或 -);进度为 current / (current + previous),限制在 0-1;格式化值使用 abs(),符号单独前置。
1c. 创建协议:位于 Sources/Domain/{Feature}/{Name}Analyzing.swift,使用 @Mockable 标注。
1d. 先写测试:位于 Tests/DomainTests/{Feature}/,遵循芝加哥学派 TDD(测试状态而非交互),创建 {Name}StatTests.swift 与 {Name}ReportTests.swift。
阶段 2:基础设施(TDD)
2a. 创建解析器(如需读取文件):位于 Sources/Infrastructure/{Provider}/{Name}Parser.swift。解析器为 struct(非协议),因为它是纯数据转换。
2b. 创建分析器:位于 Sources/Infrastructure/{Provider}/{Provider}{Name}Analyzer.swift,实现领域协议并负责:查找相关文件(按修改日期过滤以提升性能)、解析文件为记录、按时间段划分记录、聚合为 stat 模型、返回报告。性能规则:只扫描相关时间窗口内修改过的文件;在 2000+ JSONL 文件的情况下,扫描全部文件过慢。
2c. 编写基础设施测试:位于 Tests/InfrastructureTests/{Provider}/。解析器测试覆盖有效输入、缺失字段、畸形数据、时间戳;分析器测试使用含 JSONL 内容的临时目录,测试日期划分。
阶段 3:卡片视图 + 集成
3a. 创建卡片视图:位于 Sources/App/Views/{Name}CardView.swift,必须匹配现有玻璃拟态风格,以 WrappedStatCard 为参考。卡片样式清单包括:VStack 上 .padding(12);theme.cardGradient 填充 + theme.glassBorder 描边(1pt);theme.cardCornerRadius 圆角;所有文本使用 theme.fontDesign;文本层级使用 theme.textPrimary / theme.textSecondary / theme.textTertiary;进度条背景使用 theme.progressTrack;悬停缩放效果(1.015);带 delay 参数的动画进度条。
3b. 添加到 UsageSnapshot:添加报告的可选字段,并在 init 中默认 nil。
3c. 接入 Provider:将分析器注入拥有该数据的 Provider,在 refresh() 中通过 attach{Name}Report 附加报告。
3d. 在 statsGrid 中渲染:添加到 MenuContentView.statsGrid(snapshot:)。
3e. 在 ClaudeBarApp 中注册:创建 Provider 时传入分析器。
阶段 4:验证
- 运行 tuist generate
- 运行所有测试:xcodebuild test -scheme ClaudeBar-Workspace ...
- 构建应用并验证卡片出现
- 检查日志中的分析器输出
适用场景
适用于需要为 ClaudeBar 新增报告类功能的场景,即需要读取本地数据源、聚合指标、进行周期对比并以卡片形式展示的开发任务。
限制
资料未提供该技能的具体运行环境要求、依赖版本、支持的平台范围或性能基准等额外限制信息。