fix(usage): 修按天分桶时区错位 + 区分账号额度/maestro用量口径 + 成本说明文档 (tsk_JKAzHuXvSw7h)

全局面板「用量」数据问题修复与澄清:

1. 时区分桶根因(store.ts):按天/周/月分桶与今天/本月窗口起点原全用 UTC,
   UTC+8 用户本地 00:00–08:00 的 run 被算进前一天、当天窗口晚 8h → 柱状图偏移
   一天、当天偏小。新增 localDay/localMonth,periodStartISO/weekStartLabel/
   usageDetail 改用 daemon 本地时区(SQL 比绝对时刻仍正确)。

2. UI 口径区分(design/ui_kits/console):额度条标注账号级含交互会话,AGENT 卡/
   详情弹框标注仅统计 maestro 任务执行,$ 加 API 列表价估算非实际扣费提示并以 ≈
   前缀,模型列加近似角标。新增 4 个 i18n key×5 语言。

3. 文档:新增 docs/usage-cost-explained.html(两数据源/为何对不上/cost 公式/
   单价表/本地时区分桶/已知近似),登记进 docs/index.html 知识库调研。

4. 测试:budget.test.ts 新增 UTC+8 跨日分桶用例。typecheck + 268 测试全绿。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
wangjia
2026-06-30 09:18:36 +08:00
parent e115e065e6
commit d0aa53c79d
7 changed files with 322 additions and 27 deletions
+7 -1
View File
@@ -86,7 +86,13 @@ body{font-family:'IBM Plex Mono',monospace;background:var(--bg);color:var(--text
<!-- ── 知识库调研 ── -->
<div class="cat">
<div class="cat-hdr"><span class="ico">调研</span> 知识库调研 <span class="cnt">· 1</span></div>
<div class="cat-hdr"><span class="ico">调研</span> 知识库调研 <span class="cnt">· 2</span></div>
<a class="doc" href="usage-cost-explained.html">
<div class="doc-ttl">用量与成本计算说明 · 数据源口径 + cost 公式 + 时区分桶</div>
<div class="doc-path">docs/usage-cost-explained.html</div>
<div class="doc-desc">讲清全局面板「用量」的<strong>两个互不相交数据源</strong>:① 账号级订阅额度(<code>usage.ts</code> 直连 oauth/usage,含你自己的 Claude Code 交互会话)vs ② maestro 自有 run 的 cost/token<code>cc.ts→ingest→store</code>,仅任务执行)——这就是「只有 maestro 在跑却有其他 token 消费」的真相。含 <strong>cost 公式</strong>(四类 token × 各模型单价 / 1e6,引自 <code>pricing.ts</code> 单价表)、<strong>按天/周/月分桶规则与本地时区口径</strong>(修复 UTC 偏移一天 bug)、<strong>$ 为 API 列表价名义估算非订阅实账单</strong>、分模型 token 近似与未知模型记 0 两项已知近似。</div>
<div class="tags"><span class="tag html">HTML</span><span class="tag design">用量/成本</span></div>
</a>
<a class="doc" href="task-rules.html">
<div class="doc-ttl">任务执行规则参考 · 当前实现</div>
<div class="doc-path">docs/task-rules.html</div>