From e64b4100c245b1d8aa76356fe8eef2b11c82a158 Mon Sep 17 00:00:00 2001 From: yuzhantian <2205129388@qq.com> Date: Mon, 1 Jun 2026 10:21:08 +0800 Subject: [PATCH] ADD file via upload --- usage-guide.md | 400 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 400 insertions(+) create mode 100644 usage-guide.md diff --git a/usage-guide.md b/usage-guide.md new file mode 100644 index 0000000..31b97c7 --- /dev/null +++ b/usage-guide.md @@ -0,0 +1,400 @@ +# SuperDS 网站生成流程使用指南 + +## 概述 + +本文档描述如何使用 SuperDS 平台从角色切换开始，到最终生成并调优网站源码的完整流程。整个流程分为 **6 个主步骤**（其中第 6 步含手动/自动两个并行分支），对应前端代码中的具体组件和数据流。 + +--- + +## 流程图 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 第 1 步：进入项目，切换角色到"设计师" │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 路由: /projects/:orgId/:repoName │ │ +│ │ 组件: RoleSwitcher (左侧工具栏) │ │ +│ │ 状态: EditorContext.currentRole = "designer" │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ 第 2 步：点击「原型库」检查原型文件 │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 组件: PrototypeLibrary (左侧工具栏 → src/pages/design/ │ │ +│ │ _components/leftToolbar/PrototypeLibrary.tsx) │ │ +│ │ 数据源: API 返回的 wireframes (来自 PM 阶段 WireframeEditor) │ │ +│ │ 状态: EditorContext.prototypes[] │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ 有原型文件？ 无原型文件？ │ +│ │ │ │ +│ ●──→ 继续第 3 步 切换角色到"产品经理" │ +│ 路由: /projects/:orgId/:repoName/product +│ 组件: ProductPage +│ 流程: MindMap → PageFlow → Wireframe +│ 完成后导出原型 → 切回设计师 +│ ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ 第 3 步：在 AI 助手输入 /web-design-summary + 简要描述 │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 组件: AIAssistant + InputArea + SlashCommandPanel │ │ +│ │ 文件: │ │ +│ │ - src/pages/design/_components/ai/AIAssistant.tsx │ │ +│ │ - src/pages/design/_components/ai/InputArea.tsx │ │ +│ │ - src/pages/design/_components/ai/SlashCommandPanel.tsx │ │ +│ │ COMMAND_LIST: aiUtils.ts (line 16-19) │ │ +│ │ │ │ +│ │ 示例输入: /web-design-summary 帮我生成一个宝马汽车的官网 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +┌─────────────────────────────────────────────────────────────────────┐ +│ 第 4 步：与 AI 对话获取设计宣言 + 设计模板列表 │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 技能文件: web-design-summary-SKILL.md │ │ +│ │ 位置: src/assets/skill/web-design-summary-SKILL.md │ │ +│ │ 技能解析: skillLoader.ts → resolveCommandTags() │ │ +│ │ │ │ +│ │ AI 执行 4 维度分析: │ │ +│ │ ① 行业分析 (Industry Analysis) │ │ +│ │ ② 风格分析 (Style Analysis) │ │ +│ │ ③ 氛围分析 (Atmosphere Analysis) │ │ +│ │ ④ 布局分析 (Layout Analysis) │ │ +│ │ │ │ +│ │ 输出: │ │ +│ │ • 设计宣言 (Design Declaration / web-design-summary) │ │ +│ │ • 设计模板列表 (从 workspace /web/ 目录搜索模板文件) │ │ +│ │ │ │ +│ │ 用户动作: 回答 AI 可能的追问，确认后获得模板列表 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +┌─────────────────────────────────────────────────────────────────────┐ +│ 第 5 步：调用 /web-creator 生成网页源码 │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 组件: AIAssistant + InputArea │ │ +│ │ 技能文件: web-creator-SKILL.md │ │ +│ │ 位置: src/assets/skill/web-creator-SKILL.md │ │ +│ │ 技能解析: skillLoader.ts → resolveCommandTags() │ │ +│ │ │ │ +│ │ 输入参数 (3 个): │ │ +│ │ ① 设计渲染 (来自第 4 步的设计宣言) │ │ +│ │ ② 设计模板 (第 4 步模板列表中用户选中的模板文件路径) │ │ +│ │ ③ 原型文件 (第 2 步 PrototypeLibrary 中选中的 wireframe) │ │ +│ │ │ │ +│ │ 处理流程: │ │ +│ │ ① 根据模板 path 读取设计规格 (颜色、字体等 via design.md) │ │ +│ │ ② 基于设计规格 + 原型结构生成网页源码 │ │ +│ │ ③ 输出到 output/ 目录 │ │ +│ │ │ │ +│ │ 输出: 完整网页源文件 (HTML/CSS/JS) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +┌─────────────────────────────────────────────────────────────────────┐ +│ 第 6 步：网站源码调优 (两个并行路径可交替使用) │ +│ │ +│ ┌─────────────────────┐ ┌─────────────────────┐ │ +│ │ 6.1 手动 CSS 修改 │ │ 6.2 AI 自动修改 │ │ +│ │ │ │ │ │ +│ │ 组件: CSSEditor │ │ 组件: NoteEditor │ │ +│ │ 文件: CSSEditor.tsx │ │ 文件: NoteEditor.tsx│ │ +│ │ │ │ │ │ +│ │ 操作流程: │ │ 操作流程: │ │ +│ │ ① Canvas 中选中 │ │ ① Canvas 中选中 │ │ +│ │ 页面元素 │ │ 页面元素 │ │ +│ │ ② 左侧 CSSEditor │ │ ② 左侧 NoteEditor │ │ +│ │ 面板显示该元素 │ │ 面板展开 │ │ +│ │ 的 CSS 属性 │ │ ③ 编写标注/修改指令 │ │ +│ │ ③ 调整 CSS 属性值 │ │ (如：按钮加宽、 │ │ +│ │ ④ 保存 → Canvas │ │ 标题改为粗体等) │ │ +│ │ 实时渲染 │ │ ④ 发送指令 → │ │ +│ │ │ │ AIAssistant 接收 │ │ +│ │ │ │ 结合 notes[] 状态 │ │ +│ │ │ │ 调用 AI 重新生成 │ │ +│ │ │ │ 对应模块的源码 │ │ +│ └─────────────────────┘ └─────────────────────┘ │ +│ │ │ │ +│ └───────────┬─────────────────────┘ │ +│ │ │ +│ ▼ │ +│ 完成调优 → 导出/部署网页 │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 详细步骤说明 + +### 第 1 步：角色切换 + +**目标**：将当前用户角色设置为"设计师 (designer)"以进入设计工作区。 + +| 项目 | 说明 | +|------|------| +| **组件** | `RoleSwitcher` | +| **文件路径** | `frontend/src/pages/design/_components/leftToolbar/RoleSwitcher.tsx` | +| **状态存储** | `EditorContext.currentRole` | +| **支持角色** | `pm` (产品经理) / `designer` (设计师) / `developer` (开发者) / `tester` (测试员) | +| **路由映射** | `designer` → `/projects/:orgId/:repoName` (DesignPage) / `pm` → `/projects/:orgId/:repoName/product` (ProductPage) | + +**操作流程**： +1. 进入项目页面后，在左侧工具栏找到角色切换器 +2. 选择 "设计师" 角色 +3. 页面自动跳转至设计工作区 (DesignPage) + +--- + +### 第 2 步：原型库检查 + +**目标**：确认 PM 阶段是否已输出 wireframe（原型文件），作为后续网页生成的基础素材。 + +| 项目 | 说明 | +|------|------| +| **组件** | `PrototypeLibrary` | +| **文件路径** | `frontend/src/pages/design/_components/leftToolbar/PrototypeLibrary.tsx` | +| **数据源** | 通过 API 获取 wireframes（来自 PM 阶段的 WireframeEditor 导出） | + +**操作流程（有原型文件）**： +1. 点击左侧工具栏的「原型库」按钮 +2. 查看原型文件列表 +3. 选择一个原型文件作为参考 +4. 继续进行第 3 步 + +**操作流程（无原型文件 — 需要先做 PM 阶段）**： +1. 原型库为空时，切换角色到"产品经理" +2. 路由自动跳转至 `/projects/:orgId/:repoName/product` (ProductPage) +3. 依次完成 PM 阶段 3 个子流程： + - **MindMap**：绘制思维导图，确定产品功能结构 + - **PageFlow**：设计页面流转关系（页面流程图） + - **Wireframe**：绘制线框原型 +4. 导出 wireframe 后，切回"设计师"角色，重复本步骤 + +--- + +### 第 3 步：输入设计指令 + +**目标**：通过 AI 助手启动设计分析流程。 + +| 项目 | 说明 | +|------|------| +| **组件** | `AIAssistant` + `InputArea` + `SlashCommandPanel` | +| **文件路径** | `frontend/src/pages/design/_components/ai/AIAssistant.tsx` | +| **命令定义** | `COMMAND_LIST` → `frontend/src/utils/aiUtils.ts` (第 16-19 行) | + +**可用命令**： +| 命令 | 描述 | +|------|------| +| `/web-design-summary` | 生成网页设计宣言并检索相似模板 | +| `/web-creator` | 根据需求文档生成网页源码 | + +**操作流程**： +1. 点击设计工作区右侧的 AI 助手图标打开 AI 侧边栏 +2. 在输入框中输入 `/` 触发命令面板 (`SlashCommandPanel`) +3. 选择 `/web-design-summary` +4. 输入网站简要描述 + +**示例输入**： +``` +/web-design-summary 帮我生成一个宝马汽车的官网 +``` + +**技术细节**： +- `resolveCommandTags()` (`skillLoader.ts`) 在发送消息前将 `/web-design-summary` 替换为技能文件 `web-design-summary-SKILL.md` 的内容 +- 技能文件定义了 4 维度分析框架 +- 消息通过 `aiApi.sendMessage()` 发送给后端 AI，流式返回 + +--- + +### 第 4 步：获取设计宣言与模板列表 + +**目标**：与 AI 对话完成设计分析，获得可执行的设计方案。 + +| 项目 | 说明 | +|------|------| +| **技能文件** | `web-design-summary-SKILL.md` | +| **文件路径** | `frontend/src/assets/skill/web-design-summary-SKILL.md` | +| **分析维度** | 行业分析、风格分析、氛围分析、布局分析 | +| **模板搜索** | 从 workspace `/web/` 目录搜索模板文件 | + +**AI 执行流程**： + +``` +┌──────────────────────────────────────────────┐ +│ 4 维度分析 │ +│ │ +│ 行业分析 → 目标行业特征、竞品分析 │ +│ 风格分析 → 视觉风格倾向、品牌调性 │ +│ 氛围分析 → 情感氛围、用户体验基调 │ +│ 布局分析 → 页面布局模式、信息层级结构 │ +│ │ │ +│ ▼ │ +│ 输出 1: 设计宣言 (Design Declaration) │ +│ → web-design-summary 文件 │ +│ 输出 2: 模板列表 │ +│ → 从 workspace/web/ 目录匹配模板文件 │ +│ │ +│ AI 可能追问: │ +│ ・品牌主色调是否有偏好？ │ +│ ・目标用户群体？ │ +│ ・参考网站风格？ │ +│ │ +│ 用户回答后 → 获得最终模板列表 │ +└──────────────────────────────────────────────┘ +``` + +**用户动作**： +1. 查看 AI 返回的设计分析结果 +2. 回答 AI 可能的追问以细化需求 +3. 确认获得： + - **设计宣言**：完整的网页设计方案描述 + - **模板列表**：匹配的 wireframe/template 文件路径列表 +4. 从模板列表中选择一个模板（记录其文件路径） + +--- + +### 第 5 步：生成网页源码 + +**目标**：结合设计宣言、选中模板、原型文件，通过 AI 自动生成完整网页源码。 + +| 项目 | 说明 | +|------|------| +| **技能文件** | `web-creator-SKILL.md` | +| **文件路径** | `frontend/src/assets/skill/web-creator-SKILL.md` | +| **输入参数** | 设计宣言路径 + 模板文件路径 (来自第 4 步) + 原型文件路径 (来自第 2 步) | + +**操作流程**： +1. 在 AI 助手输入框输入 `/web-creator` +2. 系统自动替换为技能文件内容（`resolveCommandTags()`） +3. 补充输入 3 个参数路径： + - **设计渲染 (设计宣言路径)**：第 4 步生成的 `web-design-summary` 文件路径 + - **设计模板 (选中的)**：第 4 步模板列表中选择的模板文件路径 + - **原型文件**：第 2 步 PrototypeLibrary 中选中的 wireframe 路径 +4. AI 执行处理： + - 根据模板路径读取对应的 `design.md`（颜色、字体等设计规范） + - 基于设计规范 + 原型结构生成完整网页源码 + - 输出到 `output/` 目录 + +**技术细节**： +- 技能文件定义了代码生成规范和输出格式 +- 生成的文件可通过 Canvas 区域预览 +- 状态 `hasEditChange` (EditorContext) 标记源码变更 + +--- + +### 第 6 步：网站源码调优 + +**目标**：对 AI 生成的网页源码进行精细化调优。提供手动和自动两个并行路径，可交替使用。 + +#### 6.1 手动 CSS 修改 + +| 项目 | 说明 | +|------|------| +| **组件** | `CSSEditor` | +| **文件路径** | `frontend/src/pages/design/_components/leftToolbar/CSSEditor.tsx` | + +**操作流程**： +1. 在 Canvas 区域点击选中需要修改的页面元素 +2. 左侧工具栏自动切换至「CSS 编辑器」标签 +3. CSSEditor 面板展示该元素的所有 CSS 属性 +4. 直接修改属性值（颜色、尺寸、间距、字体等） +5. 保存修改 → Canvas 实时渲染更新 + +**适用场景**： +- 精确控制单个元素的样式细节 +- 需要微调间距、颜色、边框等视觉属性 +- 对 AI 生成结果做局部调整 + +--- + +#### 6.2 AI 自动修改 + +| 项目 | 说明 | +|------|------| +| **组件** | `NoteEditor` | +| **文件路径** | `frontend/src/pages/design/_components/leftToolbar/NoteEditor.tsx` | +| **状态** | 修改指令存储在 `EditorContext.notes[]` 中 | + +**操作流程**： +1. 在 Canvas 区域选中需要修改的元素或元素组合 +2. 左侧工具栏切换至「标注编辑器」标签 +3. 在 NoteEditor 中编写修改指令，例如： + - "将按钮宽度加宽到 200px" + - "标题改为粗体、加大字号" + - "增加 section 间距至 60px" +4. 发送指令 → AIAssistant 接收请求 +5. AI 结合当前 `notes[]` 状态和选中元素上下文，重新生成对应模块的源码 +6. 查看 AI 返回的修改结果 + +**适用场景**： +- 需要结构性修改（增加/删除元素、改变布局） +- 批量修改多个元素的统一样式 +- 复杂的设计意图描述 + +--- + +## 组件依赖关系总览 + +``` +┌─────────────────────────────────────────────────┐ +│ DesignPage (主页面) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │ +│ │Left │ │ Canvas │ │ AI │ │ +│ │Toolbar │ │ Area │ │ Assistant │ │ +│ │ │ │ │ │ │ │ +│ │Role │ │ 网页预览 │ │ 聊天界面 │ │ +│ │Switcher │ │ │ │ │ │ +│ │ │ │ │ │ InputArea │ │ +│ │Prototype │ │ │ │ │ │ +│ │Library │ │ │ │ SlashCmd Pn │ │ +│ │ │ │ │ │ │ │ +│ │Note │ │ │ │ Model │ │ +│ │Editor │ │ │ │ Selector │ │ +│ │ │ │ │ │ │ │ +│ │CSS │ │ │ │ SessionMgr │ │ +│ │Editor │ │ │ │ │ │ +│ └──────────┘ └──────────┘ └─────────────┘ │ +│ │ +│ ┌──────────────────────┐ │ +│ │ PageListView │ │ +│ │ (页面/文件列表管理) │ │ +│ └──────────────────────┘ │ +└─────────────────────────────────────────────────┘ + +状态共享层: EditorContext + ├── currentRole (当前角色: pm/designer/dev/tester) + ├── selectedElement (Canvas 中选中的元素) + ├── notes[] (标注编辑记录) + └── hasEditChange (源码变更标记) +``` + +--- + +## 路由与页面映射 + +| 路由 | 页面 | 阶段 | 核心功能 | +|------|------|------|----------| +| `/projects/:orgId/:repoName` | `DesignPage` | 设计师阶段 | 完整的网站设计与调优工作区 | +| `/projects/:orgId/:repoName/product` | `ProductPage` | 产品经理阶段 | 思维导图 + 页面流程 + 线框原型 | + +--- + +## 常见问题 + +**Q：模板列表为空怎么办？** +A：在 PM 阶段完成 Wireframe 编辑后导出原型文件，模板列表会自动出现。 + +**Q：设计宣言与模板列表在哪里查看？** +A：在 AI 对话记录中查看，模板列表中的每条记录包含文件路径，可点击导航到 PrototypeLibrary 中查看对应原型。 + +**Q：CSS 编辑器修改和 AI 修改能同时使用吗？** +A：可以。两种修改方式共享同一个 Canvas 预览和 EditorContext 状态。先使用哪种方式不影响另一种的使用。 + +**Q：生成失败怎么办？** +A：可回到之前的步骤重新调整输入参数。例如：重新选择模板、补充设计描述、或在 NoteEditor 中给出更精确的修改指令。