Data Agent 自定义网页报告

更新时间:
复制为 MD 格式

本文介绍如何通过 DataAgent 的自定义网页报告功能,使用 JSON DSL 配置来构建结构化、可交互的数据分析报告。

前提条件

  • 已开通 DMS Data Agent 服务。

  • 已创建至少一个可用的数据源。

说明

初次学习时,可以使用 DataAgent 提供的内置数据源 internal_data_employees 来跟随本教程进行练习。

快速开始

创建自定义 Agent 并开启报告功能

目前,“自定义网页报告”功能需要通过创建一个自定义 Agent 来使用。

  1. 登录数据管理DMS 5.0

  2. 在顶部导航栏选择Data+AI > Data Agent For Analytics,或在极简模式下,点击右上角image图标,选择全部功能 > Data+AI > Data Agent For Analytics进入Data Agent

    image

  3. 在 DataAgent 首页,在左侧导航栏选择自定义Agent

  4. 自定义Agent页面中,点击开始创建

  5. 创建自定义Agent页面中,在基本信息模块中输入名称描述

  6. 上下文模块中,打开选择数据范围,可选择DataAgent 提供的内置数据源 internal_data_employees

  7. 展开更多配置,找到并开启定制网页报告的开关。

    说明

    在体验阶段,建议将执行计划执行查询SQL输出网页报告过程询问等环节均设为直接执行模式,以便直接查看整体效果。

  8. 在下方的配置区域,粘贴你的网页报告定义,可参见附录:完整配置示例

    https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/oJGq75kkg0rWylAK/img/02ffa2f9-6a3a-4273-b870-4f053a11ea50.png

  9. 完成配置后,在发起会话时选择你的自定义 Agent,就可以看到网页报告的生成效果,然后不断调整配置来达到你想要的样式。

    选择自定义Agent发起会话

    体验过程中,internal_data_employees 数据库的全量报告生成预计耗时 5 至 10 分钟,请您稍候。

理解报告配置的基本框架

要定制一个网页报告,你需要提供一段 JSON 格式的配置。它的基本框架包含四个核心部分:

字段

是否必填

作用

version

可选

配置协议版本,本教程统一使用 1.0

root

必填

报告的“骨架”,用来定义报告的整体内容和结构。

metadata

可选

定义报告的全局风格,如配色、字号等,让 AI 遵循统一规范。

metrics

可选

定义报告中需要执行的 SQL 查询,供 BI 节点调用。

理解 root 与“节点”的概念

root 是整个报告的“根”。它通过父子节点的层级关系来组织报告内容。可以把每个“节点”想象成报告中的一块积木,root 就是所有积木的起点。

每个节点都包含三个基本属性:

  • type (类型):决定了这块积木“是什么”。一共有四种类型:

    类型

    说明

    Container

    容器:一个透明的盒子,本身不显示内容,专门用来划分区域、组织其他积木(子节点)的排列方式。

    Text

    纯文本:直接显示你写在配置里的固定文字。

    AGUI

    AI 生成内容:一块“魔法画布”,由 AI 根据你的提示词自动生成文字、图表等内容。

    BI

    自定义 SQL 数据:一块“数据展示板”,通过执行你预先定义的 SQL 来精确展示数据分析结果。

  • description (描述):这块积木的“说明书”。在 Text 节点里,它就是要显示的文字;而在 AGUI 和 BI 节点里,它是指导内容生成的提示词或说明。

  • layout (布局):决定了这块积木的“外观和样式”。不同类型的节点支持不同的布局,后文会逐一介绍。

动手写你的第一个报告

让我们从最简单的配置开始。下面的例子创建了一个只有标题的报告:

{
  "version": "1.0",
  "root": {
    "type": "Container",
    "layout": "Single",
    "children": [
      {
        "type": "AGUI",
        "description": "生成一个渐变色蓝紫背景的报告标题区域,用大号字体突出显示固定文本:'员工薪酬结构与公平性分析报告'。",
        "layout": "Block"
      }
    ]
  }
}

代码解读:

  • 我们用一个 Container 作为根节点,并设置其布局为 Single(即子节点从上到下垂直排列)。

  • 在这个容器的 children 数组中,我们放了一个 AGUI 类型的子节点。

  • 这个 AGUI 节点的 description 告诉 AI:“请生成一个带蓝紫渐变背景的标题,内容是‘员工薪酬结构与公平性分析报告’”。

效果如图,一个简洁的标题卡片就生成了:

https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/oJGq75kkg0rWylAK/img/b440e56f-6f76-46f5-9ec5-6aef8542aef1.png

说明

Container 节点通过其专有的 children 字段来添加子节点。想给报告增加内容,就往 children 数组中添加新的节点即可。

给报告添加更多内容

一个只有标题的报告太简陋了。假设我们想增加一节全体员工薪资分析,包含小标题、薪资分布直方图和分析结论。做法很简单:在根节点的 children 中新增一个 Container,然后在这个新容器内部放置三个子节点。

  • 一个 Text 节点(布局 AdaptiveTitle)作为小节标题。

  • 一个 AGUI 节点(布局 Chart)来绘制薪资直方图。

  • 一个 AGUI 节点(布局 Card)来展示薪资分析结论。

{
  "version": "1.0",
  "root": {
    "type": "Container",
    "layout": "Single",
    "children": [
      {
        "type": "AGUI",
        "description": "生成一个渐变色蓝紫背景的报告标题区域...",
        "layout": "Block"
      },
      // 新增的分析模块
      {
        "type": "Container",
        "layout": "Card", // 使用 Card 布局,让这个模块看起来像一张卡片
        "children": [
          {
            "type": "Text",
            "description": "员工薪资整体分布",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "AGUI",
            "description": "绘制当前员工薪资分布的直方图。X轴为薪资,Y轴为员工数量。悬停时显示具体数量。",
            "layout": "Chart"
          },
          {
            "type": "AGUI",
            "description": "生成一个带浅紫色背景和紫色左侧竖条的卡片。用一段简洁的文字概述薪资分布的核心特征。",
            "layout": "Card"
          }
        ]
      }
    ]
  }
}

效果如图,现在报告有了一个标题和一个完整的分析模块:

https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/oJGq75kkg0rWylAK/img/af639625-801d-489e-8d64-1f9f3c9b4571.png

