最好加入每个 session token 数和对应开销，以及全局开销

[jovezhong]

参考我在 https://github.com/jhlee0409/claude-code-history-viewer的共享。看到具体 token 数和对应钱还是很爽的

[MarkShawn2020]

@claude 深度调研一下此需求

[claude]

Claude finished @MarkShawn2020's task in 7m 39s —— View job • claude/issue-11-20260106-0311

---

深度调研：Session Token 统计与开销追踪功能

任务清单

• 分析 Lovcode 现有架构
• 调研 Claude Code Token 追踪机制
• 分析参考项目需求
• 设计数据模型方案
• 提出 UI/UX 设计建议
• 制定实现路线图
• 生成完整技术文档

---

一、调研总结

1.1 Claude Code Token 追踪机制

Claude Code 提供多种方式追踪 Token 使用和成本：

✅ 可用数据源

数据源	适用场景	数据粒度	可行性
Status Line API	实时会话统计	Session 级别	⭐⭐⭐⭐⭐ 推荐
/cost 命令	单次会话汇总	Session 级别	❌ 不适用（需 CLI）
OpenTelemetry	企业级监控	Per-request	⭐⭐ 复杂度高
JSONL 文件	离线解析	Message 级别	⭐⭐⭐⭐ 推荐

推荐方案：通过解析 JSONL 文件获取会话级别 Token 统计

Status Line API 数据结构

{
  "cost": {
    "total_cost_usd": 0.01234,
    "total_duration_ms": 45000,
    "total_api_duration_ms": 2300,
    "total_lines_added": 156,
    "total_lines_removed": 23
  },
  "context_window": {
    "total_input_tokens": 15234,
    "total_output_tokens": 4521,
    "context_window_size": 200000,
    "current_usage": {
      "input_tokens": 8500,
      "output_tokens": 1200,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 2000
    }
  }
}

参考文档：

• Claude Code Costs
• Status Line API
• Monitoring Usage

---

二、技术方案设计

2.1 数据模型扩展

Rust 后端（src-tauri/src/lib.rs）

// 扩展 Session 结构
#[derive(Debug, Serialize, Deserialize)]
pub struct Session {
    pub id: String,
    pub project_id: String,
    pub project_path: Option<String>,
    pub summary: Option<String>,
    pub message_count: usize,
    pub last_modified: u64,
    
    // ✨ 新增字段
    pub usage: Option<SessionUsage>,
}

#[derive(Debug, Serialize, Deserialize, Default)]
pub struct SessionUsage {
    pub total_input_tokens: u32,
    pub total_output_tokens: u32,
    pub cache_read_tokens: u32,
    pub cache_creation_tokens: u32,
    pub total_cost_usd: f64,
    pub model: Option<String>,  // 模型名称（如 claude-sonnet-4-5）
}

// 扩展 RawLine 解析结构
#[derive(Debug, Deserialize)]
struct RawLine {
    #[serde(rename = "type")]
    line_type: Option<String>,
    message: Option<RawMessage>,
    uuid: Option<String>,
    timestamp: Option<String>,
    #[serde(rename = "isMeta")]
    is_meta: Option<bool>,
    
    // ✨ 新增：解析 usage 数据
    usage: Option<UsageData>,
    cost: Option<f64>,
    model: Option<String>,
}

#[derive(Debug, Deserialize)]
struct UsageData {
    input_tokens: Option<u32>,
    output_tokens: Option<u32>,
    cache_read_input_tokens: Option<u32>,
    cache_creation_input_tokens: Option<u32>,
}

TypeScript 前端（src/types/index.ts）

export interface Session {
  id: string;
  project_id: string;
  project_path: string | null;
  summary: string | null;
  message_count: number;
  last_modified: number;
  
  // ✨ 新增字段
  usage?: SessionUsage;
}

export interface SessionUsage {
  total_input_tokens: number;
  total_output_tokens: number;
  cache_read_tokens: number;
  cache_creation_tokens: number;
  total_cost_usd: number;
  model?: string;
}

// 新增：项目级别统计
export interface ProjectUsage {
  project_id: string;
  total_sessions: number;
  total_cost_usd: number;
  total_tokens: number;
  breakdown: {
    input_tokens: number;
    output_tokens: number;
    cache_tokens: number;
  };
}

2.2 后端实现要点

推荐方案：解析 JSONL 文件

修改 list_sessions 和 get_session_messages 函数：

async fn list_sessions(project_id: String) -> Result<Vec<Session>, String> {
    // 1. 遍历 session JSONL 文件
    // 2. 解析每行的 usage/cost 字段
    // 3. 累加计算 total_input_tokens, total_output_tokens
    // 4. 返回包含 usage 数据的 Session 列表
}

优点：

• ✅ 无需外部依赖
• ✅ 可离线计算历史数据
• ✅ 性能好（可缓存）

缺点：

• ⚠️ 依赖 Claude Code 内部 JSONL 格式（通过 Option 字段容错）

---

2.3 UI 设计方案

遵循 Lovstudio Warm Academic Style (暖学术风格)

界面 1：Session 列表卡片增强

位置：src/views/Chat/SessionList.tsx:306-335

