BMAD-METHOD Excalidraw 线框渲染器：为 bmad-ux 生成 IA 图与流程线框的完整实战指南-育师

BMAD-METHOD Excalidraw 线框渲染器：为 bmad-ux 生成 IA 图与流程线框的完整实战指南

【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD

导读

本文围绕 BMAD-METHOD 开源仓库中bmad-ux技能模块的 Excalidraw 线框渲染器（skills/bmad-ux/assets/excalidraw-wireframe.md）展开，讲解如何通过子代理（subagent）为 UX 工作流产出两种低保真可视化产物——信息架构（IA）图与流程线框图（flow wireframe）。你将掌握.excalidraw文件的合法结构、index字段的两字符硬性约束及其背后的坑、两种图式的绘制规范，以及产物在bmad-ux全流程（Discovery → Finalize → 校验）中的定位与去向，从而能直接在 Excalidraw 桌面端或 excalidraw.com 中复现这套渲染流程。

一、Excalidraw Wireframe Renderer 在 bmad-ux 中的定位

bmad-ux是一个"UX 引导式协作"技能：它负责把用户的 UX 愿景沉淀为两份对等契约——DESIGN.md（视觉身份，管"看起来如何"）与EXPERIENCE.md（信息架构、行为、状态、交互、无障碍、旅程，管"用起来如何"）。在 Discovery 阶段，当"看见比多聊两句更有助于决策"（例如挑选颜色令牌、选定视觉方向、勾勒 IA、mock 棘手流程）时，技能会按需调用**创意工具（creative tools）**来渲染可选项。

Excalidraw 线框渲染器正是默认注册的四个创意工具之一。在 skills/bmad-ux/customize.toml 的creative_tools注册表中可以看到它的默认入口：

creative_tools = [ "file:assets/color-themes.md", "file:assets/design-directions.md", "file:assets/excalidraw-wireframe.md", "file:assets/key-screens.md", ]

其中color-themes.md（HTML 色板）、design-directions.md（HTML 设计方向）、excalidraw-wireframe.md（Excalidraw 线框）在Discovery阶段使用，而key-screens.md（1:1 HTML 关键屏 mock）在Finalize阶段使用。团队可以通过 override TOML（{project-root}/_bmad/custom/bmad-ux.toml团队级、{project-root}/_bmad/custom/bmad-ux.user.toml个人级）追加更多渲染器，例如 Figma MCP、自定义 skill、基于提示词的 mood board——这正是该注册表的设计意图。

渲染器的协作契约（见 skills/bmad-ux/references/creative-tools.md）如下：

父进程传入：当前.memlog.md、相关历史.working/捕获物、用户本次意图、输出路径；
子代理产出：将产物写入{doc_workspace}/.working/，文件名具有描述性；
子代理返回：仅一份紧凑摘要（文件路径、每个变体一行说明、模式覆盖情况），绝不在父上下文里倾倒完整 payload。

二、产物命名与文件路径约定

渲染器作为子代理提示词（subagent prompt），一次运行只产出一个.excalidraw文件，按图式类型落入两个命名模式之一：

图式	输出路径模式	说明
IA 图	`.working/ia-{date}.excalidraw`	信息架构图，`{date}`为当前系统日期
流程线框	`.working/flow-{name}-{date}.excalidraw`	流程线框图，`{name}`为流程名，`{date}`为日期

{date}在技能激活时由resolve_config.py解析（--key core.project_name --key modules.bmm.planning_artifacts，见 skills/bmad-ux/SKILL.md 的 On Activation 步骤），取自当前系统时间。.working/目录位于运行文件夹{doc_workspace}内，其中{doc_workspace}绑定到{workflow.ux_output_path}/{workflow.run_folder_pattern}/，默认展开为{planning_artifacts}/ux-designs/ux-{project_name}-{date}/（见 skills/bmad-ux/customize.toml 的ux_output_path与run_folder_pattern）。

三、CRITICAL：`index`字段必须恰好两个字符

这是本渲染器提示词中唯一被标注为CRITICAL的约束，也是最容易踩的坑：

每个元素的index字段必须恰好是两个字符（a0、aZ、b3……）。三个字符的 index 会导致静默的"Error: invalid file"，且没有任何诊断输出。

所谓"静默"，意味着文件写入成功、语法看似正常，但用户用 Excalidraw 打开时只会看到一个笼统的错误提示，无法直接定位到具体是哪个元素、哪一行的问题。因此提示词要求：

