cja-dimension-analysis

CJA 维度分析

分析一个或多个 CJA 维度，了解其基数、分布、趋势、异常、数据质量问题和预测结果。生成可执行的报告，帮助团队了解维度中包含的内容，以及应重点关注的方面。

工作流

按顺序执行各阶段。每个阶段都可选择执行——用户可以要求执行其中一部分（例如“只分析基数和错误”），也可以执行完整分析。默认执行所有阶段。

阶段 0 — 设置

1. 调用 findDataViews 列出可用的数据视图。如果用户尚未指定数据视图，请询问要分析哪个数据视图。使用 setDefaultSessionDataViewId 设置该数据视图。
2. 询问要分析哪些维度。选项：
   • 按名称指定维度：“分析页面名称和浏览器类型”
   • 按 ID 指定：用户直接提供维度 ID
   • 所有维度：提醒这可能需要较长时间；询问要设置的数量上限（默认：按名称排序的前 50 个）
3. 询问要执行哪些分析（或确认默认执行“全部”）：
   • 基数、分布/偏斜、趋势、异常、数据质量、比较、预测
4. 询问日期范围。如果用户尚未指定，则测试几个范围以查找数据：
   • 依次尝试最近 30 天、最近 90 天、最近 6 个月、最近 1 年，使用第一个能返回行的范围。
5. 询问用于分析分布/偏斜的主要指标（默认：发生次数或访问次数）。
6. 继续之前，请与用户确认计划。

阶段 1 — 基数

针对每个维度：

1. 调用 searchDimensionItems(dimensionId, limit: 50000) 估算唯一值数量，或使用该维度作为行并配合计数指标调用 runReport，以获取行数。
2. 对基数进行分类：

   级别	阈值
   低	< 100 个唯一值
   中	100 – 1,000 个
   高	1,000 – 10,000 个
   非常高	> 10,000 个

3. 跟踪基数随时间的变化（可选）：调用 runReport，使用维度和日期细分；统计每天/每周的唯一维度值，以查看基数增长趋势。
4. 对基数为“高”和“非常高”的维度标记性能建议。

存储：{dimensionId, name, uniqueValueCount, cardinalityLevel, cardinalityTrend}

阶段 2 — 分布与偏斜

针对每个维度：

1. 调用 runReport，将维度设为行，并添加主要指标（例如，发生次数/访问次数）。至少请求 50 行，以呈现分布形态。
2. 计算前 N 项占比（前 1、5、10 项）、基尼系数和累积分布。
3. 对偏斜情况进行分类：

   标签	条件
   极端偏斜	占比最高的值 > 总量的 50%
   高度偏斜	占比最高的值 > 总量的 30%
   中度偏斜	前 5 个值 < 总量的 70%
   长尾	前 10 个值 < 总量的 50%

4. 注意：按值细分并提供百分比和累计百分比。

存储：{dimensionId, distribution: [{value, metric, pct, cumulative}], gini, skewLabel, top1Pct, top5Pct, top10Pct}

阶段 3 — 趋势

针对每个维度：

1. 调用 runReport，使用维度和日期粒度（根据范围选择按天或按周）。比较两个时段：所选日期范围的前半段与后半段。
2. 识别：
   • 新值：在时段 2 出现，但时段 1 中没有
   • 消失值：在时段 1 中存在，但时段 2 中没有
   • 增长：时段 2 的指标比时段 1 高 > 10%
   • 下降：时段 2 的指标比时段 1 低 > 10%
   • 稳定：两个时段之间的变化 < 10%
3. 为每个值指定趋势标记：🟢 增长 | 🔴 下降 | 🟡 稳定 | 🆕 新增 | ⬜ 已消失

存储：{dimensionId, periodComparison: {period1, period2, changes: [{value, p1Metric, p2Metric, pctChange, badge}]}, newValues: [], disappearedValues: []}

第 4 阶段 — 异常

针对每个维度：

1. 根据第 3 阶段的时间序列，按维度值计算滚动均值和标准差。
2. Z 分数检测：标记 Z 分数超过阈值的（值，日期）对 （默认值：2.0；敏感：1.5；保守：3.0）。
3. 阈值告警：
   • 任一单个值在某一天占总指标的比例超过 50%
   • 某个值的计数超过该值滚动平均值的 2 倍
