8.4 KiB
8.4 KiB
任务计划：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设置入口同一区域；不插入会话列表滚动内容。
不影响现有功能的硬性验收门槛
- 关闭功能开关时，前端 DOM、交互和服务端行为与改动前一致。
- 统计模块异常、索引缺失或查询超时，消息发送和会话操作仍正常。
session_list、search_sessions、load_session的请求和响应合同不变。- 不修改现有会话文件内容；统计索引可随时删除并从源数据重建。
- 全量现有回归通过，新增统计回归通过后才允许灰度开启。
- 不在正常消息处理的同步关键路径中执行全量扫描或重聚合。
- 看板必须显示“基于当前保留数据”和最后更新时间，不能把保留期数据表述为永久审计数据。
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 合法；后续直接读取任务上下文文件，不重复该命令 |