@loom-framework/core 0.1.0-alpha.83 → 0.1.0-alpha.85

package/builtin-skills/antv-g2-chart/references/transforms/g2-transform-stack-enter.md

@@ -0,0 +1,158 @@
+---
+id: "g2-transform-stack-enter"
+title: "G2 StackEnter 入场动画堆叠变换"
+description: |
+  stackEnter 是 G2 v5 中用于分组入场动画的 Transform，
+  将同一分组内的元素按序错开入场时间（enterDelay），
+  实现"一组一组依次出现"的入场动画效果。
+  常用于柱状图、折线图的分组逐步入场展示。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "stackEnter"
+  - "入场动画"
+  - "enterDelay"
+  - "分组动画"
+  - "transform"
+  - "animation"
+
+related:
+  - "g2-animation-intro"
+  - "g2-transform-stacky"
+  - "g2-mark-interval-grouped"
+
+use_cases:
+  - "柱状图各分组逐批入场（X 分组依次出现）"
+  - "折线图系列逐条依次绘制"
+  - "数据讲述场景中按节奏逐步呈现数据"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform/stack-enter"
+---
+
+## 核心概念
+
+`stackEnter` 为每条数据分配 `enterDelay` 值：
+- 将数据按 `groupBy` 通道（默认 `['x']`）分组
+- 同一组内的元素共享相同的入场延迟
+- 不同组之间依次叠加延迟时间
+
+每组的延迟 = 前面所有组的 `enterDuration` 之和。
+
+## 基本用法（柱状图分组入场）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { month: 'Jan', value: 83 },
+    { month: 'Feb', value: 60 },
+    { month: 'Mar', value: 95 },
+    { month: 'Apr', value: 72 },
+    { month: 'May', value: 110 },
+  ],
+  encode: { x: 'month', y: 'value', color: 'month' },
+  transform: [
+    {
+      type: 'stackEnter',
+      groupBy: ['x'],          // 按 x 分组（每个月份一批）
+      orderBy: null,           // 不额外排序
+      duration: 300,           // 每组动画持续时长（毫秒），默认使用 enterDuration
+    },
+  ],
+  animate: {
+    enter: {
+      type: 'scaleInY',        // 每组柱子从下往上生长
+      duration: 300,
+    },
+  },
+});
+
+chart.render();
+```
+
+## 折线图多系列依次入场
+
+```javascript
+chart.options({
+  type: 'line',
+  data: multiSeriesData,
+  encode: { x: 'date', y: 'value', color: 'series' },
+  transform: [
+    {
+      type: 'stackEnter',
+      groupBy: ['color'],    // 按颜色（系列）分组，每条线依次入场
+      duration: 800,
+    },
+  ],
+  animate: {
+    enter: {
+      type: 'pathIn',        // 折线从左向右绘制
+      duration: 800,
+    },
+  },
+});
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  transform: [
+    {
+      type: 'stackEnter',
+      groupBy: ['x'],          // 分组通道，默认 ['x']
+                               // 可以是单个字符串或数组：['x', 'color']
+      orderBy: null,           // 组间排序依据：null | 'x' | 函数
+      reverse: false,          // 是否反转组的顺序
+      duration: undefined,     // 每组入场时长（毫秒），不设则使用 animate.enter.duration
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：忘记配置 animate.enter
+```javascript
+// ❌ 有 stackEnter 但没有 animate.enter，看不到动画效果
+chart.options({
+  transform: [{ type: 'stackEnter', groupBy: ['x'] }],
+  // 缺少 animate 配置！
+});
+
+// ✅ 必须配合 animate.enter 使用
+chart.options({
+  transform: [{ type: 'stackEnter', groupBy: ['x'], duration: 400 }],
+  animate: {
+    enter: {
+      type: 'scaleInY',    // 选择合适的入场动画类型
+      duration: 400,
+    },
+  },
+});
+```
+
+### 错误：duration 与 animate.enter.duration 不一致导致动画不连贯
+```javascript
+// ❌ stackEnter duration 与 animate.enter.duration 不匹配
+chart.options({
+  transform: [{ type: 'stackEnter', duration: 500 }],  // 500ms 每组
+  animate: { enter: { type: 'scaleInY', duration: 200 } },  // ❌ 200ms 动画（组还没完成就切换）
+
+// ✅ 保持一致
+chart.options({
+  transform: [{ type: 'stackEnter', duration: 400 }],
+  animate: { enter: { type: 'scaleInY', duration: 400 } },   // ✅ 一致
+});
+```

package/builtin-skills/antv-g2-chart/references/transforms/g2-transform-stacky.md

@@ -0,0 +1,218 @@
+---
+id: "g2-transform-stacky"
+title: "G2 StackY 堆叠变换"
+description: |
+  StackY 是 G2 v5 中用于实现数据堆叠的 Mark Transform，
+  将同一 x 位置的多个数值依次叠加，生成 y0/y1 区间。
+  配置在 transform 数组中（与 data、encode 同级），是堆叠柱状图、堆叠面积图、饼图的核心依赖。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "StackY"
+  - "堆叠"
+  - "stackY"
+  - "mark transform"
+  - "堆叠柱状图"
+  - "堆叠面积图"
+  - "spec"
+
+related:
+  - "g2-mark-interval-stacked"
+  - "g2-mark-area-stacked"
+  - "g2-transform-normalizey"
+  - "g2-transform-dodgex"
+  - "g2-data-fold"
+
+use_cases:
+  - "创建堆叠柱状图"
+  - "创建堆叠面积图"
+  - "创建饼图（配合 theta 坐标系）"
+
+difficulty: "beginner"
+completeness: "partial"
+created: "2024-01-01"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform/stack-y"
+---
+
+## 核心概念
+
+**StackY 是标记变换（Mark Transform），不是数据变换（Data Transform）**
+
+- 标记变换配置在 `transform` 数组中（与 `data`、`encode` 同级）
+- 在标记渲染过程中执行，修改视觉通道值
+- **不要**放在 `data.transform` 中
+
+StackY 对每个 x 分组内的数据进行累积计算：
+- 输入：`y` 值（各子类别的原始数值）
+- 输出：`y0`（底部位置）和 `y1`（顶部位置），驱动柱体/面积的起止位置
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],  // ✅ Mark Transform：与 data/encode 同级
+});
+```
+
+## 基本用法（Spec 模式）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 堆叠柱状图
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { month: 'Jan', type: 'A', value: 100 },
+    { month: 'Jan', type: 'B', value: 200 },
+    { month: 'Feb', type: 'A', value: 120 },
+    { month: 'Feb', type: 'B', value: 180 },
+  ],
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],   // 声明堆叠变换
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [...],
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [
+    {
+      type: 'stackY',
+      orderBy: null,     // null | 'value' | 'sum' | 'series' — 控制堆叠顺序
+      reverse: false,    // 是否反转堆叠顺序
+      y: 'y',            // 输入 y 通道名（默认 'y'）
+      y1: 'y1',          // 输出底部通道名（默认 'y1'）
+    },
+  ],
+});
+```
+
+## 与 normalizeY 组合（百分比堆叠）
+
+```javascript
+// transform 数组支持多个变换链式执行
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [
+    { type: 'stackY' },       // 先堆叠
+    { type: 'normalizeY' },   // 再归一化到 [0, 1]
+  ],
+  axis: {
+    y: { labelFormatter: (v) => `${(v * 100).toFixed(0)}%` },
+  },
+});
+```
+
+## 用于饼图（配合 theta 坐标系）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [
+    { type: '分类一', value: 40 },
+    { type: '分类二', value: 30 },
+    { type: '分类三', value: 30 },
+  ],
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],           // 将数值转为角度区间
+  coordinate: { type: 'theta', outerRadius: 0.8 },
+});
+```
+
+## 用于堆叠面积图
+
+```javascript
+chart.options({
+  type: 'area',
+  data: [...],
+  encode: { x: 'date', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：stackY 放在 data.transform 中
+
+```javascript
+// ❌ 错误：stackY 是 Mark Transform，不能放在 data.transform 中
+chart.options({
+  type: 'interval',
+   {
+    type: 'inline',
+    value: data,
+    transform: [{ type: 'stackY' }],  // ❌ 错误位置
+  },
+});
+
+// ✅ 正确：stackY 放在 mark 的 transform 中（与 data/encode 同级）
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],  // ✅ 正确
+});
+```
+
+### 错误 2：transform 写成对象而非数组
+```javascript
+// ❌ 错误：transform 必须是数组
+chart.options({ transform: { type: 'stackY' } });
+
+// ✅ 正确
+chart.options({ transform: [{ type: 'stackY' }] });
+```
+
+### 错误 3：饼图忘记 stackY
+```javascript
+// ❌ 错误：theta 坐标系中没有 stackY，所有扇形角度从 0 开始，完全重叠
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  coordinate: { type: 'theta' },
+  // 缺少 transform！
+});
+
+// ✅ 正确
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],   // 必须！
+  coordinate: { type: 'theta' },
+});
+```
+
+### 错误 4：多系列数据不堆叠直接显示导致重叠
+```javascript
+// ❌ 错误：多类型 interval 没有 stackY 或 dodgeX，柱体在同位置堆叠
+chart.options({
+  type: 'interval',
+  data: multiTypeData,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  // 既没有 stackY（堆叠）也没有 dodgeX（分组）
+});
+
+// ✅ 堆叠展示
+chart.options({ transform: [{ type: 'stackY' }], ... });
+
+// ✅ 分组展示
+chart.options({ transform: [{ type: 'dodgeX' }], ... });
+```

package/builtin-skills/antv-g2-chart/references/transforms/g2-transform-symmetryy.md

@@ -0,0 +1,122 @@
+---
+id: "g2-transform-symmetryy"
+title: "G2 SymmetryY 对称变换（蝴蝶图 / 人口金字塔）"
+description: |
+  symmetryY 对 y 通道应用偏移使数据关于 y=0 轴对称，
+  典型应用是人口金字塔（两个方向的柱状图对称展示）和蝴蝶图。
+  通常与 transpose（转置）坐标系配合，实现水平对称条形图。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "symmetryY"
+  - "对称"
+  - "人口金字塔"
+  - "蝴蝶图"
+  - "population pyramid"
+  - "transform"
+
+related:
+  - "g2-transform-stacky"
+  - "g2-coord-transpose"
+  - "g2-mark-interval-stacked"
+
+use_cases:
+  - "人口金字塔（男女年龄分布对称展示）"
+  - "A/B 对比的蝴蝶图"
+  - "正负值关于中心对称的图表"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform/symmetry-y"
+---
+
+## 最小可运行示例（人口金字塔）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { age: '0-9',   gender: '男', value: 8500 },
+  { age: '10-19', gender: '男', value: 9200 },
+  { age: '20-29', gender: '男', value: 10300 },
+  { age: '30-39', gender: '男', value: 9800 },
+  { age: '40-49', gender: '男', value: 8900 },
+  { age: '0-9',   gender: '女', value: 8100 },
+  { age: '10-19', gender: '女', value: 8800 },
+  { age: '20-29', gender: '女', value: 9900 },
+  { age: '30-39', gender: '女', value: 9500 },
+  { age: '40-49', gender: '女', value: 8700 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: {
+    x: 'age',
+    y: 'value',
+    color: 'gender',
+  },
+  transform: [
+    { type: 'stackY' },     // 先堆叠
+    { type: 'symmetryY' },  // 再对称（以 y=0 为中轴）
+  ],
+  coordinate: { transform: [{ type: 'transpose' }] },  // 转置为水平条形
+  axis: {
+    y: {
+      labelFormatter: (v) => Math.abs(v).toLocaleString(),  // 负值显示为正数
+    },
+  },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+transform: [
+  {
+    type: 'symmetryY',
+    groupBy: 'x',   // 按哪个通道分组，默认 'x'
+  },
+]
+```
+
+## 蝴蝶图（两个类别左右对称）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: abTestData,
+  encode: { x: 'metric', y: 'value', color: 'group' },
+  transform: [
+    { type: 'stackY' },
+    { type: 'symmetryY' },
+  ],
+  coordinate: { transform: [{ type: 'transpose' }] },
+  style: { fillOpacity: 0.85 },
+});
+```
+
+## 常见错误与修正
+
+### 错误：symmetryY 前忘记 stackY——分组数据不会对称
+```javascript
+// ❌ 没有 stackY，两个 gender 的柱体重叠在同侧，对称失效
+transform: [
+  { type: 'symmetryY' },  // ❌ 少了前置 stackY
+]
+
+// ✅ 必须先 stackY 再 symmetryY
+transform: [
+  { type: 'stackY' },     // ✅ 先堆叠（分组数据叠在一起）
+  { type: 'symmetryY' },  // ✅ 再对称（两组各自偏移到两侧）
+]
+```

package/builtin-skills/chart-visualization/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: chart-visualization
+description: 将数据可视化为图表。当用户需要生成柱状图、折线图、饼图、散点图、雷达图、桑基图、思维导图、流程图等图表时调用此技能，通过 curl 工具调用 AntV API 生成图表图片
+---
+
+请根据用户输入的内容，将数据可视化为图表。
+
+## 步骤
+1. 分析用户数据和需求，选择最合适的图表类型
+2. 构造符合规范的 JSON 请求体
+3. 使用 curl 工具调用 API 生成图表图片
+4. 将返回的图片 URL 以 Markdown 图片格式输出
+
+## 图表选择指南
+
+根据用户的数据特征和需求，选择最合适的图表类型：
+
+- **时间序列**：用 `line`（趋势）或 `area`（累计趋势）；两个不同量纲用 `dual-axes`
+- **比较类**：用 `bar`（横向分类对比）或 `column`（纵向分类对比）；频率分布用 `histogram`
+- **占比类**：用 `pie`（比例构成）或 `treemap`（层级占比）
+- **关系与流程**：用 `scatter`（相关性）、`sankey`（流向）或 `venn`（集合重叠）
+- **层级与树形**：用 `organization-chart` 或 `mind-map`
+- **专用类型**：
+  - `radar`：多维度对比
+  - `funnel`：流程阶段转化
+  - `liquid`：百分比/进度
+  - `word-cloud`：文本词频
+  - `boxplot` / `violin`：统计分布
+  - `network-graph`：复杂节点关系
+  - `fishbone-diagram`：因果分析
+  - `flow-diagram`：流程图
+  - `spreadsheet`：结构化数据表或透视表
+
+## API 接口
+
+POST https://antv-studio.alipay.com/api/gpt-vis
+
+请求体为 JSON，必须包含 `type` 和 `source: "chart-visualization-skills"` 字段。
+
+示例：
+```bash
+curl -X POST https://antv-studio.alipay.com/api/gpt-vis \
+  -H "Content-Type: application/json" \
+  -d '{"type":"line","source":"chart-visualization-skills","data":[{"time":"2025-01","value":100}],"title":"示例图表"}'
+```
+
+返回示例：
+```json
+{"success":true,"resultObj":"https://..."}
+```
+
+将 `resultObj` 中的 URL 以 Markdown 图片格式输出：`![图表](URL)`
+
+## 支持的图表类型
+
+| 分类 | 图表类型 |
+|------|---------|
+| 比较类 | 条形图(bar)、柱状图(column)、瀑布图(waterfall)、双轴图(dual-axes) |
+| 趋势类 | 面积图(area)、折线图(line)、散点图(scatter) |
+| 分布类 | 箱线图(boxplot)、直方图(histogram)、小提琴图(violin)、漏斗图(funnel) |
+| 占比类 | 饼图(pie)、水波图(liquid)、词云(word-cloud) |
+| 层级类 | 组织架构图(organization-chart)、思维导图(mind-map)、矩形树图(treemap)、桑基图(sankey) |
+| 关系类 | 关系图(network-graph)、韦恩图(venn) |
+| 流程类 | 流程图(flow-diagram)、鱼骨图(fishbone-diagram) |
+| 多维类 | 雷达图(radar) |
+| 表格类 | 表格/透视表(spreadsheet) |
+
+## 通用可选参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| theme | string | "default" | 主题："default" / "academy" / "dark" |
+| width | number | 600 | 图表宽度 |
+| height | number | 400 | 图表高度 |
+| title | string | "" | 图表标题 |
+| style.texture | string | "default" | 纹理："default" / "rough"（手绘风格） |
+
+带坐标轴的图表还支持：axisXTitle、axisYTitle。
+
+## 各图表 data 格式
+
+- **area / line**: `{time: string, value: number, group?: string}[]`，可选 stack: boolean
+- **bar**: `{category: string, value: number, group?: string}[]`，可选 group / stack (默认 stack: true)
+- **column**: `{category: string, value: number, group?: string}[]`，可选 group (默认 true) / stack
+- **scatter**: `{x: number, y: number, group?: string}[]`
+- **pie**: `{category: string, value: number}[]`，可选 innerRadius: number (0-1)
+- **radar**: `{name: string, value: number, group?: string}[]`
+- **funnel**: `{category: string, value: number}[]`
+- **waterfall**: `{category: string, value?: number, isTotal?: boolean, isIntermediateTotal?: boolean}[]`
+- **dual-axes**: categories: string[], series: {type: "column"|"line", data: number[], axisYTitle?: string}[]
+- **histogram**: `number[]`，可选 binNumber: number
+- **boxplot / violin**: `{category: string, value: number, group?: string}[]`
+- **liquid**: percent: number (0-1)，可选 shape: "circle"|"rect"|"pin"|"triangle"
+- **word-cloud**: `{text: string, value: number}[]`
+- **sankey**: `{source: string, target: string, value: number}[]`，可选 nodeAlign
+- **treemap**: `{name: string, value: number, children?: ...}[]` (最深 3 层)
+- **venn**: `{sets: string[], value: number, label?: string}[]`
+- **network-graph / flow-diagram**: `{nodes: {name: string}[], edges: {source: string, target: string, name?: string}[]}`
+- **fishbone-diagram / mind-map**: `{name: string, children?: ...}` (最深 3 层)
+- **organization-chart**: `{name: string, description?: string, children?: ...}` (最深 3 层)，可选 orient: "horizontal"|"vertical"
+- **spreadsheet**: `Record<string, string | number>[]`，可选 rows / columns / values（透视表字段）