顺序分配：跨所有元素顺序递增，不跳号；
推进规则：当尾随字母数字耗尽时，前导字母进位——顺序为a0..a9, aA..aZ，然后b0..，依此类推；
写前校验：落盘之前必须自查所有index均为两字符。

从该约束可以推断（结合 Excalidraw 官方文件格式对元素排序字段的解析实现），index是 Excalidraw 用于确定元素绘制层级（z-order）的排序键，其内部按字符串比较排序，对长度有严格校验，超长即整体判定文件非法。实战中建议用一个一次性脚本或正则[a-zA-Z0-9]{2,}扫描全部elements[].index，确保无一遗漏。

四、合法的 .excalidraw 文件结构

提示词给出了文件顶层骨架，必须是合法的 Excalidraw 文件：

{ "type": "excalidraw", "version": 2, "source": "https://excalidraw.com", "elements": [], "appState": { "gridSize": null, "viewBackgroundColor": "#ffffff" }, "files": {} }

字段语义：

type/version/source：标识文件类型与格式版本，source固定为官方源https://excalidraw.com（这是 Excalidraw 官方导出格式的标准签名）；
elements：全部图形元素的数组，是文件主体；
appState：画布级状态，此处规定gridSize: null（不强制网格对齐）、viewBackgroundColor: "#ffffff"（白色背景）；
files：内嵌图片/二进制资源的映射，IA 图与流程线框通常为空对象{}。

4.1 通用元素字段

每个元素必须包含 Excalidraw 标准元素字段：

字段	作用
`id`	元素唯一标识
`type`	元素类型（如`rectangle`、`text`、`arrow`、`ellipse`）
`x`/`y`	元素左上角画布坐标
`width`/`height`	元素尺寸
`angle`	旋转角度（弧度）
`strokeColor`/`backgroundColor`	描边色 / 填充色
`fillStyle`	填充风格（如`hachure`、`solid`、`cross-hatch`）
`strokeWidth`/`strokeStyle`	描边粗细 / 描边风格（实线、虚线等）
`roughness`	手绘粗糙度（Excalidraw 的手绘风格参数）
`opacity`	透明度
`groupIds`	所属分组 ID 数组
`frameId`	所属画框 ID（无则空）
`roundness`	圆角设置
`seed`	随机种子（决定手绘抖动形状）
`version`/`versionNonce`	元素版本号与防冲突随机数
`isDeleted`	删除标记（导出的有效元素通常为`false`）
`boundElements`	绑定到该元素的连线/文本引用
`updated`	更新时间戳
`link`	外链（可为 null）
`locked`	是否锁定
`index`	两字符排序键（见上文 CRITICAL）

4.2 文本元素附加字段

当元素是文本时，还需补充：

字段	作用
`text`	文本内容
`fontSize`	字号
`fontFamily`	字体族
`textAlign`	水平对齐
`verticalAlign`	垂直对齐
`baseline`	基线偏移
`containerId`	宿主容器（如所在矩形的 ID）
`originalText`	原始文本（保留字面内容）
`lineHeight`	行高

五、两种图式的绘制规范

渲染器按需产出两种低保真图式，二者定位不同，绘制规范也不同。

5.1 IA 图（信息架构图）

内容：盒子与箭头（boxes-and-arrows），覆盖：

认证栈（auth stack）；
主应用各页面/界面（main app surfaces）；
模态路由（modal routes）；
设置栈（settings stack）；
横切性能力/入口（cross-cutting affordances，如全局导航、通知等）。

风格：

颜色克制使用，仅用于区分类别（category），不做装饰性上色；
布局以人类可读性为第一目标，而非图论意义上的"图正确性"（layout for human legibility, not graph correctness）——即允许重叠归类、按阅读顺序摆放，不必追求严格的层级树状图。

IA 图服务于 Discovery 阶段的"surface closure"检查：每个被陈述的需求都要有承载它的界面，每个界面都要有落在其上的旅程。IA 图就是这种闭合关系的可视化载体。

5.2 流程线框图（Flow Wireframe）

内容：

逐屏矩形，从左到右排布（screen-by-screen rectangles left-to-right）；
屏内用简单形状表达低保真内容块：导航栏（nav bar）、CTA 按钮、内容块（content blocks）；
箭头标注触发转场的用户动作（Arrows labeled with the user action that causes transition），例如"点击注册"、"滑动删除"；
在关键节点与边界用例旁附加批注（Annotations alongside for climax and edge-case beats）——即流程的"高潮节拍"与边界情形要在图上有文字说明，而不是只在正文里描述。

流程线框服务于 EXPERIENCE.md 中"命名主角旅程（named-protagonist journeys）"的可视化，帮助用户在进入 Finalize 提炼之前，先对关键流程的转折点达成共识。

