create-vela-workflow 1.0.0

package/docs/ai-workflow-tutorial.md

@@ -0,0 +1,462 @@
+# Vela 快应用 AI 自动化生成应用 — 指导教程
+
+> 本教程介绍如何使用 AI 工作流自动生成小米 Vela 快应用，支持两种开发环境。
+
+---
+
+## 概述
+
+Vela 快应用 AI 工作流是一套面向小米智能穿戴设备（手表、手环）的自动化应用开发方案。开发者只需提供需求描述或设计稿，AI 即可自动完成从产品需求分析、技术方案设计到代码生成的全流程。
+
+### 工作流架构
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  AI 自动化工作流                        │
+├──────────────────────────────────────────────────────┤
+│                                                      │
+│  [输入]                                              │
+│    ├── 需求描述（文字 / 飞书文档 / Markdown）          │
+│    ├── 设计稿（Figma 链接 / 设计图片）                │
+│    └── 屏幕规格（480×480 圆屏 / 466×466 / 自定义）    │
+│                                                      │
+│  [S1: PRD 生成]  →  [S2: 技术方案]  →  [S3: 代码生成] │
+│                                                      │
+│  [输出]                                              │
+│    └── 可运行的 Vela 快应用项目工程                    │
+│                                                      │
+└──────────────────────────────────────────────────────┘
+```
+
+### 两种使用方式对比
+
+| 维度 | 方式一：AIoT IDE / VS Code + Copilot | 方式二：Kiro + Workflow |
+|------|--------------------------------------|------------------------|
+| IDE | AIoT IDE 或 VS Code | Kiro |
+| AI 引擎 | GitHub Copilot (GPT-4) | Kiro AI (Claude) |
+| 工作流形式 | Agent 模式 + Rules 自动注入 | Skill + Steering + Hooks |
+| 配置目录 | `.github/` | `.kiro/` + `.workflow/` |
+| 断点恢复 | 不支持 | 支持（Session 机制） |
+| 设计稿集成 | Figma MCP（uvx mcp-figma） | Figma Desktop MCP |
+| 代码校验 | Agent 内置检查步骤 | Hooks 自动触发校验 |
+| 适合场景 | 已有 Copilot 订阅的团队 | 追求深度自动化的团队 |
+
+---
+
+## 前置准备
+
+### 通用要求
+
+1. **Node.js** >= 18（[下载](https://nodejs.org/)）
+2. **aiot-toolkit**：Vela 快应用构建工具
+   ```bash
+   npm install -g aiot-toolkit
+   ```
+3. **项目脚手架验证**：
+   ```bash
+   npx create-aiot ux --name test-app --template vela-demo
+   ```
+
+### Figma 设计稿集成（可选）
+
+如果需要从 Figma 设计稿自动导出资源：
+
+1. 注册 Figma 账号并获取 Personal Access Token
+   - Figma → 头像 → Settings → Personal access tokens → Generate
+2. 确保设计稿已开启链接分享（至少 "can view"）
+
+---
+
+## 方式一：AIoT IDE / VS Code + GitHub Copilot
+
+### 1.1 环境配置
+
+#### 安装 IDE
+
+- **推荐**：[AIoT IDE](https://iot.mi.com/vela/quickapp/zh/tools/aiot-ide.html)（小米官方 IDE，内置 Vela 调试器）
+- **备选**：[VS Code](https://code.visualstudio.com/)
+
+#### 安装 GitHub Copilot
+
+1. 在 VS Code / AIoT IDE 扩展市场搜索 `GitHub Copilot`
+2. 安装并登录 GitHub 账号（需要 Copilot 订阅）
+3. 确认 Copilot Chat 功能可用
+
+#### 配置 Figma MCP（可选）
+
+在 IDE 的 MCP 配置文件中添加 Figma 服务器：
+
+**VS Code** — `~/Library/Application Support/Code/User/mcp.json`：
+
+```json
+{
+  "servers": {
+    "figma": {
+      "command": "uvx",
+      "args": ["mcp-figma"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "你的Figma Token",
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "disabled": false,
+      "autoApprove": ["get_file", "get_file_nodes", "export_image"]
+    }
+  }
+}
+```
+
+**AIoT IDE** — `~/Library/Application Support/AIoT IDE/User/settings.json`：
+
+```json
+{
+  "chat.mcp.servers": {
+    "figma": {
+      "command": "uvx",
+      "args": ["mcp-figma"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "你的Figma Token",
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      }
+    }
+  }
+}
+```
+
+### 1.2 安装工作流
+
+一行命令安装到你的项目：
+
+```bash
+npx create-vela-workflow my-project --mode copilot
+cd my-project
+```
+
+或在已有项目中安装：
+
+```bash
+cd your-existing-project
+npx create-vela-workflow . --mode copilot
+```
+
+安装后的目录结构：
+
+```
+.github/
+├── agents/                      # 自定义 Agent（在 Copilot Chat 中可选）
+│   ├── vela-workflow.agent.md   # 工作流协调器（入口）
+│   ├── vela-s1-prd.agent.md    # S1: PRD 生成
+│   ├── vela-s2-tech.agent.md   # S2: 技术方案
+│   ├── vela-s3-coding.agent.md # S3: 代码生成
+│   └── vela-knowledge.agent.md # 知识库查询
+├── rules/                       # 编码规则（自动注入，无需手动引用）
+│   ├── vela-platform.md        # 平台约束：组件+API 白名单
+│   ├── vela-format.md          # 格式规范：.ux 文件结构
+│   ├── vela-layout.md          # 布局规范：Flexbox+圆屏适配
+│   ├── vela-quality.md         # 质量标准：命名+错误处理
+│   └── project-init.md         # 初始化规范
+├── prompts/                     # 知识参考（按需加载）
+│   ├── vela-dev-guide.prompt.md      # 完整开发指南
+│   ├── vela-components.prompt.md     # 组件用法速查
+│   ├── vela-apis.prompt.md           # API 速查
+│   └── vela-best-practices.prompt.md # 最佳实践
+└── copilot-instructions.md      # Copilot 全局指令
+```
+
+### 1.3 使用工作流
+
+#### 启动方式
+
+打开 Copilot Chat，在 Agent 下拉菜单中选择 `Vela 快应用工作流`，然后输入需求：
+
+```
+创建一个天气应用，显示当前温度和未来3天天气预报
+```
+
+或者直接在对话中输入触发关键词：
+
+```
+帮我创建一个 Vela 快应用，功能是...
+```
+
+#### 工作流模式
+
+启动后会提示选择模式：
+
+- **完整流程**（推荐）：S1 PRD → S2 技术方案 → S3 代码生成
+- **快速模式**：跳过文档，直接生成代码
+
+#### 交互命令
+
+| 命令 | 说明 |
+|------|------|
+| `y` | 确认当前阶段产出，进入下一阶段 |
+| `e` | 提供修改意见，迭代当前产出 |
+| `n` | 放弃当前产出，重新生成 |
+
+#### 带设计稿的完整示例
+
+```
+用户: 创建一个音乐播放器应用
+      Figma 设计稿: https://www.figma.com/design/xxxxx
+
+AI:   👋 欢迎使用 Vela 快应用自动开发工作流！
+      🎨 检测到 Figma 设计稿，正在获取设计信息...
+      ✅ 设计稿解析完成，包含 3 个页面
+
+      ❓ 请选择工作流模式:
+        [1] 完整流程
+        [2] 快速模式
+
+用户: 2
+
+AI:   🚀 快速模式启动，正在生成代码...
+      📂 项目初始化: npx create-aiot ux --name music-player
+      📄 生成页面: index（播放器主页）、playlist（歌单列表）
+      🎨 导出设计稿图片资源...
+      ✅ 代码生成完成！
+
+      ❓ [y] 确认  [e] 修改  [n] 重做
+
+用户: y
+
+AI:   🎉 项目已创建完成！
+```
+
+---
+
+## 方式二：Kiro + Workflow
+
+### 2.1 环境配置
+
+#### 安装 Kiro
+
+下载并安装 [Kiro IDE](https://kiro.dev/)。
+
+#### 配置 Figma MCP（可选）
+
+在项目的 `.kiro/settings/mcp.json` 中配置：
+
+```json
+{
+  "mcpServers": {
+    "Figma Desktop": {
+      "url": "http://127.0.0.1:3845/mcp"
+    }
+  }
+}
+```
+
+> 注意：Kiro 使用 Figma Desktop MCP（需要 Figma 桌面客户端运行），与方式一的 uvx mcp-figma 不同。
+
+### 2.2 安装工作流
+
+一行命令安装到你的项目：
+
+```bash
+npx create-vela-workflow my-project --mode kiro
+cd my-project
+```
+
+或在已有项目中安装：
+
+```bash
+cd your-existing-project
+npx create-vela-workflow . --mode kiro
+```
+
+安装后的目录结构：
+
+```
+.kiro/
+├── skills/
+│   └── vela-js-app/
+│       └── SKILL.md            # Vela 开发完整知识库（组件、API、最佳实践）
+├── steering/
+│   └── workflow-conventions.md  # 工作流规范（自动加载）
+├── hooks/
+│   ├── figma-design-check.kiro.hook      # 设计稿对比校验
+│   ├── post-coding-validation.kiro.hook  # 代码质量校验
+│   └── validate-ux-files.kiro.hook       # .ux 文件语法校验
+└── settings/
+    └── mcp.json                # MCP 服务器配置
+
+.workflow/
+├── workflow_starter.md          # 工作流入口（引用此文件启动）
+├── workflow-config.json         # 阶段配置
+├── resource-paths.json          # 资源路径映射
+├── scripts/                     # 工作流引擎脚本
+│   ├── session_manager.js       # Session 管理
+│   ├── context_loader.js        # 上下文加载
+│   ├── checkpoint_manager.js    # 检查点管理
+│   └── figma_export.js          # Figma 导出
+└── stages/                      # 阶段编排
+    ├── s1_prd.md                # S1: PRD 生成
+    ├── s2_tech_design.md        # S2: 技术方案
+    ├── s3_coding.md             # S3: 代码生成
+    └── s4_simulator.md          # S4: 模拟器调试
+```
+
+### 2.3 使用工作流
+
+#### 启动方式
+
+在 Kiro 对话框中引用工作流入口文件：
+
+```
+@.workflow/workflow_starter.md
+```
+
+或者直接输入 Vela 相关关键词（Skill 会自动激活）：
+
+```
+帮我开发一个 Vela 快应用，功能是计步器
+```
+
+#### 工作流特性
+
+**Session 机制**：
+- 每次启动创建独立 Session，保存在 `.ai-workspace/sessions/`
+- 支持中断后恢复（输入 `q` 保存进度，下次自动检测）
+
+**自动化 Hooks**：
+- 编辑 `.ux` 文件时自动检查语法
+- 代码生成后自动校验质量（路由一致性、API 声明等）
+- 有 Figma 设计稿时自动对比设计还原度
+
+**Steering 规范**：
+- `workflow-conventions.md` 自动加载，确保所有对话遵循 Vela 平台约束
+- 禁止使用第三方 npm 包、禁止 SVG、强制 Flexbox 布局等规则自动生效
+
+#### 完整示例
+
+```
+用户: @.workflow/workflow_starter.md
+
+AI:   👋 欢迎使用 Vela 快应用自动开发工作流！
+      🔧 是否执行运行环境检查？
+        [y] 执行检查  [n] 跳过
+
+用户: n
+
+AI:   ✅ 工作流初始化完成（已跳过环境检查）
+      📝 请提供需求内容...
+
+用户: 开发一个记账应用，支持添加收支记录和查看月度统计
+
+AI:   🎨 请提供设计稿或 UI 参考:
+        - Figma 链接
+        - 设计图片
+        - 输入 "跳过" 不提供
+
+用户: 跳过
+
+AI:   📐 请提供目标设备屏幕规格（直接回车使用默认 480×480 圆屏）:
+
+用户: [回车]
+
+AI:   ✅ Session 创建成功
+      📝 Session ID: VELA-20260512-143022-a7b2
+      ❓ 请选择工作流模式:
+        [1] 完整流程  [2] 直接生成代码
+
+用户: 1
+
+AI:   🚀 执行阶段 S1 - PRD 生成...
+      [生成 PRD 文档]
+      ❓ [y] 确认  [e] 编辑  [n] 重做
+
+用户: y
+
+AI:   ➡️ 自动进入 S2 - 技术方案...
+      [生成技术方案]
+      ❓ [y] 确认  [e] 编辑  [n] 重做
+
+用户: y
+
+AI:   ➡️ 自动进入 S3 - 功能研发...
+      📂 初始化项目: npx create-aiot ux --name accounting-app
+      📄 生成页面代码...
+      ✅ 代码生成完成！
+
+      🎉 工作流全部完成！
+```
+
+---
+
+## 进阶用法
+
+### 自定义屏幕规格
+
+支持的设备屏幕参考：
+
+| 设备 | 像素尺寸 | 形状 | designWidth |
+|------|----------|------|-------------|
+| Xiaomi Watch S5 | 480×480 | 圆屏 | 480 |
+| Xiaomi Watch S3/S4 | 466×466 | 圆屏 | 466 |
+| REDMI Watch 5 | 432×514 | 方屏 | 432 |
+| 小米手环 9 | 192×490 | 跑道屏 | 192 |
+
+### 结合 Figma 设计稿
+
+提供 Figma 链接后，AI 会：
+1. 解析设计稿节点结构
+2. 提取颜色、字体、尺寸等设计 Token
+3. 导出图片资源为 PNG 格式
+4. 生成代码时严格还原设计稿样式
+
+### 需求文档导入
+
+支持多种需求来源：
+- 直接文字描述
+- 本地 Markdown 文件路径
+- 飞书文档链接（需配置飞书 MCP）
+- 其他网页链接
+
+---
+
+## 常见问题
+
+### Q: 脚手架命令执行失败？
+
+```bash
+# 检查 Node.js 版本
+node --version  # 需要 >= 18
+
+# 检查 npm 源
+npm config get registry
+
+# 切换为官方源
+npm config set registry https://registry.npmjs.org/
+```
+
+### Q: Figma 设计稿获取失败？
+
+1. 确认 Token 有效且有文件读取权限
+2. 确认设计稿已开启链接分享
+3. 检查 MCP 配置是否正确
+
+### Q: 生成的代码构建报错？
+
+```bash
+cd your-project
+npm install
+npm run build
+```
+
+如果报错，检查：
+- `manifest.json` 中的 features 是否声明了所有使用的 API
+- 页面路由配置是否与实际文件路径一致
+- 是否误用了第三方 npm 包
+
+### Q: 两种方式可以混用吗？
+
+可以。`.github/` 和 `.kiro/` + `.workflow/` 互不冲突，可以同时存在于项目中。团队成员可以根据自己使用的 IDE 选择对应方式。
+
+---
+
+## 更多资源
+
+- [Vela 快应用官方文档](https://iot.mi.com/vela/quickapp/)
+- [AIoT IDE 下载](https://iot.mi.com/vela/quickapp/zh/tools/aiot-ide.html)
+- [Kiro IDE 下载](https://kiro.dev/)
+- [GitHub Copilot](https://github.com/features/copilot)