antv-skills 0.0.1-alpha.1

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node:*)",
+      "Bash(/Users/liufu/aiWorkspaces/antv-skills/common/data/common-data-transform-patterns.md:*)",
+      "Bash(/Users/liufu/aiWorkspaces/antv-skills/common/patterns/common-pattern-responsive.md:*)",
+      "Bash(/Users/liufu/aiWorkspaces/antv-skills/common/patterns/common-pattern-performance.md:*)",
+      "Bash(/Users/liufu/aiWorkspaces/antv-skills/common/patterns/common-pattern-antv-v4-to-v5.md:*)",
+      "Bash(xargs basename:*)",
+      "Bash(xargs:*)",
+      "Bash(do:*)",
+      "Bash(git:*)"
+    ]
+  }
+}

package/CONTRIBUTING.md

@@ -0,0 +1,151 @@
+# Skill 编写规范
+
+## Skill 文件命名规则
+
+```
+{library}-{category}-{subcategory?}-{name}.md
+
+示例：
+g2-mark-interval-basic.md         ✅
+g6-layout-dagre.md                ✅
+common-data-format-graph.md       ✅
+G2_Interval_Basic.md              ❌（不符合规范）
+```
+
+规则：
+- 全部小写
+- 使用连字符（hyphen）分隔，不使用下划线
+- 文件名与 `id` 字段保持一致
+- `{name}` 部分不超过 4 个单词
+
+## Front Matter 字段说明
+
+### 必填字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 与文件名一致（不含 .md） |
+| `title` | string | 中文标题，5-60 字 |
+| `description` | string | 2-5 句话描述，20 字以上 |
+| `library` | enum | `g2` \| `g6` \| `common` |
+| `version` | string | 如 `5.x` |
+| `category` | string | 一级分类 |
+| `tags` | string[] | 至少 3 个，中英文均可 |
+
+### 推荐字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `subcategory` | string | 二级分类 |
+| `related` | string[] | 关联 Skill ID 列表 |
+| `use_cases` | string[] | 适用场景，至少 1 个 |
+| `anti_patterns` | string[] | 反模式，何时不用此 Skill |
+| `difficulty` | enum | `beginner` \| `intermediate` \| `advanced` |
+| `source_url` | string | 官方文档链接 |
+
+## Markdown 正文结构规范
+
+每个 Skill 的正文应包含以下章节（按重要性排序）：
+
+### 必须包含（至少一个）
+
+```markdown
+## 最小可运行示例
+（一个可直接复制运行的完整代码，不省略 import 和 container）
+
+## 基本用法
+（基础使用方式）
+```
+
+### 强烈推荐
+
+```markdown
+## 核心概念
+（2-5 句话解释原理，适合 beginner 和 intermediate）
+
+## 常用变体
+（2-4 个常见变化形式的代码示例）
+
+## API 速查
+（表格形式的关键 API 列表）
+
+## 常见错误与修正
+（至少 2 个，每个包含 ❌ 错误 + ✅ 正确）
+```
+
+### 可选
+
+```markdown
+## 完整类型参考
+（TypeScript 接口定义）
+
+## 性能说明
+（性能相关的使用建议）
+```
+
+## 代码规范
+
+### 1. 每个代码块必须包含 import 语句
+
+```javascript
+// ✅ 正确
+import { Chart } from '@antv/g2';
+
+// ❌ 错误（缺少 import）
+const chart = new Chart({ ... });
+```
+
+### 2. 所有示例必须指定 container
+
+```javascript
+// ✅ 正确
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+// ❌ 错误（缺少 container）
+const chart = new Chart({ width: 640, height: 480 });
+```
+
+### 3. 错误示例格式
+
+使用 `// ❌ 错误` 和 `// ✅ 正确` 标注：
+
+```javascript
+// ❌ 错误：简洁说明错误原因
+badCode();
+
+// ✅ 正确
+goodCode();
+```
+
+### 4. 注释语言
+
+关键配置使用中文注释，代码逻辑保持英文：
+
+```javascript
+const chart = new Chart({
+  container: 'container',  // DOM 容器 ID
+  autoFit: true,           // 自动适应容器尺寸
+});
+```
+
+## 质量检查清单
+
+提交 PR 前，请确认：
+
+- [ ] 文件名符合命名规范，与 `id` 字段一致
+- [ ] 所有必填 Front Matter 字段已填写
+- [ ] `tags` 包含中文和英文关键词
+- [ ] 至少一个**最小可运行示例**（含 import + container）
+- [ ] 包含至少 2 个**常见错误与修正**
+- [ ] 运行 `node tools/validate.js` 无 ERROR
+
+## 添加新 Skill 的步骤
+
+1. 确认 Skill 不在已有文件中（避免重复）
+2. 选择正确的目录位置
+3. 创建 `.md` 文件，文件名即 ID
+4. 填写 Front Matter（参考 `schema/skill.schema.json`）
+5. 编写正文（参考已有 Skill 文件）
+6. 运行 `node tools/validate.js` 检查格式
+7. 运行 `node tools/build-index.js` 重建索引
+8. 提交 PR

