create-vela-workflow 1.0.0

package/templates/.kiro/steering/workflow-conventions.md

@@ -0,0 +1,110 @@
+---
+inclusion: auto
+---
+
+# Vela 快应用工作流规范
+
+## 知识来源
+
+- 核心知识文件: #[[file:.kiro/skills/vela-js-app/SKILL.md]]
+- 官方文档站点: https://iot.mi.com/vela/quickapp/
+- 当 SKILL.md 中的信息不够详细时（如某个组件的完整属性列表），使用 webFetch 访问 SKILL.md 中标注的官网链接按需获取
+
+## 项目约束
+
+- 目标平台: VelaOS 智能手表/手环
+- 默认屏幕规格: 480×480 圆屏（可在 Session 中自定义）
+- 快应用页面文件格式: `.ux`（模板 + 脚本 + 样式合一）
+- 布局方式: Flexbox 为主，默认 flex-direction: column
+- 禁止使用第三方 npm 包（仅使用 VelaOS 内置 API 和组件）
+- 禁止使用 antd、echarts、element-ui、vant、axios、lodash 等外部库
+- 图表需求使用 Vela 内置 chart 组件，不用 echarts/d3
+- 组件只能用知识库 knowledge/components/ 中列出的内置组件
+- API 只能用 @system.xxx 系统 API（参考 knowledge/api-reference/）
+- 所有功能优先用原生 JS + CSS 实现
+
+## 代码风格
+
+- 变量/函数: camelCase
+- 组件名: PascalCase
+- 常量: UPPER_SNAKE_CASE
+- 缩进: 2 空格
+- 字符串: 单引号优先
+- 每个文件顶部必须有文件说明注释
+- 所有异步操作必须包含错误处理
+- 禁止使用 `@import` 引入 CSS，外部 CSS 必须用 `<style src="./path"></style>` 标签引入
+
+## 工作流使用提示
+
+- 启动工作流: 在对话框中输入 `#vela-workflow`（或引用 `@.workflow/workflow_starter.md`）
+- 快捷命令: y(确认) / e(编辑) / n(重做) / q(退出) / status(进度) / back(返回)
+- Session 数据保存在 `.ai-workspace/sessions/` 目录
+- 代码产出物直接写入项目工程目录（非 Session 目录）
+- `package.json` 必须基于 `knowledge/examples/settings/package.json` 模板生成
+
+## 项目初始化规范
+
+- 全新项目必须使用 `npx create-aiot ux --name <项目名>` 创建
+- 脚手架创建后必须补全缺失的产物：
+  - `package.json` 的 `devDependencies`（aiot-toolkit）
+  - `package.json` 的 `scripts`（start, build, release, watch）
+  - `README.md`（项目说明、开发/构建命令、目标平台）
+  - `.gitignore`（node_modules/, build/, dist/, .DS_Store, *.log）
+
+## Figma 设计稿对接规范
+
+### 获取设计信息流程
+
+1. 使用 `get_metadata` 获取整体页面结构和节点 ID
+2. 对每个关键页面/frame 调用 `get_design_context` 获取详细设计参数（颜色、尺寸、字体）
+3. 使用 `get_screenshot` 获取视觉参考截图
+4. 从设计上下文中提取图片资源 URL 并下载到 `src/common/`
+
+### 图片资源导出规则
+
+- **格式要求**：Vela 快应用仅支持 PNG 格式，禁止使用 SVG
+- **下载方式**：从 Figma Desktop MCP 的 localhost 资源 URL 下载（`http://localhost:3845/assets/xxx.png`）
+- **文件验证**：下载后用 `file` 命令验证是否为有效 PNG，检查文件大小（19字节 = 下载失败）
+- **尺寸控制**：图标不超过 200KB，背景图用 `sips -Z <maxDimension>` 压缩到屏幕尺寸
+- **命名规范**：`icon-<name>.png`（图标）、`bg-<name>.png`（背景）、`screenshot-<n>.png`（截图）
+
+### 尺寸还原规则
+
+- `manifest.json` 的 `config.designWidth` 必须与 Figma 设计稿宽度一致（如 466px 屏幕设为 466）
+- 所有列表项、卡片、按钮使用**固定宽高**（从 Figma 节点尺寸直接取值），不用百分比
+- border-radius 直接使用 Figma 中的数值
+
+### Scroll 容器必备设置
+
+Vela 快应用的 scroll 组件需要内部容器有明确尺寸才能正确滚动：
+
+```html
+<scroll class="page" scroll-y="true">
+  <div class="container">
+    <!-- 内容 -->
+  </div>
+</scroll>
+```
+```css
+.page {
+  width: 100%;
+  height: 100%;
+}
+.container {
+  flex-direction: column;
+  width: 100%;
+  height: 1000px; /* 必须设置固定高度，大于内容实际高度 */
+}
+```
+
+### 设计对比检查清单
+
+代码生成后自动执行以下检查（由 `figma-design-check` hook 触发）：
+
+- [ ] 布局结构（flex-direction、对齐方式）与设计稿一致
+- [ ] 关键元素尺寸（宽高、圆角、间距）使用固定值且与设计稿匹配
+- [ ] 颜色值、字号与设计稿一致
+- [ ] 所有图片引用指向 `src/common/` 下的有效 PNG 文件
+- [ ] 无 SVG 文件引用
+- [ ] 超出一屏的页面使用 scroll 包裹且 container 有固定高度
+- [ ] 圆形屏幕安全区域 padding 正确（上下 ~50px，左右 ~24-36px）

