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>
242 lines
8.8 KiB
Markdown
242 lines
8.8 KiB
Markdown
---
|
||
name: local-axure-workflow
|
||
description: 处理本地导出的 Axure 原型资源并生成主题、数据模型与页面还原的流程规范；在需要基于 sitemap.json 与本地页面资源进行分析与还原时使用。
|
||
---
|
||
|
||
# 本地 Axure 资源处理规范
|
||
|
||
处理本地导出的 Axure 原型资源，包括主题提取、数据模型识别和页面还原。
|
||
|
||
## 核心能力
|
||
|
||
1. **主题提取与合并**：从多个页面提取 design tokens，合并生成统一主题文件
|
||
2. **数据模型识别**：从页面内容识别数据结构，生成数据库文件
|
||
3. **页面还原**：基于截图、主题、内容的精确还原
|
||
4. **MCP 补充**：可选使用 MCP 工具获取在线资源（如 sitemap.json 包含 projectUrl）
|
||
|
||
## 本地资源目录结构
|
||
|
||
```
|
||
<project-dir>/
|
||
├── sitemap.json # 站点地图
|
||
└── page-<index>-<name>/ # 页面目录
|
||
├── assets/
|
||
│ ├── images/ # 图片资源
|
||
│ └── fonts/ # 字体资源（如有）
|
||
├── theme.json # 设计令牌（Top10）
|
||
├── content.md # 页面内容（Markdown）
|
||
└── screenshot.png # 页面截图
|
||
```
|
||
|
||
### 关键文件说明
|
||
|
||
- **sitemap.json**：项目名称、页面列表、原型 URL（如有）
|
||
- **theme.json**：设计令牌（colors、typography、spacing、radius、shadow 等）
|
||
- **doms.toon**：DOM 节点映射（TOON 格式，仅在需要精确还原时使用）
|
||
- **styles.toon**：样式池（TOON 格式，仅在需要完整样式时使用）
|
||
- **content.md**：页面内容（Markdown 格式）
|
||
- **screenshot.png**：页面截图（还原主要依据）
|
||
|
||
## 工作流程
|
||
|
||
### 阶段 0：定位资源目录
|
||
|
||
用户未提供目录路径时，使用 `listDirectory` 工具查找 `temp/` 下的项目目录（通常在二级目录下包含 sitemap.json）。找到后读取 sitemap.json 获取项目名称，询问用户是否处理该项目；如不是则请求提供正确路径。
|
||
|
||
### 阶段 1：识别资源
|
||
|
||
验证目录结构（检查 sitemap.json），解析站点地图，明确用户需求（默认：提取主题、识别数据、生成文档）。
|
||
|
||
### 阶段 2：提取设计主题
|
||
|
||
选择 3-5 个核心页面（首页、登录页、主要功能页），读取各页面的 `theme.json` 并结合 `screenshot.png` 分析视觉风格，合并主题数据（颜色、字体、间距、圆角、阴影），总结设计语言并生成设计规范。
|
||
|
||
**输出**：`src/themes/<theme-key>/`（包含 `globals.css` 或 `designToken.json`（designToken.json 必须包含 `name` 字段）、`DESIGN.md`、`index.tsx`，符合 `theme-guide.md` 规范）
|
||
|
||
### 阶段 3：识别数据模型
|
||
|
||
识别数据密集型页面（列表页、表单页、详情页），读取 `content.md` 提取文本内容，从表格列名、表单标签、重复模式中识别数据结构，跨页面验证并合并字段。
|
||
|
||
**输出**：`src/database/<table-name>.json`
|
||
- 文件名使用英文（如 `users.json`）
|
||
- `tableName` 使用中文（如 "用户表"）
|
||
|
||
**数据表结构（强约束）**：每个文件必须是 JSON 对象（不要输出为纯数组），包含 `tableName` + `records`。
|
||
|
||
```json
|
||
{
|
||
"tableName": "表名（中文）",
|
||
"records": [
|
||
{ "id": 1, "字段1": "值1", "字段2": "值2" }
|
||
]
|
||
}
|
||
```
|
||
|
||
**最小一致性规则（用于减少错误）**：
|
||
- `records` 必须是数组；每条记录必须包含唯一的 `id`（允许 number 或 string，同表保持类型一致）。
|
||
- 字段名优先中文并与页面一致；同义字段不混用（如“手机号/手机号码”二选一）。
|
||
- 同字段同类型；图片字段用相对路径（如 `images/xxx.png`），不要 base64。
|
||
|
||
### 阶段 4：生成项目文档
|
||
|
||
生成站点地图文档（保持层级结构，页面名称可点击）和项目简介文档（基本信息、设计风格、数据模型概览）。
|
||
|
||
**输出**：`src/docs/`
|
||
|
||
## 页面还原指南
|
||
|
||
选择还原页面（用户指定或从站点地图选择 1-2 个核心页面）。
|
||
|
||
**核心方法**：看图 → 写代码 → 交付。
|
||
|
||
### 核心流程（必须跑完）
|
||
|
||
1. **确认前置条件**
|
||
- 确认模型支持视觉识别（不支持则立即告知用户）
|
||
- 确认可以直接读取图片内容（不需要转换，不支持则立即告知用户）
|
||
- 生成页面名称（规范：小写字母、数字、连字符）
|
||
|
||
2. **获取截图**
|
||
- 本地优先：使用页面目录下的 `screenshot.png`
|
||
- 若本地缺失且 `sitemap.json` 含 `projectUrl`，可使用 MCP 获取在线截图（仅在本地不足时）
|
||
|
||
3. **验证图片读取能力**
|
||
- 尝试读取 `screenshot.png`
|
||
- **如果无法直接读取本地图片**（工具不支持或返回错误），必须：
|
||
- 立即停止流程
|
||
- 告知用户："无法读取本地图片，请将 `[图片绝对路径]` 复制到对话框后提交"
|
||
- 等待用户提交图片后再继续
|
||
- 禁止假设或猜测图片内容
|
||
- 禁止通过 Base64 编码读取图片内容
|
||
|
||
4. **生成页面代码**
|
||
|
||
**辅助数据获取**（可选，生成仍以图片为主）：
|
||
- 主题：`theme.json`（校验样式）
|
||
- 文本：`content.md`（校验文案）
|
||
|
||
- 直接基于截图生成页面代码
|
||
- 在代码生成过程中内部完成：
|
||
- 识别布局结构（Header/Sidebar/Content 等）
|
||
- 识别组件（Button/Input/Table/Card 等）
|
||
- 提取样式（颜色、字体、间距、圆角、阴影等）
|
||
- 识别交互（点击、悬停、状态切换等）
|
||
|
||
**输出文件**：
|
||
- `src/prototypes/<page-name>/index.tsx`
|
||
- `src/prototypes/<page-name>/style.css`（必须包含 `@import "tailwindcss";`）
|
||
- `src/prototypes/<page-name>/components/`（根据需要）
|
||
|
||
**核心代码规范**（必须遵守）：
|
||
- 变量名必须是 `Component`，使用 `export default Component`
|
||
- 详细规范见 `rules/development-guide.md`
|
||
|
||
5. **验收页面还原**
|
||
- 运行验收命令：`node scripts/check-app-ready.mjs /prototypes/[页面名]`
|
||
- 提供预览 URL
|
||
- 确认页面基础功能正常（无编译错误、可正常访问）
|
||
|
||
6. **生成规格文档**
|
||
- 基于已验收通过的页面代码生成规格文档
|
||
- 输出文件：`src/prototypes/<page-name>/spec.md`
|
||
- 文档内容应包括：
|
||
- 页面结构说明
|
||
- 组件清单
|
||
- 样式规范（颜色、字体、间距等）
|
||
- 交互说明
|
||
- 数据需求（如有）
|
||
|
||
7. **最终交付**
|
||
- 告知用户页面还原和规格文档已完成
|
||
- 说明可进行二次生成（修复问题或优化重构）
|
||
|
||
### 还原策略（本地数据优先级）
|
||
|
||
1. **截图**（最高优先级）：视觉识别布局、颜色、间距。
|
||
2. **主题**：应用 `theme.json` 的 design tokens。
|
||
3. **内容**：用 `content.md` 校准文案（不影响布局与交互）。
|
||
4. **节点细节**：仅在需要精确结构/定位时使用 `doms.toon`。
|
||
5. **基础设计走查与修复**：按设计与前端规范检查明显问题并修复；若修复会改变原设计意图，先向用户确认。
|
||
|
||
### 默认目标与可选优化
|
||
|
||
- **默认目标**：在用户未提出额外要求时，尽量 1:1 像素级还原截图/原型的视觉与布局（不主动“改版”）。
|
||
- **可选优化**：如需同时做“优化设计/交互”，请在需求里明确说明；否则仅做还原与基础走查修复。
|
||
|
||
**输出**：符合 `rules/development-guide.md` 规范的页面组件
|
||
|
||
|
||
## MCP 工具补充
|
||
|
||
sitemap.json 包含 projectUrl 时，可使用本项目MCP 工具获取在线资源（本地资源优先，仅在不足或需要最新数据时使用）。
|
||
|
||
## 用户交互指南
|
||
|
||
### 目录验证失败
|
||
|
||
```
|
||
⚠️ 未找到有效的 Axure 资源目录。
|
||
请确认目录包含 sitemap.json 和页面目录。
|
||
```
|
||
|
||
### 需求确认
|
||
|
||
```
|
||
✓ 已识别资源目录，共 [X] 个页面。
|
||
|
||
默认方案：
|
||
- 从核心页面提取设计主题并生成设计规范文档
|
||
- 识别数据模型
|
||
- 生成项目文档
|
||
|
||
回复"接受"按默认方案执行，或告诉我您的具体需求。
|
||
```
|
||
|
||
### 进度通知
|
||
|
||
```
|
||
正在处理...
|
||
✓ 已解析站点地图
|
||
✓ 已提取主题数据
|
||
⏳ 正在分析数据模型...
|
||
```
|
||
|
||
### 完成总结
|
||
|
||
```
|
||
✅ 已完成！
|
||
|
||
生成的资产：
|
||
- 设计主题：src/themes/<theme-key>/
|
||
- 设计规范文档：src/themes/<theme-key>/DESIGN.md
|
||
- 数据模型：src/database/
|
||
- 项目文档：src/docs/
|
||
|
||
后续建议：
|
||
💡 我还可以为您：
|
||
- 还原页面：告诉我需要还原的页面名称
|
||
- 生成业务文档：领域模型、业务流程等
|
||
|
||
需要吗？
|
||
```
|
||
|
||
### 关键原则
|
||
|
||
- 主动查找 temp 目录下的最新资源
|
||
- 主动确认重要操作
|
||
- 及时反馈进度
|
||
- 清晰总结成果
|
||
- 提供选项而非强制
|
||
- 友好处理错误
|
||
- 引导后续操作
|
||
|
||
## 注意事项
|
||
|
||
- TOON 数据量大，仅在必要时解析
|
||
- 主题提取使用 3-5 个页面，数据模型需跨页面验证
|
||
- 页面还原以截图为主要依据
|
||
|
||
## 参考
|
||
|
||
`theme-guide.md` | `development-guide.md`
|