# 进度记录：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` |
| 已完成什么？ | 整体功能、全主题适配、专项/全量回归、性能和浏览器验收 |