shiyue/cc-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4e1f987d62ea39ff850ec72cafc3a7eda8d395c5
cc-web/.planning/usage-statistics-reference-refit/findings.md

13 KiB
Raw Blame History

使用统计原型返工发现

产品化优化三项论点

  • 视觉论点：把统计页做成连续、克制、带明确阅读节奏的 cc-web 运营工作台；用留白、分隔线和字号建立层级，减少卡片马赛克、重复边框和多色竞争。
  • 内容计划：顶部用周期与五项核心数据回答“发生了什么”；中部用趋势、MCP 与 Skill 回答“功能如何被使用”；底部用最近会话提供可追溯证据。
  • 交互论点：时间筛选固定在浏览起点；排行和成功率保持明确可点击；MCP 明细从页面内跳转改为右侧抽屉；移动端指标带支持横向吸附浏览。

本轮范围

  • 保留五项指标、趋势、三组真实构成、MCP 排行、Skill 排行、最近会话与全部日期能力。
  • 不新增环比、独立用户、会话时长等统计协议不存在的数据。
  • 不修改聊天消息 DOM、草稿、附件、生成状态、会话 JSON 与统计后端。
  • 复用现有 11 个主题的语义变量，不新增主题 ID，不引入运行时图片资产。
  • 根据用户要求，本轮不派额外审计代理。

产品化实现后的视觉证据

  • 桌面端指标已变为一条连续指标带，图标改为文档、轨迹、节点、警示、火花五种 cc-web 原生线性符号；不再复制原型的圆形彩色图标。
  • 趋势与 MCP 面板通过中间分隔线形成两栏，六行 Top MCP 加“查看其余”入口后高度约 346px，与趋势区约 348px 对齐；不再由长工具清单撑高右栏。
  • MCP 默认只渲染前 6 项，其余数量使用面板底部的展开按钮；展开仍复用同一真实数据和成功率明细入口。
  • MCP 调用明细已从页面内滚动改为右侧抽屉：有遮罩、独立滚动和关闭入口，Esc/遮罩/关闭按钮均可退出，背景上下文保持不变。
  • 手机端指标改为 218px 横向吸附带；首屏可以先看到两项核心指标，趋势和 MCP 表格纵向继续阅读，表格保持横向滚动而不压缩成功率列。
  • 产品化视觉脚本第一轮报告：4 个视口与 11 个主题 dashboard/body 横向溢出均为 0；文字溢出为 0（会话表在移动端恢复合理横向滚动宽度）。

现版与原型视觉复核后的优化点

  • 现版已经正确承接原型的信息架构，但五张彩色指标卡、两个主卡、三张内嵌环图卡和底部卡片连续叠加，形成明显的“卡片马赛克”。
  • 状态区同时存在外层面板、内层三卡、环图与图例，边框层级重复；应保留数据，移除内层盒子，用分栏与细分隔线建立关系。
  • 五项指标目前各自使用高饱和图标色和折线色，注意力被平均分散；应统一为主题主强调，失败只保留状态色。
  • 标题旁重复信息图标与辅助说明密度过高；只在统计口径确有必要的位置保留一句说明，其他由标题、标签和数值自身表达。
  • MCP 表成功率是明确交互入口，但现版点击后滚动到页面中部的大明细区，破坏阅读上下文；抽屉更符合 cc-web 已有“主工作区 + 次级上下文”的应用结构。
  • 手机版五张大卡纵向堆叠会消耗过多首屏，应改为横向吸附的紧凑指标带，用户可以先读前两项，再按需横滑。

用户反馈

  • 现有实现与用户提供原型的版式、信息密度和视觉层级明显不一致。
  • 原型的关键不是配色，而是完整的大盘信息架构和组件比例。

参考图初步拆解

  • 顶部：左侧标题和时间切换，右侧全局操作。
  • 第一行：五张等宽指标卡，每张含彩色圆形图标、指标、数值、环比和小趋势。
  • 第二行：约 1:1 的双栏；左侧大趋势图，右侧 MCP 工具明细表。
  • 第三行：左侧状态统计，内含三个环图；右侧 Skill 排名表。
  • 底部：横跨整行的最近会话表。
  • 视觉：浅灰页面底、白色面板、细边线、小圆角、轻阴影、蓝色主强调，高密度但不拥挤。

参考图量化基线

  • 原始尺寸：1467 × 943px，PNG RGBA，文件大小 1,412,493 字节。
  • SHA-256：ddbcc605cdcd4ea6aab943b4fa101c1e4af7e1c729fa090d1c89d847e2fdf91d。
  • 归档路径：.trellis/tasks/08-03-usage-statistics-dashboard-refit/references/source-assets/usage-statistics-dashboard-reference.png。
  • 页面外边距约 8px；指标卡间距约 12px；主要面板圆角约 12px；边线约 1px。
  • 五张指标卡总高约 112px；主趋势/MCP 明细行高约 310px；状态/Skill 行高约 225px。
  • 桌面双栏以近似 1:1 展开，不采用当前实现的窄侧栏或散落卡片结构。

