flowcode-ui

name	flowcode-ui
description	将需求文档转化为给 UI 设计师使用的设计说明文档。Use when 用户提到“需求文档转设计文档”“PRD 转 UI 文档”“生成为设计师准备的页面说明/交互说明/视觉交付文档”“把产品需求整理成设计 brief”等场景时务必使用。适用于单个需求文件、多个相关 Markdown 文档或需求目录；输入路径与输出路径必须支持用户指定或自动推断，不能写死为固定目录。

Requirement To UI Designer Doc

使用目标

把已有需求文档整理成一份 UI 设计师可直接消费的设计说明文档，用于后续页面设计、交互设计、视觉稿或原型制作。

这份文档的目标不是复述需求原文，而是把需求中和 UI 设计直接相关的信息重新组织为：

• 页面与模块清单
• 信息层级与布局要点
• 关键交互与状态
• 文案与数据展示要求
• 设计约束、边界和待确认问题

核心原则：自动运行，自主找方案，实在不能运行就停止。遇到问题时先自行分析并尝试解决，不等待用户介入；多个方案可选时，选择最优方案直接执行；只有确认无法继续时才停止任务并说明原因。

必须遵守

• 全程使用中文输出，除非用户明确要求其他语言。
• 只从用户给出的需求文档和必要的关联文档提取内容，不编造产品规则、页面、字段、状态或业务流程。
• 不修改源需求文档原文。
• 不创建临时文件、总结文件、额外分析文件或中间草稿，除非用户明确要求。
• 只创建或更新用户要求的 UI 设计师文档。
• 如果需求不完整、存在冲突，明确写入“待确认问题”，不要偷偷补齐。
• 如果用户同时要求出画布稿或原型，先完成本设计师文档，再把它作为 flowcode_design 的输入上下文。

路径策略

不要把路径写死。把路径视为可推断参数：

sourceReqPath     需求文档文件或目录
supportingDocs    补充文档列表（可选）
outputDoc         UI 设计师文档输出文件

推断顺序：

1. 优先使用用户明确给出的输入和输出路径。
2. 如果用户只说"把需求文档转成 UI 设计师文档"，优先查找当前项目里明显承载需求内容的 Markdown 文件或目录，例如名称包含 requirement、requirements、prd、product、spec、需求、产品 的位置；如果存在多个候选且无法判断，按以下决策顺序处理：分析各候选的上下文与当前任务相关性，推断最优候选并执行；无法推断则停止任务并说明原因。
3. 如果 sourceReqPath 是单个文件且用户没指定 outputDoc，默认输出到同目录，文件名为 <原文件名>.ui-designer.md。
4. 如果 sourceReqPath 是目录且用户没指定 outputDoc，默认输出到该目录下的 ui-designer-spec.md。
5. supportingDocs 只读取和当前需求直接相关的文档，不要顺手加载整个 docs/。

在汇报中说明最终实际使用的路径。

输入范围

优先读取以下输入：

• 核心需求文档
• 与当前需求直接相关的补充文档，例如信息架构、字段说明、流程说明、接口约束、已有页面规范

不要默认读取：

• 整个代码库
• 无关设计规范
• 无关历史方案
• 与当前需求没有直接关系的长文档

如果需求引用了其他文档中的术语、状态或流程，再按需补读相关部分。

转化流程

1. 确认输入边界

1. 确认 sourceReqPath 是单文件还是目录。
2. 判断是否存在必须补读的 supportingDocs。
3. 明确本次是“新建 UI 设计师文档”还是“更新已有 UI 设计师文档”。

如果用户没有说清楚，但可以低风险推断，就先说明假设再执行；如果候选输入有多个，按以下决策顺序处理：分析各候选的上下文与当前任务相关性，推断最优候选并执行；无法推断则停止任务并说明原因。

2. 提取设计相关信息

从需求中重点提取这些信息：

• 产品目标与本次范围
• 用户角色与关键使用场景
• 页面、弹窗、抽屉、步骤流、表单、列表、详情等 UI 载体
• 每个页面或模块的核心任务
• 需要展示的数据、字段、操作入口和反馈方式
• 正常态、空态、加载态、错误态、禁用态、成功态等状态
• 权限、角色差异、平台差异、响应式差异
• 文案约束、提示语、校验规则、异常分支

