Merge pull request #4503 from VisActor/001-vchart-skill-tutorial

feat: add VChart Skill usage tutorial and navigation entry

Author: xuefei1313

.cursor/rules/specify-rules.mdc

@@ -5,6 +5,7 @@ Auto-generated from all feature plans. Last updated: 2026-01-15
 ## Active Technologies
 - TypeScript 4.x+ (Project uses TS) + `@visactor/vchart` (Core logic), `@visactor/react-vchart` (React wrapper) (007-fix-datazoom-react)
 - N/A (In-memory chart state) (007-fix-datazoom-react)
+- Markdown + JSON（文档内容与菜单配置） + `@internal/docs` 文档构建体系、`docs/assets/guide/menu.json` 导航配置、现有教程目录结构 (001-vchart-skill-tutorial)
 
 - TypeScript/React 18 + @visactor/react-vchart, @visactor/vchar (001-react-vchart-demo)
 
@@ -26,10 +27,10 @@ npm test && npm run lint
 TypeScript 4.9.5: Follow standard conventions
 
 ## Recent Changes
+- 001-vchart-skill-tutorial: Added Markdown + JSON（文档内容与菜单配置） + `@internal/docs` 文档构建体系、`docs/assets/guide/menu.json` 导航配置、现有教程目录结构
 - 007-fix-datazoom-react: Added TypeScript 4.x+ (Project uses TS) + `@visactor/vchart` (Core logic), `@visactor/react-vchart` (React wrapper)
 - 007-fix-datazoom-react: Added [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
 
-- 001-react-vchart-demo: Added TypeScript/React 18 + @visactor/react-vchart, @visactor/vchar
 
 
 <!-- MANUAL ADDITIONS START -->

docs/assets/guide/en/tutorial_docs/VChart_Skill_Usage.md

@@ -0,0 +1,85 @@
+# VChart Skill Usage
+
+VChart and VTable are core components of VisActor's visualization solution. To improve AI-assisted development efficiency and reduce onboarding cost, VisActor provides a developer skill.
+
+## Relationship with Quick Start
+
+- [Quick Start](./Getting_Started) covers VChart basics.
+- This guide focuses on using `vchart-skill` in AI editors.
+
+## Installation
+
+Use either command:
+
+```bash
+npx skills add VisActor/VChart
+```
+
+```bash
+npx skills add VisActor/VChart --skill vchart-development-assistant
+```
+
+Installation preview:
+
+![vchart-skill installation preview](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/030e176313614ac087853aca647b55df~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=H2PzvppEZrBvra4nZh1fEo%2BiOJY%3D)
+
+## Editor References
+
+- Trae docs: `https://docs.trae.ai/ide/skills?_lang=zh`
+- Cursor docs: `https://cursor.com/cn/docs/context/skills`
+
+Skill directory preview:
+
+![skills directory preview](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/e3cd80683fb34e21a02d371b1bc360c9~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=wrXQJFCJd%2B6sMd05mYc1Ehu3fu8%3D)
+
+## Demo Scenarios
+
+### 1. Generate a simple chart
+
+Suggested prompt:
+
+```text
+Use VChart to generate a basic bar chart with xField, yField, and a minimal runnable example.
+```
+
+Expected result:
+
+- A runnable minimal spec is generated.
+- The chart can render correctly.
+
+![simple chart demo](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/fc55630c49a94d84bd3d7e3a5ca59da1~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=fcmQ6R0EEMPMDp8y%2Fw38OE4nNjY%3D)
+
+### 2. Adjust chart styles
+
+Suggested prompt:
+
+```text
+Optimize colors, label style, and legend readability for the existing bar chart while preserving the current data structure.
+```
+
+Expected result:
+
+- Style changes are clearly visible.
+- Existing chart structure and data mapping remain valid.
+
+![style adjustment demo](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/3cec7ac8dc11486ca9a61eb157ac478d~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=9ETSnU3R8KdgL%2Fl6bHV%2F70RoBDg%3D)
+
+### 3. Fix spec/config issues
+
+Suggested prompt:
+
+```text
+Review the current VChart spec, identify configuration errors, and provide fixes with explanations.
+```
+
+Expected result:
+
+- Incorrect config locations are identified.
+- A directly replaceable fixed config is provided.
+
+![config fix demo](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/bb4911d4db814a7ca3b777f7549cf69e~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=J1olPfoWsglwVMxCukVu1otSycU%3D)
+
+## Notes
+
+- Make sure the skill is installed in your project editor skill directory.
+- If behavior differs by editor version, follow the latest official docs.

docs/assets/guide/menu.json

@@ -22,6 +22,13 @@
             "en": "Quick Start"
           }
         },
