# Token Ball · 产品说明

## 一句话

**把 DeepSeek Harness 每一次对话的 Token、花费、上下文压力和余额，放在手边。**

## 背景

Agent 产品的成本是“过程成本”：一次任务可能包含几十次模型请求，每次都会重新发送上下文。对话越长、工具调用越多，Token 消耗越不像一个可以用直觉判断的数字。

DeepSeek Harness 已经提供了完整的用量数据，但用户需要：

1. 打开对话详情，找到 Token 数字；
2. 心算输入、输出、缓存命中的差异；
3. 再去设置页确认余额；
4. 回到对话，继续工作。

这个来回切换很小，但发生频率很高。Token Ball 的目标不是做一个新的账单系统，而是把已经存在的信息**提前到视线边缘**。

## 产品定位

> 一个常驻在 Harness 界面上的“成本仪表盘”，而不是另一个需要打开的管理页面。

它适合：

- 每天长时间使用 Harness 的个人开发者；
- 需要关注 API 预算的小团队；
- 正在调试 Agent、想知道“这一轮到底花了多少”的构建者；
- 用赠金/充值余额、希望随时知道还能用多久的用户。

它不试图替代：

- 开放平台的正式账单；
- 团队的统一成本管理后台；
- 跨会话、跨成员的成本分析系统。

## 用户价值

| 痛点 | Token Ball 的回答 |
| --- | --- |
| Token 数字藏在详情里 | 悬浮球直接显示会话总用量和预估花费 |
| 不知道这次对话贵不贵 | 输入、输出、缓存命中分项展示，价格随时段变化 |
| 余额要跳设置页 | 充值余额和赠金余额常驻卡片 |
| 不知道上下文还剩多少 | 外圈压力环与「上下文」明细，显示已用 / 上限与构成 |
| 打断心流 | 可拖动、可收起，不占用对话区域 |
| 担心隐私 | 计算在本机完成，只返回聚合数字 |

## 核心体验

### 1. 扫一眼

悬浮球收起时只显示一个数字：当前会话的预估花费。颜色和位置足够低干扰，不遮挡对话内容。

### 2. 点开看明细

展开后看到：

- 本对话总 Token；
- 输入 / 输出 / 缓存命中 / 请求数；
- 上下文占用、实际发送、压缩释放量与 Token 构成（安装 `billion-context` 时）；
- 当前高峰或空闲价；
- 充值余额、赠金余额。

### 3. 拖到顺手的位置

位置写入 `localStorage`，下次打开 Harness 仍在原处。悬浮球跟随 Harness 主题，明暗模式都能读。

### 4. 近实时

约 1.2 秒轮询一次。每次模型请求提交后，用量和花费会在下一次轮询中更新；上下文约 10 秒轮询一次，页面隐藏时暂停；余额最多缓存 30 秒，避免频繁请求账号服务。

## 设计原则

1. **不打断**：默认收起，悬浮层点击穿透，只有球和卡片接收指针事件。
2. **先给结论，再给解释**：先显示花费，再显示分项。
3. **诚实标注估算**：所有金额都明确写“估算”，并说明以平台账单为准。
4. **本机优先**：不在插件里保存凭据，不上传对话正文。
5. **可配置**：价格表放在 Host 配置里，官方调价时不需要改代码。

## 计费模型

Token Ball 使用会话日志中每次 `assistant/message` 的 `usage` 记录，按模型和请求发生时间选择价格：

```text
cost =
  (inputTokens + cacheWriteTokens) × cacheMissPrice
  + cacheReadTokens × cacheHitPrice
  + outputTokens × outputPrice
```

价格单位是 CNY / 1M tokens。高峰时段为北京时间周一至周五 `09:00–12:00`、`14:00–18:00`，其余时间为空闲价。

当前默认价格：

| 模型 | 缓存命中 | 缓存未命中 | 输出 |
| --- | --- | --- | --- |
| `deepseek-flash` | 0.02 / 0.04 | 1 / 2 | 4 / 8 |
| `deepseek-v4-pro` | 0.15 / 0.30 | 4.5 / 9 | 13.5 / 27 |

格式为 `空闲 / 高峰`。

## 边界与诚实声明

- 金额是**估算**，不包含节假日调价、未来价格变动、平台优惠或退款。
- 只统计当前会话，不包含 subagent 独立会话。
- 上下文联动是可选的；未安装 `billion-context` 或服务不可达时自动隐藏，不影响原有功能。
- 余额来自账号服务，可能有刷新延迟。
- 目前只支持 DeepSeek 模型价格；其他 provider 会回退到 Flash 价格并标记为未定价请求。
- 没有历史趋势、预算告警和团队汇总。

这些边界不是缺陷清单，而是 v1 的产品选择：先把“当前这一眼”做好。

## 后续方向

1. **历史与趋势**：按天、按模型、按会话的回看。
2. **预算**：日/周/会话阈值与提醒。
3. **子树汇总**：把 subagent 成本归并到父会话。
4. **价格中心**：在线价格表、模型映射、手动覆盖。
5. **更好的第一眼**：真实截图、主题适配细节、移动端布局。

## 发布文案（1.0，历史存档）

> **Token Ball 1.0 发布：让 DeepSeek Harness 的花费可见**
>
> 写 Agent 的时候，你有没有想过：这一轮对话到底烧了多少 Token？
>
> Token Ball 是一个 Harness 悬浮球插件。它常驻在界面右下角，显示当前对话的 Token、按官方峰谷价估算的花费，以及你的充值/赠金余额。拖动、点击、收起，不打断对话。
>
> - 会话级 Token 与预估成本
> - 输入 / 输出 / 缓存命中 / 请求数
> - 真实账户余额
> - 明暗主题、位置记忆、近实时刷新
> - 本机计算，不上传对话
>
> 安装：把仓库目录交给 Harness 的插件管理器安装，刷新页面即可。
>
> 它不替代平台账单，但能让你在写下一行代码之前，先知道这一眼大概多少钱。