实现边界

  • 复用现有统计结果和交互，不增加无法从现有数据得到的“组织、独立用户、会话时长、人工/自动消息”等字段。
  • 不新增主题，不改变统计后端协议。
  • 需要同步桌面和移动端，不强行在手机上维持五列与双栏。

代码定位

  • codebase-memory 项目 home-cc-web：4,720 节点、10,178 条边，索引状态 ready。
  • 看板总渲染入口：public/app.js 的 renderUsageDashboard。
  • 趋势渲染：renderUsageTrend；Skill 排行：renderUsageSkills；最近会话：renderUsageSessions。
  • 数据聚合与索引在 lib/usage-statistics.js，当前返工不修改其协议和统计口径。
  • 后续需要继续定位 MCP 表格、状态统计、日期控件和事件绑定函数，再建立“参考区域 → DOM → 数据 → CSS”映射。

当前渲染能力

  • renderUsageDashboard 只负责填充 overview 指标、消息拆分、MCP 失败率、更新时间与覆盖说明，然后调用五个子渲染函数。
  • 当前共有 6 个 usage 渲染函数：Dashboard、Trend、McpStatus、McpTools、Skills、Sessions。
  • 现有数据已经足够支撑原型中的五个顶层指标、趋势区、MCP 表格、状态区、Skill 排行与最近会话；主要缺口是 DOM 信息架构和视觉表达，不是后端数据。
  • renderUsageDashboard 由 handleUsageStatisticsResult 和 openUsageDashboard 调用，重构时保持这两个入口不变。

当前 DOM 与原型偏差

  • 当前第二行是“趋势 + MCP 状态”，原型要求“使用趋势 + MCP 使用明细”。
  • 当前 MCP 工具表独占整行，原型要求它位于趋势右侧。
  • 当前第三行是“Skill + 最近会话”，原型要求“状态统计 + Skill 排行”。
  • 当前最近会话只占半行，原型要求底部横跨整行。
  • 当前指标卡只有文字/数字/说明，缺少原型中的图标、色彩编码、微趋势和清晰的左右信息分区。
  • 日期控件拆成两个原生 input 和“应用”，原型是一个紧凑日期范围控件；保留现有两个 input 的交互语义，但外观合并为一个控件组。

参考区域到现有 DOM 映射

  • 顶部标题/筛选 → usage-dashboard__header + usage-dashboard__toolbar。
  • 五项概览 → usage-dashboard__metric-grid 与 data-usage-metric。
  • 使用趋势 → usage-dashboard__panel--trend + usage-dashboard-trend SVG。
  • MCP 使用明细 → usage-dashboard-mcp-rows。
  • 状态统计 → usage-dashboard-mcp-status；将现有条形状态改为原型式环图卡。
  • Skill 排行 → usage-dashboard-skill-rows；改造成表格行与占比条。
  • 最近会话 → usage-dashboard-session-rows；改为全宽底部表。
  • MCP 调用明细 → usage-dashboard-detail；作为工具表下方/浮层扩展状态继续保留。

渲染与样式重构决策

  • 当前主内容列宽为 2.4fr : 1fr，直接导致右侧 MCP 状态变成窄边栏；返工为近似 1fr : 1fr。
  • 顶部指标卡保留五列，但增加图标区、信息区和按 data.trend 生成的真实 sparkline，不使用静态假曲线。
  • 趋势图改为“消息/MCP 柱 + 会话/Skill 线”的混合表达，更接近原型且完全来自现有 trend 数据。
  • MCP 工具表改为“排名、Server / Tool、调用、成功、失败、成功率”；成功率单元格同时承担详情入口。
  • 状态统计改为三张真实环图卡：MCP 结果、直接/跨会话消息来源、MCP/Skill 功能使用构成。
  • Skill 排行增加使用占比和进度条；不展示协议没有的独立用户数。
  • 最近会话改为全宽表，增加明确“查看”操作；不展示协议没有的用户和会话时长。
  • 浅色基础视觉对齐参考图；深色/特殊主题只覆盖语义 token 和局部圆角，不复制业务布局。

日期范围交互

  • 现有状态只绑定“本周/本月”，但 syncUsageDashboardPeriod 已允许其他 period 值且不会覆盖日期输入。
  • 新增“自定义”按钮时只需增加 DOM 引用、aria-pressed 同步和事件绑定；查询仍复用 usageRangeFromInputs 与 usage_stats_query。
  • 两个 date input 保持真实可编辑和可访问性，CSS 将它们组合成原型中的单一日期范围控件外观。