不要把纯技术实现细节原样搬进 UI 文档，除非它直接影响设计，例如：

• 字段长度限制影响输入框设计
• 状态枚举影响标签和颜色映射
• 权限模型影响页面是否可见或是否可操作

3. 重组为 UI 设计师视角

把原始需求重组为设计师易读结构，而不是照抄原文顺序。优先按“页面/模块/流程”组织。

对于每个页面或模块，尽量回答：

• 为什么存在
• 用户在这里要完成什么
• 页面上应该出现哪些区域
• 每个区域承载什么信息
• 有哪些主操作、次操作和危险操作
• 关键状态和切换条件是什么
• 有哪些设计上必须保留的限制

4. 处理不确定信息

遇到以下情况时不要猜：

• 需求里没有明确页面载体，但隐含存在交互
• 同一字段在不同段落定义不一致
• 页面流程前后冲突
• 验收标准和正文描述冲突
• 用户角色或权限边界缺失

统一写入“待确认问题”，并注明来源段落或冲突点。

输出文档结构

默认生成一份 Markdown 文档，推荐使用以下结构：

# UI 设计师文档：<需求主题>

## 1. 文档信息
- 来源需求：`<sourceReqPath>`
- 补充文档：`<supportingDocs，没有则写 无>`
- 输出目的：供 UI / 交互 / 视觉设计使用

## 2. 需求摘要
- 目标
- 本次范围
- 非本次范围

## 3. 用户角色与核心场景
- 角色
- 场景
- 任务目标

## 4. 页面与模块清单
- 页面/模块名称
- 类型：页面 / 弹窗 / 抽屉 / 流程步骤 / 组件区块
- 对应目标

## 5. 页面或模块详细说明
### 5.1 <页面或模块名>
- 目标
- 进入条件 / 出现时机
- 信息架构
- 布局区块建议
- 关键字段与展示规则
- 主操作 / 次操作
- 交互规则
- 状态设计
- 校验与提示
- 权限 / 角色差异
- 响应式或平台差异

## 6. 组件与复用建议
- 可复用组件
- 相同交互模式
- 需要统一的状态样式

## 7. 文案与可访问性要求
- 关键文案
- 风险提示
- 空态 / 错误态文案
- 无障碍或可读性约束

## 8. 设计约束
- 业务约束
- 技术约束中会影响 UI 的部分
- 必须保留的信息或流程

## 9. 待确认问题
- Q1 ...
- Q2 ...

如果用户指定了自己的模板或章节名，优先遵循用户模板；没有指定时再使用上述结构。

编写规则

• 用 UI 设计师能直接消费的语言写，不要写成研发实现方案。
• 每个页面或模块优先写“目标、结构、状态、交互”，避免空泛总结。
• 字段、按钮、状态名称尽量沿用需求原词，避免自行改名造成对齐成本。
• 如果需求原文已经给了页面名称、按钮文案、状态文案，优先保留。
• 如果同一个交互模式在多个页面重复出现，提炼到“组件与复用建议”。
• 如果某条信息只会影响开发、不影响设计，就不要占正文篇幅；必要时在“设计约束”中一句带过。

校验

完成后检查：

• 输出文档是否只基于真实输入文档内容，没有凭空新增业务结论。
• 每个核心页面、模块或流程是否都覆盖了目标、结构、操作和状态。
• 不确定信息是否都进入“待确认问题”，而不是被伪装成确定结论。
• outputDoc 是否是本次唯一新增或更新的目标文档，除非用户另有要求。
• 如果引用了补充文档，是否在文档信息里列出。

与其他 Skill 的衔接

• 用户接着要求“根据这份文档出页面设计 / 线框图 / dashboard / 画布原型”时，使用 flowcode_design。
• 如果用户先给的是一整个需求文档目录且结构混乱，必要时可以先借助 flowcode_wiki 整理，但只有在用户明确需要时才这样做，不要默认扩大工作范围。

汇报格式

完成后简短说明：

• 使用的 sourceReqPath、supportingDocs 和 outputDoc
• 新建还是更新了 UI 设计师文档
• 覆盖了哪些页面、模块或流程
• 有多少条待确认问题