SuperAPI AI 工具集

add-report

编程与开发

查看项目

更新于 10-16 06:56

技能介绍

用途

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 新增报告类功能的场景,即需要读取本地数据源、聚合指标、进行周期对比并以卡片形式展示的开发任务。

限制

资料未提供该技能的具体运行环境要求、依赖版本、支持的平台范围或性能基准等额外限制信息。