feat: add conversation search and usage dashboard

.planning/usage-statistics-dashboard-plan/findings.md

@@ -0,0 +1,102 @@
+# 调研结论：cc-web 使用统计看板
+
+## 用户要求
+
+- 当前只需要可执行计划，不实施产品代码。
+- 看板必须不影响现有聊天、会话、检索和工具调用功能。
+- 指标必须有明确口径，不能使用含糊的“活跃会话”。
+- Skill 只统计显式 `$skill` 使用，不宣称能够监控实际读取或执行。
+- 用户已授权开始实施，并要求先完成整体功能，再适配所有现有主题。
+- 用户指定统计入口位于侧栏底部：会话列表下方、现有 `CC-Web` 设置入口同一区域，而不是会话列表内部。
+- 入口参考图为 `sessions/_attachments/750cb7a2-a109-44a9-ae3d-6ca352d4aba0.jpg`；图中底部操作区在会话列表滚动区域之外。
+
+## 现有数据能力
+
+- 会话数据保存在 `sessions/*.json`。
+- 用户消息可持久化 `composerMentions`，可识别显式 `$skill` mention。
+- Codex App 的 MCP 调用会规范化到 assistant message 的 `toolCalls[]`，包含 `server`、`tool`、`status`。
+- 现存 MCP 工具调用没有独立时间戳；历史统计只能暂时使用所属 assistant 消息完成时间。
+- 会话持久化有消息数和每条消息工具调用数上限，因此看板只能统计“当前保留数据”，不能声称是永久全量审计。
+- 当前会话主创建字段为 `created`；134 个会话均有 `created/updated`，当前 2,226 条保留消息均有 `timestamp`。
+- 当前扫描得到 1,745 次 MCP 调用，`completed=1645`、`failed=100`；失败调用同样可能 `done=true`，失败口径必须读取 `meta.status`。
+- 显式 Skill mention 的稳定判定是 `composerMentions[].kind === 'skill'`，不能扫描消息正文中的 `$xxx`。
+- `crossConversation` 可区分跨会话自动消息；界面使用“直接发送消息”和“跨会话消息”，避免把前者绝对命名为人工消息。
+
+## 已有数据扫描结果
+
+- 134 个会话 JSON，总量约 82 MB。
+- 1,678 次 MCP 调用，`server/tool` 解析率 100%。
+- MCP 状态：`completed=1578`，`failed=100`。
+- 显式 Skill mention 共 7 次。
+- 一次全量扫描约 0.93 秒，峰值 RSS 约 116 MB。
+
+## 架构判断
+
+- 82 MB 数据量下，全量扫描可以用于一次性回填或维护操作。
+- 不应让每次看板刷新都全量解析所有会话文件，否则数据增长后会和聊天服务争用 CPU、内存和磁盘 IO。
+- 最稳妥的结构是：独立索引文件、异步更新、独立查询协议、独立前端工作区。
+- 统计是旁路只读能力，不进入消息发送和会话写入的同步关键路径。
+- 统计索引采用懒加载：第一次打开看板才加载/回填，未使用看板时不增加服务启动成本。
+- 索引初始化后可防抖增量更新；调度与删除必须内层 `try/catch`，不能让统计异常进入 `saveSession` 或删除会话的主错误分支。
+- 统计响应只返回聚合值、工具名、Skill 名和会话元数据，不返回消息正文、MCP 参数或工具结果。
+
+## 页面范围
+
+- 顶部：时间范围、本周、本月、自定义范围、刷新。
+- 首行指标：新建会话、发送消息、MCP 调用、MCP 失败、Skill 显式使用。
+- 中部：按日趋势；MCP 工具使用明细。
+- 下部：MCP 状态分布；Skill 显式使用排行；最近会话明细。
+- MCP 工具明细行可进入该工具的调用明细；该交互属于网页实现，不需要在生图提示词中逐字描述。
+- 看板作为 `.chat-main` 内局部覆盖工作区，聊天 DOM 保持挂载；高级检索与看板互斥打开。
+- 入口必须使用独立 `.usage-dashboard-open`，不能复用 `.settings-btn`，否则 Wasteland 的齿轮伪元素会污染统计按钮。
+- 当前共有 11 个主题 ID；基础样式使用语义 token，专属修正只需要 coolvibe、共享暗色组、gilded 和 wasteland。
+
+## 代码落点依据
+
+- `public/index.html` 已有 sidebar 与 `main.chat-main`，看板可以作为 chat-main 内独立工作区，而不必重做应用外壳。
+- `server.js` WebSocket 分发已有独立消息类型模式，可新增统计查询类型而不改变现有协议。
+- `scripts/regression.js` 已覆盖高级检索的独立入口和独立状态模式，统计看板可沿用相同隔离策略。
+- codebase-memory 项目 `home-cc-web` 索引状态为 ready（4,455 nodes / 9,320 edges）。
+- `saveSession()` 是高入度核心写入函数，统计逻辑不得直接接入其同步调用链；旁路索引应在看板查询或独立后台任务中刷新。
+- 用户和 assistant 消息均有 `timestamp`；Codex App steer 用户消息也会持久化 `composerMentions`。
+- MCP 调用继续从 assistant message 的 `toolCalls` 读取，`ensureToolCall()` 负责归一化名称、kind、meta 和状态更新。
+
+## 风险与控制
+
+| 风险 | 控制方式 |
+|---|---|
+| 看板查询拖慢聊天服务 | 使用增量索引；请求限时；禁止请求时全量扫描 |
+| 索引与会话数据不一致 | 保存源文件指纹；可重建；界面显示统计更新时间 |
+| 历史 MCP 时间不准确 | 明示按 assistant 消息时间归属；不展示伪精确耗时 |
+| Skill 指标被误解 | 指标名称固定为“Skill 显式使用” |
+| 前端状态污染聊天 | 独立状态对象、DOM 根节点、样式命名空间和关闭恢复流程 |
+| 新功能引入回归 | 功能开关、合同测试、现有完整回归、灰度启用 |
+| 现有文件已有未提交修改 | 只在精确区块追加，不重排或覆盖高级会话检索改动；以任务开始时 diff 为基线 |
+
+## 计划审查记录
+
+- 第一次审查发现原计划缺少“全部现有主题逐一适配”的独立阶段。
+- 已新增 Phase 5 和硬性主题验收门槛，第二次审查通过。
+- 复审确认现有会话主创建字段为 `created`；实施以此为主，`createdAt` 只作历史兼容兜底。
+- 统计响应需携带 `schemaVersion`，性能验收已补充明确阈值。
+
+## 资源
+
+- 参考图：`sessions/_attachments/67a5f5ae-ea62-4c12-b723-deb9adb98c2f.png`
+- 会话存储与 WebSocket：`server.js`
+- Codex App 工具调用归一化：`lib/codex-app-runtime.js`
+- 页面外壳：`public/index.html`
+- 现有前端状态与交互：`public/app.js`
+- 回归测试：`scripts/regression.js`
+
+## 实施与验收结论
+
+- 统计索引在第一次打开看板时才构建；未初始化时保存会话不会安排统计更新。
+- 查询响应包含 `schemaVersion` 和 `[from,to)` 语义，不包含消息正文、MCP 参数或结果。
+- `usage_stats_query` 使用独立 requestId，真实协议回归确认不会新增 `session_list`。
+- `CC_WEB_USAGE_STATISTICS=0` 会关闭鉴权 feature flag，并让查询返回 `disabled`，不影响服务其他能力。
+- 真实数据最终性能：83,335,652 字节、134 个会话，回填 1,146.68 ms，查询 P95 51.79 ms，峰值 RSS 119,476 KB，缓存 394,629 字节。
+- 浏览器验收：Chrome Headless 151.0.7922.71，视口为 1440×900、1024×768、768×1024、390×844、360×800；11 个主题共 55 组。
+- 页面级横向溢出均为 0；窄屏 MCP 表格按设计在 `.usage-dashboard__table-wrap` 内局部滚动。
+- Wasteland 的 `.usage-dashboard-open` 没有继承 `.settings-btn::before`；移动端入口为 44×44，桌面为 34×34。
+- 浏览器动态状态已覆盖 loading、MCP 明细、空态和错误态；Wasteland 根看板使用实色背景，避免下层聊天视觉透出。

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

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