+        {
+          "path": "VChart_Skill_Usage",
+          "title": {
+            "zh": "VChart Skill 使用",
+            "en": "VChart Skill Usage"
+          }
+        },
         {
           "path": "Contribution_Guide",
           "title": {
@@ -967,4 +974,4 @@
       ]
     }
   ]
-}
+}

docs/assets/guide/zh/tutorial_docs/VChart_Skill_Usage.md

@@ -0,0 +1,105 @@
+# VChart Skill 使用
+
+VChart 和 VTable 作为 VisActor 数据可视化解决方案的核心组件，为了帮助开发者通过 AI 提升效率、降低使用门槛，VisActor 提供了开发者 skill。
+
+## 与快速上手的关系
+
+- [快速上手](./Getting_Started) 介绍的是 VChart 基础安装与绘图流程。
+- 本文聚焦 `vchart-skill` 在 AI 编辑器中的使用方式，帮助你更快完成图表生成、样式调整和配置修复。
+- 建议阅读顺序：先完成[快速上手](./Getting_Started)，再阅读本文。
+
+## 简介
+
+`vchart-skill` 面向支持 skills 的 AI 编辑器，核心目标是让模型更准确理解 VChart 语义与实践路径，从而减少试错成本。
+
+## 安装与简单 Demo
+
+### 1. Skill 安装
+
+VChart 开发 skill 已发布在 GitHub：
+
+- 仓库入口：`https://github.com/VisActor/VChart`
+- skill 目录：`https://github.com/VisActor/VChart/tree/develop/skills/vchart-development-assistant`
+
+可使用以下任一命令安装：
+
+```bash
+npx skills add VisActor/VChart
+```
+
+```bash
+npx skills add VisActor/VChart --skill vchart-development-assistant
+```
+
+安装过程示意：
+
+![vchart-skill 安装示意](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/030e176313614ac087853aca647b55df~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=H2PzvppEZrBvra4nZh1fEo%2BiOJY%3D)
+
+### 2. 编辑器参考
+
+- Trae 文档：`https://docs.trae.ai/ide/skills?_lang=zh`
+- Cursor 文档：`https://cursor.com/cn/docs/context/skills`
+
+安装后，通常会落到项目内编辑器对应的 skills 目录（例如 `.cursor/skills` 或其他 `.<editor>/skills` 目录），请确认目录中能看到 `vchart-development-assistant`。
+
+目录示意：
+
+![skills 目录示意](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/e3cd80683fb34e21a02d371b1bc360c9~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=wrXQJFCJd%2B6sMd05mYc1Ehu3fu8%3D)
+
+### 3. 示例一：生成简单图表
+
+建议提示词：
+
+```text
+使用 VChart 生成一个基础柱状图，包含 xField、yField 和最小可运行示例。
+```
+
+验收点：
+
+- 能输出可运行的最小 spec。
+- 图表可正常渲染。
+
+示例效果：
+
+![生成简单图表示例](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/fc55630c49a94d84bd3d7e3a5ca59da1~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=fcmQ6R0EEMPMDp8y%2Fw38OE4nNjY%3D)
+
+### 4. 示例二：调整图表样式
+
+建议提示词：
+
+```text
+在已有柱状图基础上，优化颜色、标签样式和图例可读性，保留原有数据结构。
+```
+
+验收点：
+
+- 样式改动清晰可见。
+- 不破坏原有图表结构与数据映射。
+
+示例效果：
+
+![调整图表样式示例](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/3cec7ac8dc11486ca9a61eb157ac478d~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=9ETSnU3R8KdgL%2Fl6bHV%2F70RoBDg%3D)
+
+### 5. 示例三：修复配置问题
+
+建议提示词：
+
+```text
+检查当前 VChart spec 的配置错误并给出修复方案，解释每一处修复原因。
+```
+
+验收点：
+
+- 明确指出错误位置。
+- 给出可直接替换的修复配置。
+
+示例效果：
+
+![修复配置问题示例](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/bb4911d4db814a7ca3b777f7549cf69e~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg546E6a2C:q75.awebp?rk3s=f64ab15b&x-expires=1773307752&x-signature=J1olPfoWsglwVMxCukVu1otSycU%3D)
+
+## 常见问题与注意事项
+
+- 如果编辑器不支持 skills，需先确认当前版本是否提供该能力。
+- 如果命令执行成功但效果不明显，优先检查 skill 目录是否正确写入。
+- 若项目上下文不足，建议先补充图表目标、字段含义和预期输出。
+- 外部链接或命令可能随版本变化，请以最新官方文档为准。

