Skill: Product Designer

基于 Phase 1 需求文档中的场景，细化交互流程和功能规格，生成产品原型。原型形式根据产品类型自动适配（Web/CLI/Library 等）。场景编号与 Phase 1 保持一致。

触发条件

• 用户要求写产品设计文档或功能规格
• 用户要求画原型或设计交互
• 用户提到 "Phase 2"、"产品设计层"、"WHAT"
• 已有需求文档（含场景定义），需要开始设计解决方案

核心能力

1. 识别产品类型，确定对应的原型形式（见下方产品类型与原型策略）
2. 设计信息架构（页面结构 / 命令结构 / API 结构）
3. 以 Phase 1 场景为骨架，细化交互流程和功能规格
4. 为每个场景补充交互级 GIVEN/WHEN/THEN 验收条件
5. 生成适合产品类型的原型
6. 当场景粒度过大时，拆分为子场景（S01.1, S01.2）

产品类型与原型策略

执行本 Skill 前，先判断产品类型（可从需求文档的约束与边界、logos-project.yaml 的 tech_stack 推断），选择对应的原型形式：

产品类型	典型特征	原型形式	交互规格重点
Web 应用	有 UI 页面、用户登录	HTML 可交互页面	页面流转、表单校验、状态变化
CLI 工具	终端命令、无 GUI	终端交互示例（命令 + 输出模拟）	命令格式、参数设计、输出格式、错误提示
AI Skills / 对话式产品	用户通过自然语言与 AI 交互	对话流程图 + 示例对话脚本	对话步骤、AI 提问策略、产出物格式
库 / SDK	被其他程序调用	API 使用示例（代码片段）	公开接口、参数设计、返回值、错误码
移动应用	手机端 UI	HTML 页面（移动视口）	手势交互、导航模式、离线状态
桌面应用	本地安装、含 GUI、独立窗口（Electron / Tauri / SwiftUI / Jetpack Compose / Qt / WPF / GTK 等）	HTML 模拟桌面布局（含菜单栏 / 工具栏 / 状态栏）或对应栈风格指南	窗口管理、菜单栏 / 上下文菜单、快捷键、系统托盘、多窗口协作、文件系统交互
混合型	多种交付物组合	按交付物分别选择对应形式	各交付物间的交互衔接

执行步骤

Step 1: 读取需求文档，识别产品类型

读取 Phase 1 需求文档，提取：

• 场景清单（S01, S02...）及优先级
• 约束与边界 → 判断产品类型
• logos-project.yaml 的 tech_stack → 确认技术形态

场景粒度检查：在阅读场景列表时，留意场景是否实际上是单个 CRUD 操作（如"创建任务"、"获取任务列表"、"更新任务"、"删除任务"作为 4 个独立场景）。如果发现此模式，建议回到 Phase 1 按业务目标重新组织场景，再进行产品设计。为 CRUD 级别的"场景"设计交互规格只会产出浅层规格，无法反映真实的用户工作流。

输出产品类型判断和原型策略选择理由。

Step 2: 设计信息架构

根据产品类型设计不同层面的架构：

• Web 应用：页面结构、导航层级、路由设计
• CLI 工具：命令树结构、子命令层级、全局选项
• AI Skills：Skill 触发关系、对话步骤编排、产出物依赖链
• 库 / SDK：模块结构、公开 API 分组
• 桌面应用：窗口结构、菜单 / 快捷键体系、IPC 设计（主进程↔渲染进程 / 各 native 层）、本地存储与文件系统

Step 3: 逐场景细化交互规格

为每个场景定义完整的交互细节（格式见下方示例）。不同产品类型侧重不同的交互维度。

Step 4: 补充交互级验收条件

在 Phase 1 的 GIVEN/WHEN/THEN 基础上，细化到交互元素级别。

Step 5: 生成原型

Step 5a（仅 GUI 类产品）：调用 ui-ux-pro-max 获取设计系统

适用条件：凡产品交付物中包含图形用户界面（GUI）的产品类型——

