| name | prototype-wireframe |
| description | BKFlow 唯一的原型产出方式。用 wiremd 纯文本线框 + Mermaid 流程图 + 全页截图，产出低保真但完整标注交互细节的原型，交给设计师出高保真设计稿，并在 TAPD 提设计需求。触发条件："做个原型"、"设计页面"、"出个交互稿"、"给设计师出稿"、"提设计需求"、"prototype xxx"。 |
原型产出与提设计需求（wiremd 线框流程）
核心理念：原型即纯文本。用 wiremd 写低保真线框（可 diff、可版本化、可导 Figma），用 Mermaid 画全局交互/状态流，用截图内嵌成一份可交付 README，再在 TAPD 提设计需求交给设计师出高保真稿。
低保真是刻意的：线框只表达"结构 + 交互细节"，视觉（配色/字体/圆角/间距）交给设计师按蓝鲸 bk-magic-vue 设计系统定稿。
这是唯一方式
BKFlow 的原型产出统一走本流程。已废弃、不再使用：
prototype-generator（纯 HTML 工具包 prototypes/base.html + bkflow-prototype.css/js）ui-prototype（直接改真实 Vue 页面当原型）
需求确认后想直接进入编码实现，属于 writing-plans / test-driven-development 的范畴，不再用"改 Vue 当原型"这种方式先行。
触发场景
- 用户说「做个原型」「设计一下页面」「出个交互稿」「给设计师出稿」「提设计需求」「prototype xxx」
- 一个方案（新页面 / 页面改版 / 新 UI 模块）需要交给设计师出高保真设计稿
- 需要在编码前，用可评审的形式对齐交互细节
前置条件
原型必须建立在已确认的方案之上，不要凭空发挥：
- 若方案尚未成形 → 先走
brainstorming skill 澄清意图与方案。
- 原型应对应一份
docs/specs/YYYY-MM-DD-<topic>-design.md（设计文档）和 / 或 docs/plans/YYYY-MM-DD-<feature>.md（实现计划）。原型 README 必须回链这两份文档。
- 若涉及后端已有数据模型（改造类页面），先读后端 Model / Config / Serializer，按真实字段与
choices 设计控件，不靠猜。
工作流程
digraph proto_flow {
"已确认方案 (spec/plan)" [shape=ellipse];
"确定要覆盖的屏与状态" [shape=box];
"写 wiremd 线框 + callout 标注" [shape=box];
"画 Mermaid 流程/状态图" [shape=box];
"渲染 + 全页截图" [shape=box];
"汇总 README (截图+流程图+交互表)" [shape=box];
"TAPD 提设计需求给设计师" [shape=box];
"已确认方案 (spec/plan)" -> "确定要覆盖的屏与状态";
"确定要覆盖的屏与状态" -> "写 wiremd 线框 + callout 标注";
"写 wiremd 线框 + callout 标注" -> "画 Mermaid 流程/状态图";
"画 Mermaid 流程/状态图" -> "渲染 + 全页截图";
"渲染 + 全页截图" -> "汇总 README (截图+流程图+交互表)";
"汇总 README (截图+流程图+交互表)" -> "TAPD 提设计需求给设计师";
}
1. 确定要覆盖的屏与状态（全状态覆盖）
- 列出方案涉及的所有页面 / 面板 / 步骤，每个独立状态各出一屏。
- 禁止只出一个 Tab / 一种状态：列表 + 详情、弹窗打开态、成功 / 失败 / 校验异常态都要单独体现。
- 每屏对应
prototypes/output/<feature-name>/screens/NN-<name>.md 一个源文件。
2. 写 wiremd 线框 + callout 交互标注
- 每屏一个
screens/*.md，用 wiremd 语法搭结构（容器 / 表单 / 表格 / 按钮 / 徽标）。
- 交互标注写成
<!-- ❶ ... --> HTML 注释（渲染时 --show-comments 显示），用编号 ❶❷❸ 对应界面元素。
- 标注必须覆盖：保存时机（即时 / 失焦 / 手动）、校验规则与失败表现、状态指示（已配置 / 默认 / 异常）、危险操作二次确认、特殊控件行为、导航跳转。
- Mock 数据要有真实业务语义（流程名、空间、凭证、任务状态），不用「测试1」「aaa」「foo」。
- 语法细节、已知坑与规避见
.ai/docs/guides/prototyping-workflow.md。
3. 画 Mermaid 流程 / 状态图
- 用
flowchart 画全局导航与操作流，用 stateDiagram-v2 画验证 / 交互状态机，用 flowchart LR 画数据联动。
- 放进 README（GitHub 与多数 Markdown 预览器可直接渲染），补足线框无法表达的"跨屏流转"。
4. 渲染 + 全页截图
- 用
npx @eclectic-ai/wiremd 把 screens/*.md 渲染成 sketch 手绘风 HTML。
- 用 Playwright 对每屏做全页截图，存
shots/*.png。
- HTML 产物不入库：README 内嵌截图即可，需要交互查看时按 guide 命令现渲染。
5. 汇总可交付 README
prototypes/output/<feature-name>/README.md 包含：
- 概览 + 关联 spec / plan 链接（回链
docs/specs/、docs/plans/）。
- Mermaid 流程 / 状态图。
- 每屏一节：截图 + 编号交互说明表（
| 编号 | 元素 | 交互说明 |）。
- 预览与渲染命令（引用 guide）。
- 补充说明（媒体位待补、视觉以 bk-magic-vue 为准、全状态覆盖情况）。
6. 在 TAPD 提设计需求给设计师
- 先用
tapd-workitem-sync 确定 / 获取本次功能的父需求单 ID。
- 在其下创建一条子需求单指派给设计师，描述里包含：方案一句话背景 + spec / plan / 原型 README 的链接 + 关键交互要点 + 期望产出（高保真设计稿 / 交互稿）。
- 具体 TAPD 字段与创建方式见
.ai/docs/guides/prototyping-workflow.md 的「提设计需求」一节。
产物目录约定
prototypes/output/<feature-name>/
├── README.md # 概览 + Mermaid 流程图 + 每屏截图 + 编号交互说明表
├── screens/ # wiremd 线框源文件（唯一真源，可 diff / 迭代 / 导 Figma）
│ ├── 01-<name>.md
│ └── ...
└── shots/ # 各屏全页截图（README 内嵌）
├── 01-<name>.png
└── ...
screens/*.md 是唯一真源：改一行重渲染即可，天然可版本化 diff、可 AI 迭代、可导出 Figma。shots/*.png 是展示用截图。- HTML 不保存进仓库。
强制规则（MUST）
| 规则 | 说明 |
|---|
| 先有方案 | 原型基于已确认的 spec/plan，缺则先 brainstorming |
| 全状态覆盖 | 有几个 Tab / 步骤 / 状态就出几屏，含成功 / 失败 / 异常态 |
| 交互标注 | 每屏用 <!-- ❶ --> callout 标注交互，README 汇成编号说明表 |
| 纯文本真源 | 线框以 screens/*.md 为准，可 diff；HTML 不入库 |
| 真实 Mock | 用接近真实业务的数据，不用占位符 |
| 先读后端 | 改造类页面先读 Model/Config/Serializer，按真实字段设计控件 |
| 回链文档 | README 回链对应 docs/specs/ 与 docs/plans/ |
| 提设计需求 | 产出后在 TAPD 建子需求单交付设计师，附全部链接 |
| 低保真 | 只表达结构与交互，视觉交给设计师定稿 |
反模式（禁止）
| 错误做法 | 正确做法 |
|---|
| 用旧 HTML 工具包 / 改 Vue 页面当原型 | 一律用 wiremd 线框流程 |
| 只出一屏让人脑补其他状态 | 每个状态各出一屏，全状态覆盖 |
| 交互只写文字、图上不标 | 用 <!-- ❶ --> callout 标在图上 |
| 追求高保真配色/像素 | 低保真线框，视觉留给设计师 |
| 把 HTML 产物提交进仓库 | HTML 现渲染，仓库只留 screens/*.md + 截图 |
| 产出原型就完事 | 必须在 TAPD 提设计需求闭环 |
参考
- 工具链、wiremd 语法速查、已知坑、渲染 / 截图 / Figma 命令、提设计需求模板：
.ai/docs/guides/prototyping-workflow.md
- 通用 UI 设计原则：
.ai/skills/prototype-wireframe/reference/design-principles.md
- TAPD 单据创建：
.ai/skills/tapd-workitem-sync/SKILL.md
- 已跑通的完整样例：
prototypes/output/space-config-redesign/（随空间配置改版特性分支入库）
