TokenBoard｜产品说明（作品集整理稿）
审阅状态：初稿。 内容依据当前 TokenBoard 源码、README、第三方素材说明及作品集 assets/tokenboard-case/SOURCES.md 整理。涉及个人经历、完整过程、设计决策缘由、最终视觉和真机表现的表述均需本人核对。案例页面现使用 2026-11-03 SwiftUI 模拟器演示图和 8 张介绍板；App 数值为 proof snapshot 合成样例，不是个人真实账户或实体真机画面。
01 产品缘起
TokenBoard 起初是 Mac 端的数据与网页看板，用来集中查看不同 AI 服务的订阅额度、账户余额与使用情况。后续形态转为 SwiftUI 原生 iPhone App，并继续探索桌面小组件：将需要时打开网页查看，变为在手机概览和系统组件中快速扫读。小组件是推动移动端原生化的重要动机。具体问题场景、用户访谈、目标人群与验证结论尚无可引用证据，待本人补充；不将个人工具描述为已验证的商业产品。
02 形态演进与职责
- Mac / Web 看板： 原有数据采集与网页呈现基础。准确版本、时间节点、旧版截图和实现范围待核验。
- iPhone 原生 App： 以 SwiftUI 呈现快照和用量；手机端读取 Mac 提供的只读鉴权快照，不扫描或分析 Mac 会话文件。
- WidgetKit： 当前工程定义小号 2×2 WidgetKit 组件；系统决定实际刷新时机。设置或 App 更新可请求刷新，但不承诺即时刷新。真机组件体验尚未验收。
用户提出需求并主导产品范围及视觉方向；AI 协助设计与开发。具体哪些页面、交互与代码由谁完成，需结合版本记录及本人确认后再逐项写明。本稿不虚构独立设计、团队规模、上线或商业成果。
03 需求边界
- 快速查看跨 Provider 的订阅额度、积分/余额/流量，以及由记录汇总的 Token 用量。
- 在周期、来源和日期维度查看活动与趋势，能回到来源明细。
- 支持浅色、深色、跟随系统、隐藏数值和额度已用/剩余显示切换。
- 数据不可用或总量未知时明确保留未知状态，不造数、不把未知总量当零。
- Widget 只展示精简状态；保护隐私并接受系统控制刷新节奏。
04 信息架构
正式底部 Tab 为 概览 / 用量 / 设置。概览含周期用量摘要、订阅额度卡、积分与余额卡；点击卡片进入相应详情。用量含近 26 周每日活动、日期明细、区间趋势、来源/周期筛选、月度汇总与模型明细（按实际记录可用性呈现）。设置含外观、隐藏数值、订阅额度显示方向、币种/汇率及连接状态说明。DEBUG 小组件图库只用于开发预览，不是正式第四个 Tab。
05 数据卡片与计算口径
| 卡片 | 展示重点 | 数据限制 |
|---|---|---|
| 单周期订阅额度 | 周期额度、剩余/已用比例、重置时间 | 仅有有效总量和剩余值时计算比例；缺失显示未知 |
| 多周期订阅额度 | 分行显示各周期、各自重置时间 | 周期独立，不合并成虚构的总额度 |
| WorkBuddy | 账户剩余积分 | 剩余积分来自额度观测；按模型分摊的积分才是估算 |
| DeepSeek | 货币余额 | 没有可验证总量时不显示比例、不补总额 |
| 良心云 | 剩余流量、已知总量/进度、到期信息 | 以来源可得数据为准；演示总量不可写成线上真实配置 |
| Grok | 有证据支持的订阅额度窗口 | 当前无可用用量记录时不展示虚构 Token 或费用 |
费用按带来源的价格表估算，不等于订阅账单；模型积分分摊是估算，不是逐请求官方账单。近 26 周活动、日期明细、区间趋势及月度汇总来自记录。无需为了版面完整而填入研究、数值或成果。
06 产品交互状态
- 加载： 显示准备/刷新状态；不伪造进度百分比。
- 成功： 显示快照生成时间及来源观测时间（两者可能不同）。下拉刷新请求更新。
- 失败 / 离线： 保留上次缓存并说明连接状态；不把旧数据包装为实时。
- 空数据： 明确提示所选来源/周期没有记录。
- 缺失与未知： 数值、总量、比例分别按可用性呈现；未知值用破折号/说明，不补零。
- 隐私： 隐藏用量与金额时，App 和组件对应数值及相关进度同步隐藏。
- Widget： 首次配置可能需要先打开 App 同步连接信息和快照；刷新由系统掌控，可能显示离线/旧观测时间。
07 视觉规范（依据当前产品整理）
| 项目 | 现有方向 |
|---|---|
| 背景 | 暖白 #F7F6F2；深色 #0E0E0D |
| 强调色 | 陶土 #C26E52 |
| 卡片 | 约 24 pt 圆角，留白分组；数值使用衬线数字层次 |
| 信息层级 | 产品名与周期摘要优先，周期/重置和来源状态辅助，说明文字克制 |
| 图表 | Activity Heatmap、Range Lens 组件来自 SwiftPieces，保留其授权声明并标注第三方来源 |
| 参考 | 原 TokenBoard 网页暖白/陶土/衬线数字；Nowdex 公开 Status、Usage、Widgets 信息层级参考。借鉴层级不表示复制源码或合作 |
字体使用 Anthropic Serif 的本地静态实例、犬仓旧明朝少数字形子集与苹方回退；公开分发前需确认字体许可。Lobe Icons、Muse、Solar 等图标也按 THIRD_PARTY_NOTICES.md 标注来源和许可；品牌商标归各权利人。
08 当前验证与缺口
| 项目 | 已知状态 |
|---|---|
| 原生 App / WidgetKit 工程 | 源码存在；README 记录在 iOS 27 模拟器环境开发验证 |
| iPhone 安装 | 交接记录称 2026-10-28 已覆盖安装带 WidgetKit 的构建；本次未复核设备 |
| Widget 视觉 | 当前案例板使用 screenshots/simulator-2026-11-03/widget-proof-*.png 中正式 TokenWidgetView 的 ImageRenderer 渲染预览；非系统主屏/真机截图，且来自独立合成快照。历史 widgets.png 是 DEBUG WidgetSampleCard 画廊，已不用于当前页面 |
| 真机组件 | 组件添加、首次同步、刷新与视觉交互待用户验收；刷新由系统控制 |
| 当前截图 | screenshots/simulator-2026-11-03/ 保存当前 AppShell 模拟器截图与正式组件 ImageRenderer 原图；App 与组件使用独立合成快照。详细列表见 SOURCES.md |
| 上线 / 用户 / 报价 / 效果 | 无可引用证据；不可宣称已发布、获客或量化提升 |
| 案例状态 | 已接入 TokenBoard 案例页并保留产品说明入口；内容与视觉仍待本人确认，真机组件交互仍待设备验证 |
09 素材来源与发布核对
- 原始模拟器/组件图保存在
assets/tokenboard-case/screenshots/simulator-2026-11-03/，8 张介绍板保存在assets/tokenboard-case/boards/。案例页集中说明模拟器、合成数据及 ImageRenderer 组件渲染边界；来源清单逐图记录来源。板面只等比排版，未裁切、重绘或改写 UI 像素。 - SwiftPieces Activity Heatmap / Range Lens：MIT + Commons Clause（以源码附带声明为准）。
- Lobe Icons：MIT；Muse 图标来源见 Wikimedia / Muse 说明；Solar Icons：CC BY 4.0，按来源文件要求署名。
- 字体许可仍待核实；公开案例前核对所有字体与图标的再分发条件。
- 所有截图应保留原始比例与内容；不得将合成图或模拟器演示描述为个人真实账户数据/实体真机，也不得将 ImageRenderer 组件渲染描述为系统主屏截图。