• ✅ 触发：Web 应用 / 移动应用 / 桌面应用（Electron / Tauri / SwiftUI / Jetpack Compose / Qt / WPF / GTK 等）/ 混合型中含 GUI 交付物的部分
• ❌ 不触发：纯 CLI 工具 / Library / AI Skills / 纯 API 服务 等无 GUI 交付物的产品

执行步骤：

1. 从 Phase 1 需求文档提取关键词：产品类型（SaaS / e-commerce / dashboard / portfolio 等）+ 行业 + 风格倾向
2. 调用 ui-ux-pro-max：

   python3 logos/skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <style_keywords>" --design-system -p "<项目名>"
   

3. 消费输出：风格 + 调色板 + 字体配对 + 登陆页模式 + 反模式清单作为 Step 5 生成原型的视觉基础
   • Web 应用：用 HTML 实现风格指南
   • 桌面 / 移动应用：按对应技术栈输出风格指南（Electron / Tauri 直接复用 react / shadcn / html-tailwind 数据；SwiftUI / Jetpack Compose / Flutter 直接命中对应 stack 数据；其余 native 栈使用 stack 无关的风格/配色/字体推荐）

降级路径：

检测不到 python3 时跳过本步并提示用户「检测到 ui-ux-pro-max 依赖的 Python 3 不可用。原型将使用通用风格生成。如需专业级设计系统建议，请安装 Python 3 后重试。」原型用通用风格继续生成，不阻塞 Step 5。

Step 5a 补充：UI/UX 子流程可被 change-writer 在提案阶段复用（proposal-ui-ux-first）

Step 5a 的 UI/UX 子流程（调用 ui-ux-pro-max 设计系统 → 落地 design-system.json 令牌 → 以设计系统为基础产出 page-design 原型）不仅用于 Phase 2 全新产品设计——对已 launched 的 GUI 产品项目，同一子流程可被 change-writer 在变更提案阶段（plan 节点、plan-exit 门前）复用，把 UI/UX 确认从「批准后自动实现期间」前移到「批准提案」门。

复用点（前移，非仅 Phase 2）：

• 谁调用：变更走 Delta 流程时，由 driver 在 plan 节点派发的 change-writer（producer）复用本 Step 5a 子流程，而非 Phase 2 的 product-designer 主流程。触发与产出规则见 skills/change-writer/SKILL.md 的「Step 6 补充二：GUI 项目提案阶段前置 UI/UX 原型」。
• 何时调用：提案阶段（plan-exit 门前），当 product_type ∈ GUI 且本次 ui_impact:true 时。区别于 Phase 2 在完整需求就绪后一次性产出全部页面设计。

产物与 Step 5a 完全一致（复用即产出一致）：