完成配置后,在发起会话时选择你的自定义 Agent,就可以看到网页报告的生成效果了。接下来,你可以不断调整 JSON 配置,直到报告样式完全符合你的预期。


节点类型与布局详解

这一章将逐一介绍每种节点类型下支持的 layout 布局,并配有代码示例和效果图,帮你在实际配置中快速选用。

Container(容器节点)

Container 本身不显示任何业务内容,它的唯一职责是组织和排列子节点。只有 Container 才能使用 children 字段来包含子节点。

布局

效果

适用场景

Single

单列布局:子节点从上到下依次纵向排列,每个子节点独占整行。

报告中的大章节区域,用于串联多个内容块。

Double

左右双列布局:子节点分为左右两列显示,可通过 ratio 字段控制宽度比例(如 "1:1")。

对比类场景,如图文并茂的分析。

Flex

自适应网格布局:子节点根据屏幕宽度自动排列成多列网格。

多个同类卡片的并排展示,如 KPI 指标卡片组。

Card

卡片容器:一个带有统一样式的卡片区域,所有子节点都包裹在同一张卡片内。

将一组强相关的内容(如标题+图表+文字)包裹成一个视觉整体。

Footer

页脚布局:位于页面底部的小号灰色文字区域。

放置免责声明、数据来源、生成时间等辅助信息。

  • Single - 单列布局

    • 代码示例:

      {
        "type": "Container",
        "description": "核心发现与建议",
        "layout": "Single",
        "children": [
          {
            "type": "Text",
            "description": "核心发现与建议",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "AGUI",
            "description": "主要发现卡片,浅紫色背景(#F5F0FF),紫色左侧竖条(#7C3AED)。标题"主要发现"使用深紫色(#5B21B6)加粗。以带序号的列表呈现核心发现。",
            "layout": "Card"
          },
          {
            "type": "AGUI",
            "description": "可执行建议卡片,浅绿色背景(#F0F9F1),绿色左侧竖条(#16A34A)。以表格形式展示相关建议。",
            "layout": "Table"
          }
        ]
      }
      
    • 效果示例:

      Single布局效果

  • Double — 左右双列布局

    • 代码示例:

      {
        "type": "Container",
        "description": "性别薪资对比展示区",
        "layout": "Double",
        "ratio": "1:1",
        "gap": "4",
        "children": [
          {
            "type": "AGUI",
            "description": "整体公平性评价卡片,浅绿色背景。",
            "layout": "Card"
          },
          {
            "type": "AGUI",
            "description": "关键问题发现卡片,浅黄色背景。",
            "layout": "Card"
          }
        ]
      }
      
    • 效果示例:

      Double布局效果

    重要

    使用 Double 布局时,请务必显式声明 ratio 字段(如 "1:1" 或 "1:2"),否则可能导致意外的宽度分配。

  • Flex — 自适应网格布局

    • 代码示例:

      {
        "type": "Container",
        "description": "关键指标卡片组",
        "layout": "Flex",
        "gap": "4",
        "children": [
          {
            "type": "AGUI",
            "description": "平均薪资指标块,白色背景带阴影。大号数字居中,下方小字说明。顶部蓝色横条。",
            "layout": "Block"
          },
          {
            "type": "AGUI",
            "description": "员工总数指标块,白色背景带阴影。大号数字居中,下方小字说明。顶部绿色横条。",
            "layout": "Block"
          },
          {
            "type": "AGUI",
            "description": "部门数量指标块,白色背景带阴影。大号数字居中,下方小字说明。顶部紫色横条。",
            "layout": "Block"
          }
        ]
      }
      
    • 效果示例:

      Flex布局效果

  • Card — 卡片容器

    • 代码示例:

      {
        "type": "Container",
        "description": "模块五:性别与薪资差异分析",
        "layout": "Card",
        "children": [
          {
            "type": "Text",
            "description": "五、性别与薪资差异分析",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "AGUI",
            "description": "绘制四象限散点图展示部门薪资与人数分布。",
            "layout": "Chart"
          }
        ]
      }
      
    • 效果示例:

      Card布局效果

  • Footer — 页脚布局

    • 代码示例:

      {
        "type": "Container",
        "description": "报告页脚区域",
        "layout": "Footer",
        "children": [
          {
            "type": "AGUI",
            "description": "页脚信息块,深灰色背景,白色文字。居中显示数据来源、生成时间和版权信息。使用小号字体。",
            "layout": "Block"
          }
        ]
      }
      
    • 效果示例:

      Footer布局效果

Text(纯文本节点)

Text 节点用于显示固定的、确定的文字。它的 description 内容会被原样展示,不会被 AI 加工。

布局

效果

适用场景

AdaptiveTitle

根据上下文自动调整样式的标题或段落文字。

报告主标题、各章节小标题、段落说明。

Span

较短的内联文本块。

卡片内的小标签、简短注释等。

  • AdaptiveTitle — 自适应标题

    • 代码示例:

      {
        "type": "Text",
        "description": "核心发现与建议",
        "layout": "AdaptiveTitle"
      }
      
    • 效果示例:

      AdaptiveTitle效果

  • Span — 短文本标签

    • 代码示例:

      {
        "type": "Text",
        "description": "关键问题发现",
        "layout": "Span"
      }
      
    • 效果示例:

      Span效果

AGUI(AI 生成内容节点)

AGUI 节点由 AI 大模型根据 description 中的提示词自动生成内容。这里的 description 不是最终文字,而是给 AI 的生成指令。

新手提示:在 description 中写得越具体(颜色、布局、数据要求),AI 生成的内容就越符合你的预期。避免模糊指令,如“随便写一段分析”。

布局

效果

适用场景

CardHeader

视觉效果突出的头部卡片,适合做章节的“封面”。

某个大段内容的开头标题区域。

Chart

基于 Recharts 库生成的可视化图表(柱状图、折线图、饼图等)。

各类数据的可视化展示。

Table

带表头和表体的数据表格。

明细数据表、排名表、对比表等。

Card

带边框、阴影和内边距的常规卡片,通常包含图标、标题和正文。

指标展示卡、洞察卡、建议卡等偏文字内容的展示。

Block

相对自由的内容区域,可混合文本、列表、图标等,样式灵活。

