# topface

**Repository Path**: kool2017/topface

## Basic Information

- **Project Name**: topface
- **Description**: macOS 端展示 Kimi Code token 额度使用量的悬浮球工具，同时支持通过 USB 串口或蓝牙 BLE 将用量数据推送到 `topface_device` 桌面硬件显示。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kimi Usage Ball

![UI图](UI.png)

macOS 端展示 Kimi Code token 额度使用量的悬浮球工具，同时支持通过 USB 串口或蓝牙 BLE 将用量数据推送到 `topface_device` 桌面硬件显示。

## 功能

- 无边框悬浮圆球，常驻屏幕右下角
- 展示两个指标：
  - 本周用量（已用 / 总额）及重置时间
  - 5 小时用量（已用 / 总额）及重置时间
- 窗口透明度可调（1% ~ 100%），默认 50%
- 鼠标悬浮时窗口变为不透明，移开后恢复配置透明度
- 配置面板打开期间保持不透明，关闭后恢复
- 右键菜单：刷新、配置、退出应用
- 配置面板可实时调整：
  - 透明度
  - 自动刷新间隔（5 / 10 / 30 / 60 分钟）
  - 开机自启动
  - 通信方式（USB 串口 / 蓝牙 BLE）
  - USB 串口模式下可手动扫描并选择串口
- 自动刷新，配置保存在本地 `config.json`
- 首次使用或鉴权过期时自动打开 Kimi 控制台登录窗口，捕获 `authorization` 后持久化到 `auth.json`
- 通过 USB 串口或蓝牙 BLE 连接 `topface_device` 桌面硬件，将用量数据以 NDJSON 格式实时推送到 1.44 寸 TFT 屏幕显示

## 技术栈

- Electron `^31.0.0`
- Vite `^5.3.0`
- 原生 Fetch（Node.js 18+）
- `serialport`（USB 串口通信）
- `@stoprocent/noble`（蓝牙 BLE 通信）

## 开发

```bash
# 安装依赖
pnpm install

# 启动开发模式
npm run dev
```

## 构建与打包

```bash
# 仅构建前端产物
npm run build

# 构建并启动生产版本
npm run start

# 打包为 macOS DMG（支持 x64 / arm64）
npm run dist
```

## 项目结构

```
├── src/
│   ├── main/          # Electron 主进程
│   │   ├── index.js   # 主入口、窗口管理、IPC、接口请求、配置持久化
│   │   ├── hardware.js# 通信方式管理（串口 / BLE 切换）
│   │   ├── device.js  # USB 串口通信：扫描、连接、推送用量
│   │   └── ble.js     # 蓝牙 BLE 通信：NUS 扫描、连接、推送用量
│   ├── preload/       # 预加载脚本，暴露安全的 IPC API
│   └── renderer/      # 渲染进程页面（Vite 构建）
├── dist/              # Vite 构建输出
├── release/           # electron-builder 打包输出
├── package.json
└── vite.config.mjs
```

## 配置说明

配置保存在 Electron `userData` 目录（macOS 下通常为 `~/Library/Application Support/KimiUsageBall/config.json`）：

```json
{
  "opacity": 0.5,
  "refreshIntervalMinutes": 30,
  "openAtLogin": false,
  "commMode": "serial",
  "serialPort": "/dev/tty.usbserial-XXXX"
}
```

| 字段 | 说明 |
|------|------|
| `opacity` | 悬浮球透明度，0.01 ~ 1 |
| `refreshIntervalMinutes` | 自动刷新间隔，可选 5 / 10 / 30 / 60 |
| `openAtLogin` | 是否开机自启动 |
| `commMode` | 通信方式，`serial` 或 `ble` |
| `serialPort` | USB 串口路径，仅在 `commMode` 为 `serial` 时生效 |

## 硬件连接

### USB 串口

- 当 `commMode` 为 `serial` 且 `serialPort` 为空时，应用会按 VID/PID/制造商自动匹配 ESP32 类设备。
- 建议在配置面板中手动扫描并选择目标串口，保存后将只连接该指定串口。
- 修改串口后，应用会自动断开旧连接并重新连接新串口。

### 蓝牙 BLE

- 当 `commMode` 为 `ble` 时，应用扫描 Nordic UART Service（UUID `6e400001-b5a3-f393-e0a9-e50e24dcca9e`）。
- 连接后通过 RX 特征写入用量数据，通过 TX 特征接收 ACK。

## 数据接口

数据来自 `https://www.kimi.com/apiv2/kimi.gateway.billing.v1.BillingService/GetUsages`，通过请求头中的 `authorization` 鉴权。鉴权信息从登录窗口的网络请求中自动捕获。

## 授权文件

授权信息保存在 `userData/auth.json`：

```json
{
  "token": "Bearer xxx",
  "deviceId": "xxx"
}
```

> 注意：`auth.json` 包含用户敏感鉴权信息，请勿提交到版本控制。