shiyue/cc-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e7d28935ef243322e0ae53801e141961981dddcc
cc-web/.planning/usage-statistics-dashboard-plan/task_plan.md

8.4 KiB
Raw Blame History

任务计划：cc-web 使用统计看板

目标

在不改变现有聊天、会话列表、会话检索和消息发送行为的前提下，为 cc-web 增加一个可独立启停、只读、可回滚的使用统计看板。

当前阶段

已完成：功能、主题、回归、性能、浏览器与在线验收

实施阶段

Phase 1：边界与统计口径确认

  • 明确当前可可靠统计的数据
  • 明确当前不可可靠统计的数据
  • 定义“不影响现有功能”的不可变边界
  • 状态： complete

Phase 2：安全基线、只读统计核心与历史回填

  • 记录现有回归结果及消息发送、会话切换、检索的行为基线
  • 建立独立功能开关，CC_WEB_USAGE_STATISTICS=0 时不显示入口、不创建索引
  • 新增独立统计模块，读取保留期内的 sessions/*.json
  • 第一次打开看板时懒加载回填，不把 83.3 MB 扫描放进服务启动或消息处理链路
  • 将聚合结果写入独立索引文件，不回写任何会话 JSON
  • 索引就绪后通过防抖 save/delete 旁路钩子更新，钩子失败不进入主错误链路
  • 索引只保存统计事件、源文件指纹和会话元数据，可删除重建
  • 索引异常时返回看板错误，不阻塞聊天和会话持久化
  • 状态： complete

Phase 3：独立查询协议

  • 新增只读 usage_stats_query/result/error 协议
  • 响应携带稳定的 schemaVersion=1
  • 请求参数仅包含时间范围、时区和内部固定上限
  • 响应包含概览、趋势、MCP 明细、Skill 显式使用排行和会话明细
  • 不修改 session_list、search_sessions、load_session 等现有协议和负载结构
  • 增加排行/明细上限、频率限制和异常隔离
  • 状态： complete

Phase 4：独立看板工作区

  • 在侧栏固定 footer 增加独立“统计”入口
  • 看板使用自己的前端状态、DOM 根节点和样式命名空间
  • 顶部提供本周、本月、自定义时间和刷新
  • 展示可靠指标，不展示无法准确解释的“活跃会话”
  • MCP 支持明细窗口，会话行可返回对应会话
  • 关闭看板后恢复原聊天滚动、焦点和输入选区
  • 状态： complete

Phase 5：全部现有主题适配

  • 枚举 THEME_OPTIONS 中全部 11 个现有主题
  • 适配侧栏底部入口、概览、趋势、表格、空态、错误态和加载态
  • 主题差异只通过语义变量和主题限定选择器实现，没有复制业务 DOM 或 JS
  • 11 主题 × 5 视口完成真实浏览器几何验收
  • 检查 prefers-reduced-motion、文字对比度、日期图标和焦点可见性
  • 状态： complete

Phase 6：兼容性、性能与故障回归

  • 执行现有全量回归并记录结果
  • 增加统计协议、时间边界、失败状态、空数据、限额和隐私测试
  • 增加入口隔离、刷新、错误态和 reduced-motion 前端合同
  • 验证统计查询后会话加载、会话搜索及 session_list 均不受影响
  • 验证索引缓存复用、增量、删除、空文件和损坏文件隔离
  • 对当前 83.3 MB 会话数据完成性能验收
  • 状态： complete

Phase 7：灰度启用与回滚

  • 使用功能开关控制统计入口和统计查询服务
  • 当前环境已重启启用，用户已确认在线效果
  • 记录 CPU、内存、回填、查询耗时和索引比例
  • 回滚时可设 CC_WEB_USAGE_STATISTICS=0，不涉及会话数据迁移
  • 状态： complete

统计口径

指标 定义 时间归属 可靠性
新建会话 created 落在时间范围内的会话数量，兼容 createdAt 历史兜底 会话创建时间 保留会话范围内高
发送消息 时间范围内当前仍被保留的用户消息数量 用户消息时间 保留数据范围内高
自动协作消息 非人工触发、由协作链路产生的消息数量 对应消息时间 先验证字段；无法稳定分类则首版不展示
MCP 调用 assistant message 中 toolCalls 的 MCP 调用条目数量 暂按所属 assistant 消息时间 中
MCP 失败 MCP 调用中 status=failed 的条目数量 暂按所属 assistant 消息时间 中
Skill 显式使用 用户消息 composerMentions 中显式 $skill mention 数量 用户消息时间 保留数据范围内高

当前版本明确不做

  • 不统计 Skill 文件被模型实际读取或执行的次数。
  • 不将“活跃会话”作为指标。
  • 不修改历史或未来的会话 JSON schema。
  • 不把统计字段塞入 session_list 或会话列表负载。
  • 不为统计而改造现有消息发送、会话检索或 MCP 执行链路。
  • 不承诺历史 MCP 的精确调用时刻和耗时。
  • 不在页面每次刷新时全量扫描所有会话 JSON。

核心架构决策

决策 理由
采用“历史回填 + 异步增量索引 + 独立查询” 当前全量扫描可用但长期不适合每次看板请求执行
首版使用可重建的旁路索引，不引入数据库依赖 降低发布和 CentOS 单文件打包风险；当前数据规模足够使用
索引与会话源数据完全分离 索引可以删除重建，不给现有会话数据带来迁移风险
新增独立 WebSocket 消息类型 避免改变现有会话列表、搜索和加载协议
看板作为独立工作区 页面结构可复用现有外壳，同时隔离聊天状态和交互
提供可立即关闭的功能开关 用户确认落地后默认展示入口；出现问题时可只关闭看板，不回滚会话功能
MCP 历史数据暂按 assistant 消息时间聚合 当前工具调用记录本身没有时间戳，必须在界面说明口径

看板界面基线

  • 视觉主张： 延续 cc-web 现有应用外壳，形成安静、紧凑、可快速扫描的运营工作区；不单独设计营销主题。
  • 内容结构： 时间与刷新控制 → 核心数字 → 趋势和 MCP 明细 → 状态与 Skill 排行 → 最近会话。
  • 交互主张： 切换看板时保留聊天现场；筛选刷新只更新看板区域；明细查看在看板内部完成，返回后保留筛选条件。
  • 组件原则： 只有可交互或需要独立语义的区域使用卡片，其余优先使用分栏、分隔线、图表和紧凑表格，避免卡片拼贴。
  • 入口位置： 固定在侧栏底部操作区，处于会话列表下方，与截图中的 CC-Web 设置入口同一区域；不插入会话列表滚动内容。

不影响现有功能的硬性验收门槛

  1. 关闭功能开关时，前端 DOM、交互和服务端行为与改动前一致。
  2. 统计模块异常、索引缺失或查询超时，消息发送和会话操作仍正常。
  3. session_list、search_sessions、load_session 的请求和响应合同不变。
  4. 不修改现有会话文件内容；统计索引可随时删除并从源数据重建。
  5. 全量现有回归通过，新增统计回归通过后才允许灰度开启。
  6. 不在正常消息处理的同步关键路径中执行全量扫描或重聚合。
  7. 看板必须显示“基于当前保留数据”和最后更新时间，不能把保留期数据表述为永久审计数据。
  8. THEME_OPTIONS 中全部现有主题都必须完成桌面和窄屏验收；侧栏入口位置一致，看板内容可读，且聊天恢复、会话切换、搜索、消息发送和 MCP 功能不受影响。

发布门禁建议

  • 基线：先记录当前回归结果和典型聊天操作耗时。
  • 开发态：仅显式开启功能开关后显示入口。
  • 灰度态：限制单用户或指定环境开启，观察至少一个完整统计周期。
  • 正式态：只有错误率、CPU、内存和 P95 查询耗时满足阈值才默认开启。
  • 回滚：关闭功能开关；保留独立索引无害，必要时可后续清理。

首版性能阈值

  • 当前约 82 MB 会话数据的专项回填目标不超过 3 秒。
  • 索引就绪后的本周/本月查询 P95 目标不超过 100 ms。
  • 专项回填进程峰值 RSS 目标不超过 160 MB。
  • 旁路索引文件目标不超过源会话 JSON 总量的 35%。

错误记录

错误 尝试 处理
无 1 —
task.py list-context ... implement 参数不被当前脚本接受 1 task.py validate 已确认 context JSONL 合法；后续直接读取任务上下文文件，不重复该命令