cc-web/.trellis/tasks/08-03-usage-statistics-dashboard/prd.md

使用统计看板 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. 真实浏览器完成桌面、移动端及动态状态验收。