a27e3b8e43
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
128 lines
5.6 KiB
Markdown
128 lines
5.6 KiB
Markdown
---
|
||
name: stitch-main-workflow
|
||
description: 本项目 Stitch 主技能/总编排：先完成 spec.md，再完成并确认 Stitch 设计，最后才允许生成 index.tsx；若 Stitch MCP 不可用则立即停止。
|
||
allowed-tools:
|
||
- "stitch*:*"
|
||
- "Read"
|
||
- "Write"
|
||
- "Bash"
|
||
- "web_fetch"
|
||
- "chrome*:*"
|
||
---
|
||
|
||
# Stitch 主流程（总编排）
|
||
|
||
本技能用于把 `design-md` / `stitch-loop` / `react-components` 组织为统一流程，强制执行：
|
||
|
||
1. 先完成 `spec.md`
|
||
2. 再完成并确认 Stitch 设计
|
||
3. 最后才允许创建或修改 `index.tsx`
|
||
|
||
## 目标与硬门槛（必须满足）
|
||
|
||
- **硬门槛 1**：未完成 Stitch 设计确认前，不允许创建或修改 `src/prototypes/<name>/index.tsx` 或 `src/components/<name>/index.tsx`。
|
||
- **硬门槛 2**：如果 Stitch MCP 不可用或调用失败，必须直接反馈并停止，不进入代码生成阶段。
|
||
|
||
## 环境自检（阻塞，失败即停）
|
||
|
||
开始主流程前，必须先做一次 Stitch MCP 探针调用，再决定是否继续：
|
||
|
||
- 可用探针示例：`list_projects` 或 `create_project`
|
||
- 探针成功：继续执行主流程
|
||
- 探针失败：输出以下固定反馈并停止
|
||
|
||
```text
|
||
⚠️ 当前环境未启用 Stitch MCP（无法调用 Stitch 工具），因此无法在 index.tsx 前完成 Stitch 设计。请启用 Stitch MCP 后重试。
|
||
```
|
||
|
||
## 主流程（顺序固定）
|
||
|
||
### 1) 准备目标路径
|
||
|
||
- 目标目录只能是：
|
||
- `src/prototypes/<name>/`
|
||
- `src/components/<name>/`
|
||
- `<name>` 只能使用小写字母、数字、连字符（kebab-case）
|
||
|
||
### 2) 先完成 `spec.md`（作为 Stitch prompt 合同）
|
||
|
||
- 按 `src/docs/templates/spec-template.md` 产出 `spec.md`（本技能不重复展开模板细节）
|
||
- `spec.md` 至少包含：
|
||
- 目标
|
||
- 模块 IA（树形结构）
|
||
- 关键文案语气
|
||
- 数据字段
|
||
- 响应式要点
|
||
|
||
### 3) 使用 Stitch 完成“设计”并确认
|
||
|
||
> **根目录 `DESIGN.md` 自动同步**：当用户在管理后台“设为默认主题”时，该主题的 `DESIGN.md` 会被自动同步到项目根目录（`/DESIGN.md`）。如果根目录存在此文件且用户没有特殊指定，应默认将其内容提交给 Stitch 作为设计规范进行生成。
|
||
|
||
1. （可选）如需风格统一，先用 `design-md` 从既有 Stitch screen 生成 `DESIGN.md`；或直接使用根目录已同步的 `DESIGN.md`
|
||
2. 使用 `generate_screen_from_text`，prompt 以 `spec.md` 为基础；若有 `DESIGN.md`（优先检查根目录），把设计系统相关内容并入 prompt
|
||
3. 使用 `get_screen` 获取最终候选 screen 的 `screenshot` 与 `htmlCode`
|
||
4. 如果结果不符合 `spec.md`，使用 `edit_screens` 迭代，直到满足
|
||
5. 设计确认最小产物：
|
||
- `screenshot`
|
||
- `html`
|
||
|
||
本地保存建议放在 `temp/` 或 `.drafts/`（两者都被 `.gitignore` 忽略）。
|
||
|
||
### 3.5) 交互与响应式提醒（按用户需求为准，不以 Stitch 产物为准）
|
||
|
||
Stitch 产物偏静态（HTML/CSS），经常会出现“截图对齐了，但交互/响应式并不等同于需求”的情况。这里不把检查做成硬门槛，但你必须遵守一个原则：
|
||
|
||
- **交互与响应式的验收基准永远来自用户需求 / `spec.md`**，不要把 Stitch 输出当成“需求本身”或“默认标准”。
|
||
|
||
按需做快速核对（仅在 `spec.md` 明确要求时）：
|
||
|
||
- **响应式**：如果 `spec.md` 要求断点/多端适配，就检查对应设备下是否塌陷、溢出、信息层级是否仍成立。
|
||
- **交互状态**：如果 `spec.md` 要求交互/可访问性，就核对 hover/focus/disabled 等状态与键盘可达性是否满足。
|
||
- **动态交互**：如果需求包含弹窗、抽屉、复杂表单校验、异步加载等 Stitch 难以表达的动态行为，应在 `spec.md` 明确标注为“代码阶段补齐”，避免误判“设计已完成”。
|
||
|
||
> 可选：若当前环境提供 Chrome MCP，可用它辅助做“缩放/断点切换 + 截图”验证，作为发现问题的手段即可。
|
||
|
||
### 4) 回写 `spec.md`（与 Stitch 最终设计对齐）
|
||
|
||
在 `spec.md` 中补齐以下字段：
|
||
|
||
- Stitch `projectId`
|
||
- Stitch `screenId`
|
||
- 截图本地保存路径
|
||
- HTML 本地保存路径
|
||
- 最终模块结构确认点
|
||
|
||
### 5) 最后生成 `index.tsx`（从 Stitch 设计落地）
|
||
|
||
本主流程只负责编排与 gate，具体转换实现参考：
|
||
|
||
- `skills/third-party/stitch-skills/react-components/SKILL.md`
|
||
|
||
本项目最小必须约束（仅保留以下）：
|
||
|
||
- `index.tsx` 顶部必须包含 `@name` 中文注释块（参考 `rules/development-guide.md`）
|
||
- 组件或页面必须 `export default`（参考 `vite-plugins/axhubComponentEnforcer.ts`）
|
||
- 使用 Tailwind 时，`style.css` 顶部必须包含 `@import "tailwindcss";`
|
||
|
||
### 6) 验收（必须跑完）
|
||
|
||
按目标类型执行验收脚本，结果必须为 `READY`：
|
||
|
||
```bash
|
||
node scripts/check-app-ready.mjs /prototypes/<name>
|
||
node scripts/check-app-ready.mjs /components/<name>
|
||
```
|
||
|
||
## 技能路由指南（触发条件 -> 使用技能 -> 产出）
|
||
|
||
| 触发条件 | 使用技能 | 产出 |
|
||
|---|---|---|
|
||
| 已有 Stitch 设计，或多页需要统一风格 | `design-md` | `DESIGN.md`，供后续 prompt 复用 |
|
||
| 需要多页迭代、baton 编排建站 | `stitch-loop` | 循环生成多页 screen 与任务接力 |
|
||
| 需要把 Stitch HTML/设计落地成 React 代码 | `react-components` | 组件/页面代码，并对齐 `@name`、默认导出、Tailwind 引入约束 |
|
||
|
||
## 说明与非目标
|
||
|
||
- 本技能不重复展开“必读规范”的详细说明，只做最小引用（默认已完成基础规范阅读）。
|
||
- 本技能不要求额外平台接口适配约束；只要求本项目最小代码约束与验收通过。
|