makecindy / makecindy/cindy

feat(desktop): 额度 hover 提示与底栏 chip 升级为结构化用量卡片(提案 + 认领)

Open
#1,261 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
2.7k
Forks
395
Avg merge
21h 48m
Merged PRs (30d)
776

Description

## 现状与痛点

桌面端右下角额度 chip 的 hover 提示目前是一整块纯文本(`TodaySpendChip.tsx` 中 `buildClaudeSubscriptionTooltipNode` 把所有信息 `join('\n')` 进一个 ``),实际使用中有几个体验问题:

1. **十几行字平铺**,账号级额度窗口、套餐、本轮 token 明细、优化建议混在一列,没有层级和分区;
2. **没有视觉量感**——已用 95% 和已用 2% 长得一模一样,额度紧张时毫无预警(chip 只有 ≥90% 的二元变红);
3. **「打开 Claude 用量页面」看起来像链接但点不了**——`Tip` 是 `disableHoverableContent=true` 的 Radix Tooltip,鼠标根本移不进内容;
4. chip 上的「5小时 剩余 99%|6天 剩余 96%」是纯文字,扫一眼没有形状信息。

## 提案

把 Claude 订阅计费形态的 hover 提示升级为**结构化、可交互的用量卡片**(Popover),底栏 chip 同步换成「迷你进度条 + 剩余百分比」。示意图(数据为实机截图真实值):

| 浅色 | 深色 |
|---|---|
| ![卡片-浅色](https://raw.githubusercontent.com/0xmariowu/cindy/quota-issue-assets/card-light.png) | ![卡片-深色](https://raw.githubusercontent.com/0xmariowu/cindy/quota-issue-assets/card-dark.png) |

核心设计(布局参照 CodexBar 的卡片结构,MIT):

- **每个额度窗口一个分区**:标题 + 进度条 + 左「已用 %」右「重置时间」,覆盖 5 小时 / 周限 / 全部分模型周限;
- **三档颜色**:常态 → >70% 提醒 → >90% 告急,阈值与现有 ContextCapacityRing(70/90)和 `WINDOW_ALERT_UTILIZATION_PERCENT`(90)对齐;
- **消耗节奏预测(pace)**:周限区多一行「按当前速度能否撑到重置 / 预计何时耗尽」,算法参照 CodexBar `UsagePace.weekly`(纯前端本地计算,窗口经过 <3% 不显示避免瞎预测);
- **本轮消耗表格化**:标签左、数值右、`tabular-nums` 对齐;「建议」单独做浅色提示条;
- **动作行是真按钮**:Popover 内「打开 Claude 用量页面」可点击、键盘可达;
- **数据边界全兼容**:两种数据源(oauth-endpoint / unified-headers)字段差异、快照缺失、resetsAt 为空、extra usage(只显示启用状态,单位未文档化不显示数值)等情形均有确定降级展示。

## 变更范围与 PR 拆分

全部 renderer-only(不动 main 进程、协议、shared 数据契约),仅改 Claude 订阅分支,按「一 PR 一问题」拆三个:

1. **PR1 — 结构化卡片**:新增 `QuotaBar` 进度条组件 + `QuotaHoverCard` 纯展示卡片(含边界情形单测),`TodaySpendChip` Claude 分支 Tip→Popover,删除旧字符串拼接 builder;
2. **PR2 — 周限 pace 预测**:`quotaPace.ts` 纯函数 + 单测(守卫齐全),卡片周限区接节奏行;
3. **PR3 — 底栏 chip 迷你进度条**:chip 文字段换迷你条 + 变色,圆环(上下文占用)不动。

每个 PR 按模板附截图、设计规范引用、验证命令实录,commit 全部 DCO 签名。

## 想请维护者拍板的点

1. **常态配色**:示意图用了 CodexBar 风格的暖色进度条;若按 DESIGN.md 近黑白纪律,常态应为灰阶填充、仅 >70/>90 走 `--warning-fg` / `--error-flat` 语义 token。组件实现上颜色全部走可注入变量,两种结论都不需要返工——想听你们的偏好。
2. **其它计费形态**(Codex / xAI / 网关)本次不动;如果方向认可,愿意后续逐个跟进。

如方向 OK,我这边直接按上述拆分提 PR。

Contributor guide

Open the contributing guide

Research direction

Start in TodaySpendChip.tsx, especially buildClaudeSubscriptionTooltipNode and the Claude subscription branch; compare its thresholds with ContextCapacityRing and WINDOW_ALERT_UTILIZATION_PERCENT. Begin with PR1's QuotaBar and QuotaHoverCard plus boundary-case tests, then verify the Popover action and the documented fallback cases for both data sources. Done means the card renders the agreed sections and the chip shows the mini progress indicator.

Written by the indexing model from the issue text.

Assessment

Tech stack
electron, typescript
Domain
desktop-dev, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.