1. 原型：以 ui-ux-pro-max 设计系统为视觉基础产出的裸 HTML 原型（关键几屏 + 各交互状态）。提案阶段复用时，原型作为 page-design delta 写入 logos/changes/<slug>/deltas/prd/2-product-design/2-page-design/*.html（Phase 2 则直接写 logos/resources/prd/2-product-design/2-page-design/）。
2. design-system.json：ui-ux-pro-max 令牌产物，用于追溯「原型出自设计系统」。提案阶段复用时留存于提案目录 logos/changes/<slug>/ 作审计产物。仅 design_system_mode: generated（走了设计系统）时产出并要求；fallback（降级）时不产 / 不要求 design-system.json、禁伪造令牌（详见下「降级路径」）。

两种 design_system_mode（机器可读，提案阶段复用时写入声明段）：

• generated：python3 可用、正常走 ui-ux-pro-max 设计系统 → 产出 design-system.json 令牌。
• fallback：降级 → 声明段填 design_system_fallback_reason（如「Python3 缺失」），不产 / 不要求 design-system.json、禁伪造令牌。

降级路径一致：检测不到 python3 时，两处（Phase 2 主流程 / 提案阶段复用）均以通用风格兜底、置 design_system_mode: fallback 并填 design_system_fallback_reason（不产令牌），不阻塞、不报错。字段与对账契约详见 skills/change-writer/SKILL.md 的「Step 6 补充二」④/⑥。

适用/不适用一致：仅 GUI 类产品触发（Web / 移动 / 桌面 / 含 GUI 交付物的混合型）；纯 CLI / Library / AI Skills / 纯 API 服务不触发。

Step 5b：根据产品类型生成对应形式的原型

根据产品类型生成对应形式的原型（见示例）。GUI 类产品在 Step 5a 已获取设计系统的基础上落地视觉/交互；非 GUI 类产品直接按产品类型选择对应原型形式。

Step 6: 输出产品设计文档

按场景组织，每个场景包含交互规格 + 对应原型。

场景展开示例

Web 应用示例

### S01: 邮箱注册 — 交互规格

**涉及页面**：注册页、邮件验证等待页、验证成功页

**交互流程**：
1. 用户在首页点击「注册」→ 跳转注册页
2. 注册页包含：邮箱输入框、密码输入框、确认密码输入框、注册按钮
3. 实时校验：邮箱格式、密码长度 ≥ 8、两次密码一致
4. 提交成功 → 跳转邮件验证等待页

#### 验收条件（交互级）

##### 正常：成功注册
- **GIVEN** 用户在注册页面，所有字段为空
- **WHEN** 用户填写 test@example.com、密码 "Pass1234"、确认密码 "Pass1234"，点击「注册」按钮
- **THEN** 「注册」按钮变为 loading 状态，1-3 秒后跳转到邮件验证等待页

原型：01-register-prototype.html（可交互的 HTML 页面）

CLI 工具示例

### S01: CLI 初始化项目 — 交互规格

**命令格式**：`openlogos init [name]`

**参数设计**：
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| name | string | 否 | 当前目录名 | 项目名称 |

**交互流程**：
1. 用户在终端运行 `openlogos init my-project`
2. CLI 检查 `logos/logos.config.json` 是否已存在
3. 不存在 → 创建目录结构，逐行输出创建的文件清单
4. 存在 → 输出错误提示并退出

**终端输出模拟**：

正常路径：
```
$ openlogos init my-project

Creating OpenLogos project structure...

  ✓ logos/resources/prd/1-product-requirements/
  ✓ logos/resources/prd/2-product-design/
  ✓ logos/resources/prd/3-technical-plan/1-architecture/
  ✓ logos/resources/prd/3-technical-plan/2-scenario-implementation/
  ✓ logos/resources/api/
  ✓ logos/resources/database/
  ✓ logos/resources/scenario/
  ✓ logos/changes/
  ✓ logos/logos.config.json
  ✓ logos/logos-project.yaml
  ✓ AGENTS.md
  ✓ CLAUDE.md

Project initialized. Next steps:
  1. Edit logos/logos.config.json to configure your project
  2. Start with Phase 1: tell AI "帮我写需求文档"
  3. Run `openlogos status` to check progress at any time
```

错误路径：
```
$ openlogos init
Error: logos/logos.config.json already exists in current directory.
This directory has already been initialized as an OpenLogos project.
```

#### 验收条件（交互级）

##### 正常：全新项目
- **GIVEN** 当前目录无 `logos/logos.config.json`
- **WHEN** 用户运行 `openlogos init my-project`
- **THEN** 终端逐行输出创建的 12 个文件/目录，最后输出 "Next steps" 引导，退出码为 0

##### 异常：已初始化
- **GIVEN** 当前目录已存在 `logos/logos.config.json`
- **WHEN** 用户运行 `openlogos init`
- **THEN** 终端输出红色错误提示，不创建任何文件，退出码为 1

原型：01-init-terminal.md（终端交互模拟文档）

AI Skills / 对话式产品示例

### S02: AI 辅助写需求文档 — 交互规格

**触发方式**：用户在 AI 编程工具中输入自然语言

**对话流程**：
1. 用户说「帮我写需求文档」
2. AI 读取 prd-writer Skill
3. AI 追问：「请先告诉我你的产品定位——这个产品要解决什么人的什么问题？」
4. 用户描述产品想法
5. AI 追问：「核心用户是谁？能描述一个具体的人吗？」
6. 用户描述用户画像
7. AI 汇总信息，开始输出结构化需求文档
8. AI 输出后询问：「需求文档初稿已生成，请 review 后告诉我需要修改的地方」

**AI 行为规范**：
- 追问不超过 3 轮，每轮聚焦 1 个关键信息
- 如果用户在第一条消息中提供了充分信息，跳过追问直接输出
- 输出的文档格式严格遵循 prd-writer 规范

#### 验收条件（交互级）

##### 正常：信息充分
- **GIVEN** 用户在第一条消息中描述了产品定位、目标用户和核心痛点
- **WHEN** AI 开始执行 prd-writer Skill
- **THEN** AI 直接输出结构化需求文档，不进行追问

##### 正常：信息不足
- **GIVEN** 用户只说了「帮我写需求文档」
- **WHEN** AI 开始执行 prd-writer Skill
- **THEN** AI 追问产品定位（第 1 轮）→ 用户回答 → AI 追问目标用户（第 2 轮）→ 用户回答 → AI 输出需求文档

原型：02-prd-writer-dialogue.md（对话流程脚本）

输出规范

• 功能规格：logos/resources/prd/2-product-design/1-feature-specs/
• 原型：logos/resources/prd/2-product-design/2-page-design/
• 设计文档与原型成对出现：<module>-{序号}-{名称}-design.md + <module>-{序号}-{名称}-prototype.{ext}（从 logos-project.yaml 的 modules[] 读取当前模块，默认为 core）
  • Web 应用：.html
  • CLI 工具：-terminal.md（终端交互模拟）
  • AI Skills：-dialogue.md（对话流程脚本）
  • 库 / SDK：-api-examples.md（使用示例）
• 场景编号必须与 Phase 1 一致，如需拆分使用子编号（S01.1）

实践经验

• 场景是骨架：不要按"页面"或"命令"组织文档，按"场景"组织
• Phase 1 的验收条件是输入：Phase 2 不是重写验收条件，而是在 Phase 1 的基础上细化到交互元素级别
• 子场景拆分要有理由：只在 Phase 1 的场景确实包含两条独立的交互路径时才拆分
• CLI 的"原型"是终端输出模拟：不需要 HTML，用代码块模拟终端的输入输出即可
• AI Skills 的"原型"是对话脚本：模拟用户和 AI 的多轮对话，明确 AI 在每个节点的行为
• 混合型产品按场景分：同一个产品中 CLI 场景用终端模拟、Web 场景用 HTML，不需要统一形式
• Markdown 嵌套代码块：当文档内容本身包含 ``` 代码围栏时（如对话脚本中 AI 输出代码片段、终端模拟中嵌套命令输出），外层围栏必须使用 4 个反引号（````），内层保持 3 个。这是 Markdown 标准语法，避免解析器误判层级导致格式错乱。上方 CLI 工具示例已体现此规则

推荐提示词

以下提示词可以直接复制给 AI 使用：

• 基于需求文档做产品设计
• 帮我设计 S01 的交互流程和原型
• 帮我把所有场景的产品设计做出来
• 帮我设计 CLI 命令的交互流程
• 帮我设计 AI Skill 的对话流程

⚠️ 收尾步骤（强制）：更新 resource_index

完成本 Skill 的所有文档产出后，必须将新生成的文档追加写入 logos/logos-project.yaml 的 resource_index 字段：

resource_index:
  # ...已有条目...
  - path: logos/resources/prd/2-product-design/1-feature-specs/<文件名>.md
    desc: <功能规格/信息架构描述>。涉及 <相关场景> 的交互设计、功能规格时必读。
  - path: logos/resources/prd/2-product-design/2-page-design/<文件名>.md
    desc: <原型描述>。涉及 <相关场景> 的页面交互、对话脚本时必读。

不执行此步骤将导致后续 AI 无法感知已完成的产品设计文档，影响场景建模和代码生成阶段的上下文质量。