package/README.md

@@ -0,0 +1,169 @@
+# AntV Skills
+
+> 帮助大模型更好地生成 G2、G6 可视化代码的 Skill 知识库
+
+## 简介
+
+AntV Skills 是一个结构化的知识库，通过 **RAG（检索增强生成）** 和 **Few-shot** 等技术，显著提升大模型生成 [G2 v5](https://g2.antv.antgroup.com)（图表库）和 [G6 v5](https://g6.antv.antgroup.com)（图分析库）代码的准确性。
+
+**核心价值：**
+- 防止 LLM 使用 G2/G6 v4 的废弃 API（最常见的幻觉错误）
+- 提供可直接运行的代码示例作为 Few-shot
+- 覆盖从入门到高级的完整使用场景
+
+## 目录结构
+
+```
+antv-skills/
+├── schema/           # Skill 文件的 JSON Schema 定义
+├── index/            # 构建生成的索引文件（RAG 检索用）
+├── prompts/          # G2/G6 代码生成的 System Prompt 模板
+├── common/           # 公共基础概念（图形语法、数据格式等）
+├── g2/               # G2 图表库 Skills
+│   ├── core/         # 初始化、通道系统等核心概念
+│   ├── marks/        # Mark 类型（interval/line/point/arc 等）
+│   ├── transforms/   # 数据变换（stackY/dodgeX/normalizeY 等）
+│   ├── scales/       # 比例尺
+│   ├── coordinates/  # 坐标系
+│   ├── interactions/ # 交互（tooltip/brush/zoom 等）
+│   ├── compositions/ # 复合图表（layer/facet/view）
+│   ├── themes/       # 主题
+│   ├── animations/   # 动画
+│   └── recipes/      # 完整图表配方
+└── g6/               # G6 图分析库 Skills
+    ├── core/         # 初始化、数据模型等核心概念
+    ├── elements/     # 节点/边/Combo 配置
+    ├── layouts/      # 布局算法（force/dagre/tree 等）
+    ├── behaviors/    # 交互行为
+    ├── plugins/      # 插件
+    ├── animations/   # 动画
+    └── recipes/      # 完整图谱配方
+```
+
+## Skill 文件格式
+
+每个 Skill 是一个 `.md` 文件，采用 **YAML Front Matter + Markdown Body** 格式：
+
+```markdown
+---
+id: "g2-mark-interval-basic"
+title: "G2 基础柱状图（Interval Mark）"
+description: "使用 Interval Mark 创建基础柱状图..."
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "interval"
+tags: ["柱状图", "bar chart", "Interval"]
+related: ["g2-mark-interval-stacked", "g2-core-encode-channel"]
+use_cases: ["比较不同类别的数值大小"]
+anti_patterns: ["不适合展示连续趋势（改用 Line）"]
+difficulty: "beginner"
+---
+
+## 最小可运行示例
+...
+
+## 常用变体
+...
+
+## 常见错误与修正
+...
+```
+
+## 快速开始
+
+### 1. 构建索引
+
+```bash
+node tools/build-index.js
+```
+
+### 2. 测试检索
+
+```bash
+node tools/rag-retrieval.js "如何创建柱状图"
+node tools/rag-retrieval.js "力导向布局" --library=g6
+```
+
+### 3. 校验文件格式
+
+```bash
+node tools/validate.js
+```
+
+## 如何在 AI 应用中使用
+
+### 方式 1：RAG 检索（推荐）
+
+```python
+# 伪代码示例
+from antv_skills import SkillRetriever
+
+retriever = SkillRetriever(index_path="index/full.index.json")
+
+def generate_chart_code(user_query):
+    # 1. 检索相关 Skill
+    skills = retriever.search(user_query, top_k=5)
+
+    # 2. 组装 System Prompt
+    system_prompt = load_template("prompts/g2-system-prompt.md")
+    skill_context = "\n\n".join(skill.key_content for skill in skills)
+    system_prompt = system_prompt.replace("{RETRIEVED_SKILLS_CONTENT}", skill_context)
+
+    # 3. 调用 LLM
+    return llm.complete(system_prompt, user_query)
+```
+
+### 方式 2：直接注入 System Prompt
+
+将 `prompts/g2-system-prompt.md` 或 `prompts/g6-system-prompt.md` 的内容直接作为系统提示词，适合轻量级场景。
+
+### 方式 3：MCP Server
+
+可将 Skills 封装为 MCP (Model Context Protocol) 工具，供 Claude Code 等 AI 工具调用。
+
+## Skill 分类覆盖
+
+> 当前共 **87 个 Skill**：G2 46 个 · G6 31 个 · Common 10 个
+
+### G2 Skills（图表库）46 个
+
+| 分类 | 数量 | 已覆盖 Skill |
+|------|:----:|-------------|
+| `core` | 3 | Chart 初始化、encode 通道系统、view 视图组合 |
+| `marks` | 17 | interval（基础/堆叠/分组/百分比）、line、area（基础/堆叠）、arc（饼图/环形图）、point 散点图、cell 热力图、box 箱线图、text 文字标注、gauge 仪表盘、sankey 桑基图、treemap 矩形树图、radar 雷达图 |
+| `transforms` | 6 | stackY、dodgeX、normalizeY、binX、sortX、fold |
+| `scales` | 3 | band 分类比例尺、time 时间比例尺、linear 线性比例尺 |
+| `coordinates` | 1 | transpose 转置坐标系 |
+| `components` | 5 | axis 坐标轴、legend 图例、annotation 标注、labels 数据标签、tooltip 自定义配置 |
+| `interactions` | 5 | tooltip、brush 框选、elementHighlight 元素高亮、elementSelect 元素选中、sliderFilter 缩略轴过滤 |
+| `compositions` | 2 | facetRect 矩形分面、repeatMatrix 重复矩阵 |
+| `themes` | 1 | 内置主题（classic / classicDark / academy） |
+| `recipes` | 3 | 数据看板、时序对比图、漏斗图 |
+
+### G6 Skills（图分析库）31 个
+
+| 分类 | 数量 | 已覆盖 Skill |
+|------|:----:|-------------|
+| `core` | 2 | Graph 初始化、数据模型（nodes/edges/combos CRUD）|
+| `elements` | 5 | 内置节点形状、内置边类型、节点样式映射、元素状态样式、Combo 分组容器 |
+| `layouts` | 8 | force 力导向、dagre 有向无环图、compactBox 树形、circular 环形、grid 网格、radial 辐射、concentric 同心圆、mindmap 思维导图 |
+| `behaviors` | 6 | drag-canvas 拖拽画布、click-select 点击选择、hover-activate 悬停激活、zoom-canvas 画布缩放、brush-select 框选、collapse-expand 折叠展开 |
+| `plugins` | 6 | tooltip 气泡提示、minimap 缩略图、contextmenu 右键菜单、toolbar 工具栏、history 历史记录、legend 图例 |
+| `recipes` | 4 | 流程图、知识图谱、组织架构图、思维导图 |
+
+### Common Skills（公共基础）10 个
+
+| 分类 | 数量 | 已覆盖 Skill |
+|------|:----:|-------------|
+| `concepts` | 4 | 图形语法原理、视觉通道理论、图表类型选择指南、数据可视化配色理论 |
+| `data` | 3 | G2 表格数据格式、G6 图数据格式、通用数据转换模式 |
+| `patterns` | 3 | 响应式图表适配、大数据量性能优化、G2/G6 v4→v5 迁移指南 |
+
+## 贡献指南
+
+请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何添加或修改 Skill。
+
+## License
+
+MIT

package/common/concepts/common-concept-chart-selection.md

@@ -0,0 +1,235 @@
+---
+id: "common-concept-chart-selection"
+title: "图表类型选择指南"
+description: |
+  根据数据特征和分析目的选择合适的图表类型。
+  覆盖比较、趋势、占比、分布、关系、流程六大场景，
+  对应 G2/G6 的具体实现方式，帮助避免"用错图表"的常见错误。
+
+library: "common"
+version: "5.x"
+category: "concepts"
+tags:
+  - "图表选择"
+  - "chart selection"
+  - "可视化设计"
+  - "柱状图"
+  - "折线图"
+  - "饼图"
+  - "散点图"
+  - "决策"
+
+related:
+  - "common-concept-visual-channels"
+  - "g2-mark-interval-basic"
+  - "g2-mark-line-basic"
+  - "g2-mark-arc-pie"
+  - "g2-mark-point-scatter"
+
+use_cases:
+  - "根据用户需求选择正确的图表类型"
+  - "避免在不合适场景使用饼图或折线图"
+  - "理解何时用 G2 图表 vs G6 图分析"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+---
+
+## 核心决策树
+
+```
+你的数据和目的是什么？
+
+├── 比较类别间的大小 → 柱状图 / 条形图
+├── 展示随时间的变化趋势 → 折线图 / 面积图
+├── 展示部分与整体的占比 → 饼图 / 环形图 / 堆叠柱状图
+├── 展示两个变量的相关性 → 散点图 / 气泡图
+├── 展示数据的分布规律 → 直方图 / 箱线图 / 小提琴图
+└── 展示节点间的关系网络 → G6 图（force/dagre/tree 布局）
+```
+
+## 场景一：比较（Comparison）
+
+**目的**：比较不同类别/时间点的数值大小
+
+| 数据特征 | 推荐图表 | G2 实现 |
+|---------|---------|---------|
+| 类别 ≤ 10，竖向标签可读 | **柱状图** | `type: 'interval'` |
+| 类别名称较长 / 类别多 | **条形图**（水平） | `type: 'interval'` + `coordinate: { type: 'transpose' }` |
+| 多个系列并排比较 | **分组柱状图** | `transform: [{ type: 'dodgeX' }]` |
+| 展示子类在总量中的贡献 | **堆叠柱状图** | `transform: [{ type: 'stackY' }]` |
+
+```javascript
+// 柱状图（最常见的比较图）
+chart.options({
+  type: 'interval',
+   data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  transform: [{ type: 'sortX', by: 'y', reverse: true }],  // 按值降序
+});
+```
+
+## 场景二：趋势（Trend）
+
+**目的**：展示数值随时间或序列的变化
+
+| 数据特征 | 推荐图表 | G2 实现 |
+|---------|---------|---------|
+| 单一指标时间趋势 | **折线图** | `type: 'line'` |
+| 多指标对比趋势 | **多系列折线图** | `type: 'line'` + `encode.color: 'series'` |
+| 强调面积/累积量 | **面积图** | `type: 'area'` |
+| 展示数量随时间增减 | **面积图**（堆叠）| `type: 'area'` + `transform: [{ type: 'stackY' }]` |
+
+```javascript
+// 多系列折线图
+chart.options({
+  type: 'line',
+   data,
+  encode: { x: 'date', y: 'value', color: 'series' },
+  scale: { x: { type: 'time' } },
+  labels: [{ text: 'series', selector: 'last', position: 'right' }],
+});
+```
+
+## 场景三：占比（Part-to-Whole）
+
+**目的**：展示部分占整体的比例
+
+| 数据特征 | 推荐图表 | G2 实现 | 注意 |
+|---------|---------|---------|------|
+| 类别 ≤ 5，强调比例 | **饼图** | `interval` + `theta` 坐标 | 类别多时难区分 |
+| 需要中心留白 | **环形图** | 饼图 + `innerRadius` | 可在中心放总数 |
+| 类别多，强调排名 | **百分比堆叠柱状图** | `stackY` + `normalizeY` | |
+| 多层级占比 | **旭日图** | 暂用 `sunburst` 插件 | |
+
+```javascript
+// 饼图（类别 ≤ 5 时）
+chart.options({
+  type: 'interval',
+   data,
+  encode: { y: 'value', color: 'category' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta', outerRadius: 0.85 },
+  labels: [{
+    text: (d) => `${d.category}\n${d.pct}%`,
+    position: 'outside',
+    connector: true,
+  }],
+});
+```
+
+## 场景四：相关性（Correlation）
+
+**目的**：探索两个或多个变量之间的关系
+
+| 数据特征 | 推荐图表 | G2 实现 |
+|---------|---------|---------|
+| 两个数值变量 | **散点图** | `type: 'point'` |
+| 两个数值 + 第三数值维度 | **气泡图** | `point` + `encode.size` |
+| 多变量热力矩阵 | **热力图** | `type: 'cell'` |
+| 展示分布+相关 | **散点图 + 趋势线** | `view` + `point` + `line` |
+
+```javascript
+// 气泡图
+chart.options({
+  type: 'point',
+   data,
+  encode: {
+    x: 'income',
+    y: 'happiness',
+    size: 'population',  // 第三数值维度
+    color: 'region',
+  },
+  scale: { size: { range: [4, 30] } },
+});
+```
+
+## 场景五：分布（Distribution）
+
+**目的**：了解数据的分布规律
+
+| 数据特征 | 推荐图表 | G2 实现 |
+|---------|---------|---------|
+| 单变量分布 | **直方图** | `type: 'interval'` + `transform: [{ type: 'binX' }]` |
+| 多组分布比较 | **箱线图** | `type: 'boxplot'` |
+| 展示中位数/四分位 | **箱线图** | `type: 'boxplot'` |
+
+```javascript
+// 直方图
+chart.options({
+  type: 'interval',
+   data,
+  encode: { x: 'value', y: 'count' },
+  transform: [{ type: 'binX', y: 'count' }],
+});
+```
+
+## 场景六：关系网络（Relationship）
+
+**目的**：展示实体间的连接关系、层次结构、流向
+
+| 数据特征 | 推荐库 | G6 布局 |
+|---------|--------|---------|
+| 无层级的网络关系 | **G6** | `force`（力导向） |
+| 有方向的流程/依赖 | **G6** | `dagre`（有向无环图） |
+| 单根树形层级 | **G6** | `compactBox`（树形）|
+| 对等环状关系 | **G6** | `circular`（环形） |
+
+```javascript
+// G6 知识图谱（力导向）
+const graph = new Graph({
+  layout: { type: 'force', preventOverlap: true },
+  data: { nodes, edges },
+});
+await graph.render();
+```
+
+## 快速选择口诀
+
+```
+比较用柱状，趋势用折线，
+占比用饼图，关系用散点，
+分布用直方，层级用树形，
+网络用 G6，复杂用组合。
+```
+
+## 常见错误
+
+### 错误 1：用折线图表示无时间顺序的分类数据
+
+```javascript
+// ❌ 误用：城市名称没有顺序，不应该用折线（会误导"趋势"感知）
+chart.options({
+  type: 'line',
+   [{ city: '北京', gdp: 3.6 }, { city: '上海', gdp: 4.3 }],
+  encode: { x: 'city', y: 'gdp' },   // ❌ 城市是无序分类，不是时序
+});
+
+// ✅ 正确：分类比较用柱状图
+chart.options({
+  type: 'interval',
+  encode: { x: 'city', y: 'gdp' },
+});
+```
+
+### 错误 2：用饼图展示 8+ 个类别
+
+```javascript
+// ❌ 误用：10个类别的饼图，各扇区难以区分
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'theta' },
+  // 如果有 10 个国家/地区...很难读取
+});
+
+// ✅ 正确：超过 5 类改用排序条形图
+chart.options({
+  type: 'interval',
+  encode: { x: 'country', y: 'value' },
+  coordinate: { type: 'transpose' },
+  transform: [{ type: 'sortX', by: 'y', reverse: true }],
+});
+```