Excalidraw 协作草图、仓库接入与数据治理手册

高谷深陵大约 5 分钟约 1371 字

Excalidraw 场景、协作与归档边界画布元素、内嵌文件和协作状态经收敛与审查，形成可维护场景和只读发布物。高清原图

Excalidraw 的手绘表达适合方案探索、评审沟通和快速拆解。它不应被误用为所有正式架构资产的终点。一个 .excalidraw 文件包含画布元素、样式与可能的内嵌文件；在线协作和分享链接还保存仓库之外的会话状态。团队需要区分草图阶段、收敛阶段和长期归档阶段。

先定义草图何时算完成

安装或启用 Excalidraw 可以使用官方网页应用，也可以在产品中集成官方包。浏览器 PWA、第三方编辑器扩展和自建组件具有不同权限。涉及敏感系统时，应确认数据是否离开浏览器、协作服务由谁运营、分享链接如何撤销；不能因为界面像白板就降低安全要求。

草图的完成条件不是“讨论结束”，而是结论已经进入 ADR、任务或正式架构模型，画布上仍有价值的上下文得到整理。未确认的箭头、临时便签和个人名字不应长期充当系统事实。

长期保留的画布保存为 .excalidraw，只读消费端使用 SVG 或 PNG。目录按主题建立单一 owner，并在 README 说明结论入口。JSON 源的 diff 可能受到元素顺序和坐标影响，评审应结合渲染图，避免逐字符解释坐标噪声。

design-notes/
  checkout-review.excalidraw
  checkout-review.svg
  checkout-decision.md

多人协作结束后，由 owner 完成一次收敛提交：删除无意义游标痕迹，命名关键分组，确认字体和附件，关联决策。项目接入不追求实时把每个笔画写入 Git，而是在稳定检查点保存可恢复场景。

使用组件包集成时，应把包版本、导出参数和字体作为构建配置。程序化导出需要同时传入元素、应用状态和文件集合，否则包含图片的画布可能导出空占位。

const svg = await exportToSvg({
  elements,
  appState: {exportBackground: true},
  files,
})

正向实验在新浏览器配置中打开场景，确认文本、分组、链接和内嵌图片完整，再生成只读输出并检查尺寸与可访问描述。成功证据包括源文件、输出、包或应用版本及关联决策，而不是只保留分享链接。