myccusage 1.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- myccusage-1.1.0/LICENSE +21 -0
- myccusage-1.1.0/PKG-INFO +320 -0
- myccusage-1.1.0/README.md +283 -0
- myccusage-1.1.0/myccusage.egg-info/PKG-INFO +320 -0
- myccusage-1.1.0/myccusage.egg-info/SOURCES.txt +16 -0
- myccusage-1.1.0/myccusage.egg-info/dependency_links.txt +1 -0
- myccusage-1.1.0/myccusage.egg-info/entry_points.txt +3 -0
- myccusage-1.1.0/myccusage.egg-info/top_level.txt +1 -0
- myccusage-1.1.0/myccusage_lib/__init__.py +5 -0
- myccusage-1.1.0/myccusage_lib/cli.py +473 -0
- myccusage-1.1.0/myccusage_lib/core.py +821 -0
- myccusage-1.1.0/myccusage_lib/web/__init__.py +4 -0
- myccusage-1.1.0/myccusage_lib/web/server.py +227 -0
- myccusage-1.1.0/myccusage_lib/web/static/app.js +1797 -0
- myccusage-1.1.0/myccusage_lib/web/static/index.html +399 -0
- myccusage-1.1.0/myccusage_lib/web/static/style.css +1574 -0
- myccusage-1.1.0/pyproject.toml +41 -0
- myccusage-1.1.0/setup.cfg +4 -0
myccusage-1.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Richard Huang
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
myccusage-1.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,320 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: myccusage
|
|
3
|
+
Version: 1.1.0
|
|
4
|
+
Summary: Multi-Agent session usage analytics and DeepSeek-V4-Flash cost estimator
|
|
5
|
+
Author-email: Richard Huang <RichardHuang0001@users.noreply.github.com>
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2026 Richard Huang
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Keywords: claude-code,antigravity,deepseek,llm-cost,token-usage,developer-tools,cli
|
|
29
|
+
Classifier: Programming Language :: Python :: 3
|
|
30
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
31
|
+
Classifier: Operating System :: OS Independent
|
|
32
|
+
Classifier: Environment :: Console
|
|
33
|
+
Requires-Python: >=3.8
|
|
34
|
+
Description-Content-Type: text/markdown
|
|
35
|
+
License-File: LICENSE
|
|
36
|
+
Dynamic: license-file
|
|
37
|
+
|
|
38
|
+
# myccusage
|
|
39
|
+
|
|
40
|
+
`myccusage` 是一个专为开发者打造的多 AI 编程 Agent（Antigravity、Claude Code、Hermes、Codex、Grok、Pi、OpenCode）本地会话用量分析与 **DeepSeek-V4-Flash 高峰期等效计费** 命令行工具。
|
|
41
|
+
|
|
42
|
+
支持极速双模分流（默认每日账本模式 vs 项目总览模式），完美解决多日跨度会话导致的日消耗漂移与前日用量被“窃取”问题。
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 🌟 核心特性
|
|
47
|
+
|
|
48
|
+
### 1. 方案 A：双模分流模式 (Dual-Mode CLI)
|
|
49
|
+
- **`-d` / `--daily` [默认模式]：每日会话账本模式**
|
|
50
|
+
- **核心设计**：“此日、此 Session”。如果一个会话跨越了昨天与今天，今天只统计**今天实际发生**的 Token 增量，昨天只保留昨天实际发生的净消耗。
|
|
51
|
+
- **防漂移日/周小计**：每日小计与每周小计严格对应真实发生额，绝不混淆前日用量。
|
|
52
|
+
- **极速秒开智能缓存 (`~/.cache/myccusage/`)**：历史已结账日自动落盘缓存，仅对“跨日活动日”与“今日”进行精确切片同步，7 个 Agent 均在 1~2 秒内秒级出表。
|
|
53
|
+
- **`-s` / `--session`：项目全生命周期总览模式**
|
|
54
|
+
- **核心设计**：专注于每个 Project / Session 从创建到当前的总消耗，帮助你直观评估一个大型工程任务、代码重构项目的全生命周期总成本。
|
|
55
|
+
- 支持配合 `-t` / `--tokens` 找出消耗最大的“Token 吞吐大户”项目。
|
|
56
|
+
|
|
57
|
+
### 2. 输出排序优化
|
|
58
|
+
- 默认采用**时间正序（最新在最底部）**，打开终端查看即直接落在最新日期与最新会话上，省去每次手动向下滑动的繁琐操作。
|
|
59
|
+
- 每日小计、每周小计自然呈现在对应周期下方。
|
|
60
|
+
|
|
61
|
+
### 3. 严格的 Token 守恒与 DeepSeek-V4-Flash 等效计费
|
|
62
|
+
- 严格遵循：`总 Token = Input + Cache + Output`
|
|
63
|
+
- **Input（输入未命中）**：¥3.00 / 1M Tokens
|
|
64
|
+
- **Cache（KV 缓存命中）**：¥0.10 / 1M Tokens
|
|
65
|
+
- **Output（输出 + 思维链/Reasoning）**：¥9.00 / 1M Tokens
|
|
66
|
+
- 自动转换等效人民币（¥）与等效美元（$）。
|
|
67
|
+
|
|
68
|
+
### 4. 深度原生会话标题与元数据解析
|
|
69
|
+
全自动从底层数据源提取真实提问或项目标题，告别冷冰冰的 Session ID：
|
|
70
|
+
- **Google Antigravity**：从 `agyhub_summaries_proto.pb` 二进制反序列化提炼，回退解析 `transcript.jsonl` 首行 prompt。
|
|
71
|
+
- **Claude Code**：解析 `history.jsonl` 与各项目日志 `.claude/projects/*/*.jsonl`。
|
|
72
|
+
- **Hermes Agent**：直接读取 `.hermes/state.db` SQLite 数据库会话标题与精确时间。
|
|
73
|
+
- **OpenAI Codex**：解析 `.codex/session_index.jsonl` 与各 session rollout 记录。
|
|
74
|
+
- **Grok**：读取 `.grok/sessions/session_search.sqlite` 与 `prompt_history.jsonl`。
|
|
75
|
+
- **Pi Agent**：读取 `.pi/agent/sessions/*/*.jsonl` 第一轮消息 prompt。
|
|
76
|
+
- **OpenCode**：连接 `.local/share/opencode/opencode.db` 提取会话主题。
|
|
77
|
+
|
|
78
|
+
### 5. 现代化 Web 前端 Dashboard 仪表盘 (`--web` / `-w`)
|
|
79
|
+
- **一键免构建秒级启动**：运行 `myccusage --web` 自动开启本地轻量服务并打开默认浏览器，零第三方 pip / npm 依赖。
|
|
80
|
+
- **全 Agent 全景对比**：支持在一张看板上汇总 7 大 Agent 的总支出与用量分布，直观对比各大 AI 助手的使用频度。
|
|
81
|
+
- **趋势与构成可视化**：内置每日堆叠趋势图（Output / Input Miss / Cache Hit）与费用走势双轴分析，以及 Token 占比环形图。
|
|
82
|
+
- **客户端毫秒级检索**：即时模糊搜索标题与 Session ID，支持按周、按日树状层级折叠与一键复制 Session ID。
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 🏛️ 系统架构设计与调用链
|
|
87
|
+
|
|
88
|
+
`myccusage` 采用极轻量、高内聚的分层架构，无任何外部重型依赖，整体由 **CLI 参数路由层**、**双轨元数据提取引擎**、**数据切片与两级缓存层**、**Token 计价内核** 以及 **自适应终端渲染器** 组成。
|
|
89
|
+
|
|
90
|
+
### 1. 系统架构分层 (Architecture Layers)
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
94
|
+
│ User Terminal / CLI Interface │
|
|
95
|
+
│ myccusage [--agy|--claude|--hermes|...] [-d|-s] [-t] │
|
|
96
|
+
└────────────────────────────────────┬────────────────────────────────────┘
|
|
97
|
+
│
|
|
98
|
+
▼
|
|
99
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
100
|
+
│ 1. 参数路由与配置解析 (Argument Routing & Config Resolver) │
|
|
101
|
+
│ - 识别目标 Agent 类型（映射至底层 ccusage 子命令） │
|
|
102
|
+
│ - 模式仲裁：-d (默认每日账本) vs -s (项目全生命周期) │
|
|
103
|
+
│ - 排序控制：时间正序 (最新在最底) vs -t (Token 用量降序) │
|
|
104
|
+
└───────────────────┬─────────────────────────────────┬───────────────────┘
|
|
105
|
+
│ │
|
|
106
|
+
▼ ▼
|
|
107
|
+
┌──────────────────────────────────────┐ ┌───────────────────────────────┐
|
|
108
|
+
│ 2. 原生元数据提取引擎 │ │ 3. 数据切片与智能缓存层 │
|
|
109
|
+
│ (Native Title & Metadata Engine) │ │ (Slice Engine & Cache) │
|
|
110
|
+
│ - Antigravity: protobuf / jsonl │ │ - 全局日度基准：ccusage daily │
|
|
111
|
+
│ - Claude Code: history & projects │ │ - 历史切片缓存：~/.cache/... │
|
|
112
|
+
│ - Hermes/OpenCode: SQLite DB │ │ - 跨日单日精确切片： │
|
|
113
|
+
│ - Codex/Grok/Pi: session indices │ │ ccusage session -s D -u D │
|
|
114
|
+
└───────────────────┬──────────────────┘ └───────────────┬───────────────┘
|
|
115
|
+
│ │
|
|
116
|
+
└──────────────────┬──────────────────┘
|
|
117
|
+
│
|
|
118
|
+
▼
|
|
119
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
120
|
+
│ 4. 计费与聚合内核 (Accounting & Aggregation Core) │
|
|
121
|
+
│ - 约束校验：Total = Input + Cache + Output │
|
|
122
|
+
│ - DeepSeek-V4-Flash 官方高峰期定价模型 (未命中¥3/M, 命中¥0.1/M, 输出¥9/M)│
|
|
123
|
+
│ - 分层聚合：会话明细 -> 日计 (含星期指示) -> 周计 (ISO-W) -> 全周期汇总 │
|
|
124
|
+
└──────────────────────────────────────┬──────────────────────────────────┘
|
|
125
|
+
│
|
|
126
|
+
▼
|
|
127
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
128
|
+
│ 5. 终端动态排版与渲染器 (Terminal Responsive Formatter) │
|
|
129
|
+
│ - East Asian Width 宽度计算（确保中英文字符在终端严格对齐） │
|
|
130
|
+
│ - 终端宽度动态感知与智能截断 (shutil.get_terminal_size) │
|
|
131
|
+
│ - 视口友好渲染（最新会话直接沉底显示） │
|
|
132
|
+
└─────────────────────────────────────────────────────────────────────────┘
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 2. 核心端到端调用链 (Execution Call Flow)
|
|
136
|
+
|
|
137
|
+
#### 模式一：`-d` / `--daily` [默认] 每日账本模式调用链
|
|
138
|
+
|
|
139
|
+
```mermaid
|
|
140
|
+
sequenceDiagram
|
|
141
|
+
autonumber
|
|
142
|
+
actor User as 用户 (CLI)
|
|
143
|
+
participant Core as myccusage 主程序
|
|
144
|
+
participant NativeDB as 本地 Agent 状态源 (SQLite/Proto/JSONL)
|
|
145
|
+
participant Cache as 本地日切片缓存 (~/.cache/myccusage/)
|
|
146
|
+
participant CCUsage as 底层 ccusage CLI
|
|
147
|
+
participant Renderer as 终端排版渲染器
|
|
148
|
+
|
|
149
|
+
User->>Core: 运行 myccusage --agy (默认 -d)
|
|
150
|
+
Core->>NativeDB: 并行提取所有 Session 的真实标题与修改时间映射 (Map[SessionID -> Title])
|
|
151
|
+
Core->>CCUsage: 执行 ccusage <agent> daily --json (获取所有有活动的日期基准列表)
|
|
152
|
+
CCUsage-->>Core: 返回活动日序列 [D1, D2, ... D_today]
|
|
153
|
+
|
|
154
|
+
loop 遍历每一个活动日 D_i
|
|
155
|
+
alt D_i 为历史日 且 在 Cache 中命中
|
|
156
|
+
Core->>Cache: 直接读取 D_i 的会话切片列表
|
|
157
|
+
Cache-->>Core: 0.1ms 瞬时返回精准切片数据
|
|
158
|
+
else D_i 为今日 (D_today) 或 首次未缓存的历史日
|
|
159
|
+
Core->>CCUsage: 执行 ccusage <agent> session -s D_i -u D_i --json
|
|
160
|
+
CCUsage-->>Core: 返回该日内发生的 turns 聚合记录 (此日此Session)
|
|
161
|
+
opt D_i 为历史日
|
|
162
|
+
Core->>Cache: 将切片数据写入 ~/.cache/myccusage/{agent}_daily.json
|
|
163
|
+
end
|
|
164
|
+
end
|
|
165
|
+
end
|
|
166
|
+
|
|
167
|
+
Core->>Core: 组装每笔日度明细，计算 DeepSeek-V4 等效价格，计算日小计与周小计
|
|
168
|
+
Core->>Renderer: 注入会话标题映射，按时间正序排列 (最新在最底)
|
|
169
|
+
Renderer->>User: 终端输出格式化表格，光标直接落在最新记录与汇总
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
#### 模式二：`-s` / `--session` 项目全生命周期总览模式调用链
|
|
173
|
+
|
|
174
|
+
```mermaid
|
|
175
|
+
sequenceDiagram
|
|
176
|
+
autonumber
|
|
177
|
+
actor User as 用户 (CLI)
|
|
178
|
+
participant Core as myccusage 主程序
|
|
179
|
+
participant NativeDB as 本地 Agent 状态源
|
|
180
|
+
participant CCUsage as 底层 ccusage CLI
|
|
181
|
+
participant Renderer as 终端排版渲染器
|
|
182
|
+
|
|
183
|
+
User->>Core: 运行 myccusage --agy -s [-t]
|
|
184
|
+
Core->>NativeDB: 提取 SessionID 标题库
|
|
185
|
+
Core->>CCUsage: 执行 ccusage <agent> session --json (一次性拉取全量会话总消耗)
|
|
186
|
+
CCUsage-->>Core: 返回各会话全生命周期 Cumulative Tokens
|
|
187
|
+
Core->>Core: 按各会话最后活跃时间 (或 -t Token 用量) 进行排序
|
|
188
|
+
Core->>Core: 计算全周期 DeepSeek 等效总费用与日/周活跃分布
|
|
189
|
+
Core->>Renderer: 注入标题并进行中英文对齐排版
|
|
190
|
+
Renderer->>User: 终端输出项目总览报表
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## 🚀 支持的 Agent 参数
|
|
196
|
+
|
|
197
|
+
| Agent | 参数 | 对应官方 CLI | 数据源解析机制 |
|
|
198
|
+
| :--- | :--- | :--- | :--- |
|
|
199
|
+
| **Google Antigravity** | `--agy`, `--antigravity` | Antigravity App / CLI | `agyhub_summaries_proto.pb` + `transcript.jsonl` |
|
|
200
|
+
| **Claude Code** | `--claude` | `claude` | `history.jsonl` + `.claude/projects/*/*.jsonl` |
|
|
201
|
+
| **Hermes Agent** | `--hermes` | `hermes` | `.hermes/state.db` (SQLite) |
|
|
202
|
+
| **OpenAI Codex** | `--codex` | `codex` | `.codex/session_index.jsonl` + session logs |
|
|
203
|
+
| **Grok** | `--grok` | `grok` | `.grok/sessions/session_search.sqlite` + `prompt_history.jsonl` |
|
|
204
|
+
| **Pi Agent** | `--pi` | `pi` | `.pi/agent/sessions/*/*.jsonl` |
|
|
205
|
+
| **OpenCode** | `--opencode` | `opencode` | `.local/share/opencode/opencode.db` (SQLite) |
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## 🛠️ 前置条件 (Prerequisites)
|
|
210
|
+
|
|
211
|
+
本项目基于开源的 [ccusage](https://github.com/ryoppippi/ccusage) 获取底层基础切片，请确保已安装 `ccusage`（二选一即可）：
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
# 使用 npm 安装
|
|
215
|
+
npm install -g ccusage
|
|
216
|
+
|
|
217
|
+
# 或使用 bun 安装
|
|
218
|
+
bun add -g ccusage
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## 💻 快速安装
|
|
224
|
+
|
|
225
|
+
本项目采用现代 Python 标准打包，同时提供**一键脚本**与 **pip 直装**两种体验：
|
|
226
|
+
|
|
227
|
+
### 方式 1：一行命令通过 pip 直装（最推荐）
|
|
228
|
+
|
|
229
|
+
无需手动克隆仓库，直接在终端执行：
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
# 通过 GitHub 直装（自动注册 myccusage 和 ccusage-sessions 全局命令）
|
|
233
|
+
pip install git+https://github.com/RichardHuang0001/ccusage-sessions.git
|
|
234
|
+
|
|
235
|
+
# 国内网络加速镜像直装
|
|
236
|
+
pip install git+https://ghproxy.net/https://github.com/RichardHuang0001/ccusage-sessions.git
|
|
237
|
+
|
|
238
|
+
# 或使用现代隔离工具 pipx / uv
|
|
239
|
+
pipx install git+https://github.com/RichardHuang0001/ccusage-sessions.git
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
### 方式 2：克隆仓库并使用一键脚本配置
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
# 1. 克隆仓库
|
|
246
|
+
git clone https://github.com/RichardHuang0001/ccusage-sessions.git
|
|
247
|
+
cd ccusage-sessions
|
|
248
|
+
|
|
249
|
+
# 2. 运行一键配置脚本（自动检查依赖、配置 PATH 与全局软链接）
|
|
250
|
+
./install.sh
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## 📖 使用示例
|
|
256
|
+
|
|
257
|
+
### 1. 默认每日会话账本模式 (`-d` / 默认)
|
|
258
|
+
精准分列每日净消耗，最新记录在底部：
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
# 查看 Antigravity 每日账本
|
|
262
|
+
myccusage --agy
|
|
263
|
+
|
|
264
|
+
# 查看 Claude Code 每日账本
|
|
265
|
+
myccusage --claude
|
|
266
|
+
|
|
267
|
+
# 查看 Codex / Grok / OpenCode 每日账本
|
|
268
|
+
myccusage --codex
|
|
269
|
+
myccusage --grok
|
|
270
|
+
myccusage --opencode
|
|
271
|
+
|
|
272
|
+
# 旧命令 ccusage-sessions 保持完全兼容
|
|
273
|
+
ccusage-sessions --agy
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
### 2. 项目全生命周期总览模式 (`-s`)
|
|
277
|
+
查看每个项目从头到尾的累计用量：
|
|
278
|
+
|
|
279
|
+
```bash
|
|
280
|
+
# 查看 Antigravity 所有项目累计用量
|
|
281
|
+
myccusage --agy -s
|
|
282
|
+
|
|
283
|
+
# 按累计 Token 消耗排行，揪出最耗费的项目
|
|
284
|
+
myccusage --agy -s -t
|
|
285
|
+
myccusage --claude -s -t
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
### 3. 现代化网页仪表盘模式 (`--web` / `-w`)
|
|
289
|
+
启动本地轻量 Web 服务，在浏览器中查看全景看板与可视化图表：
|
|
290
|
+
|
|
291
|
+
```bash
|
|
292
|
+
# 启动 Web Dashboard (默认端口 8488，并自动在浏览器中打开)
|
|
293
|
+
myccusage --web
|
|
294
|
+
|
|
295
|
+
# 指定端口启动
|
|
296
|
+
myccusage --web --port 9000
|
|
297
|
+
|
|
298
|
+
# 启动并直接聚焦特定 Agent
|
|
299
|
+
myccusage --claude --web
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### 4. 查看帮助信息
|
|
303
|
+
```bash
|
|
304
|
+
myccusage -h
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## 🔒 隐私与安全承诺 (Privacy & Security)
|
|
310
|
+
|
|
311
|
+
- **100% 纯本地离线运行**：所有原生会话标题提取、Token 切片计算均在本地设备完成，绝不向任何第三方云端或个人服务器上传任何代码、提问内容或使用量元数据。
|
|
312
|
+
- **零遥测追踪 (No Telemetry)**：本项目不包含任何埋点、统计或追踪代码。
|
|
313
|
+
- **本地回环网络安全**：内置 Web 仪表盘默认严格绑定 `127.0.0.1` 本地回环地址，关闭浏览器网页后看门狗会自动安全退出，绝不暴露公网或局域网端口。
|
|
314
|
+
|
|
315
|
+
---
|
|
316
|
+
|
|
317
|
+
## 📄 开源许可
|
|
318
|
+
|
|
319
|
+
[MIT License](LICENSE) © 2026 Richard Huang
|
|
320
|
+
|
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
# myccusage
|
|
2
|
+
|
|
3
|
+
`myccusage` 是一个专为开发者打造的多 AI 编程 Agent（Antigravity、Claude Code、Hermes、Codex、Grok、Pi、OpenCode）本地会话用量分析与 **DeepSeek-V4-Flash 高峰期等效计费** 命令行工具。
|
|
4
|
+
|
|
5
|
+
支持极速双模分流（默认每日账本模式 vs 项目总览模式），完美解决多日跨度会话导致的日消耗漂移与前日用量被“窃取”问题。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 🌟 核心特性
|
|
10
|
+
|
|
11
|
+
### 1. 方案 A：双模分流模式 (Dual-Mode CLI)
|
|
12
|
+
- **`-d` / `--daily` [默认模式]：每日会话账本模式**
|
|
13
|
+
- **核心设计**：“此日、此 Session”。如果一个会话跨越了昨天与今天，今天只统计**今天实际发生**的 Token 增量，昨天只保留昨天实际发生的净消耗。
|
|
14
|
+
- **防漂移日/周小计**：每日小计与每周小计严格对应真实发生额，绝不混淆前日用量。
|
|
15
|
+
- **极速秒开智能缓存 (`~/.cache/myccusage/`)**：历史已结账日自动落盘缓存，仅对“跨日活动日”与“今日”进行精确切片同步，7 个 Agent 均在 1~2 秒内秒级出表。
|
|
16
|
+
- **`-s` / `--session`：项目全生命周期总览模式**
|
|
17
|
+
- **核心设计**：专注于每个 Project / Session 从创建到当前的总消耗，帮助你直观评估一个大型工程任务、代码重构项目的全生命周期总成本。
|
|
18
|
+
- 支持配合 `-t` / `--tokens` 找出消耗最大的“Token 吞吐大户”项目。
|
|
19
|
+
|
|
20
|
+
### 2. 输出排序优化
|
|
21
|
+
- 默认采用**时间正序（最新在最底部）**，打开终端查看即直接落在最新日期与最新会话上，省去每次手动向下滑动的繁琐操作。
|
|
22
|
+
- 每日小计、每周小计自然呈现在对应周期下方。
|
|
23
|
+
|
|
24
|
+
### 3. 严格的 Token 守恒与 DeepSeek-V4-Flash 等效计费
|
|
25
|
+
- 严格遵循：`总 Token = Input + Cache + Output`
|
|
26
|
+
- **Input（输入未命中）**：¥3.00 / 1M Tokens
|
|
27
|
+
- **Cache（KV 缓存命中）**：¥0.10 / 1M Tokens
|
|
28
|
+
- **Output（输出 + 思维链/Reasoning）**：¥9.00 / 1M Tokens
|
|
29
|
+
- 自动转换等效人民币（¥）与等效美元（$）。
|
|
30
|
+
|
|
31
|
+
### 4. 深度原生会话标题与元数据解析
|
|
32
|
+
全自动从底层数据源提取真实提问或项目标题，告别冷冰冰的 Session ID：
|
|
33
|
+
- **Google Antigravity**：从 `agyhub_summaries_proto.pb` 二进制反序列化提炼，回退解析 `transcript.jsonl` 首行 prompt。
|
|
34
|
+
- **Claude Code**：解析 `history.jsonl` 与各项目日志 `.claude/projects/*/*.jsonl`。
|
|
35
|
+
- **Hermes Agent**：直接读取 `.hermes/state.db` SQLite 数据库会话标题与精确时间。
|
|
36
|
+
- **OpenAI Codex**：解析 `.codex/session_index.jsonl` 与各 session rollout 记录。
|
|
37
|
+
- **Grok**：读取 `.grok/sessions/session_search.sqlite` 与 `prompt_history.jsonl`。
|
|
38
|
+
- **Pi Agent**：读取 `.pi/agent/sessions/*/*.jsonl` 第一轮消息 prompt。
|
|
39
|
+
- **OpenCode**：连接 `.local/share/opencode/opencode.db` 提取会话主题。
|
|
40
|
+
|
|
41
|
+
### 5. 现代化 Web 前端 Dashboard 仪表盘 (`--web` / `-w`)
|
|
42
|
+
- **一键免构建秒级启动**：运行 `myccusage --web` 自动开启本地轻量服务并打开默认浏览器，零第三方 pip / npm 依赖。
|
|
43
|
+
- **全 Agent 全景对比**：支持在一张看板上汇总 7 大 Agent 的总支出与用量分布，直观对比各大 AI 助手的使用频度。
|
|
44
|
+
- **趋势与构成可视化**：内置每日堆叠趋势图（Output / Input Miss / Cache Hit）与费用走势双轴分析，以及 Token 占比环形图。
|
|
45
|
+
- **客户端毫秒级检索**：即时模糊搜索标题与 Session ID，支持按周、按日树状层级折叠与一键复制 Session ID。
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## 🏛️ 系统架构设计与调用链
|
|
50
|
+
|
|
51
|
+
`myccusage` 采用极轻量、高内聚的分层架构，无任何外部重型依赖，整体由 **CLI 参数路由层**、**双轨元数据提取引擎**、**数据切片与两级缓存层**、**Token 计价内核** 以及 **自适应终端渲染器** 组成。
|
|
52
|
+
|
|
53
|
+
### 1. 系统架构分层 (Architecture Layers)
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
57
|
+
│ User Terminal / CLI Interface │
|
|
58
|
+
│ myccusage [--agy|--claude|--hermes|...] [-d|-s] [-t] │
|
|
59
|
+
└────────────────────────────────────┬────────────────────────────────────┘
|
|
60
|
+
│
|
|
61
|
+
▼
|
|
62
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
63
|
+
│ 1. 参数路由与配置解析 (Argument Routing & Config Resolver) │
|
|
64
|
+
│ - 识别目标 Agent 类型（映射至底层 ccusage 子命令） │
|
|
65
|
+
│ - 模式仲裁：-d (默认每日账本) vs -s (项目全生命周期) │
|
|
66
|
+
│ - 排序控制：时间正序 (最新在最底) vs -t (Token 用量降序) │
|
|
67
|
+
└───────────────────┬─────────────────────────────────┬───────────────────┘
|
|
68
|
+
│ │
|
|
69
|
+
▼ ▼
|
|
70
|
+
┌──────────────────────────────────────┐ ┌───────────────────────────────┐
|
|
71
|
+
│ 2. 原生元数据提取引擎 │ │ 3. 数据切片与智能缓存层 │
|
|
72
|
+
│ (Native Title & Metadata Engine) │ │ (Slice Engine & Cache) │
|
|
73
|
+
│ - Antigravity: protobuf / jsonl │ │ - 全局日度基准：ccusage daily │
|
|
74
|
+
│ - Claude Code: history & projects │ │ - 历史切片缓存：~/.cache/... │
|
|
75
|
+
│ - Hermes/OpenCode: SQLite DB │ │ - 跨日单日精确切片： │
|
|
76
|
+
│ - Codex/Grok/Pi: session indices │ │ ccusage session -s D -u D │
|
|
77
|
+
└───────────────────┬──────────────────┘ └───────────────┬───────────────┘
|
|
78
|
+
│ │
|
|
79
|
+
└──────────────────┬──────────────────┘
|
|
80
|
+
│
|
|
81
|
+
▼
|
|
82
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
83
|
+
│ 4. 计费与聚合内核 (Accounting & Aggregation Core) │
|
|
84
|
+
│ - 约束校验：Total = Input + Cache + Output │
|
|
85
|
+
│ - DeepSeek-V4-Flash 官方高峰期定价模型 (未命中¥3/M, 命中¥0.1/M, 输出¥9/M)│
|
|
86
|
+
│ - 分层聚合：会话明细 -> 日计 (含星期指示) -> 周计 (ISO-W) -> 全周期汇总 │
|
|
87
|
+
└──────────────────────────────────────┬──────────────────────────────────┘
|
|
88
|
+
│
|
|
89
|
+
▼
|
|
90
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
91
|
+
│ 5. 终端动态排版与渲染器 (Terminal Responsive Formatter) │
|
|
92
|
+
│ - East Asian Width 宽度计算（确保中英文字符在终端严格对齐） │
|
|
93
|
+
│ - 终端宽度动态感知与智能截断 (shutil.get_terminal_size) │
|
|
94
|
+
│ - 视口友好渲染（最新会话直接沉底显示） │
|
|
95
|
+
└─────────────────────────────────────────────────────────────────────────┘
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### 2. 核心端到端调用链 (Execution Call Flow)
|
|
99
|
+
|
|
100
|
+
#### 模式一：`-d` / `--daily` [默认] 每日账本模式调用链
|
|
101
|
+
|
|
102
|
+
```mermaid
|
|
103
|
+
sequenceDiagram
|
|
104
|
+
autonumber
|
|
105
|
+
actor User as 用户 (CLI)
|
|
106
|
+
participant Core as myccusage 主程序
|
|
107
|
+
participant NativeDB as 本地 Agent 状态源 (SQLite/Proto/JSONL)
|
|
108
|
+
participant Cache as 本地日切片缓存 (~/.cache/myccusage/)
|
|
109
|
+
participant CCUsage as 底层 ccusage CLI
|
|
110
|
+
participant Renderer as 终端排版渲染器
|
|
111
|
+
|
|
112
|
+
User->>Core: 运行 myccusage --agy (默认 -d)
|
|
113
|
+
Core->>NativeDB: 并行提取所有 Session 的真实标题与修改时间映射 (Map[SessionID -> Title])
|
|
114
|
+
Core->>CCUsage: 执行 ccusage <agent> daily --json (获取所有有活动的日期基准列表)
|
|
115
|
+
CCUsage-->>Core: 返回活动日序列 [D1, D2, ... D_today]
|
|
116
|
+
|
|
117
|
+
loop 遍历每一个活动日 D_i
|
|
118
|
+
alt D_i 为历史日 且 在 Cache 中命中
|
|
119
|
+
Core->>Cache: 直接读取 D_i 的会话切片列表
|
|
120
|
+
Cache-->>Core: 0.1ms 瞬时返回精准切片数据
|
|
121
|
+
else D_i 为今日 (D_today) 或 首次未缓存的历史日
|
|
122
|
+
Core->>CCUsage: 执行 ccusage <agent> session -s D_i -u D_i --json
|
|
123
|
+
CCUsage-->>Core: 返回该日内发生的 turns 聚合记录 (此日此Session)
|
|
124
|
+
opt D_i 为历史日
|
|
125
|
+
Core->>Cache: 将切片数据写入 ~/.cache/myccusage/{agent}_daily.json
|
|
126
|
+
end
|
|
127
|
+
end
|
|
128
|
+
end
|
|
129
|
+
|
|
130
|
+
Core->>Core: 组装每笔日度明细，计算 DeepSeek-V4 等效价格，计算日小计与周小计
|
|
131
|
+
Core->>Renderer: 注入会话标题映射，按时间正序排列 (最新在最底)
|
|
132
|
+
Renderer->>User: 终端输出格式化表格，光标直接落在最新记录与汇总
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
#### 模式二：`-s` / `--session` 项目全生命周期总览模式调用链
|
|
136
|
+
|
|
137
|
+
```mermaid
|
|
138
|
+
sequenceDiagram
|
|
139
|
+
autonumber
|
|
140
|
+
actor User as 用户 (CLI)
|
|
141
|
+
participant Core as myccusage 主程序
|
|
142
|
+
participant NativeDB as 本地 Agent 状态源
|
|
143
|
+
participant CCUsage as 底层 ccusage CLI
|
|
144
|
+
participant Renderer as 终端排版渲染器
|
|
145
|
+
|
|
146
|
+
User->>Core: 运行 myccusage --agy -s [-t]
|
|
147
|
+
Core->>NativeDB: 提取 SessionID 标题库
|
|
148
|
+
Core->>CCUsage: 执行 ccusage <agent> session --json (一次性拉取全量会话总消耗)
|
|
149
|
+
CCUsage-->>Core: 返回各会话全生命周期 Cumulative Tokens
|
|
150
|
+
Core->>Core: 按各会话最后活跃时间 (或 -t Token 用量) 进行排序
|
|
151
|
+
Core->>Core: 计算全周期 DeepSeek 等效总费用与日/周活跃分布
|
|
152
|
+
Core->>Renderer: 注入标题并进行中英文对齐排版
|
|
153
|
+
Renderer->>User: 终端输出项目总览报表
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## 🚀 支持的 Agent 参数
|
|
159
|
+
|
|
160
|
+
| Agent | 参数 | 对应官方 CLI | 数据源解析机制 |
|
|
161
|
+
| :--- | :--- | :--- | :--- |
|
|
162
|
+
| **Google Antigravity** | `--agy`, `--antigravity` | Antigravity App / CLI | `agyhub_summaries_proto.pb` + `transcript.jsonl` |
|
|
163
|
+
| **Claude Code** | `--claude` | `claude` | `history.jsonl` + `.claude/projects/*/*.jsonl` |
|
|
164
|
+
| **Hermes Agent** | `--hermes` | `hermes` | `.hermes/state.db` (SQLite) |
|
|
165
|
+
| **OpenAI Codex** | `--codex` | `codex` | `.codex/session_index.jsonl` + session logs |
|
|
166
|
+
| **Grok** | `--grok` | `grok` | `.grok/sessions/session_search.sqlite` + `prompt_history.jsonl` |
|
|
167
|
+
| **Pi Agent** | `--pi` | `pi` | `.pi/agent/sessions/*/*.jsonl` |
|
|
168
|
+
| **OpenCode** | `--opencode` | `opencode` | `.local/share/opencode/opencode.db` (SQLite) |
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## 🛠️ 前置条件 (Prerequisites)
|
|
173
|
+
|
|
174
|
+
本项目基于开源的 [ccusage](https://github.com/ryoppippi/ccusage) 获取底层基础切片，请确保已安装 `ccusage`（二选一即可）：
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
# 使用 npm 安装
|
|
178
|
+
npm install -g ccusage
|
|
179
|
+
|
|
180
|
+
# 或使用 bun 安装
|
|
181
|
+
bun add -g ccusage
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## 💻 快速安装
|
|
187
|
+
|
|
188
|
+
本项目采用现代 Python 标准打包，同时提供**一键脚本**与 **pip 直装**两种体验：
|
|
189
|
+
|
|
190
|
+
### 方式 1：一行命令通过 pip 直装（最推荐）
|
|
191
|
+
|
|
192
|
+
无需手动克隆仓库，直接在终端执行：
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
# 通过 GitHub 直装（自动注册 myccusage 和 ccusage-sessions 全局命令）
|
|
196
|
+
pip install git+https://github.com/RichardHuang0001/ccusage-sessions.git
|
|
197
|
+
|
|
198
|
+
# 国内网络加速镜像直装
|
|
199
|
+
pip install git+https://ghproxy.net/https://github.com/RichardHuang0001/ccusage-sessions.git
|
|
200
|
+
|
|
201
|
+
# 或使用现代隔离工具 pipx / uv
|
|
202
|
+
pipx install git+https://github.com/RichardHuang0001/ccusage-sessions.git
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### 方式 2：克隆仓库并使用一键脚本配置
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
# 1. 克隆仓库
|
|
209
|
+
git clone https://github.com/RichardHuang0001/ccusage-sessions.git
|
|
210
|
+
cd ccusage-sessions
|
|
211
|
+
|
|
212
|
+
# 2. 运行一键配置脚本（自动检查依赖、配置 PATH 与全局软链接）
|
|
213
|
+
./install.sh
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## 📖 使用示例
|
|
219
|
+
|
|
220
|
+
### 1. 默认每日会话账本模式 (`-d` / 默认)
|
|
221
|
+
精准分列每日净消耗，最新记录在底部：
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
# 查看 Antigravity 每日账本
|
|
225
|
+
myccusage --agy
|
|
226
|
+
|
|
227
|
+
# 查看 Claude Code 每日账本
|
|
228
|
+
myccusage --claude
|
|
229
|
+
|
|
230
|
+
# 查看 Codex / Grok / OpenCode 每日账本
|
|
231
|
+
myccusage --codex
|
|
232
|
+
myccusage --grok
|
|
233
|
+
myccusage --opencode
|
|
234
|
+
|
|
235
|
+
# 旧命令 ccusage-sessions 保持完全兼容
|
|
236
|
+
ccusage-sessions --agy
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### 2. 项目全生命周期总览模式 (`-s`)
|
|
240
|
+
查看每个项目从头到尾的累计用量：
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
# 查看 Antigravity 所有项目累计用量
|
|
244
|
+
myccusage --agy -s
|
|
245
|
+
|
|
246
|
+
# 按累计 Token 消耗排行，揪出最耗费的项目
|
|
247
|
+
myccusage --agy -s -t
|
|
248
|
+
myccusage --claude -s -t
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### 3. 现代化网页仪表盘模式 (`--web` / `-w`)
|
|
252
|
+
启动本地轻量 Web 服务，在浏览器中查看全景看板与可视化图表：
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
# 启动 Web Dashboard (默认端口 8488，并自动在浏览器中打开)
|
|
256
|
+
myccusage --web
|
|
257
|
+
|
|
258
|
+
# 指定端口启动
|
|
259
|
+
myccusage --web --port 9000
|
|
260
|
+
|
|
261
|
+
# 启动并直接聚焦特定 Agent
|
|
262
|
+
myccusage --claude --web
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### 4. 查看帮助信息
|
|
266
|
+
```bash
|
|
267
|
+
myccusage -h
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
---
|
|
271
|
+
|
|
272
|
+
## 🔒 隐私与安全承诺 (Privacy & Security)
|
|
273
|
+
|
|
274
|
+
- **100% 纯本地离线运行**：所有原生会话标题提取、Token 切片计算均在本地设备完成，绝不向任何第三方云端或个人服务器上传任何代码、提问内容或使用量元数据。
|
|
275
|
+
- **零遥测追踪 (No Telemetry)**：本项目不包含任何埋点、统计或追踪代码。
|
|
276
|
+
- **本地回环网络安全**：内置 Web 仪表盘默认严格绑定 `127.0.0.1` 本地回环地址，关闭浏览器网页后看门狗会自动安全退出，绝不暴露公网或局域网端口。
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
## 📄 开源许可
|
|
281
|
+
|
|
282
|
+
[MIT License](LICENSE) © 2026 Richard Huang
|
|
283
|
+
|