package/templates/.workflow/resource-paths.json

@@ -0,0 +1,62 @@
+{
+    "version": "2.0.0",
+    "paths": {
+        "agents_root": "agents",
+        "knowledge_root": "knowledge",
+        "skill_file": ".kiro/skills/vela-js-app/SKILL.md"
+    },
+    "knowledge_mode": "skill-first",
+    "skill_mappings": {
+        "prd/generate": {
+            "path": "agents/prd_agent.prompt.md",
+            "description": "S1: PRD 生成"
+        },
+        "tech/design": {
+            "path": "agents/tech_design_agent.prompt.md",
+            "description": "S2: 技术方案"
+        },
+        "coding/implement": {
+            "path": "agents/coding_agent.prompt.md",
+            "description": "S3: 功能研发"
+        }
+    },
+    "knowledge_mappings": {
+        "vela/dev-paradigm": {
+            "path": "knowledge/dev-paradigm",
+            "index_file": "INDEX.md",
+            "key_files": ["README.md", "quickapp-lifecycle.md", "page-routing.md", "manifest-config.md", "project-structure.md", "app-entry.md", "page-file-spec.md"],
+            "description": "Vela 快应用开发范式（生命周期、页面路由、manifest 配置、项目结构、脚本/样式规范）"
+        },
+        "vela/api-reference": {
+            "path": "knowledge/api-reference",
+            "index_file": "INDEX.md",
+            "key_files": ["README.md", "router-api.md", "app-api.md", "device-api.md", "storage-api.md", "fetch-api.md", "interconnect-api.md"],
+            "description": "Vela 快应用 API 接口（router、app、device、storage、fetch、audio、sensor 等 24 个系统 API）"
+        },
+        "vela/components": {
+            "path": "knowledge/components",
+            "index_file": "INDEX.md",
+            "key_files": ["README.md", "div.md", "list.md", "text.md", "image.md", "input.md", "scroll.md"],
+            "description": "Vela 快应用组件规范（容器组件 6 个、基础组件 10 个、表单组件 4 个、通用参考 4 个）"
+        },
+        "vela/examples": {
+            "path": "knowledge/examples",
+            "index_file": "INDEX.md",
+            "key_files": ["README.md", "todo-app.md", "album-app.md", "calculator-app.md"],
+            "description": "Vela 快应用代码示例（chart、todolist、player、settings、输入法等项目模板）"
+        },
+        "vela/best-practices": {
+            "path": "knowledge/best-practices",
+            "index_file": "INDEX.md",
+            "key_files": ["README.md", "start.md", "memory.md", "business.md"],
+            "description": "Vela 快应用最佳实践（启动优化、内存管理、业务实践）"
+        }
+    },
+    "stage_knowledge": {
+        "S1": ["skill"],
+        "S2": ["skill"],
+        "S3": ["skill", "vela/examples"],
+        "S4": ["skill"]
+    },
+    "skill_knowledge_note": "所有阶段优先使用 SKILL.md 作为基础知识。当需要某个组件/API 的完整属性列表时，Agent 应使用 webFetch 访问 SKILL.md 中标注的官网链接按需获取详细文档。vela/examples 仅在 S3 阶段加载，提供完整项目模板参考。"
+}

package/templates/.workflow/scripts/checkpoint_manager.js