六、返回父进程的摘要契约

渲染完成后，子代理必须向父进程返回紧凑摘要，且不得把 JSON 倾倒进父上下文。摘要包含：

文件路径（file path）；
图式类型（kind：IA 或 flow）；
单行主题（one-line subject）；
元素数量（element count）；
全部 index 均为两字符的确认（confirmation that all indices are two-character）。

最后还要告知用户去 Excalidraw 桌面端或 excalidraw.com 打开该文件。这一契约与 skills/bmad-ux/references/creative-tools.md 中"渲染器契约"一致：父进程绝不持有完整 payload，只消费摘要，避免污染对话上下文。

七、产物在完整工作流中的去向

.working/是整个运行过程的审计轨迹（audit trail），运行结束仍保留。该产物的生命周期贯穿bmad-ux的三个阶段（见 skills/bmad-ux/SKILL.md）：

Discovery：Excalidraw 线框渲染器在此阶段被调用（注册于creative_tools），产物落在.working/；
Finalize：
- Layout extracted, artifacts promoted：提炼子代理重读.working/与imports/中的每个产物，把视觉决策抬升进DESIGN.md、行为决策抬升进EXPERIENCE.md；随后，.working/中具有持续参考价值的产物被**提升（promote）**到{doc_workspace}/wireframes/（Excalidraw 文件）或{doc_workspace}/mockups/（HTML mock）。提升门槛是：未来阅读DESIGN.md或EXPERIENCE.md的人会不会打开它？默认留在.working/；
- Mock coverage confirmed：逐屏走查每个 IA surface，区分mocked与spine-only；
- 提升后的线框以行内相对链接（inline relative links）挂到相关 spine 章节，并重申一次"spines-win-on-conflict"（契约胜出原则：DESIGN.md与EXPERIENCE.md在冲突时压过任何 mock、线框或 import）；
Validate / Reviewer Gate：校验规则中的Pass 1 第 5 项 Visual reference coverage会逐一核对mockups/、wireframes/、imports/中的每个文件，要求 spines 在相关章节行内链接到它们并说明其所阐释的内容（见 skills/bmad-ux/references/validate.md），同时检查是否存在孤儿文件（orphans）与不具体的引用。

因此，一张合格的 Excalidraw 线框不仅是 Discovery 阶段的讨论工具，还可能在 Finalize 被提升为wireframes/中的正式视觉参考，进而成为 spine 的链接锚点与后续校验的检查对象。

八、Headless 模式下的行为差异

当运行处于 headless 模式（调用方设置headless: true、由其他 skill 或非交互 runner 触发、或激活步骤声明）时，行为有明确差异（见 skills/bmad-ux/references/headless.md）：

创意工具默认关闭：Excalidraw 线框这类渲染器默认不执行；调用方可显式覆盖开启；
即使产出了产物，也只落在.working/，除非调用方明确指示，否则不提升；
不问候、不提问、不执行浏览器打开步骤。

九、实战核查清单

结合全文，将本渲染器落地到真实运行中时，建议按以下清单自查：

命名：IA 图 →.working/ia-{date}.excalidraw；流程线框 →.working/flow-{name}-{date}.excalidraw；
index 两字符：所有elements[].index均为两字符，顺序分配，无跳号（a0..a9, aA..aZ, b0..）；
文件骨架：type/version/source、elements、appState（gridSize: null、viewBackgroundColor: "#ffffff"）、files: {}齐全；
元素字段：通用字段完整；文本元素补齐text/fontSize/fontFamily/textAlign/verticalAlign/baseline/containerId/originalText/lineHeight；
图式语义：IA 图按类别克制用色、优先人类可读；流程线框从左到右逐屏、箭头标注用户动作、关键节拍与边界情形有批注；
摘要返回：只回路径/类型/单行主题/元素数/index 确认五要素，不倾倒 JSON；
打开方式：提示用户在 Excalidraw 桌面端或 excalidraw.com 打开。

遵循以上步骤，即可让 Excalidraw 线框渲染器稳定地产出可被bmad-ux后续 Finalize 提升、被校验规则复查的合法.excalidraw文件，把 IA 与关键流程的决策以低保真、高可读的形式固化到 UX 工作流中。

【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

BMAD-METHOD Excalidraw 线框渲染器：为 bmad-ux 生成 IA 图与流程线框的完整实战指南

BMAD-METHOD Excalidraw 线框渲染器：为 bmad-ux 生成 IA 图与流程线框的完整实战指南

导读