Excalidraw CI/CD集成：自动化测试与发布流程

原创于 2025-12-20 16:19:58 发布 · 521 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#Excalidraw # CI/CD # 设计即代码

部署运行你感兴趣的模型镜像

Excalidraw CI/CD集成：自动化测试与发布流程

在现代软件工程中，一个长期被忽视的痛点正逐渐浮出水面：设计图始终游离于代码之外。无论是系统架构图、流程草图还是产品原型，它们大多以截图或独立文件的形式存在，难以版本化、无法自动化验证，更别提融入CI/CD流水线。这种割裂导致“图文不一致”成为常态，新人理解系统依赖口述，而关键决策过程也因缺乏可追溯的设计资产而模糊不清。

Excalidraw 的出现，正在悄然改变这一局面。这款开源手绘风格白板工具，凭借其简洁直观的交互和强大的协作能力，早已超越了普通绘图工具的范畴。尤其是当它开始与AI结合，并因其基于JSON的开放文件格式而具备高度可编程性时，我们突然意识到——这张“纸”，其实可以像代码一样被管理。

Excalidraw 的核心优势之一，在于它的 .excalidraw 文件本质上是一个结构清晰的 JSON 文档。这意味着，你画的每一条线、每一个文本框，都被精确地记录为带有坐标、样式和内容的数据对象。这样的设计看似简单，却为自动化打开了大门。

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    {
      "id": "A1",
      "type": "text",
      "text": "用户服务",
      "x": 100,
      "y": 200
    },
    {
      "id": "B2",
      "type": "rectangle",
      "width": 80,
      "height": 40,
      "x": 90,
      "y": 190
    }
  ],
  "appState": {
    "zoom": { "value": 1 }
  }
}

这段数据不仅人类可读，机器也能轻松解析。更重要的是，它能被 Git 完美追踪——你可以查看某次提交中谁修改了哪个模块的标注，甚至通过 diff 工具发现两个版本间图元的增删变化。这正是“设计即代码（Design as Code）”的第一步：让图形成为一等公民，纳入版本控制体系。

但仅仅存储还不够。真正的价值在于自动化处理。比如，我们可以写一个简单的 Python 脚本，自动扫描所有 .excalidraw 文件中的文本元素，检查是否包含敏感词或未定义的缩写：

import json

def extract_text_elements(file_path):
    with open(file_path, 'r', encoding='utf-8') as f:
        data = json.load(f)

    text_elements = []
    for elem in data.get("elements", []):
        if elem["type"] == "text":
            text_elements.append({
                "id": elem["id"],
                "content": elem["text"],
                "x": elem["x"],
                "y": elem["y"]
            })

    return text_elements

# 使用示例
texts = extract_text_elements("architecture.excalidraw")
for t in texts:
    print(f"Found text at ({t['x']}, {t['y']}): {t['content']}")

这个脚本可以在 CI 流程中运行，作为 PR 检查的一部分。如果发现“TODO”、“FIXME”或某些内部禁用术语，就直接标记构建失败。这样一来，设计文档的质量也能像代码一样受到保障。

当然，Excalidraw 不只是静态存储。它的实时协作机制才是团队协同的灵魂。官方版本通过 WebSocket 和 Operational Transformation（OT）算法实现多用户同步编辑，确保即使十几个人同时操作，画布状态依然一致。对于企业级应用，社区还提供了 excalidraw-room 这样的开源项目，允许你在内网部署私有协作服务器，既满足安全合规要求，又能保留完整的协作体验。

git clone https://github.com/excalidraw/excalidraw-room.git
cd excalidraw-room
npm start

启动后，前端只需连接到本地 WebSocket 地址即可加入房间。这种能力在 CI/CD 中也有妙用——比如自动化录制演示动画，或者回放设计评审过程，帮助新成员快速理解上下文。

然而，真正让 Excalidraw 从“工具”跃升为“平台”的，是它与 AI 的融合。想象这样一个场景：你在 GitHub 提交了一个 Issue，“请设计一个新的订单履约流程”。传统做法是几天后有人手动画出草图；而现在，一套自动化流程可以立即响应。

借助大语言模型（LLM），我们可以将自然语言描述转化为结构化的图元数据。例如，使用 GPT-4o 解析语义，识别出“用户”、“支付网关”、“库存服务”等实体及其关系，再将其映射为 Excalidraw 兼容的 JSON 格式。

import openai
import json

def generate_diagram_prompt(natural_language_desc):
    prompt = f"""
你是一个专业的技术绘图助手。请根据以下描述生成 Excalidraw 兼容的 elements 列表（只需输出 JSON 数组，不要解释）。

要求：
- 使用基本图元：rectangle 表示服务，arrow 表示调用关系
- 添加适当的文字标签
- 坐标尽量分散避免重叠

描述：{natural_language_desc}
"""
    response = openai.ChatCompletion.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.3
    )
    try:
        elements = json.loads(response.choices[0].message.content.strip())
        return elements
    except json.JSONDecodeError:
        print("Failed to parse LLM output")
        return []

这段代码可以在 CI 流水线中触发执行。一旦检测到特定标签的 Issue 创建，就自动生成初步架构图，并提交为 Pull Request，附带 PNG 预览图。团队成员可以直接在 PR 中评论、修改，最终合入主分支。整个过程无需人工干预，极大提升了敏捷响应速度。

但这并不意味着我们可以完全信任 AI 输出。当前的模型虽然能捕捉高层语义，但在细节控制上仍有局限——比如手绘风格的还原度、图元布局的合理性、颜色命名的一致性等。因此，在生产环境中，建议采取“AI 初稿 + 人工精修”的模式，并建立模板库来规范输出风格。

实际落地时，还需要考虑一些工程细节。比如：

安全性：避免在公共 CI 日志中打印 LLM 请求内容，防止敏感信息泄露；
成本控制：AI 调用按 token 计费，应对输入做截断和清洗；
缓存机制：对已生成的图表建立哈希索引，避免重复计算；
可访问性：为生成的图表添加 alt-text 描述，提升无障碍体验；
风格统一：定义图元样式模板（颜色、字体、间距），保证输出一致性。

典型的集成架构如下：

[GitHub/GitLab]
     │
     ▼
[Webhook 触发]
     │
     ▼
[CI Runner (GitHub Actions / GitLab CI)]
     ├── 检测 .excalidraw 文件变更
     ├── 调用 Python 脚本进行内容审计
     ├── 若涉及 AI 生成，则调用 LLM API
     ├── 生成 PNG 预览图（via Puppeteer 或 headless browser）
     └── 提交更新或评论反馈
             │
             ▼
       [制品仓库 / 文档站点]

在这个链条中，Headless 浏览器负责将 .excalidraw 文件渲染成 PNG 或 SVG 图像，供文档系统引用；而文档生成器如 MkDocs 或 Sphinx，则可以自动嵌入这些图表，确保每次构建的文档都与最新设计保持同步。

这种深度集成解决了多个长期存在的问题：