specs/001-vchart-skill-tutorial/PR_BODY.md

@@ -0,0 +1,91 @@
+<!--
+First of all, thank you for your contribution! 😄
+For requesting to pull a new feature or bugfix, please send it from a feature/bugfix branch based on the `main` branch.
+Before submitting your pull request, please make sure the checklist below is confirmed.
+Your pull requests will be merged after one of the collaborators approve.
+Thank you!
+-->
+
+[[中文版模板 / Chinese template](https://github.com/VisActor/VChart/blob/main/.github/PULL_REQUEST_TEMPLATE/pr_cn.md?plain=1)]
+
+### 🤔 This is a ...
+
+- [x] New feature
+- [ ] Bug fix
+- [ ] TypeScript definition update
+- [ ] Bundle size optimization
+- [ ] Performance optimization
+- [ ] Enhancement feature
+- [ ] Refactoring
+- [ ] Update dependency
+- [ ] Code style optimization
+- [ ] Test Case
+- [ ] Branch merge
+- [ ] Release
+- [ ] Site / documentation update
+- [ ] Demo update
+- [ ] Workflow
+- [ ] Other (about what?)
+
+### 🔗 Related issue link
+
+<!--
+1. Put the related issue or discussion links here.
+2. close #xxxx or fix #xxxx for instance.
+-->
+
+### 🔗 Related PR link
+
+<!-- Put the related PR links here. -->
+
+### 🐞 Bugserver case id
+
+<!-- paste the `fileid` field in the bugserver case url -->
+
+### 💡 Background and solution
+
+在 VChart 文档站新增一篇“VChart Skill 使用”教程，并将其挂载到与“快速上手”同级的导航层级。教程以用户提供的参考正文为语义来源，覆盖技能简介、安装方式、编辑器适配（Cursor/Trae）以及三个可执行场景（生成简单图表、调整图表样式、修复配置问题），同时保持与现有文档规范一致。
+
+**Language/Version**: Markdown + JSON（文档内容与菜单配置）
+**Primary Dependencies**: `@internal/docs` 文档构建体系、`docs/assets/guide/menu.json` 导航配置、现有教程目录结构
+**Storage**: N/A
+**Testing**: 文档构建与链接可达性检查（本地 docs 预览 + 静态路径校验）
+**Target Platform**: VChart 官方文档站（zh 主路径，en 路径不新增正文）
+**Project Type**: Rush Monorepo（文档子系统变更）
+**Performance Goals**: 不引入额外运行时成本；页面加载复杂度与现有教程同级
+**Constraints**: 必须与“快速上手”同级；教程内容与参考正文一致但需可验证；不得破坏现有导航结构
+**Scale/Scope**: 1 篇新增教程 + 1 处导航配置调整 + 文档内链与示例片段
+### 📝 Changelog
+
+<!--
+Describe changes from the user side, and list all potential break changes or other risks.
+--->
+
+| Language   | Changelog |
+| ---------- | --------- |
+| 🇺🇸 English | Add a VChart Skill tutorial and place it at the same navigation level as Quick Start, with installation, editor references, and guided demo scenarios. |
+| 🇨🇳 Chinese |           |
+
+### ☑️ Self-Check before Merge
+
+⚠️ Please check all items below before requesting a reviewing. ⚠️
+
+- [ ] Doc is updated/provided or not needed
+- [ ] Demo is updated/provided or not needed
+- [ ] TypeScript definition is updated/provided or not needed
+- [ ] Changelog is provided or not needed
+
+---
+
+<!--
+Below are template for copilot to generate CR message.
+Please DO NOT modify it.
+-->
+
+### 🚀 Summary
+
+copilot:summary
+
+### 🔍 Walkthrough
+
+copilot:walkthrough

specs/001-vchart-skill-tutorial/checklists/requirements.md

@@ -0,0 +1,38 @@
+# Specification Quality Checklist: 新增 vchart-skill 教程文档
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-06
+**Feature**: [/Users/bytedance/Documents/GitHub/VChart/specs/001-vchart-skill-tutorial/spec.md](/Users/bytedance/Documents/GitHub/VChart/specs/001-vchart-skill-tutorial/spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- 已完成一轮规范自检，全部检查项通过。
+- 无需额外澄清问题（0 个 [NEEDS CLARIFICATION] 标记）。
+- 已根据用户补充的参考正文（含安装命令、编辑器适配、3 个示例场景）完成二次 refine。
+- 已实现文档与导航变更：新增 `VChart_Skill_Usage` 菜单节点，并新增中英文教程文档文件。
+- 链接完整性校验通过：菜单路径存在，`zh/en` 对应文件存在，文内相对链接可解析。