.planning/usage-statistics-dashboard-plan/task_plan.md

@@ -0,0 +1,151 @@
+# 任务计划：cc-web 使用统计看板
+
+## 目标
+
+在不改变现有聊天、会话列表、会话检索和消息发送行为的前提下，为 cc-web 增加一个可独立启停、只读、可回滚的使用统计看板。
+
+## 当前阶段
+
+已完成：功能、主题、回归、性能、浏览器与在线验收
+
+## 实施阶段
+
+### Phase 1：边界与统计口径确认
+
+- [x] 明确当前可可靠统计的数据
+- [x] 明确当前不可可靠统计的数据
+- [x] 定义“不影响现有功能”的不可变边界
+- **状态：** complete
+
+### Phase 2：安全基线、只读统计核心与历史回填
+
+- [x] 记录现有回归结果及消息发送、会话切换、检索的行为基线
+- [x] 建立独立功能开关，`CC_WEB_USAGE_STATISTICS=0` 时不显示入口、不创建索引
+- [x] 新增独立统计模块，读取保留期内的 `sessions/*.json`
+- [x] 第一次打开看板时懒加载回填，不把 83.3 MB 扫描放进服务启动或消息处理链路
+- [x] 将聚合结果写入独立索引文件，不回写任何会话 JSON
+- [x] 索引就绪后通过防抖 save/delete 旁路钩子更新，钩子失败不进入主错误链路
+- [x] 索引只保存统计事件、源文件指纹和会话元数据，可删除重建
+- [x] 索引异常时返回看板错误，不阻塞聊天和会话持久化
+- **状态：** complete
+
+### Phase 3：独立查询协议
+
+- [x] 新增只读 `usage_stats_query/result/error` 协议
+- [x] 响应携带稳定的 `schemaVersion=1`
+- [x] 请求参数仅包含时间范围、时区和内部固定上限
+- [x] 响应包含概览、趋势、MCP 明细、Skill 显式使用排行和会话明细
+- [x] 不修改 `session_list`、`search_sessions`、`load_session` 等现有协议和负载结构
+- [x] 增加排行/明细上限、频率限制和异常隔离
+- **状态：** complete
+
+### Phase 4：独立看板工作区
+
+- [x] 在侧栏固定 footer 增加独立“统计”入口
+- [x] 看板使用自己的前端状态、DOM 根节点和样式命名空间
+- [x] 顶部提供本周、本月、自定义时间和刷新
+- [x] 展示可靠指标，不展示无法准确解释的“活跃会话”
+- [x] MCP 支持明细窗口，会话行可返回对应会话
+- [x] 关闭看板后恢复原聊天滚动、焦点和输入选区
+- **状态：** complete
+
+### Phase 5：全部现有主题适配
+
+- [x] 枚举 `THEME_OPTIONS` 中全部 11 个现有主题
+- [x] 适配侧栏底部入口、概览、趋势、表格、空态、错误态和加载态
+- [x] 主题差异只通过语义变量和主题限定选择器实现，没有复制业务 DOM 或 JS
+- [x] 11 主题 × 5 视口完成真实浏览器几何验收
+- [x] 检查 `prefers-reduced-motion`、文字对比度、日期图标和焦点可见性
+- **状态：** complete
+
+### Phase 6：兼容性、性能与故障回归
+
+- [x] 执行现有全量回归并记录结果
+- [x] 增加统计协议、时间边界、失败状态、空数据、限额和隐私测试
+- [x] 增加入口隔离、刷新、错误态和 reduced-motion 前端合同
+- [x] 验证统计查询后会话加载、会话搜索及 `session_list` 均不受影响
+- [x] 验证索引缓存复用、增量、删除、空文件和损坏文件隔离
+- [x] 对当前 83.3 MB 会话数据完成性能验收
+- **状态：** complete
+
+### Phase 7：灰度启用与回滚
+
+- [x] 使用功能开关控制统计入口和统计查询服务
+- [x] 当前环境已重启启用，用户已确认在线效果
+- [x] 记录 CPU、内存、回填、查询耗时和索引比例
+- [x] 回滚时可设 `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 合法；后续直接读取任务上下文文件，不重复该命令 |