# deepseek-tavern-script

**Repository Path**: yushui688/deepseek-tavern-script

## Basic Information

- **Project Name**: deepseek-tavern-script
- **Description**: DeepSeek API 使用预测脚本 - SillyTavern 酒馆助手自动更新
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-11
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepSeek 使用预测 - SillyTavern酒馆助手 脚本

实时统计和预测 DeepSeek API 的 token 消耗、费用、预测剩余对话数和缓存命中情况。

## 预览

<p align="center">
  <img src="演示/屏幕截图%202026-06-27%20221118.png" width="18%">
  <img src="演示/屏幕截图%202026-06-27%20221246.png" width="18%">
  <img src="演示/屏幕截图%202026-06-27%20221255.png" width="18%">
  <img src="演示/屏幕截图%202026-06-27%20221307.png" width="18%">
  <img src="演示/屏幕截图%202026-06-27%20221346.png" width="18%">
</p>

## 功能

- **实时统计**：自动记录每次 API 调用的 token 消耗、费用、缓存命中率、耗时和token速率
- **实时预测**：依照历史对话记录消耗，准确预测未来使用趋势和剩余对话轮数
- **余额同步**：通过API同步DS官方账户余额，准确可视
- **多存档管理**：支持多个存档文件，可切换查看对比不同角色卡的统计数据
- **消息对比**：对比不同对话的请求消息，找出缓存发散点
- **统计图表**：Token/费用趋势、缓存命中率曲线、模型汇总列表准确判断token趋势
- **操作便捷**：每张图表独立控制 X 轴范围，支持缩放和平移
- **自动更新**：自动触发更新检查，获取最新版本
- **历史记录导入导出**：完整备份/还原历史记录与统计信息，导出文件不含 API 密钥，旧版本导出文件可在未来版本中继续导入
- **自定义价格与峰谷时段**：自定义模型名称与价格（¥/百万 tokens），自定义高峰时段（支持跨天），兼容未来模型名更新与价格变化

## 下载

前往 [Releases](https://github.com/janmk1453/deepseek-tavern-script/releases) 页面下载最新版本。

| 文件 | 说明 | 推荐 |
|------|------|------|
| `DeepSeek_Statistic_auto_update.json` | 自动更新版（GitHub Pages），导入后自动获取最新脚本 | ✅推荐 |
| `DeepSeek_Statistic_auto_update_jsDelivr_cdn.json` | 自动更新版（jsDelivr CDN），导入后自动获取最新脚本 | 该渠道更新较慢，但国内网络适应性强 |
| `DeepSeek_Statistic_VX.XX.json` | 完整版脚本，需手动导入 | 需要特定版本时使用 |

## 使用方法

### 自动更新（推荐）

1. 下载 `DeepSeek_Statistic_auto_update.json`
2. 在 SillyTavern 的酒馆助手中导入该文件
3. 之后每次启动自动获取最新版本，无需手动更新

### 手动更新

1. 下载 `DeepSeek_Statistic_VX.XX.json`
2. 在 SillyTavern 的酒馆助手中导入该文件
3. 每次更新需重新导入

## 快速开始

1. **配置 API 密钥**：在设置中输入 DeepSeek API 密钥并保存（非必需）
2. **查询余额**：点击「查询」按钮获取账户余额
3. **开始对话**：正常与 AI 对话，插件自动记录统计数据
4. **查看统计**：点击「图表」按钮查看详细统计数据

## 详细功能

### 使用预测

- 依照历史对话记录消耗，准确预测未来使用趋势和剩余对话轮数

### 使用统计

- 总花费（人民币）
- Token 历史消耗
- 输入（命中缓存）/ 输入（未命中缓存）/ 输出
- 加权缓存命中率
- 平均每轮消、平均耗时、平均速率
- 单次请求首字延迟（TTFT，用户发出请求后到首个输出字符出现的时间），在使用详情中查看
- 支出明细（预计节省 / 支出在输入 / 支出在输出）

### 消息对比（beta）

1. 在历史记录中找到想对比的两条消息
2. 前者点击「旧」，后者点击「新」
3. 弹出对比面板显示请求消息的文字差异
4. 差异点即缓存发散起始位置（前 N 条相同为缓存命中阶段）

### 统计图表

- **图 1：Token 趋势** - 显示每次对话的 Token 消耗（命中/未命中/输出）
- **图 2：费用趋势** - 显示每次对话的费用变化
- **图 3：缓存命中率** - 显示缓存命中率的变化曲线
- **图表操作**：滚轮缩放、拖拽平移、重置缩放
- **模型切换**：切换查看不同模型（内置及自定义）的统计数据
- 注意：首次打开图表页面需要加载较长时间，请保证良好网络环境耐心等待

### 存档管理

- 切换不同的存档文件管理多组统计数据
- 删除单个存档或清空全部存档
- 数据保存在 SillyTavern localStorage 中

### 历史记录导入导出

- 在「历史记录」标题行最右侧点击「📤 导出」下载完整数据（全部存档、当前存档、余额、设置、消息计数），导出文件**不含 API 密钥**
- 点击「📥 导入」选择导出的 JSON 文件，可选择「覆盖导入」或「合并导入」
  - 覆盖导入：整体替换当前数据，结果与导出时完全一致
  - 合并导入：仅新增存档或按时间戳合并同存档的历史记录，保留当前余额与设置
- 导入后自动根据历史记录重算所有统计汇总，确保完整正确还原
- 导出文件带格式版本号：旧版本导出的文件可被未来脚本正常导入（向后兼容）；格式结构升级时会保留迁移支持；若文件版本高于脚本支持范围会提示升级脚本

### 设置选项

- **自动校准余额**：设置自动查询余额的间隔
- **自定义余额**：手动设置余额，设置后将覆盖 API 查询值
- **新价格机制**：兼容 DeepSeek 7月中旬后的峰谷定价机制，支持设置生效日期；高峰时段可自定义多个时间段（结束早于开始视为跨天，如 22:00~次日02:00）
- **模型与价格**：自定义模型名称与价格（¥/百万 tokens），内置模型价格可覆盖、不可删除，可新增自定义模型；价格或时段变更后自动按当前配置重算历史费用
- **调试模式**：模拟单次对话的 token 消耗，不产生 API 费用

## TODO

- [ ] 实现更准确的余额预测
- [ ] 可视化使用预测和趋势
- [x] 图表中显示高峰/非高峰时段标记
- [ ] 重构UI
- [x] 实现脚本自动更新

## 已知问题

- 极端窗口比例时面板可能错位
- GitHub Pages 缓存导致自动更新存在十分钟左右延迟，jsDelivr CDN存在超过24小时的延迟
- 面对数百条记录可能存在性能问题

## 技术说明

- **自动更新原理**：通过 GitHub Pages 提供最新的 JavaScript 脚本，SillyTavern 启动时自动加载
- **数据存储**：所有数据保存在 SillyTavern 的 localStorage 中，不会上传到任何服务器
- **API 密钥安全**：密钥使用 XOR 加密存储，但仍建议使用权限受限的 API 密钥

## 许可证

MIT License