cc-web/.planning/usage-statistics-dashboard-plan/progress.md

进度记录：cc-web 使用统计看板计划

2026-08-03

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

• 状态： complete
• 已确认当前只产出计划，不修改产品代码。
• 已确认可靠指标及其时间归属。
• 已排除“活跃会话”和“Skill 实际读取次数”等不可靠指标。
• 已记录“不影响现有功能”的硬性边界。

Phase 2 至 Phase 6：实施与验收

• 状态： complete
• 用户已确认进入代码实施，并指定侧栏底部入口位置。
• 已补充看板视觉主张、内容结构和交互原则；本轮仍未改产品代码。
• 已把“先记录现有行为基线、功能开关默认关闭”设为实施第一道门禁。
• 已创建 Trellis 任务 08-03-usage-statistics-dashboard。
• 已记录现有高级会话检索相关脏文件，后续不得覆盖或清理。
• 计划审查指出缺少独立的全部主题适配阶段；已补充 Phase 5 和对应硬性验收门槛。
• 已确认 codebase-memory 索引可用，并开始定位会话写入、MCP toolCalls、composerMentions 和前端入口链路。
• 第二次计划审查已通过；已修正 created 字段口径并加入 schema 版本和性能阈值。
• 已完成后端数据结构、前端入口、回归落点和 11 个主题的并行只读审计。
• 已确定看板使用 .chat-main 局部覆盖、独立状态机、独立请求 ID 和懒加载派生索引。
• 实施清单第 1 项完成，进入只读统计聚合模块与单元测试实现。
• 新增 lib/usage-statistics.js 和 scripts/usage-statistics-unit.js；语法检查、纯夹具单测和 git diff --check 通过。
• 实施清单第 2 项完成，进入独立 WebSocket 统计查询协议接入。
• 独立协议、指定入口、看板 DOM、前端状态机、趋势/明细交互及基础响应式样式已完成首轮实现。
• 已通过 node --check、统计单测和相关文件 git diff --check，进入全部现有主题适配。
• 已完成 CoolVibe、Carbon/Nocturne/Cinder、Gilded、Wasteland 的限定覆盖；其他主题直接继承看板语义变量。
• 已新增 usage-statistics 回归目标，真实 WebSocket 验证查询不会额外发送 session_list，禁用开关返回 disabled。
• 83.3 MB / 134 个真实会话最终首次回填 1.15 秒，查询 P95 51.79 ms，峰值 RSS 116.7 MB，索引占源数据 0.47%。
• Chrome Headless 151 完成 11 个主题 × 5 个视口共 55 组布局验收；桌面、平板、移动端均无页面级横向溢出。
• 已验证 loading、MCP 长工具名明细、空态和无效日期错误态；Wasteland 根看板改为实色，避免下层输入框视觉透出。
• gilded-theme、wasteland-theme、advanced-session-search、统计专项和全量回归均通过。

Phase 7：最终审查与交付

• 状态： complete
• 两轮独立审查均无高等级问题；提出的 4 个中等级问题已全部修复并补回归合同。
• 已限制 MCP/Skill 返回规模、公开 total/returned、明确明细“最近 X / 共 Y 条”，回填改为每文件让出事件循环。
• 已修复异常空文件增量可能保留旧文档，并把聚合核心单测接入统计专项和全量回归。
• 已修复 CoolVibe 选中按钮对比度和暗色日期原生图标；Chrome computed style 验证通过。
• PM2 服务已在线加载，用户确认最终效果可用。
• 最终清理只删除本任务生成的临时浏览器包、截图和根目录 TODO CSV；未清理既有高级检索改动。

本轮文件变更

• lib/usage-statistics.js：新增懒加载、可重建的只读统计索引与聚合器。
• scripts/usage-statistics-unit.js：新增统计口径、隐私、增量和损坏文件单测。
• server.js：新增功能开关、安全生命周期钩子和独立查询协议。
• public/index.html：新增固定 footer 入口和 chat-main 局部看板 DOM。
• public/app.js：新增独立看板状态、查询、渲染和恢复交互。
• public/style.css：新增基础响应式看板与现有主题限定覆盖。
• scripts/regression.js：新增统计专项合同和真实 WebSocket 回归。
• 计划、Trellis 和临时 CSV 仅用于过程记录；现有高级检索脏改动全部保留。

验证结果

验证项	预期	实际	状态
单元与专项	统计口径、隐私、协议隔离	全部通过	通过
全量回归	现有功能不回归	Regression checks passed.	通过
性能	回填 ≤3s、P95 ≤100ms、RSS ≤160MB、索引 ≤35%	1.15s / 51.79ms / 116.7MB / 0.47%	通过
浏览器	11 主题 × 5 视口、动态状态	55 组 + loading/detail/empty/error	通过
风险隔离	独立入口、协议、索引和关闭开关	CC_WEB_USAGE_STATISTICS=0 可即时关闭	通过

错误日志

时间	错误	尝试	处理
2026-08-03	无	1	—
2026-08-03	task.py list-context 不接受 action 位置参数	1	已有 task.py validate 通过结果，改为由实现代理读取 implement.jsonl
2026-08-03	Wasteland 回归把三暗色统计 selector 识别为五主题共享层	1	将统计暗色组改用等价 :where(...)，保留既有共享层合同
2026-08-03	浏览器验收把局部表格 scrollWidth 误报为页面溢出	1	以 document/body/dashboard body 为页面口径，表格保留明确的局部横向滚动
2026-08-03	动态状态脚本刚完成查询即刷新，命中 250ms 限流	1	按真实操作节奏增加 350ms 间隔，协议行为符合设计

5 问检查

问题	答案
当前在哪？	功能与验收完成，正在最终独立审查和清理
接下来去哪？	审查结论、运行服务激活、交付记录
目标是什么？	不影响现有功能地增加只读使用统计看板
已学到什么？	见 findings.md
已完成什么？	整体功能、全主题适配、专项/全量回归、性能和浏览器验收