@loom-framework/core 0.1.0-alpha.9 → 0.1.0-alpha.90

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/app-skill/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: {{projectName}}-data
+description: |
+  [阅读 references/models.md 中的数据模型和 AI 按钮定义，编写触发短语。
+  包含：用户语言中的常见增删改查动词、各数据模型相关的操作、AI 按钮的标签。
+  格式："This skill should be used when the user asks to '短语1', '短语2',
+  or any request about <此项目管理的内容> in the {{projectName}} project."]
+version: 1.0.0
+---
+
+# {{projectName}} — App Skill
+
+## Overview
+
+[阅读 references/models.md，用2-3句话描述：项目做什么、管理哪些数据模型、用户如何通过 AI 对话与数据交互。]
+
+## Usage Scenarios
+
+[**必须加载 references/models.md 和 references/data-semantics.md**，这两个文件包含从 loom.config.ts 动态注入的项目特定信息，不加载则无法生成正确内容。
+- models.md — 当前项目的数据模型字段表（字段名、类型、enum 取值、默认值）、AI 按钮定义（id、label、prompt、placement）、CLI 命令语法（read/write/update/delete，不要使用 create/list 等不存在的命令）。
+- data-semantics.md — 当前项目的数据模型名称列表、write 的 --data JSON 构造规则（字段类型格式、enum 取值约束、贴合业务的真实示例值）、read 的 --filter JSON 构造规则（优先用 enum/boolean 字段筛选、跨模型关联查询）。
+再生成8-10个典型用户请求，每个格式：用户说的话 → 对应的 `loom data` CLI 命令。每个数据模型至少包含一个场景。]
+
+## Technical Reference
+
+- 数据模型结构、CLI 语法和操作规范：**references/models.md**
+- 语义引导（示例数据生成、筛选选择、关系推断）：**references/data-semantics.md**

package/builtin-skills/app-skill/references/data-semantics.md

@@ -0,0 +1,44 @@
+# 数据语义引导
+
+> 本文件由 `loom generate capabilities` 自动生成。请勿手动编辑 — 重新生成时将被覆盖。
+
+生成 `loom data` CLI 命令时，阅读 `loom.config.ts` 获取数据模型定义，并遵循以下规则生成贴合业务的输出。
+
+注：本文中的"数据模型"指 loom.config.ts 中定义的数据结构（如 wrong_questions、review_plans），而非大语言模型。
+
+## 示例数据生成
+
+构造 write 命令的 `--data` JSON 时：
+
+- 根据字段名、类型、描述和枚举值生成**贴合业务的真实值**。
+  例如名为 `questionContent`、描述为"题目内容"的字段，应填真实题目如 `"3+5=?"`，而非 `"value"`。
+- 遵守 **FieldType**：`number` → 不加引号的数字（`1`），`boolean` → 不加引号的布尔值（`false`），
+  `date` → ISO 日期字符串（`"2026-01-15"`），`string[]` → JSON 数组（`["标签1"]`），`json` → JSON 对象（`{}`）。
+- 有 **enum** 时必须使用枚举值 — 这是该字段唯一切合法的取值。
+- write 命令只需包含**必填字段**，可选字段可省略。
+- update 命令只需传入**要变更的字段**。
+
+## 筛选条件选择
+
+构造 read 命令的 `--filter` JSON 时：
+
+- **优先使用 enum 和 boolean 字段**做筛选 — 它们能产生最有意义的分区
+  （如 `{"subject": "数学"}`、`{"mastered": false}`）。
+- 选择**业务含义最丰富的筛选条件**，而非按字母序取第一个字段。
+- 可组合多个筛选：`{"subject": "数学", "mastered": false}`。
+- 数据量大时使用 `--limit` 避免输出过多。
+
+## 跨数据模型关联
+
+当字段名以 `Id` 结尾（如 `wrongQuestionId`）时，通常引用的是另一个数据模型的记录。
+
+- 查询关联记录：`loom data read <目标数据模型> --id <值>`。
+- 查询指向某条记录的所有关联：`loom data read <数据模型> --filter '{"<外键字段>": "<id>"}'`。
+- 常见命名模式：`parentId` → 自引用，`<数据模型名>Id` → 引用该数据模型。
+
+<!-- MODEL_NAMES -->
+
+## AI 按钮校验
+
+执行 AI 按钮操作前，验证 prompt 中所有 `{{var}}` 占位符是否对应目标数据模型上的实际字段。
+如果变量引用了不存在的字段，告知用户并建议添加该字段或更新 prompt。

package/builtin-skills/app-skill/references/models.md

@@ -0,0 +1,31 @@
+# 数据模型与 CLI 参考
+
+> 本文件由 `loom generate capabilities` 自动生成。请勿手动编辑 — 重新生成时将被覆盖。
+
+## 数据模型
+
+<!-- DATA_MODELS -->
+
+## CLI 命令
+
+所有数据操作使用 `loom data` CLI 命令，需在项目根目录下执行。
+
+| 命令 | 说明 |
+|------|------|
+| `loom data read <model> [--id <id>] [--filter <json>] [--limit <n>]` | 读取记录 |
+| `loom data write <model> --data '<json>'` | 创建记录 |
+| `loom data update <model> --id <id> --data '<json>'` | 更新记录 |
+| `loom data delete <model> --id <id>` | 删除记录 |
+| `loom data schema [model]` | 查看数据模型结构 |
+
+<!-- AI_BUTTONS -->
+
+## 操作规范
+
+1. 所有数据操作必须使用 `loom data` CLI 命令，不要直接访问文件或数据库。
+2. 命令在项目根目录下执行。
+3. 执行删除等不可逆操作前，需与用户确认。
+4. 创建/更新时确保必填字段齐全。不确定时用 `loom data schema <model>` 查看。
+5. `update` 只需传入要修改的字段，未指定的字段保持不变。
+6. CLI 输出格式为 JSON — 解析输出以理解数据结构。
+7. 数据变更后，告知用户页面会自动刷新。