4. 新增/消失告警：标记在周期中途出现或消失的值（来自第 3 阶段）。
5. 收集：异常类型（激增、骤降、新增、消失、阈值）、维度值、日期、幅度。

存储：{dimensionId, anomalies: [{value, date, type, magnitude, zScore}]}

第 5 阶段 — 数据质量 / 错误

针对每个维度：

1. 使用 searchDimensionItems 搜索已知的异常值：
   • "Unspecified"、"None"、"(empty)"、""、"null"、"undefined"、"N/A"、"unknown"
2. 使用 runReport 按每个已知异常值进行筛选，并统计出现次数。
3. 计算：缺失数据 % =（异常值出现次数总和）/ 总出现次数。
4. 标记：缺失数据 > 5% 的维度（警告），> 20% 的维度（严重）。
5. 如果维度具有预期格式（URL、电子邮件、日期），请注明 — 但除非用户要求，否则不要自动验证 格式。

存储：{dimensionId, errorPatterns: [{pattern, count, pct}], missingDataPct, missingDataSeverity}

第 6 阶段 — 比较（多维度或时间段）

当用户分析 2 个或更多维度，或要求比较时间段时，运行此阶段。

并排比较（2–3 个维度）：

1. 对每对维度，比较基数级别、偏斜度、前 5 个值和错误率。
2. 生成比较表：针对每项指标比较维度 A、B、C。

时间段比较（单个维度）：

1. 比较用户提供的两个自定义日期范围（或自动检测：前半段与后半段）。
2. 针对每个值，提供第 1 个时间段的指标、第 2 个时间段的指标、变化量、变化百分比。
3. 列出变化最大的值（增长前 5 名、下降前 5 名）。

存储：{comparisons: [{type, dimensions or periods, table}]}

第 7 阶段 — 预测

针对具有足够时间序列数据（>= 7 个数据点）的每个维度：

1. 对指标排名前 5–10 的值，拟合时间序列线性回归。
2. 向前预测 7 个周期。
3. 报告：
   • 趋势方向：上升 / 下降 / 持平（根据斜率判断）
   • 置信度：高（R² > 0.7）、中（0.4–0.7）、低（< 0.4）
   • 预测窗口结束时的预测值
4. 标记具有明显上升趋势（可能成为主导值）或明显下降趋势（可能很快消失）的值。

存储：{dimensionId, forecasts: [{value, slope, r2, direction, confidence, projectedValues: []}]}

第 8 阶段 — 生成报告

完成所有分析阶段后：

1. 将所有收集的数据保存到 JSON 文件： dimension_analysis_results_YYYY-MM-DD_HH-MM.json （保存到临时输出目录，例如 /tmp/cja-dimension-analysis/，或用户指定的路径）

2. 运行 Python 报告生成器：

   python3 scripts/cja_dimension_analysis.py \
     <analysis_json> \
     "<data_view_name>" \
     "<data_view_id>" \
     [output_directory] \
     [--format=html|markdown] \
     [--keep-analyses=N]
   

   选项：

   • --format=html（默认）：带有 Chart.js 可视化图表的交互式 HTML 仪表板
   • --format=markdown：包含表格的综合文本报告
   • --keep-analyses=N（默认值：0 = 全部保留）：自动清理旧的分析文件

3. 脚本会生成第二个输出文件：报告（HTML 或 Markdown）。

4. 使用 open <output_directory>/dimension_analysis_report_*.html 打开

5. 向用户提供报告路径，并总结关键发现：

   • 基数为高 / 非常高的维度
   • 偏斜度极端或较高的维度
   • 发现的任何异常
   • 超过警告阈值的数据质量问题
   • 值得关注的预测趋势

CJA MCP 工具

工具	阶段	用途
findDataViews	0	列出可用的数据视图
setDefaultSessionDataViewId	0	设置会话的活动数据视图
findDimensions	0	按名称或搜索条件发现维度
describeDimension	0	获取维度元数据和 ID
searchDimensionItems	1, 5	统计唯一值；搜索特定项目（错误模式）
runReport	1–7	主要数据引擎：维度行 + 指标，可选按日期细分