<div className="flex items-center gap-3 mt-2 text-xs text-muted-foreground">
  <span className="flex items-center gap-1">
    <ChatBubbleIcon className="w-3 h-3" />
    {session.message_count} msgs
  </span>
  
  {session.usage && (
    <>
      <span className="flex items-center gap-1">
        <Layers className="w-3 h-3" />
        {(session.usage.total_input_tokens + session.usage.total_output_tokens).toLocaleString()} tokens
      </span>
      <span className="flex items-center gap-1 text-primary font-medium">
        <DollarSign className="w-3 h-3" />
        ${session.usage.total_cost_usd.toFixed(4)}
      </span>
    </>
  )}
  
  <span className="ml-auto">{formatDate(session.last_modified)}</span>
</div>

效果预览：

┌─────────────────────────────────────────────┐
│ Fix authentication bug in login flow       │
│ 💬 12 msgs  📊 15,234 tokens  💰 $0.0123  │
│                            2 hours ago →    │
└─────────────────────────────────────────────┘

界面 2：项目级统计卡片

位置：src/views/Chat/SessionList.tsx:160 (header 区域)

显示项目总览：

• 总会话数
• 总 Token 消耗
• 总成本
• Token 分布图（Input/Output/Cache）

界面 3：Session 详情页增强

位置：src/views/Chat/MessageView.tsx:90

在 Header 添加 Session Cost Badge：

┌──────────────────┐
│ Session Cost     │
│  $0.0123         │
│  15,234 tokens   │
└──────────────────┘

界面 4：全局开销统计页

新增页面：src/views/Usage/GlobalUsageView.tsx

功能：

• 总览卡片（总成本、总 Token、会话数、项目数）
• 按项目分组的成本表格
• 按成本/Token/会话数排序
• 导出报告（CSV/JSON）

---

三、实现路线图

Phase 1：后端数据解析（核心）

优先级：🔴 P0 (必须)
预计工作量：2-3 天

• 扩展 Rust 数据结构（Session, RawLine, SessionUsage）
• 修改 list_sessions 解析 JSONL 文件中的 usage 字段
• 实现 Session 级别 Token 累加逻辑
• 添加 Tauri 命令：get_project_usage(project_id) 返回项目统计
• 添加 Tauri 命令：get_global_usage() 返回全局统计
• 添加缓存机制（避免重复解析大文件）

Phase 2：前端 UI 集成（体验）

优先级：🟡 P1 (重要)
预计工作量：2-3 天

• 扩展 TypeScript 类型定义（SessionUsage, ProjectUsage）
• SessionList 卡片显示 Token & Cost
• SessionList Header 显示项目统计卡片
• MessageView Header 显示 Session Cost Badge
• 新增 GlobalUsageView 页面
• 添加导航入口（侧边栏 "Usage Analytics"）

Phase 3：高级功能（增强）

优先级：🟢 P2 (可选)
预计工作量：3-5 天

• 导出功能：支持导出项目/全局成本报告（CSV/JSON）
• 趋势图表：按时间维度显示成本变化（使用 recharts）
• 预算告警：设置项目预算上限，超标提醒
• 模型对比：不同模型（Sonnet/Opus/Haiku）成本分布
• Cache 效率分析：Cache Hit Rate 可视化

---

四、参考项目对比

jhlee0409/claude-code-history-viewer

根据用户提供的截图，该项目已实现：

✅ Session 列表显示 Token & Cost
✅ 按 Cost 排序
✅ Total Cost 汇总

Lovcode 优势：

• 🎨 更美观的 Warm Academic 设计风格
• 📊 项目级别统计（vs 仅 Session）
• 🌐 全局 Usage 视图
• 💾 本地桌面应用（vs Web）
• 🔍 中文分词搜索（Jieba）
• ⚡ 高性能缓存机制

---

五、技术难点与解决方案

难点 1：JSONL 格式兼容性

问题：Claude Code 未公开 JSONL 内部格式，可能随版本变动

解决方案：

// 使用宽松的 Deserialize，缺失字段不报错
#[derive(Debug, Deserialize)]
struct RawLine {
    usage: Option<UsageData>,  // Option 包裹，缺失时为 None
    #[serde(default)]
    cost: Option<f64>,
}

难点 2：历史数据缺失 Usage

问题：旧版本 Claude Code 创建的 Session 可能无 usage 字段

解决方案：

• UI 优雅降级：无数据时显示 "N/A" 或隐藏
• 提供手动触发索引重建功能

难点 3：性能优化

问题：大项目（1000+ Sessions）解析耗时

解决方案：

// 1. 增量解析（仅解析新增/修改的文件）
// 2. 使用 rayon 并行处理
use rayon::prelude::*;

sessions.par_iter()
    .map(|session| parse_session_usage(session))
    .collect()

---

六、总结

✅ 调研完成

已深入分析以下内容：

1. Claude Code 机制：理解 Token 追踪的多种方式（JSONL、Status Line、OTel）
2. 数据模型设计：完成 Rust + TypeScript 类型定义
3. UI/UX 方案：遵循 Warm Academic 风格的 4 套界面设计
4. 实现路线：分 3 阶段，核心功能 5-6 天可完成
5. 技术难点：识别并提供兼容性、性能、降级方案

📄 技术文档

完整的技术设计文档已生成：docs/feature-token-tracking.md

包含：

• 完整的代码示例
• UI 设计稿
• 实现检查清单
• 性能优化方案
• 参考链接

🚀 下一步建议

建议优先实现 Phase 1 + Phase 2，完成基础 Token 统计和 UI 展示，满足用户核心需求（参考 jhlee0409 项目）。

Phase 3 的高级功能（趋势图、预算告警等）可根据用户反馈迭代添加。

---

📦 提交内容

已提交技术文档到分支：claude/issue-11-20260106-0311

Create a PR

---

| Branch: claude/issue-11-20260106-0311