@@ -0,0 +1,284 @@
+/**
+ * Checkpoint 管理模块
+ *
+ * 负责阶段间的人工审核（Checkpoint）机制和阶段流转逻辑。
+ * 提供产出物审核状态管理、y/e/n 命令处理、阶段推进和前置条件校验。
+ *
+ * Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 10.2, 10.5
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  resumeSession,
+  updateStageStatus,
+  safeWriteSessionJson,
+  SESSIONS_DIR,
+  VALID_STAGE_IDS
+} = require('./session_manager');
+
+// 工作流配置文件路径
+const WORKFLOW_CONFIG_PATH = path.resolve(__dirname, '../workflow-config.json');
+
+/**
+ * 加载工作流配置
+ * @returns {{ success: boolean, config?: object, error?: string }}
+ */
+function loadWorkflowConfig() {
+  try {
+    const raw = fs.readFileSync(WORKFLOW_CONFIG_PATH, 'utf-8');
+    return { success: true, config: JSON.parse(raw) };
+  } catch (err) {
+    return { success: false, error: `加载工作流配置失败: ${err.message}` };
+  }
+}
+
+/**
+ * 处理 Checkpoint（阶段审核点）
+ *
+ * 当阶段产出物生成完成时调用，将阶段状态设为 pending_review，
+ * 返回描述 checkpoint 状态的对象供工作流编排器使用。
+ *
+ * @param {string} sessionId - Session ID
+ * @param {string} stageId - 阶段 ID（S1/S2/S3）
+ * @param {string} output - 产出物内容路径
+ * @returns {{ success: boolean, checkpoint?: object, error?: string }}
+ */
+function handleCheckpoint(sessionId, stageId, output) {
+  // 参数校验
+  if (!sessionId || typeof sessionId !== 'string') {
+    return { success: false, error: 'Session ID 不能为空' };
+  }
+  if (!VALID_STAGE_IDS.includes(stageId)) {
+    return { success: false, error: `无效的阶段 ID: ${stageId}，应为 S1/S2/S3` };
+  }
+  if (!output || typeof output !== 'string') {
+    return { success: false, error: '产出物路径不能为空' };
+  }
+
+  // 加载工作流配置获取阶段名称
+  const configResult = loadWorkflowConfig();
+  if (!configResult.success) {
+    return configResult;
+  }
+
+  const stageConfig = configResult.config.stages[stageId];
+  if (!stageConfig) {
+    return { success: false, error: `工作流配置中未找到阶段: ${stageId}` };
+  }
+
+  // 更新阶段状态为 pending_review
+  const updateResult = updateStageStatus(sessionId, stageId, 'pending_review', output);
+  if (!updateResult.success) {
+    return updateResult;
+  }
+
+  return {
+    success: true,
+    checkpoint: {
+      stageId,
+      stageName: stageConfig.name,
+      outputPath: output,
+      status: 'pending_review'
+    }
+  };
+}
+
+/**
+ * 处理 Checkpoint 命令（y/e/n）
+ *
+ * 根据用户的审核命令执行对应操作：
+ * - y: 标记阶段为 completed，推进到下一阶段
+ * - e: 保持阶段为 in_progress，返回编辑指示
+ * - n: 重置阶段为 in_progress，清除产出物
+ *
+ * @param {string} sessionId - Session ID
+ * @param {string} stageId - 阶段 ID（S1/S2/S3）
+ * @param {string} command - 用户命令（y/e/n）
+ * @param {string} outputPath - 当前产出物路径
+ * @returns {{ success: boolean, result?: object, error?: string }}
+ */
+function processCheckpointCommand(sessionId, stageId, command, outputPath) {
+  // 参数校验
+  if (!sessionId || typeof sessionId !== 'string') {
+    return { success: false, error: 'Session ID 不能为空' };
+  }
+  if (!VALID_STAGE_IDS.includes(stageId)) {
+    return { success: false, error: `无效的阶段 ID: ${stageId}，应为 S1/S2/S3` };
+  }
+  if (!['y', 'e', 'n'].includes(command)) {
+    return { success: false, error: `无效的命令: ${command}，应为 y/e/n` };
+  }
+
+  if (command === 'y') {
+    // 确认通过：标记为 completed，推进到下一阶段
+    const updateResult = updateStageStatus(sessionId, stageId, 'completed', outputPath);
+    if (!updateResult.success) {
+      return updateResult;
+    }
+
+    const advanceResult = advanceToNextStage(sessionId, stageId);
+    if (!advanceResult.success) {
+      return advanceResult;
+    }
+
+    return {
+      success: true,
+      result: {
+        action: 'advance',
+        nextStage: advanceResult.nextStage
+      }
+    };
+  }
+
+  if (command === 'e') {
+    // 编辑修改：保持为 in_progress，等待用户反馈后重新生成
+    const updateResult = updateStageStatus(sessionId, stageId, 'in_progress', outputPath);
+    if (!updateResult.success) {
+      return updateResult;
+    }
+
+    return {
+      success: true,
+      result: {
+        action: 'edit'
+      }
+    };
+  }
+
+  // command === 'n'
+  // 放弃重新生成：重置为 in_progress，清除产出物
+  const updateResult = updateStageStatus(sessionId, stageId, 'in_progress', null);
+  if (!updateResult.success) {
+    return updateResult;
+  }
+
+  return {
+    success: true,
+    result: {
+      action: 'redo'
+    }
+  };
+}
+
+/**
+ * 推进到下一阶段
+ *
+ * 根据 workflow-config.json 中的 next_stage 配置，更新 session.json 的 current_stage。
+ * 如果当前阶段是最终阶段（next_stage 为 null），返回工作流完成指示。
+ *
+ * @param {string} sessionId - Session ID
+ * @param {string} currentStageId - 当前阶段 ID（S1/S2/S3）
+ * @returns {{ success: boolean, nextStage: string|null, isComplete: boolean, error?: string }}
+ */
+function advanceToNextStage(sessionId, currentStageId) {
+  // 参数校验
+  if (!sessionId || typeof sessionId !== 'string') {
+    return { success: false, nextStage: null, isComplete: false, error: 'Session ID 不能为空' };
+  }
+  if (!VALID_STAGE_IDS.includes(currentStageId)) {
+    return { success: false, nextStage: null, isComplete: false, error: `无效的阶段 ID: ${currentStageId}，应为 S1/S2/S3` };
+  }
+
+  // 加载工作流配置
+  const configResult = loadWorkflowConfig();
+  if (!configResult.success) {
+    return { success: false, nextStage: null, isComplete: false, error: configResult.error };
+  }
+
+  const stageConfig = configResult.config.stages[currentStageId];
+  if (!stageConfig) {
+    return { success: false, nextStage: null, isComplete: false, error: `工作流配置中未找到阶段: ${currentStageId}` };
+  }
+
+  const nextStage = stageConfig.next_stage;
+
+  // 如果没有下一阶段，工作流完成
+  if (!nextStage) {
+    return { success: true, nextStage: null, isComplete: true };
+  }
+
+  // 更新 session.json 的 current_stage
+  const sessionResult = resumeSession(sessionId);
+  if (!sessionResult.success) {
+    return { success: false, nextStage: null, isComplete: false, error: sessionResult.error };
+  }
+
+  const sessionData = sessionResult.session;
+  sessionData.current_stage = nextStage;
+  sessionData.updated_at = new Date().toISOString();
+
+  const writeResult = safeWriteSessionJson(sessionId, sessionData);
+  if (!writeResult.success) {
+    return { success: false, nextStage: null, isComplete: false, error: `更新 Session 失败: ${writeResult.error}` };
+  }
+  return { success: true, nextStage, isComplete: false };
+}
+
+/**
+ * 校验前置条件
+ *
+ * 检查指定阶段的所有前置阶段是否已完成。
+ * 根据 workflow-config.json 中的 prerequisites 配置进行校验。
+ *
+ * @param {string} sessionId - Session ID
+ * @param {string} stageId - 要校验的阶段 ID（S1/S2/S3）
+ * @returns {{ success: boolean, valid?: boolean, missingPrerequisites?: string[], error?: string }}
+ */
+function validatePrerequisites(sessionId, stageId) {
+  // 参数校验
+  if (!sessionId || typeof sessionId !== 'string') {
+    return { success: false, error: 'Session ID 不能为空' };
+  }
+  if (!VALID_STAGE_IDS.includes(stageId)) {
+    return { success: false, error: `无效的阶段 ID: ${stageId}，应为 S1/S2/S3` };
+  }
+
+  // 加载工作流配置
+  const configResult = loadWorkflowConfig();
+  if (!configResult.success) {
+    return { success: false, error: configResult.error };
+  }
+
+  const stageConfig = configResult.config.stages[stageId];
+  if (!stageConfig) {
+    return { success: false, error: `工作流配置中未找到阶段: ${stageId}` };
+  }
+
+  const prerequisites = stageConfig.prerequisites || [];
+
+  // 没有前置条件，直接通过
+  if (prerequisites.length === 0) {
+    return { success: true, valid: true, missingPrerequisites: [] };
+  }
+
+  // 恢复 Session 数据
+  const sessionResult = resumeSession(sessionId);
+  if (!sessionResult.success) {
+    return { success: false, error: sessionResult.error };
+  }
+
+  const stages = sessionResult.session.stages;
+  const missing = [];
+
+  for (const prereq of prerequisites) {
+    if (!stages[prereq] || stages[prereq].status !== 'completed') {
+      missing.push(prereq);
+    }
+  }
+
+  return {
+    success: true,
+    valid: missing.length === 0,
+    missingPrerequisites: missing
+  };
+}
+
+module.exports = {
+  handleCheckpoint,
+  processCheckpointCommand,
+  advanceToNextStage,
+  validatePrerequisites,
+  loadWorkflowConfig,
+  WORKFLOW_CONFIG_PATH
+};