需要一些排版但不想被“卡片”样式束缚的复杂分析段落。

Text

以文字为主,但会加入图标、加粗等视觉元素,比纯文本更有表现力。

重点说明、关键洞察的文字块。

  • CardHeader — 章节头部卡片

    • 代码示例:

      {
        "type": "AGUI",
        "description": "薪资分析报告标题头部,渐变蓝紫背景。主标题"薪资结构深度分析"使用大号白色字体加粗,副标题"基于2003年全年数据的综合评估"使用中号浅色字体。",
        "layout": "CardHeader"
      }
      
    • 效果示例:

      CardHeader效果

  • Chart — 图表

    • 代码示例:

      {
        "type": "AGUI",
        "description": "绘制柱状图展示各职位薪资变异系数对比。X轴为职位名称,Y轴为薪资变异系数。柱状图按变异系数从高到低排序,配色使用紫色系。",
        "layout": "Chart"
      }
      
    • 效果示例:

      Chart效果

  • Table — 表格

    • 代码示例:

      {
        "type": "AGUI",
        "description": "可执行建议卡片,浅绿色背景(#F0F9F1),绿色左侧竖条(#16A34A)。以表格形式展示建议,表头为"问题领域"和"建议措施"。",
        "layout": "Table"
      }
      
    • 效果示例:

      Table效果

  • Card — 卡片

    • 代码示例:

      {
        "type": "AGUI",
        "description": "薪资分布核心特征卡片,浅紫色背景(#F5F0FF),紫色左侧竖条(#7C3AED)。标题"分布特征"使用深紫色加粗。以一段简洁文字概述分布特征。",
        "layout": "Card"
      }
      
    • 效果示例:

      Card效果

  • Block — 自由内容块

    • 代码示例:

      {
        "type": "AGUI",
        "description": "部门数量指标块,白色背景带阴影。大号数字"9"居中显示,下方小字"业务部门数"。顶部紫色横条,右上角建筑图标。",
        "layout": "Block"
      }
      
    • 效果示例:

      Block效果

  • Text — 增强文字块

    • 代码示例:

      {
        "type": "AGUI",
        "description": "数据说明文本块,深灰色文字。内容:"本报告数据来源于HR系统,涵盖2003年全年薪资记录。分析方法包括描述性统计、相关性分析和趋势预测。所有货币单位为人民币元。"左对齐,标准字号。",
        "layout": "Text"
      }
      
    • 效果示例:

      Text布局效果

BI(自定义 SQL 数据节点)

BI 节点让你能在报告中插入由你编写的 SQL 查询结果。它通过 metric 字段与顶层 metrics 数组中定义的 SQL 进行关联。

说明

AGUI 是让 AI 自由发挥,BI 则是让你精确控制数据来源——你写 SQL,系统执行,结果直接展示。

布局

效果

适用场景

Table

支持数字格式化、标签、图标等高级功能的数据表格。

需要精确展示数据的指标表,如“风险等级表”。

ScatterQuadrant

带有 X/Y 均值参考线的四象限散点图,用于分类分析。

“高薪高人数”等四象限分析场景。

MetricCard

单个关键指标的大号展示卡片,包含标题、主数值和图标。

核心 KPI 的突出展示,如平均薪资、员工总数。

  • Table — BI 表格

    • 代码示例:

      {
        "type": "BI",
        "metric": "salary_info",
        "description": "部门薪资统计表,展示各部门员工人数、平均薪资和薪资标准差。表格带边框,奇偶行交替背景色。",
        "layout": "Table",
        "params": {
          "bordered": true,
          "striped": true,
          "headerBg": "bg-blue-100",
          "column_styles": {
            "平均薪资": {
              "numberFormat": { "type": "fixed", "decimalPlaces": 2 },
              "unit": " 元"
            },
            "薪资标准差": {
              "numberFormat": { "type": "fixed", "decimalPlaces": 2 },
              "unit": " 元"
            }
          }
        },
        "select_columns": ["dept_name", "员工人数", "平均薪资", "薪资标准差"]
      }
      
    • 效果示例:

      BI Table效果

    重要

    metric 的值(这里是 salary_info)必须与你在配置顶层 metrics 数组中某个指标的 name 字段完全一致

  • ScatterQuadrant — 四象限散点图

    • 代码示例:

      {
        "type": "BI",
        "metric": "salary_info",
        "description": "部门薪资四象限图,X轴为平均薪资,Y轴为薪资标准差。",
        "layout": "ScatterQuadrant",
        "params": {
          "xColumn": "平均薪资",
          "yColumn": "薪资标准差",
          "labelColumn": "dept_name",
          "xAxisLabel": "部门平均薪资(元)",
          "yAxisLabel": "部门薪资标准差(元)"
        }
      }
      
    • 效果示例:

      ScatterQuadrant效果

  • MetricCard — KPI 指标卡片

    • 代码示例:

      {
        "type": "BI",
        "metric": "avg_salary",
        "description": "平均薪资指标卡片。",
        "layout": "MetricCard",
        "params": {
          "title": "公司平均薪资",
          "icon": "TrendingUp",
          "iconColor": "#16a34a"
        }
      }
      
    • 效果示例:

      MetricCard效果

高级配置

全局风格控制:metadata