输出格式

HTML 仪表板（默认）

交互式报告，包含：

• 执行摘要卡片（维度总数、已标记维度、严重问题）
• 各维度板块：基数徽章、分布图（Chart.js 柱状图）、偏斜指标、 趋势表、异常列表、数据质量指标
• 对比板块（如果请求了多个维度或期间对比）
• 预测板块（如果运行了预测）
• 建议面板：按优先级分组（严重 → 警告 → 信息）
• 设计：深海军蓝到蓝色渐变标题栏、全宽、卡片式布局、可折叠板块

报告 HTML 样式 — 必须遵循

生成的 HTML 必须采用所有技能共用的编辑风格设计系统： 温暖的米白色背景、衬线字体标题、红黑渐变标题栏，以及悬停时带下划线的文本链接导航。不要使用企业蓝色风格的界面元素、居中标题或其他渐变。

阅读 template.html 并原样使用。文件中包含 Google Fonts <link> 标签、完整的 CSS 块和 <header> 结构。 将 <head> 块粘贴到生成报告的 <head> 中，将 <header> 块粘贴到 <body> 顶部，并填入 {ORG_NAME}、 {DIMENSION_COUNT}、{DATE_RANGE}、{DATA_VIEW_NAME} 和 {DATE} 占位符。不要自行发挥样式。

其中，{ORG_NAME} 是客户的品牌名称（去掉 — Prod、 - Demo、 MCP、 Stage 等技术后缀）。标题中绝不能替换为供应商或产品名称。标题应全部为白色 — 不要将任何文字设为红色。对于单维度报告，将 h1 替换为 {ORG_NAME} {DIMENSION_NAME} Report。

板块标题 — 不带阶段前缀：HTML 报告中的板块标题不得包含阶段编号。仅使用简洁的板块名称：

• ✅ “基数” — 而不是“阶段 1 — 基数”
• ✅ “分布与偏斜” — 而不是“阶段 2 — 分布与偏斜”
• ✅ “趋势” — 而不是“阶段 3 — 趋势”
• ✅ “数据质量” — 而不是“阶段 5 — 数据质量 / 错误”

Markdown 报告

文本格式的报告，包含：

• 所有维度的汇总表
• 各维度深入分析板块及内嵌表格
• 异常日志
• 附带依据的建议

scripts/cja_dimension_analysis.py 使用的 JSON 架构源自上述各阶段中的 Store: {...} 结构。脚本会处理自身的输入约定；请按照各阶段的 Store 条目构建 JSON。

示例交互

“你能分析一下我们的‘营销渠道’维度表现如何，并按设备类型细分吗？”

1. 设置： 使用 findDataViews 确认数据视图。调用 setDefaultSessionDataViewId。
2. 发现维度： 调用 findDimensions 查找“营销渠道”维度及其 ID。使用 searchDimensionItems 确认其存在且包含数据。
3. 分析： 运行 runReport，分析过去 30 天内营销渠道的表现（访问次数、转化次数、收入）。找出表现最佳和最差的项目。
4. 细分： 运行第二份报告，按设备类型维度交叉统计营销渠道，以揭示移动设备与桌面设备的模式。
5. 报告： 运行 Python 分析脚本，生成交互式 HTML 报告。打开报告。总结主要发现：“电子邮件带来了 38% 的转化，尽管流量占比只有 12%。付费搜索在移动设备上的转化率是桌面设备的 2 倍。”

重要注意事项

• 切勿修改维度定义或项目数据。本分析为只读操作。
• 如果所选日期范围内某个维度没有返回数据，请先尝试扩大日期范围，再决定是否放弃。
• 对于基数非常高（> 50k 个值）的维度，请说明完整分布分析可能会被截断，并使用采样后的前 N 个值。
• 如果针对某个维度的 runReport 超时，请减少行数限制并说明该限制。
• 始终告知用户正在运行哪些分析，以及跳过了哪些分析。
• 对于大型维度集合（> 20 个维度），先运行第 1–2 阶段，并询问用户是否希望对某个子集进行更深入的分析。
• 随着各阶段推进，向用户告知进度：“第 1 阶段已完成（5 个维度的基数）。正在运行第 2 阶段（分布）……”