# 使用统计看板 PRD

## 目标

为 cc-web 增加一个只读、可回滚的使用统计看板，同时保持聊天、会话列表、会话检索、消息发送和 MCP 执行链路的既有行为不变。

## 用户入口

- 入口固定在侧栏底部操作区。
- 位于会话列表下方，与现有 `CC-Web` 设置入口同一区域。
- 入口不能成为会话列表滚动项。
- 点击后切换到独立统计工作区；返回聊天时保留原会话、滚动位置和输入草稿。

参考图：`sessions/_attachments/750cb7a2-a109-44a9-ae3d-6ca352d4aba0.jpg`。

## 首版功能

- 时间范围：本周、本月、自定义范围。
- 概览：新建会话、发送消息、MCP 调用、MCP 失败、Skill 显式使用。
- 趋势：按日展示上述指标。
- MCP：按 server/tool 统计调用、成功、失败，并可查看该工具的调用明细。
- Skill：按 `composerMentions` 统计显式 `$skill` 排行。
- 会话：展示所选时间范围内的最近会话统计明细。
- 页面显示数据范围说明和最后统计时间。

## 数据口径

- 只统计当前保留的 `sessions/*.json` 数据。
- MCP 历史调用没有独立时间戳，归属到所属 assistant 消息时间。
- Skill 只统计用户显式 `$skill` mention，不统计模型实际读取或执行。
- 不使用“活跃会话”这一含糊指标。
- 自动协作消息只有在现有字段可稳定区分时才单独展示。

## 架构边界

- 新增独立统计模块和独立查询协议。
- 不修改会话 JSON schema，不回写源会话文件。
- 不改变 `session_list`、`search_sessions`、`load_session` 等现有协议。
- 不在消息处理同步链路执行统计扫描。
- 统计索引和错误必须与聊天功能隔离。
- 提供可立即关闭统计入口和查询的功能开关。

## 前端基线

- 视觉主张：延续 cc-web 现有外壳，安静、紧凑、可快速扫描。
- 内容结构：筛选与刷新 → 核心数字 → 趋势与 MCP 明细 → 状态与 Skill 排行 → 最近会话。
- 交互主张：切换保留聊天现场；看板内部刷新；明细返回后保留筛选。
- 避免通用 SaaS 卡片拼盘；卡片只用于真正可交互或需要独立语义的区域。

## 完成标准

1. 核心统计模块、独立查询协议和完整看板可用。
2. 入口位置符合用户截图指定区域。
3. 所有现有主题完成样式适配，窄屏可用。
4. 现有回归与新增专项回归通过。
5. 统计失败或索引损坏不影响消息、会话、搜索和 MCP。
6. 真实浏览器完成桌面、移动端及动态状态验收。