metadata 用来设置报告级别的通用规则。这些规则会作为全局 Prompt 传给 AI 模型,让所有 AGUI 节点在生成内容时都遵循统一的风格规范,无需在每个节点的 description 里重复描述。

  • 配置推荐结构:

    "metadata": {
      "ai_code_requirements": {
        "framework": "React",
        "empty_state_handling": { ... },
        "style": "...",
        "data_format": "...",
        "language_style": "...",
        "coding_style": "...",
        "avoid_paths": [ ... ]
      }
    }
  • 配置参数说明:

    参数名

    作用

    配置示例

    framework

    声明前端框架类型

    React — 生成 React 函数式组件

    empty_state_handling

    定义数据为空或计算出错时的显示规则

    分别为 card_valuecharttableai_text 设定空状态提示

    style

    全局视觉风格指导

    蓝紫=洞察,黄橙=预警,绿=正面,灰=一般

    data_format

    数值的格式化规则

    0.123 → 12.3%,薪资保留整数并加"元"

    language_style

    AI 文本表述风格约束

    减少重复、引用具体数据支撑论点

    coding_style

    JSX 代码编写规范

    特殊字符用 {""} 包裹

    avoid_paths

    已知错误案例

    禁用 ButtonGroup;避免 > / <

  • 配置示例:

    "metadata": {
        "ai_code_requirements": {
          "framework": "React",
          "empty_state_handling": {
            "null_data_per_module": {
              "card_value": "显示 '--' 或 '暂无数据'",
              "chart": "显示空白图表 + 居中文字 '暂无数据'",
              "table": "显示表头 + 表体一行 '暂无数据'",
              "ai_text": "显示 '暂无分析建议,请确认该周期内有业务数据。'"
            },
            "calculation_error": "如分母为0,显示 '--'"
          },
          "style": "视觉效果丰富,善于运用背景色、带颜色的左侧起始条、Icon等营造视觉效果。不同类型的分析内容使用不同的卡片样式:洞察发现使用蓝色/紫色系,风险预警使用黄色/橙色系,正面结论使用绿色系,一般说明使用灰色系。",
          "data_format": "有单位的数字在展示的时候带上单位,尤其是如果有%不要省略;当观察到数值内容可能是小数形式的百分比的时候,应当将其转为百分比。所有小数均保留到一位小数。",
          "language_style": "减少重复文本的出现,以保持内容精炼;生成的文本风格要充实专业,产生的推断和建议要有理有据、客观可信,避免出现基于猜测的数值;分析文本需引用具体数据支撑论点",
          "coding_style": "使用{\"\"} 包裹括号,比如 2 {\">\"} 1 ; 1 {\"<\"} 2",
          "avoid_paths": [
            "ButtonGroup is not exported -- don't use ButtonGroup",
            "Unexpected token `>` -- avoid to use raw > or <"
          ]
        }
      }

自定义 SQL 查询:metrics

metrics 是配置顶层的一个数组字段,用来定义报告所需的所有 SQL 查询。

  1. 定义 SQL 查询:
    在 metrics 数组中,为每个查询定义一个 name(唯一标识)和 sql(查询语句)。

    "metrics": [
        {
          "name": "salary_info",
          "sql": "SELECT d.dept_name, COUNT(s.emp_no) AS 员工人数, AVG(s.salary) AS 平均薪资, STDDEV(s.salary) AS 薪资标准差  FROM `salaries` s  INNER JOIN `dept_emp` de ON s.emp_no = de.emp_no  INNER JOIN `departments` d ON de.dept_no = d.dept_no  WHERE s.to_date = '2003-01-01'  AND de.to_date = '2003-01-01'  GROUP BY d.dept_name;"
        },
        {
          "name": "total_employees",
          "sql": "SELECT COUNT(DISTINCT de.emp_no) AS total FROM `dept_emp` de WHERE de.to_date = '2003-01-01';"
        },
        {
          "name": "avg_salary",
          "sql": "SELECT AVG(s.salary) AS average_salary FROM `salaries` s WHERE s.to_date = '2003-01-01';"
        }
      ]

    字段

    类型

    说明

    name

    string

    指标的唯一标识名,BI 节点通过这个名字来引用对应的查询结果

    sql

    string

    要执行的 SQL 查询语句

  2. 在 BI 节点中引用:
    在 BI 节点中,通过 metric 字段填写对应的 name 值即可关联到查询结果。

    {
      "type": "BI",
      "metric": "salary_info",
      "description": "部门薪资统计表(BI Table示例),展示各部门员工人数、平均薪资和薪资标准差。表格带边框,奇偶行交替背景色。",
      "layout": "Table",
      "params": {
        "bordered": true,
        "striped": true,
        "headerBg": "bg-blue-100",
        "column_styles": {
          "平均薪资": {
            "numberFormat": {
              "type": "fixed",
              "decimalPlaces": 2
            },
            "unit": " 元"
          }
        }
      },
      "select_columns": [
        "dept_name",
        "员工人数",
        "平均薪资",
        "薪资标准差"
      ]
    }
    重要

    BI 节点的 metric 值必须与 metrics 数组中某个指标的 name 完全匹配。

使用 Skill 一键生成配置

