diff --git a/.cursor/rules/specify-rules.mdc b/.cursor/rules/specify-rules.mdc index 29a80f02e5..f4448e2042 100644 --- a/.cursor/rules/specify-rules.mdc +++ b/.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 diff --git a/docs/assets/guide/en/tutorial_docs/VChart_Skill_Usage.md b/docs/assets/guide/en/tutorial_docs/VChart_Skill_Usage.md new file mode 100644 index 0000000000..5266bbf509 --- /dev/null +++ b/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. diff --git a/docs/assets/guide/menu.json b/docs/assets/guide/menu.json index 3fe4488545..d3c09a0c13 100644 --- a/docs/assets/guide/menu.json +++ b/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 @@ ] } ] -} \ No newline at end of file +} diff --git a/docs/assets/guide/zh/tutorial_docs/VChart_Skill_Usage.md b/docs/assets/guide/zh/tutorial_docs/VChart_Skill_Usage.md new file mode 100644 index 0000000000..cae4964d1e --- /dev/null +++ b/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` 或其他 `./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 目录是否正确写入。 +- 若项目上下文不足，建议先补充图表目标、字段含义和预期输出。 +- 外部链接或命令可能随版本变化，请以最新官方文档为准。 diff --git a/specs/001-vchart-skill-tutorial/PR_BODY.md b/specs/001-vchart-skill-tutorial/PR_BODY.md new file mode 100644 index 0000000000..d1794c2413 --- /dev/null +++ b/specs/001-vchart-skill-tutorial/PR_BODY.md @@ -0,0 +1,91 @@ + + +[[中文版模板 / 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 + + + +### 🔗 Related PR link + + + +### 🐞 Bugserver case id + + + +### 💡 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 + + + +| 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 + +--- + + + +### 🚀 Summary + +copilot:summary + +### 🔍 Walkthrough + +copilot:walkthrough \ No newline at end of file diff --git a/specs/001-vchart-skill-tutorial/checklists/requirements.md b/specs/001-vchart-skill-tutorial/checklists/requirements.md new file mode 100644 index 0000000000..9369a9d229 --- /dev/null +++ b/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` 对应文件存在，文内相对链接可解析。 diff --git a/specs/001-vchart-skill-tutorial/contracts/interface.md b/specs/001-vchart-skill-tutorial/contracts/interface.md new file mode 100644 index 0000000000..ce48b920e6 --- /dev/null +++ b/specs/001-vchart-skill-tutorial/contracts/interface.md @@ -0,0 +1,37 @@ +# Documentation Contract: vchart-skill Tutorial + +## 1. Navigation Contract + +- **Contract ID**: DOC-NAV-001 +- **Input**: 新增教程菜单配置 +- **Rules**: + - 菜单节点必须位于与“快速上手”同级层级。 + - 菜单节点必须指向有效教程路径。 + - 菜单文案需清晰表达主题（vchart-skill 使用）。 +- **Output**: 文档站可见教程入口且可访问。 + +## 2. Content Contract + +- **Contract ID**: DOC-CONTENT-001 +- **Input**: 教程 markdown 正文 +- **Rules**: + - 必须包含“简介”“安装与简单 Demo”一级章节。 + - 必须包含两条安装命令： + - `npx skills add VisActor/VChart` + - `npx skills add VisActor/VChart --skill vchart-development-assistant` + - 必须包含三类示例： + - 生成简单图表 + - 调整图表样式 + - 修复配置问题 + - 必须包含编辑器适配信息（Cursor、Trae）与参考链接。 +- **Output**: 教程内容完整且可执行。 + +## 3. Link Integrity Contract + +- **Contract ID**: DOC-LINK-001 +- **Input**: 菜单路径、文内链接、外部参考链接 +- **Rules**: + - 站内链接不得产生 404。 + - 文内外部链接需具备可识别描述文本。 + - 构建后教程页面可正常加载，无关键资源缺失。 +- **Output**: 文档站链接健康，满足可用性要求。 diff --git a/specs/001-vchart-skill-tutorial/data-model.md b/specs/001-vchart-skill-tutorial/data-model.md new file mode 100644 index 0000000000..9d179a12e6 --- /dev/null +++ b/specs/001-vchart-skill-tutorial/data-model.md @@ -0,0 +1,49 @@ +# Data Model: vchart-skill 教程文档 + +## Entities + +### TutorialDoc（教程文档） +- Fields: + - id: String（唯一标识） + - title: String（文档标题，如“VChart Skill 使用”） + - locale: Enum(`zh`, `en`)（本期主要为 `zh`） + - path: String（文档相对路径） + - sections: Section[]（章节集合） + - updatedAt: Date（更新时间） + +### Section（章节） +- Fields: + - key: String（章节标识，如 `intro`, `install`, `demo`） + - heading: String（章节标题） + - order: Number（章节顺序） + - contentBlocks: ContentBlock[]（段落/代码/图片等） + +### ContentBlock（内容块） +- Fields: + - type: Enum(`paragraph`, `code`, `image`, `link`, `list`) + - value: String/Object（内容本体） + - required: Boolean（是否必填） + +### MenuItem（导航节点） +- Fields: + - key: String（菜单项唯一 key） + - zh: String（中文名称） + - en: String（英文名称，允许占位） + - menu: String（关联文档路径） + - category: String（所属目录） + - order: Number（排序） + - level: Number（层级） + +## Relationships + +- 一个 `TutorialDoc` 包含多个 `Section`（1:N）。 +- 一个 `Section` 包含多个 `ContentBlock`（1:N）。 +- 一个 `MenuItem` 关联一个 `TutorialDoc.path`（1:1）。 + +## Validation Rules + +- 教程必须包含 `intro` 与 `install-demo` 两个一级章节（对应 FR-004）。 +- 教程必须包含两条安装命令内容块（对应 FR-006）。 +- 教程必须包含三类 Demo 场景内容块（对应 FR-012）。 +- `MenuItem.level` 必须与“快速上手”所在节点同级（对应 FR-002）。 +- `MenuItem.menu` 与 `TutorialDoc.path` 必须可解析且构建后无死链（对应 FR-008）。 diff --git a/specs/001-vchart-skill-tutorial/plan.md b/specs/001-vchart-skill-tutorial/plan.md new file mode 100644 index 0000000000..6be0773a08 --- /dev/null +++ b/specs/001-vchart-skill-tutorial/plan.md @@ -0,0 +1,67 @@ +# Implementation Plan: 新增 vchart-skill 教程文档 + +**Branch**: `001-vchart-skill-tutorial` | **Date**: 2026-03-06 | **Spec**: [spec.md](./spec.md) +**Input**: Feature specification from `/specs/001-vchart-skill-tutorial/spec.md` + +**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow. + +## Summary + +在 VChart 文档站新增一篇“VChart Skill 使用”教程，并将其挂载到与“快速上手”同级的导航层级。教程以用户提供的参考正文为语义来源，覆盖技能简介、安装方式、编辑器适配（Cursor/Trae）以及三个可执行场景（生成简单图表、调整图表样式、修复配置问题），同时保持与现有文档规范一致。 + +## Technical Context + +**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 处导航配置调整 + 文档内链与示例片段 + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +- [x] **质量优先**: 以文档可执行性和链接正确性为验收标准，避免“只有介绍无操作闭环”。 +- [x] **用户体验驱动**: 教程明确安装步骤、编辑器适配与常见场景，降低上手成本。 +- [x] **规范驱动开发**: 已完成 `spec.md` 与 checklist，本计划仅围绕规范展开。 +- [x] **开放协作**: 参考内容来源与假设均在文档中透明记录，便于后续审阅与更新。 +- [x] **增量演进**: 仅新增教程与菜单节点，不改变现有核心渲染或 API 行为。 +- [x] **文档与示例同步**: 本变更本质为文档功能，产出即为对外可见能力。 + +## Project Structure + +### Documentation (this feature) + +```text +specs/001-vchart-skill-tutorial/ +├── plan.md # This file (/speckit.plan command output) +├── research.md # Phase 0 output (/speckit.plan command) +├── data-model.md # Phase 1 output (/speckit.plan command) +├── quickstart.md # Phase 1 output (/speckit.plan command) +├── contracts/ # Phase 1 output (/speckit.plan command) +└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan) +``` + +### Source Code (repository root) + +```text +docs/assets/guide/ +├── menu.json # 导航结构，新增与“快速上手”同级入口 +└── zh/tutorial_docs/ + ├── Getting_Started.md # 现有“快速上手”（用于同级定位参考） + └── Basic/ + └── VChart_Skill_Usage.md # 新增教程文档（拟定路径） + +docs/assets/guide/en/tutorial_docs/ +└── (no new tutorial content in this feature scope) # 本期不新增英文正文，仅保证导航不产生坏链 +``` + +**Structure Decision**: 采用“中文教程正文 + 导航同级挂载”的最小增量策略；通过 `menu.json` 增加节点并落地到 `zh/tutorial_docs/Basic` 下新文档，避免对现有章节结构造成破坏。 + +## Complexity Tracking + +No constitution violations identified for this feature. diff --git a/specs/001-vchart-skill-tutorial/quickstart.md b/specs/001-vchart-skill-tutorial/quickstart.md new file mode 100644 index 0000000000..8bf86d4e5f --- /dev/null +++ b/specs/001-vchart-skill-tutorial/quickstart.md @@ -0,0 +1,32 @@ +# Quickstart + +## 目标 + +快速验证“vchart-skill 教程”是否满足规范：可发现、可执行、可复用。 + +## 预置条件 + +- 当前分支：`001-vchart-skill-tutorial` +- 已完成 `spec.md`、`plan.md`、`research.md` +- 本地可启动文档站（按仓库既有 docs 流程） + +## 执行步骤 + +1. 在中文教程目录新增 `VChart_Skill_Usage.md`（名称可按最终命名规范调整）。 +2. 在 `docs/assets/guide/menu.json` 新增导航节点，确保层级与“快速上手”同级。 +3. 在教程正文中写入以下必含内容： + - 简介（vchart-skill 价值说明） + - 安装命令（两种方式） + - 编辑器参考（Cursor、Trae） + - 三个 Demo 场景（生成图表、调整样式、修复配置） + - 注意事项/常见问题 +4. 本地启动文档站并验证： + - 导航可见该教程入口 + - 入口点击后页面可正常加载 + - 正文代码块与链接格式符合现有教程规范 + +## 验收检查 + +- 导航层级符合 FR-002。 +- 教程结构符合 FR-004、FR-006、FR-010、FR-012。 +- 无死链，且“快速上手”关系说明清晰（FR-008、FR-009）。 diff --git a/specs/001-vchart-skill-tutorial/research.md b/specs/001-vchart-skill-tutorial/research.md new file mode 100644 index 0000000000..9a58004b30 --- /dev/null +++ b/specs/001-vchart-skill-tutorial/research.md @@ -0,0 +1,32 @@ +# Research: 新增 vchart-skill 教程文档 + +## 决策与依据 + +### Decision 1: 教程主文仅新增中文版本 +- **Decision**: 本期仅在 `zh` 文档路径新增完整教程，不新增英文正文。 +- **Rationale**: 需求明确目标为“新增教程并与快速上手同级”，且输入内容为中文；可在最小范围内快速交付。 +- **Alternatives considered**: 同步新增中英文双语教程（成本更高，超出当前需求范围）。 + +### Decision 2: 导航“同级”按 menu 节点层级定义 +- **Decision**: “与快速上手同级”解释为 `menu.json` 中节点深度同级，而非文档标题层级。 +- **Rationale**: 这是文档站信息架构层面的可验证标准，且已在 spec 假设中明确。 +- **Alternatives considered**: 仅在正文中增加“快速上手”跳转（无法满足导航同级要求）。 + +### Decision 3: 教程内容以“可执行闭环”组织 +- **Decision**: 教程采用“简介 → 安装 → 三个 Demo 场景 → 注意事项”结构。 +- **Rationale**: 与用户提供参考正文一致，并满足首次用户可直接复现的核心目标。 +- **Alternatives considered**: 纯概念说明（无法满足 FR-006/FR-012 的可执行要求）。 + +### Decision 4: 安装指令采用双命令并列展示 +- **Decision**: 明确保留两种安装命令：`npx skills add VisActor/VChart` 与 `--skill vchart-development-assistant` 形式。 +- **Rationale**: 两种方式都在用户提供正文中出现，可覆盖不同用户偏好。 +- **Alternatives considered**: 只保留一种命令（降低兼容性与参考一致性）。 + +### Decision 5: 编辑器适配最小范围覆盖 Cursor 与 Trae +- **Decision**: 教程明确支持 Cursor、Trae 两类编辑器，并给出参考文档入口。 +- **Rationale**: 这是参考正文的主要外部依赖信息，可显著降低首次配置失败率。 +- **Alternatives considered**: 广泛扩展到更多编辑器（超出当前输入范围，维护成本更高）。 + +## 未解决问题 + +无 `NEEDS CLARIFICATION` 项，研究阶段完成。 diff --git a/specs/001-vchart-skill-tutorial/spec.md b/specs/001-vchart-skill-tutorial/spec.md new file mode 100644 index 0000000000..c1a7fbc42a --- /dev/null +++ b/specs/001-vchart-skill-tutorial/spec.md @@ -0,0 +1,99 @@ +# Feature Specification: 新增 vchart-skill 教程文档 + +**Feature Branch**: `001-vchart-skill-tutorial` +**Created**: 2026-03-06 +**Status**: Draft +**Input**: User description: "增加一篇教程文档介绍如何使用vchart-skill，放到文档中与快速上手同级，文档内容参考 https://juejin.cn/post/7605535884939526195" + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - 新用户可通过教程完成首次接入 (Priority: P1) + +作为首次接触 `vchart-skill` 的开发者，我希望在文档站中看到一篇结构完整的教程，并按教程步骤完成环境准备、核心用法理解与最小可运行示例。 + +**Why this priority**: 这是该需求的核心价值，直接决定用户是否能够成功使用 `vchart-skill`。 + +**Independent Test**: 仅基于该教程与现有公开文档，新用户可在一次阅读中完成“安装/配置/运行最小示例”的闭环。 + +**Acceptance Scenarios**: + +1. **Given** 用户进入文档站教程目录，**When** 用户查看与“快速上手”同级的导航项，**Then** 可看到 `vchart-skill` 教程入口并成功打开。 +2. **Given** 用户按教程顺序阅读，**When** 用户执行教程提供的安装与启用步骤，**Then** 能在支持 skills 的 AI 编辑器中完成 `vchart-skill` 的可用状态验证。 +3. **Given** 用户已完成技能安装，**When** 用户跟随教程完成简单图表生成示例，**Then** 能获得与示例目标一致的图表产出。 + +--- + +### User Story 2 - 现有用户可快速定位 vchart-skill 最佳实践 (Priority: P2) + +作为已在使用 VChart 的开发者，我希望通过教程快速定位 `vchart-skill` 的使用场景、关键能力和常见坑点，减少试错成本。 + +**Why this priority**: 在完成“能用”后，用户需要“用对”；该故事提升教程实用性与复用价值。 + +**Independent Test**: 现有用户可在教程中快速找到“适用场景、步骤说明、注意事项”并据此调整项目实践。 + +**Acceptance Scenarios**: + +1. **Given** 用户已有 VChart 使用经验，**When** 用户浏览教程内容目录与小节标题，**Then** 可在 3 分钟内定位目标知识点（如场景、步骤、注意事项）。 +2. **Given** 用户遇到配置偏差或预期不一致，**When** 用户查看教程中的注意事项或排查提示，**Then** 能得到明确处理方向。 +3. **Given** 用户希望提升图表质量，**When** 用户参考教程中的样式调整示例，**Then** 能在已有图表基础上完成可见的样式优化。 + +--- + +### User Story 3 - 文档维护者可长期维护教程一致性 (Priority: P3) + +作为文档维护者，我希望该教程遵循现有文档规范（命名、结构、导航挂载方式），保证后续更新可持续。 + +**Why this priority**: 有利于后续迭代与版本演进，避免单篇教程成为孤立内容。 + +**Independent Test**: 按现有文档提交流程，维护者可完成教程更新并保持导航与文档结构一致。 + +**Acceptance Scenarios**: + +1. **Given** 维护者检查文档目录与菜单配置，**When** 教程被加入站点导航，**Then** 教程位置与“快速上手”同级且命名清晰。 +2. **Given** 后续需要补充教程内容，**When** 维护者按照既有格式编辑文档，**Then** 不需要额外定制流程即可完成更新。 + +### Edge Cases + +- 参考文章中包含不适用于当前文档站的信息时，教程应仅保留与 `vchart-skill` 使用直接相关且可验证的内容。 +- 若参考文章部分步骤依赖外部上下文，教程需补齐必要前置条件，避免用户因信息缺失无法完成实践。 +- 当用户从英文导航进入对应区域时，不应出现死链或指向错误路径。 +- 若后续版本变更导致部分字段或步骤失效，教程需提供可识别的版本前提或更新提示。 +- 当用户使用的 AI 编辑器不支持 skills 或目录结构不同于教程示例时，教程需提供兼容性说明与替代路径。 + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: 文档系统 MUST 新增一篇主题为“如何使用 `vchart-skill`”的教程文档。 +- **FR-002**: 新增教程 MUST 在文档导航结构中与“快速上手（Getting Started）”处于同级层级展示。 +- **FR-003**: 教程内容 MUST 覆盖 `vchart-skill` 的使用目标、前置条件、核心步骤与最小实践结果说明，并说明其用于降低 VChart/VTable 使用门槛与提升开发效率的价值定位。 +- **FR-004**: 教程内容 MUST 参考用户提供的文章主题结构与关键知识点，并在文档语境下进行可执行重组，至少包含“简介”“安装与简单 Demo”两个一级章节。 +- **FR-005**: 教程 MUST 使用与现有教程一致的文档格式规范（标题层级、段落组织、代码片段呈现风格）。 +- **FR-006**: 教程 MUST 包含技能安装说明，并展示用户可直接复制执行的安装方式（包括 `npx skills add VisActor/VChart` 与带 `--skill vchart-development-assistant` 的方式）。 +- **FR-007**: 教程 MUST 包含常见问题或注意事项小节，用于覆盖高频误用或易错点。 +- **FR-008**: 导航入口与文档路径 MUST 在站点构建后可正常访问，不得出现死链。 +- **FR-009**: 教程 MUST 与当前“快速上手”内容形成互补，不重复基础入门定义，必要时通过跳转关系说明阅读顺序。 +- **FR-010**: 教程 MUST 明确至少两类支持 skills 的编辑器场景，并提供对应参考资料入口（例如 Cursor、Trae）。 +- **FR-011**: 教程 MUST 描述技能应安装在项目的技能目录下，并通过示意说明帮助用户确认安装结果。 +- **FR-012**: 教程 MUST 提供三个可执行示例场景：生成简单图表、调整图表样式、修复配置问题。 + +### Key Entities *(include if feature involves data)* + +- **教程文档条目**: 表示新增的 `vchart-skill` 教程页面，核心属性包括标题、路径、正文结构、示例步骤、注意事项。 +- **导航菜单节点**: 表示文档侧边栏或目录中的入口项，核心属性包括显示名称、层级、排序、关联文档路径。 +- **教程步骤块**: 表示教程中的可执行步骤单元，核心属性包括前置条件、执行动作、预期结果、排查提示。 + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: 100% 文档站用户可通过导航在 2 次点击内到达 `vchart-skill` 教程页面。 +- **SC-002**: 至少 90% 的首次阅读用户可仅依赖该教程完成技能安装与简单图表生成流程，并得到预期结果。 +- **SC-003**: 教程发布后首轮评审中，文档完整性（目标、前置、步骤、结果、注意事项）检查项通过率达到 100%。 +- **SC-004**: 教程上线后与该主题相关的“入口找不到/步骤缺失/安装失败无指引”类反馈在一个迭代内低于 2 条。 + +## Assumptions + +- 本次需求范围以中文文档教程为主，不强制新增英文同等内容。 +- “与快速上手同级”指文档导航层级同级，而非文内标题层级同级。 +- 教程中的安装命令与示例以用户在 2026-03-06 提供的参考正文为基准；后续如上游地址或命令变更，按最新可验证信息更新。 diff --git a/specs/001-vchart-skill-tutorial/tasks.md b/specs/001-vchart-skill-tutorial/tasks.md new file mode 100644 index 0000000000..659413f4f4 --- /dev/null +++ b/specs/001-vchart-skill-tutorial/tasks.md @@ -0,0 +1,177 @@ +# Tasks: 新增 vchart-skill 教程文档 + +**Input**: Design documents from `/specs/001-vchart-skill-tutorial/` +**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ + +**Tests**: 本特性未要求 TDD 或新增自动化测试，采用文档构建与人工验收检查。 + +**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. + +## Format: `[ID] [P?] [Story] Description` + +- **[P]**: Can run in parallel (different files, no dependencies) +- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) +- Include exact file paths in descriptions + +## Phase 1: Setup (Shared Infrastructure) + +**Purpose**: 确认文档信息架构落点与文件命名，建立变更骨架 + +- [x] T001 Audit existing guide navigation structure in docs/assets/guide/menu.json and locate the "快速上手" sibling insertion position +- [x] T002 Create tutorial draft file skeleton in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md with top-level headings +- [x] T003 [P] Collect and normalize external reference links (VChart repo, Cursor docs, Trae docs) in specs/001-vchart-skill-tutorial/research.md for copy-safe usage + +--- + +## Phase 2: Foundational (Blocking Prerequisites) + +**Purpose**: 完成所有用户故事共享的导航与文档契约前置项 + +**⚠️ CRITICAL**: No user story work can begin until this phase is complete + +- [x] T004 Add a new zh tutorial menu node at the same level as "快速上手" in docs/assets/guide/menu.json +- [x] T005 Define final tutorial metadata (title/path/order) and align with menu mapping in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T006 [P] Add "与快速上手的关系" section anchor and intra-doc cross-reference in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T007 Validate menu path resolution and avoid dead links against docs/assets/guide/menu.json and docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md + +**Checkpoint**: Foundation ready - user story implementation can now begin in parallel + +--- + +## Phase 3: User Story 1 - 新用户可通过教程完成首次接入 (Priority: P1) 🎯 MVP + +**Goal**: 新用户可完成 skill 安装、启用与最小示例闭环 + +**Independent Test**: 仅阅读该教程可完成安装与“生成简单图表”示例，不依赖额外上下文 + +### Implementation for User Story 1 + +- [x] T008 [US1] Write introduction and value proposition section in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T009 [US1] Add installation section with command `npx skills add VisActor/VChart` in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T010 [US1] Add installation section with command `npx skills add VisActor/VChart --skill vchart-development-assistant` in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T011 [P] [US1] Add Cursor skill setup reference and usage note in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T012 [P] [US1] Add Trae skill setup reference and usage note in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T013 [US1] Add "生成简单图表" demo walkthrough with expected output description in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T014 [US1] Add project skill-directory verification guidance (e.g., .cursor/skills style path explanation) in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T015 [US1] Run MVP content self-check against FR-003/FR-004/FR-006/FR-010/FR-011 in specs/001-vchart-skill-tutorial/checklists/requirements.md + +**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently + +--- + +## Phase 4: User Story 2 - 现有用户可快速定位 vchart-skill 最佳实践 (Priority: P2) + +**Goal**: 让已有 VChart 用户快速定位可复用实践与排障路径 + +**Independent Test**: 有经验用户可在 3 分钟内定位“样式调整/配置修复/注意事项”并完成实践迁移 + +### Implementation for User Story 2 + +- [x] T016 [US2] Add "调整图表样式" scenario with prompt examples and expected improvement notes in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T017 [US2] Add "修复配置问题" scenario with troubleshooting flow in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T018 [US2] Add "常见问题与注意事项" section for editor compatibility and context gaps in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T019 [P] [US2] Add quick-jump table of contents for scenario navigation in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T020 [US2] Validate scenario completeness against contract DOC-CONTENT-001 in specs/001-vchart-skill-tutorial/contracts/interface.md + +**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently + +--- + +## Phase 5: User Story 3 - 文档维护者可长期维护教程一致性 (Priority: P3) + +**Goal**: 确保教程长期可维护，结构与命名符合既有文档规范 + +**Independent Test**: 维护者可按既有流程更新教程且不破坏导航与链接 + +### Implementation for User Story 3 + +- [x] T021 [US3] Align naming/style conventions (headings, code block style, link labels) with neighboring docs in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T022 [US3] Add maintenance note for future command/link drift and update trigger in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T023 [P] [US3] Cross-check menu node consistency (zh/en labels and ordering) in docs/assets/guide/menu.json +- [x] T024 [US3] Update feature checklist status after maintainability review in specs/001-vchart-skill-tutorial/checklists/requirements.md + +**Checkpoint**: All user stories should now be independently functional + +--- + +## Phase 6: Polish & Cross-Cutting Concerns + +**Purpose**: 全局收尾与最终验收 + +- [x] T025 [P] Run final markdown quality pass for docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md (typos, heading levels, code formatting) +- [x] T026 Verify link integrity contract DOC-LINK-001 for docs/assets/guide/menu.json and docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md +- [x] T027 Execute quickstart verification checklist in specs/001-vchart-skill-tutorial/quickstart.md and record outcome in specs/001-vchart-skill-tutorial/checklists/requirements.md +- [x] T028 [P] Prepare implementation handoff notes for /speckit.implement in specs/001-vchart-skill-tutorial/tasks.md + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Setup (Phase 1)**: No dependencies - can start immediately +- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories +- **User Stories (Phase 3+)**: All depend on Foundational phase completion +- **Polish (Phase 6)**: Depends on all desired user stories being complete + +### User Story Dependencies + +- **User Story 1 (P1)**: Can start after Phase 2 - delivers MVP independently +- **User Story 2 (P2)**: Can start after Phase 2 - depends on US1 tutorial skeleton but independently testable +- **User Story 3 (P3)**: Can start after Phase 2 - focuses on maintainability and governance + +### Within Each User Story + +- Skeleton/navigation first +- Core scenario content next +- Review/checklist updates last + +### Parallel Opportunities + +- Phase 1: T003 in parallel with T001/T002 +- Phase 2: T006 can run in parallel after T004 starts +- US1: T011 and T012 can run in parallel +- US2: T019 can run in parallel with T016/T017 +- US3: T023 can run in parallel with T021/T022 +- Polish: T025 and T028 can run in parallel + +--- + +## Parallel Example: User Story 1 + +```bash +Task: "Add Cursor skill setup reference in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md" +Task: "Add Trae skill setup reference in docs/assets/guide/zh/tutorial_docs/Basic/VChart_Skill_Usage.md" +``` + +--- + +## Implementation Strategy + +### MVP First (User Story 1 Only) + +1. Complete Phase 1: Setup +2. Complete Phase 2: Foundational +3. Complete Phase 3: User Story 1 +4. Validate with quickstart and checklist gates + +### Incremental Delivery + +1. Deliver US1 as MVP (installation + simple chart) +2. Add US2 scenarios (style tuning + config fix) +3. Add US3 maintainability hardening +4. Run final polish and contract checks + +### Parallel Team Strategy + +1. One owner handles menu/navigation (T004-T007) +2. One owner writes US1 core tutorial (T008-T015) +3. One owner prepares US2/US3 improvements after US1 skeleton stabilizes + +--- + +## Notes + +- [P] tasks = different file segments, low coupling, can run in parallel +- [USx] labels map tasks directly to user stories for traceability +- Prefer finishing each phase checkpoint before starting broad parallel execution