趋势字段核对

  • lib/usage-statistics.js 的每日 bucket 已包含 newSessions、messages、directMessages、crossConversationMessages、mcpCalls、mcpFailures、skillMentions。
  • 因此五张指标卡都能生成真实 sparkline，MCP 失败卡不需要用静态图或按总失败率推测每日值。

浏览器验收环境

  • 现有 cc-web 服务 http://127.0.0.1:8002/ 返回 200；远程命名空间地址为 11.144.144.11。
  • PATH 中没有 Chrome，但可复用 /home/hdzx/.cache/ms-playwright/chromium-1228/chrome-linux64/chrome。
  • 项目已有 ws 依赖，可通过 Chrome DevTools Protocol 完成登录、打开看板、读取几何和截图，无需安装新包。
  • 为避免读取或输出线上密码，视觉验收使用单独端口和临时已知测试密码启动同一代码，不重启线上服务。
  • 打开看板会立即触发默认范围查询；自定义日期脚本必须等待该查询结束，否则 disabled 的“应用”按钮不会响应程序化 click。
  • 服务端对同一 WebSocket 的统计查询设置 250ms 间隔；浏览器验收在默认查询完成后等待 320ms，再提交自定义范围。

首轮真实视觉结果

  • 1467×943、washi 主题下，五卡横排，每卡约 222px；主区趋势与 MCP 面板均约 573.5px，严格等宽。
  • 状态与 Skill 面板同样等宽，最近会话从首屏底部露出，整体信息架构已与参考原型一致。
  • 看板和 body 横向溢出均为 0；11 个主题的页面/面板背景均取到对应语义颜色。
  • 待修 1：222px 指标卡中 copy 列过窄，标题和说明出现省略号。
  • 待修 2：MCP 表继承 640px 最小宽度，大于 573.5px 面板内宽，导致成功率百分比需要横向滚动。

第二轮真实视觉结果

  • 指标卡标题/数字/说明已无截断；1467、1024、768、390 四档 textOverflow 均为 0。
  • MCP 表最小宽度降为 520px 后，桌面端六列完整显示，成功率进度条和百分比均可见。
  • 1467×943 下仍保持五卡约 222px、主双栏各 573.5px；看板和 body 横向溢出继续为 0。
  • 与原型相比，顶部筛选和五卡的 y/高度已经接近；主行和下排行略高，导致最近会话首屏只露出标题，需要结合移动端与暗色截图决定是否继续压缩。

移动与暗色对照

  • 390×844 下筛选、日期、五张单列指标卡完整显示，未发生控件重叠；趋势图按页面纵向继续滚动。
  • wasteland 1440×900 下结构、环图、表格和强调色均正确，主题专属 2px 圆角继续生效。
  • 需要隐藏手机标题下过长覆盖说明，并进一步收紧最长指标标题、MCP 行和 Skill 行。

第三轮几何结果

  • 四档视口继续保持横向溢出 0、文字溢出 0；手机标题说明已隐藏。
  • 11 主题中仅 coolvibe 在 1440×900 对最长 Skill 指标标题出现 1 处省略，其他主题均为 0。
  • MCP 紧凑 padding 首次放在通用 table padding 之前，被后置同权重规则覆盖；需调整声明顺序后再测。

最终视觉验收结果

  • 1467×943：五卡横排；主趋势/MCP 各 573.5px 宽、309px 高；状态/Skill 各 573.5px 宽、247.5px 高；最近会话 y=819.2，可见表头与首行。
  • 1024×768、768×1024、390×844：按断点折叠，无页面横向溢出、无检测到的文字溢出。
  • 11 个主题在 1440×900 均为 dashboardOverflowX=0、bodyOverflowX=0、textOverflowCount=0。
  • MCP 调用明细已真实点击展开并截图，成功/失败/其他状态、会话和 Agent 列可见。
  • 共保留 16 张真实 Chrome 截图和 visual-report.json，数据来自临时真实会话与真实 usage_stats_query。

视觉验收数据

  • 视觉夹具复用真实会话 JSON 结构：composerMentions 表达 Skill，assistant.toolCalls 表达 MCP，时间戳覆盖完整自定义日期范围。
  • 夹具仅写入系统临时目录，通过 CC_WEB_CONFIG_DIR / CC_WEB_SESSIONS_DIR / CC_WEB_LOGS_DIR 注入，不污染项目会话数据。
  • 浏览器会设置自定义日期后触发真实 usage_stats_query，截图不是静态 HTML mock。
  • 直接/跨会话消息由 user message 的 crossConversation 布尔值决定；MCP 状态取 toolCall.meta.status；Skill 取 composerMentions，因此视觉夹具可覆盖三个环图的全部分段。