如果你觉得手动编写 JSON 配置太繁琐,可以使用 Skill 工具 来辅助生成。你只需用自然语言描述你想要的报告内容和大致样式,Skill 就能自动生成一份初版配置,然后你再根据实际效果进行微调。

  • Skill 配置文件(skill.md)

    在你的 Skill 中使用以下配置(详情参考 web-report-json-builder 技能):

    ---
    name: web-report-json-builder
    description: 用于构建符合规范的网页报告JSON结构。提供ContainerNode/TextNode/BINode/AGUINode节点详解、典型布局模式、元数据规范、指标管理指南及常见错误规避。当需要生成可渲染为网页报告的JSON(含布局容器、静态文本、BI可视化、AI生成内容等节点组合)时使用此技能。
    ---
    
    # 网页报告JSON构建指南
    
    > 本技能为Claude提供构建网页报告JSON的完整规范。所有内容均为Claude执行时需遵循的硬性规则,非建议性说明。
    
    ## 核心原则
    - **TextNode仅含最终文本**:禁止包含"请生成""分析如下"等提示语
    - **AGUI提示词即指令**:描述需包含结构+样式+示例+边界处理
    - **Container是纯骨架**:不承载业务逻辑,仅组织子节点布局
    - **复用优于重复**:指标在root.metrics统一管理,metadata定义全局规则
    
    ## 节点规范速查
    
    ### ContainerNode(布局容器)
    ```json
    {
      "type": "Container",
      "layout": "Card|Single|Double|Flex|Footer",
      "ratio": "1:2", // 仅Double布局需要
      "children": [...]
    }
    ```
    ✅ **必须**  
    - 用`Card`替代废弃的CardWithHeader/CardWithoutHeader  
    - 双栏布局显式声明`ratio`(如"1:1")  
    ❌ **禁止**  
    - 在`description`写业务说明(该字段仅调试用)  
    - 混入文本内容(用TextNode承载)
    
    ### TextNode(静态文本)
    ```json
    {
      "type": "Text",
      "layout": "AdaptiveTitle|Span",
      "description": "模块标题" // 必须是最终渲染文本
    }
    ```
    ✅ **适用**:标题/标签/固定说明  
    ❌ **禁止**:  
    - `"description": "请写经营小结"` → 应为`"本周经营小结"`  
    - 任何需AI生成的内容
    
    ### BINode(BI可视化)
    ```json
    {
      "type": "BI",
      "layout": "Table|ScatterQuadrant|MetricCard",
      "metric": "shop_core", // 必须匹配metrics.name
      "select_columns": ["指标名称", "本期数值"],
      "params": {
        "column_styles": {
          "本期数值": { "numberFormat": { "type": "percentage", "decimalPlaces": 1 } }
        }
      }
    }
    ```
    ✅ **必须**  
    - 显式声明`select_columns`(避免冗余列)  
    - 百分比等格式在`params`中定义,具体语法以各组件支持的语法为准  
    ❌ **禁止**:禁止使用未在root.metrics注册的metric
    
    ### AGUINode(AI生成内容)
    ```json
    {
      "type": "AGUI",
      "layout": "Card|Block",
      "description": "生成浅黄色背景卡片(#FFF9E6),深棕色文字(#5A3E1F)。内容:1. 潜力部分(标题+影响)2. 重点行动(措施标题+影响)。仅针对未达标指标,1-2条。示例:改善售罄问题→售罄率降低15.5%。无数据时显示'暂无用户反馈'"
    }
    ```
    **提示词六要素**(缺一不可):  
    1. 内容结构(分点/标题)  
    2. 输出范围("仅未达标指标")  
    3. 数据依据("基于指标关联模型")  
    4. 样式细节(颜色/字号/组件)  
    5. 格式示例("改善...→降低X%")  
    6. 边界处理("无数据时显示...")  
    ❌ **禁止**:"写一段分析""自由发挥"等模糊指令
    
    ## 全局规范
    
    ### metadata(根节点字段)
    ```json
    "metadata": {
      "ai_code_requirements": {
        "framework": "React",
        "style": "正文字号text-sm,善用背景色和Icon",
        "data_format": "百分比保留1位小数,带%单位",
        "language_style": "避免geek风格,建议需有理有据",
        "avoid_paths": ["禁用ButtonGroup", "避免raw>"]
      }
    }
    ```
    → 所有AGUI节点继承此规范,避免重复描述
    
    ### metrics(根节点字段)
    ```json
    "metrics": [
      {
        "name": "shop_cnt",
        "sql": "SELECT count(*) FROM `shops` WHERE manager_name='{经理名称}'"
      }
    ]
    ```
    ✅ **必须**  
    - SQL压缩为单行(用`\n`转义换行)  
    - 模板变量用`{变量名}`(如`{开始日期}`)  
    - 同一指标多处复用  
    
    ## 典型模式(直接复用)
    
    ### 模式1:标准模块
    ```json
    {
      "type": "Container",
      "layout": "Card",
      "children": [
        {"type": "Text", "description": "销售分析", "layout": "AdaptiveTitle"},
        {"type": "BI", "layout": "Table", "metric": "sales_data", "select_columns": ["品类", "销售额"]},
        {"type": "AGUI", "layout": "Card", "description": "生成蓝色标题卡片...(遵循六要素)"}
      ]
    }
    ```
    
    ### 模式2:双栏对比
    ```json
    {
      "type": "Container",
      "layout": "Double",
      "ratio": "1:1",
      "children": [
        {"type": "BI", "metric": "metric_a"},
        {"type": "BI", "metric": "metric_b"}
      ]
    }
    ```
    
    ### 模式3:指标卡片组
    ```json
    {
      "type": "Container",
      "layout": "Flex",
      "children": [
        {"type": "BI", "layout": "MetricCard", "metric": "a"},
        {"type": "BI", "layout": "MetricCard", "metric": "b"}
      ]
    }
    ```
    
    ## 常见错误速查表
    | 错误现象 | 正确做法 |
    |----------|----------|
    | TextNode写"请生成标题" | 直接写"本周经营小结" |
    | ContainerCardWithHeader | 改用`"layout": "Card"` |
    | AGUI提示词模糊 | 补全六要素(结构+范围+依据+样式+示例+边界) |
    | BI未指定select_columns | 显式声明所需列名 |
    | 忽略空数据处理 | 依赖metadata规范或提示词中声明 |
    
    ## 执行清单(生成前必查)
    - [ ] 所有TextNode.description为最终文本  
    - [ ] AGUI提示词包含六要素  
    - [ ] BINodemetric已在root.metrics注册  
    - [ ] Container仅用Card/Single/Double/Flex  
    - [ ] metadata已定义全局样式与空状态规则  
    - [ ] 双栏布局显式声明ratio  
    - [ ] 指标SQL使用模板变量(如`{经理名称}`)  
    
    > 本技能为自包含规范,无需外部资源。所有规则均需严格遵守,确保生成的JSON可被渲染引擎正确解析。
  • 提问示例

    你可以将你的分析计划和样式要求一起发给 AI,让它调用 Skill 来生成配置。例如:

    <requirement>
    <plan>
    <item>
    <order>1</order>
    <name>员工薪资整体分布与趋势分析</name>
    <description>了解1985-2002年间公司员工薪资的整体水平、分布特征及时间变化趋势,为后续深入分析提供基础。</description>
    <content>
    - 统计各年度在职员工的平均薪资、中位数薪资、最高/最低薪资;
    - 展示薪资随时间变化的趋势图(如年度平均薪资走势);
    - 分析薪资的分布形态(如薪资区间的员工人数分布直方图);
    - 识别薪资异常值或极端情况(如极高或极低薪资记录)。
    </content>
    <type>趋势</type>
    <dependency></dependency>
    </item>
    <item>
    <order>2</order>
    <name>不同部门的薪资对比分析</name>
    <description>揭示各部门之间的薪资差异,辅助评估部门间薪酬公平性与资源配置合理性。</description>
    <content>
    - 按部门(dept_name)分组,计算当前有效记录下的平均薪资、薪资总额及员工人数;
    - 对比各部门历史平均薪资变化趋势(1985–2002);
    - 识别薪资水平显著高于或低于公司平均水平的部门;
    - 结合部门管理者信息,初步判断管理层与普通员工薪资差距。
    </content>
    <type>分类</type>
    <dependency>1</dependency>
    </item>
    <item>
    <order>3</order>
    <name>职位级别对薪资的影响分析</name>
    <description>探究不同职位级别(title)与薪资之间的关系,验证职级体系是否与薪酬结构匹配。</description>
    <content>
    - 按职位名称(title)分组,统计各职级的平均薪资、薪资范围及人数;
    - 分析同一职级内薪资的离散程度(标准差或四分位距);
    - 跟踪典型职级的薪资随时间的变化趋势;
    - 识别是否存在“同岗不同薪”现象及其可能原因(如入职时间、性别等)。
    </content>
    <type>洞察</type>
    <dependency>1</dependency>
    </item>
    <item>
    <order>4</order>
    <name>性别与薪资公平性分析</name>
    <description>评估公司是否存在性别薪酬差距,支持人力资源政策的合规性与公平性审查。</description>
    <content>
    - 按性别(gender)分组,计算平均薪资、中位数薪资及各职级内的薪资对比;
    - 控制职位、部门、工龄等因素后,分析性别对薪资的独立影响(描述性层面);
    - 统计高薪群体(如薪资前10%)中的性别比例;
    - 对比男性与女性员工的薪资增长速度与晋升机会(结合titlessalaries表)。
    </content>
    <type>洞察</type>
    <dependency>1,2,3</dependency>
    </item>
    </plan>
    <questions>
    </questions>
    </requirement>
    
    这是分析任务的执行计划,现在我需要你根据这里面的内容,调用 /​web_report_config_generator​ 来生成一个网页报告的约束,我希望报告整体颜色使用蓝黄淡色系,root中每个子节点配置中只进行一个任务,例如绘制柱状、绘制折线图、进行分析总结等,将生成的配置覆盖写到test.json
  • 效果示例

    Skill生成的报告效果

附录:完整配置示例

下面是一个完整的自定义网页报告配置实例,覆盖了前文介绍的大部分节点类型和布局。你可以将其作为模板,根据自己的需求进行修改。

{
  "version": "1.0",
  "root": {
    "type": "Container",
    "description": "页面根容器,内包含所有业务模块,采用单列布局。",
    "layout": "Single",
    "children": [
      {
        "type": "AGUI",
        "description": "渐变色蓝紫背景的报告标题区域,用大字体突出展示\u201c员工薪酬结构与公平性分析报告\u201d(固定文本),副标题用小字体显示\u201c数据截至2003年1月1日 \u00b7 覆盖240,124名在职员工\u201d。",
        "layout": "Block"
      },
      {
        "type": "Container",
        "description": "核心发现与建议",
        "layout": "Single",
        "children": [
          {
            "type": "Text",
            "description": "核心发现与建议",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "AGUI",
            "description": "主要发现卡片,浅紫色背景(#F5F0FF),紫色左侧竖条(#7C3AED)。标题\u201c主要发现\u201d使用深紫色(#5B21B6)加粗。以带序号的列表呈现核心发现,列表项间有适当间距,关键数据加粗。",
            "layout": "Card"
          },
          {
            "type": "AGUI",
            "description": "可执行建议卡片,浅绿色背景(#F0F9F1),绿色左侧竖条(#16A34A)。标题使用深绿色(#2E6B3E)加粗,标题文本为\u201c可执行建议\u201d。以表格形式展示相关建议,表头为\u201c问题领域\u201d和\u201c建议措施\u201d,表头深绿色背景。\n文字颜色使用深绿色(#2E6B3E)。",
            "layout": "Table"
          }
        ]
      },
      {
        "type": "Container",
        "description": "模块一:员工薪资整体分布",
        "layout": "Card",
        "children": [
          {
            "type": "Text",
            "description": "一、员工薪资整体分布",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "AGUI",
            "description": "绘制当前员工薪资分布直方图:X轴为薪资,Y轴为员工数量。悬停显示薪资区间对应员工数量。",
            "layout": "Chart"
          },
          {
            "type": "Container",
            "description": "薪资分布分析文本区",
            "layout": "Single",
            "children": [
              {
                "type": "AGUI",
                "description": "薪资分布核心特征卡片,浅紫色背景(#F5F0FF),紫色左侧竖条(#7C3AED)。标题\u201c分布特征\u201d使用深紫色加粗。以一段简洁文字概述分布特征。关键数据加粗显示。",
                "layout": "Card"
              }
            ]
          }
        ]
      },
      {
        "type": "Container",
        "description": "模块二:不同部门的薪资水平对比",
        "layout": "Card",
        "children": [
          {
            "type": "Text",
            "description": "二、不同部门的薪资水平对比",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "AGUI",
            "description": "绘制柱状图展示各部门平均薪资对比。X轴为部门名称,Y轴为平均薪资(元)。图表标题为\u201c各部门平均薪资对比\u201d。柱状图按薪资从高到低排序,配色使用紫色系。",
            "layout": "Chart"
          },
          {
            "type": "Container",
            "description": "部门薪资分析文本区",
            "layout": "Single",
            "children": [
              {
                "type": "AGUI",
                "description": "部门梯队分布卡片,浅蓝色背景(#EFF6FF),蓝色标题。标题\u201c部门薪资梯队分布\u201d使用蓝色(#1D4ED8)加粗。内容以结构化方式展示按照部门的平均薪资划分的梯队,按部门平均薪资排序,每个部门展示人数、标准差和平均薪资三个指标。各梯队之间通过换行区分,关键数据加粗。",
                "layout": "Card"
              },
              {
                "type": "AGUI",
                "description": "直接影响归因卡片,灰色背景(#F9FAFB),蓝色左侧竖条(#2563EB)。CardHeader为\u201c\ud83d\udcca 归因分析\u201d,加粗。分析不同部门薪资差异的形成原因。关键数字加粗。",
                "layout": "Card"
              }
            ]
          }
        ]
      },
      {
        "type": "Container",
        "description": "模块三:薪资与职位级别的关联分析",
        "layout": "Card",
        "children": [
          {
            "type": "Text",
            "description": "三、薪资与职位级别的关联分析",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "AGUI",
            "description": "绘制柱状图展示各职位平均薪资对比。X轴为职位名称,Y轴为平均薪资(元)。图表标题为\u201c各职位平均薪资对比\u201d。柱状图按薪资从高到低排序,配色使用紫色系。",
            "layout": "Chart"
          },
          {
            "type": "Container",
            "description": "职级薪资分析文本区",
            "layout": "Single",
            "children": [
              {
                "type": "AGUI",
                "description": "职级-薪资异常预警卡片,灰色背景(#F9FAFB),红色左侧竖条(#DC2626)。内容分为两个段落,异常数据使用红色加粗突出(Manager: 77,724元 {\u201c<\u201d} Senior Staff: 80,707元)。",
                "layout": "Card"
              },
              {
                "type": "AGUI",
                "description": "绘制柱状图展示各职位薪资变异系数对比。X轴为职位名称,Y轴为薪资变异系数。图表标题为\u201c各职位薪资变异系数对比\u201d。柱状图按变异系数从高到低排序,配色使用紫色系。",
                "layout": "Chart"
              },
              {
                "type": "AGUI",
                "description": "非技术岗离散度洞察卡片,浅黄色背景(#FFF9E6),黄色左侧竖条(#CA8A04)。标题使用深棕色(#5A3E1F)加粗,前缀\ud83d\udca1图标。内容以对比方式呈现。文字颜色使用深棕色(#5A3E1F),关键变异系数数字加粗。",
                "layout": "Card"
              }
            ]
          }
        ]
      },
      {
        "type": "Container",
        "description": "模块四:薪资随时间变化的趋势分析",
        "layout": "Card",
        "children": [
          {
            "type": "Text",
            "description": "四、薪资随时间变化的趋势分析",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "AGUI",
            "description": "绘制折线图展示公司年度平均薪资变化趋势。X轴为年份,Y轴为平均薪资(元)。图表标题为\u201c公司年度平均薪资变化趋势\u201d。配色使用深紫色。",
            "layout": "Chart"
          },
          {
            "type": "Container",
            "description": "趋势分析文本区",
            "layout": "Single",
            "children": [
              {
                "type": "AGUI",
                "description": "整体增长趋势卡片,浅蓝色背景(#EFF6FF),蓝色左侧竖条(#2563EB)。标题使用蓝色(#1D4ED8)加粗,前缀\ud83d\udcc8图标。从分析时间区间内增长值和增长速度的变化情况来分析。\n\n关键增长率和薪资数字加粗,要点之间通过换行区分。",
                "layout": "Card"
              },
              {
                "type": "AGUI",
                "description": "绘制多条折线图展示不同入职年代员工的薪资增长曲线对比。X轴为薪资年份,Y轴为平均薪资(元)。图表标题为\u201c不同入职年代员工的薪资增长曲线对比\u201d。包含三条折线分别代表1980s、1990s、2000s入职群体,需要图例标注。配色使用紫色系渐变,三条线颜色区分明显。",
                "layout": "Chart"
              },
              {
                "type": "AGUI",
                "description": "入职年代群体分化洞察卡片,灰色背景(#F9FAFB),紫色左侧竖条(#7C3AED)。CardHeader为\u201c\ud83d\udca1 不同入职年代群体增长路径分化\u201d,加粗。内容以三行对比呈现。\n关键增幅百分比和薪资数字加粗。三行之间通过适当间距区分。",
                "layout": "Card"
              }
            ]
          }
        ]
      },
      {
        "type": "Container",
        "description": "模块五:性别与薪资差异分析",
        "layout": "Card",
        "children": [
          {
            "type": "Text",
            "description": "五、性别与薪资差异分析",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "AGUI",
            "description": "绘制四象限散点图展示部门薪资与人数分布。X轴为平均薪资,Y轴为员工人数。添加X轴和Y轴均值参考线。图表标题为\u201c部门薪资与规模四象限分析\u201d。配色使用紫色系。",
            "layout": "Chart",
            "chart_type": "ScatterWithReferenceLines"
          },
          {
            "type": "Container",
            "description": "性别薪资对比展示区(Double布局示例)",
            "layout": "Double",
            "ratio": "1:1",
            "gap": "4",
            "children": [
              {
                "type": "AGUI",
                "description": "整体公平性评价卡片,浅绿色背景(#F0F9F1),绿色左侧竖条(#16A34A)。标题使用深绿色(#2E6B3E)加粗,前缀\u2705图标。对比男性和女性的薪资分布特点。内容文字颜色使用深绿色(#2E6B3E),关键百分比数字加粗。",
                "layout": "Card"
              },
              {
                "type": "AGUI",
                "description": "关键问题发现卡片,浅黄色背景(#FFF9E6),橙色左侧竖条(#EA580C)。标题使用深棕色(#5A3E1F)加粗,前缀\u26a0\ufe0f图标。内容以递进关系展示,并给出改进建议。文字颜色使用深棕色(#5A3E1F),关键占比数字加粗。",
                "layout": "Card"
              }
            ]
          }
        ]
      },
      {
        "type": "Container",
        "description": "模块六:补充示例展示剩余布局组合",
        "layout": "Card",
        "children": [
          {
            "type": "Text",
            "description": "六、布局组合完整示例",
            "layout": "AdaptiveTitle"
          },
          {
            "type": "Text",
            "description": "关键问题发现",
            "layout": "Span"
          },
          {
            "type": "AGUI",
            "description": "薪资分析报告标题头部,渐变蓝紫背景。主标题\u201c薪资结构深度分析\u201d使用大号白色字体加粗,副标题\u201c基于2003年全年数据的综合评估\u201d使用中号浅色字体。",
            "layout": "CardHeader"
          },
          {
            "type": "Container",
            "description": "关键指标卡片组(Flex布局示例)",
            "layout": "Flex",
            "gap": "4",
            "children": [
              {
                "type": "AGUI",
                "description": "平均薪资指标块,白色背景带阴影。大号数字\u201c63,810元\u201d居中显示,下方小字\u201c全公司平均薪资\u201d。顶部蓝色横条,右上角钱袋图标。",
                "layout": "Block"
              },
              {
                "type": "AGUI",
                "description": "员工总数指标块,白色背景带阴影。大号数字\u201c240,124\u201d居中显示,下方小字\u201c在职员工总数\u201d。顶部绿色横条,右上角用户图标。",
                "layout": "Block"
              },
              {
                "type": "AGUI",
                "description": "部门数量指标块,白色背景带阴影。大号数字\u201c9\u201d居中显示,下方小字\u201c业务部门数\u201d。顶部紫色横条,右上角建筑图标。",
                "layout": "Block"
              }
            ]
          },
          {
            "type": "AGUI",
            "description": "数据说明文本块(Text布局),深灰色文字。内容:\u201c本报告数据来源于HR系统,涵盖2003年全年薪资记录。分析方法包括描述性统计、相关性分析和趋势预测。所有货币单位为人民币元。\u201d左对齐,标准字号。",
            "layout": "Text"
          },
          {
            "type": "BI",
            "metric": "salary_info",
            "description": "部门薪资统计表(BI Table示例),展示各部门员工人数、平均薪资和薪资标准差。表格带边框,奇偶行交替背景色。",
            "layout": "Table",
            "params": {
              "bordered": true,
              "striped": true,
              "headerBg": "bg-blue-100",
              "column_styles": {
                "平均薪资": {
                  "numberFormat": {
                    "type": "fixed",
                    "decimalPlaces": 2
                  },
                  "unit": " 元"
                },
                "薪资标准差": {
                  "numberFormat": {
                    "type": "fixed",
                    "decimalPlaces": 2
                  },
                  "unit": " 元"
                }
              }
            },
            "select_columns": [
              "dept_name",
              "员工人数",
              "平均薪资",
              "薪资标准差"
            ]
          },
          {
            "type": "BI",
            "metric": "salary_info",
            "description": "部门薪资四象限图(BI ScatterQuadrant示例),X轴为平均薪资,Y轴为薪资标准差。通过四象限分析部门薪资结构特征。",
            "layout": "ScatterQuadrant",
            "params": {
              "xColumn": "平均薪资",
              "yColumn": "薪资标准差",
              "labelColumn": "dept_name",
              "xAxisLabel": "部门平均薪资(元)",
              "yAxisLabel": "部门薪资标准差(元)"
            }
          },
          {
            "type": "AGUI",
            "description": "BI MetricCard说明卡片。内容:“BI MetricCard布局用于展示单一KPI指标卡片,需要配置返回单值的SQL指标。示例配置:SELECT COUNT(*) as total FROM employees,然后设置layout为MetricCard,params包含title、icon、iconColor等参数。”浅灰背景,左侧蓝色竖条。",
            "layout": "Card"
          },
          {
            "type": "BI",
            "metric": "avg_salary",
            "description": "平均薪资分析卡片,展示各部门员工人数、平均薪资和薪资标准差。",
            "layout": "MetricCard",
            "params": {
              "title": "公司平均薪资",
              "icon": "TrendingUp",
              "iconColor": "#16a34a"
            }
          }
        ]
      },
      {
        "type": "Container",
        "description": "报告页脚区域(Footer布局示例)",
        "layout": "Footer",
        "children": [
          {
            "type": "AGUI",
            "description": "页脚信息块,深灰色背景(#374151),白色文字。居中显示三行内容:第一行\u201c数据来源:HR系统 | 分析周期:2003年全年\u201d,第二行\u201c报告生成时间 | 机密等级:内部使用\u201d,第三行\u201c© 2003 Company HR Analytics Team\u201d。使用小号字体。",
            "layout": "Block"
          }
        ]
      }
    ]
  },
  "metadata": {
    "ai_code_requirements": {
      "framework": "React",
      "empty_state_handling": {
        "null_data_per_module": {
          "card_value": "显示 '--' 或 '暂无数据'",
          "chart": "显示空白图表 + 居中文字 '暂无数据'",
          "table": "显示表头 + 表体一行 '暂无数据'",
          "ai_text": "显示 '暂无分析建议,请确认该周期内有业务数据。'"
        },
        "calculation_error": "如分母为0,显示 '--'"
      },
      "style": "视觉效果丰富,善于运用背景色、带颜色的左侧起始条、Icon等营造视觉效果。不同类型的分析内容使用不同的卡片样式:洞察发现使用蓝色/紫色系,风险预警使用黄色/橙色系,正面结论使用绿色系,一般说明使用灰色系。字体对比关系安排妥当,标题突出、正文舒适。作为基准,正文字号采用ShadCN标准的text-sm,其他字号根据相对关系调整",
      "data_format": "有单位的数字在展示的时候带上单位,尤其是如果有%不要省略;当观察到数值内容可能是小数形式的百分比的时候,应当将其转为百分比。所有小数均保留到一位小数。薪资数值保留到整数或两位小数,带\u201c元\u201d单位",
      "language_style": "减少重复文本的出现(如排比、列表中出现相同的前缀等),以保持内容精炼;生成的文本风格要充实专业,产生的推断和建议要有理有据、客观可信,避免出现基于猜测的数值,尤其是行动建议方面;分析文本需引用具体数据支撑论点",
      "coding_style": "使用{\"\"}包裹括号,比如 2 {\">\"} 1 ; 1 {\"<\"} 2 ; 原因A {\"->\"} 结论B",
      "avoid_paths": [
        "ButtonGroup is not exported by \"src/components/ui/button.tsx\" -- don't use ButtonGroup",
        " Unexpected token `>`. Did you mean `&gt;` or `{\">\"}` -- avoid to use raw > or < "
      ]
    }
  },
  "metrics": [
    {
      "name": "salary_info",
      "sql": "SELECT d.dept_name, COUNT(s.emp_no) AS 员工人数, AVG(s.salary) AS 平均薪资, STDDEV(s.salary) AS 薪资标准差  FROM `salaries` s  INNER JOIN `dept_emp` de ON s.emp_no = de.emp_no  INNER JOIN `departments` d ON de.dept_no = d.dept_no  WHERE s.to_date = '2003-01-01'  AND de.to_date = '2003-01-01'  GROUP BY d.dept_name;"
    },
    {
      "name": "total_employees",
      "sql": "SELECT COUNT(DISTINCT de.emp_no) AS total FROM `dept_emp` de WHERE de.to_date = '2003-01-01';"
    },
    {
      "name": "avg_salary",
      "sql": "SELECT AVG(s.salary) AS average_salary FROM `salaries` s WHERE s.to_date = '2003-01-01';"
    }
  ]
}

报告完整效果请参考:Data Agent for Analytics (1).pdf