Beautiful Feishu Whiteboard 开源解读：把 AI 画白板从随意涂鸦变成风格工程

大家好，我是若风。

最近我发现了一个很特别的开源项目，zarazhangrui/beautiful-feishu-whiteboard，340 个 Star，23 个 Fork，MIT 许可证。

坦率的讲，它做的事情听起来很小，给飞书白板配了 35 套配色风格，让 AI Agent 画白板时不再乱用颜色。

但打开仓库仔细看，我发现它想的比「配色」深得多。

这个项目的作者 Zara Zhang，就是那个在 X 上说出「好的 skill 不是靠写 skill 文件做出来的，你先把事情做一遍，修 20 次，然后让 AI 把你刚才做的一切装瓶封装」的人。Beautiful Feishu Whiteboard 就是这句话的产物，它不是凭空设计出来的，是在飞书白板渲染器上反复撞墙后，把能做的和不能做的全部摸清楚，再封装成 Agent 能用的 Skill。

说实话，我一开始对「白板配色」这件事没太大期待。白板嘛，不就是画几个框、连几条线，颜色差不多就行了。

看完仓库里的 RULES.md 和 CATALOG.md，我的感觉变了。

说真的，这 35 套配色背后，藏着一个更根本的问题，Agent 生成视觉内容时，自由度过高反而是灾难。

先说结论

Beautiful Feishu Whiteboard 的核心价值，不在于「让白板更好看」，而在于把 AI 生成白板这件事，从自由涂鸦变成了有约束、有风格、可复现的工程流程。

用一句话概括，

Beautiful Feishu Whiteboard 把 AI 画白板这件事，从「你看着办」变成了「按这套风格来」。

这不是一个简单的调色板。它是一套面向 Agent 的飞书白板视觉规范系统。

为什么飞书白板需要风格约束

要理解这个项目的价值，得先理解飞书白板的渲染限制。

飞书白板底层是 SVG 渲染器，但它的 SVG 支持非常有限。RULES.md 里记录了几条硬限制，只支持原生形状，不能画复杂自定义 SVG；不支持透明度（opacity）；不支持渐变和模糊效果；文字颜色导出时还有 bug。

这些限制意味着，如果你让 AI Agent 自由发挥画白板，它大概率会画出一些飞书白板根本渲染不出来的东西。

你想想看，更麻烦的是，即使渲染出来了，没有配色约束的 AI 白板通常长这样，框是默认蓝色，文字是黑色，连线是灰色，所有元素挤在一起，没有任何视觉层级。看起来像是 1998 年的流程图。

这就是 Beautiful Feishu Whiteboard 要解决的问题。

它没有试图突破飞书白板的渲染限制，那个改不了。它做的事情更务实，在限制之内，把配色和布局做到最好。

第一层：35 套风格，不只是调色板

仓库把 35 套风格分成三组。

克制组（Restrained）有 9 套，包括 Avocado Press、Macchiato、Monochrome、Reading Room 等。这组风格适合正式场合，比如内部报告、架构图、流程文档。颜色少，对比低，看着不累。

平衡组（Balanced）有 15 套，包括 Berry Pop、Cobalt Bloom、Editorial Forest、Riptide Cobalt 等。这组是日常主力，适合产品介绍、项目复盘、方案讲解。有色彩但不炸眼。

大胆组（Bold）有 11 套，包括 BlockFrame、Riso Brut、Specimen Bold、Neo-Grid Bold 等。这组适合对外展示、发布会、创意提案。颜色冲击力强，结构感明显。

每组风格在 templates/<slug>/design.md 里都有自己的配色方案和使用指南。Agent 拿到风格后，不是随机选颜色，而是按模板规定的主色、辅色、背景色、强调色来用。

举个例子，Riso Brut 风格走的是粗粝印刷感，高对比、强色块、粗边框，像 70 年代的 risograph 印刷品。Macchiato 则走温暖咖啡调，米色底、棕色线、奶白色块，适合需要「不咄咄逼人」的场合。

这里有一个很关键的细节。

反正我觉得，35 套风格的设计模板只约束配色，不约束布局。布局由 Agent 根据内容自由安排。

这个分寸感很好。配色管住视觉品质的下限，布局留给 Agent 发挥空间。如果连布局也锁死，白板就会变成填空题，反而失去了白板「自由组织想法」的优势。

第二层：RULES.md，用撞墙换来的渲染真经

RULES.md 是这个仓库最硬核的文件。

它不是从文档抄来的，是在飞书白板上反复试出来的。Zara 在 README 里用的词是「hard won, on board verified knowledge」，真刀真枪画过、渲染过、导出过，才知道什么能做什么不能做。

这种「撞墙知识」在 AI Agent 开发里特别珍贵。

你想想看，大模型训练数据里没有「飞书白板 SVG 渲染器不支持 opacity」这种信息。Agent 自己也不知道。如果你不告诉它，它会高高兴兴地画一个带半透明渐变的效果，然后渲染出来是一坨黑的。

RULES.md 把这些坑全部标出来了。

原生形状 only，不要尝试自定义 SVG path。不要用 opacity，不要用 gradient，不要用 blur。文字颜色导出有坑，用特定方式处理。形状的边框宽度、圆角半径、阴影参数都有上限和下限。

这些规则看起来像限制。

但它们其实是护栏。

没有护栏的高速公路不是更自由，是更危险。Agent 画白板也是一样。把不能做的提前告诉它，它反而能在能做范围内做得更好。

第三层：Agent 工作流，先问风格再动手

SKILL.md 定义了 Agent 画白板的完整流程。

第一步，理解白板的目的。是架构图、流程图、头脑风暴、还是项目路线图？不同目的对应不同的信息密度和视觉需求。

第二步，确认风格。Agent 会根据用户想要的氛围（专业、活泼、创意、温暖）从 CATALOG.md 里推荐风格。用户可以指定，也可以让 Agent 选。

第三步，按模板配色生成白板。Agent 读取 templates/<slug>/design.md 里的配色方案，用飞书白板的原生形状组织内容。

第四步，自检修正。Agent 检查元素是否溢出、边距是否合理、是否有重叠、配色是否符合模板。

第五步，写入飞书文档。通过 lark-cli 和 whiteboard-cli 把白板写进用户的飞书空间，返回文档链接和预览图。

这个流程有一个设计我很喜欢。

它要求 Agent 在动手之前先确认风格。这不是多此一举。AI 做视觉内容最容易翻车的地方，就是用户心里有一个画面，但 Agent 画出来的是另一个画面。提前确认风格，等于在认知对齐上花 30 秒，避免后面 5 分钟的重画。

第四层：安装体验，preflight.sh 的设计判断

Beautiful Feishu Whiteboard 的安装有两种方式。

推荐方式是用 npx skills add，

npx skills add zarazhangrui/beautiful-feishu-whiteboard

也可以手动 clone 到 Agent 的 skills 目录。

安装后需要满足三个前置条件，Node.js 20 以上，飞书账号，lark-cli 已认证。然后运行 bash scripts/preflight.sh 做环境检查。

preflight.sh 这一步看着简单，但设计判断很好。

很多 Agent Skill 的安装文档就写「先装这个、再装那个」，用户装到一半卡住了也不知道哪里出了问题。preflight 把检查集中到一个脚本里，Node 版本、CLI 安装、认证状态一次性过完。有问题当场报，没问题直接进入可用状态。

这是一个很小的细节。

但你想想看，它反映的是作者对「Skill 不是写完就行，要能跑通」这件事的理解。

适合什么场景

第一，技术架构图。 微服务拓扑、数据流、系统分层，用克制组风格画出来，比默认白板专业很多。

第二，产品方案讲解。 用户旅程、功能矩阵、竞品对比，平衡组风格刚好不抢内容的风头。

第三，头脑风暴和 workshop。 用大胆组风格做共创白板，视觉冲击力能让讨论更有能量。

第四，对外演示和发布会。 Riso Brut 或 Specimen Bold 这类风格，做出来的白板可以直接截图放进 PPT。

第五，任何需要「看起来像设计过的」飞书白板。 这个需求比想象中大。很多团队的飞书白板内容很好，但视觉上太随意，发给老板或客户时总觉得差点意思。套一套风格，同样的内容观感完全不同。

不适合什么场景

第一，需要复杂数据可视化的场景。 飞书白板没有图表引擎，柱状图、折线图、热力图这些做不了。

第二，需要高保真 UI 原型的场景。 白板是示意图级别的表达，不是像素级设计工具。

第三，完全不想碰命令行的用户。 这个 Skill 依赖 lark-cli 认证和 whiteboard-cli 渲染，需要基本的终端操作。

第四，需要多人实时协作编辑白板内容的场景。 Agent 生成的白板是静态内容，如果要多人同时在上面改，不如直接开一个空白板手动画。

我最喜欢的 3 个判断

第一，在限制内做到最好，而不是假装限制不存在。

飞书白板渲染器有硬伤，这是客观事实。很多工具会选择绕开或者假装看不见，让用户在渲染失败时自己踩坑。Beautiful Feishu Whiteboard 选择把所有限制写进 RULES.md，让 Agent 在安全区内发挥。这是一种对用户诚实的工程态度。

第二，配色模板只约束颜色，不约束布局。

这个分寸很难拿。锁太多变成填空题，锁太少等于没锁。35 套风格只规定配色，让 Agent 在视觉品质有保底的前提下自由组织内容，是一个很聪明的平衡点。

第三，preflight.sh 把环境问题前置。

AI Agent 工具最大的落地障碍不是能力不够，是装不上、跑不通。一个 20 行的环境检查脚本，比 200 行的能力说明更能决定用户能不能真正用起来。

我最担心的 3 个问题

第一，风格数量多但差异梯度不够细。

35 套风格听起来很多，但其中一些风格之间的差异主要在色相上，结构语言变化不大。如果用户找不到完全匹配自己品牌调性的风格，目前没有自定义配色的入口。

第二，飞书白板渲染器的限制是动态的。

飞书产品在迭代，渲染器可能会支持 opacity、渐变这些目前不支持的特性。但 RULES.md 是静态文件，如果规则不跟着更新，Agent 会被过时的限制束缚住，画不出本该能画的效果。

第三，质量依赖 Agent 对 RULES.md 的执行力。

Skill 写得再好，如果 Agent 不认真读 RULES.md、跳过自检步骤、或者对「原生形状 only」这条规则理解不到位，白板渲染还是会出问题。这个问题不是 Beautiful Feishu Whiteboard 独有的，是所有 Agent Skill 都面临的挑战。

写在最后

Beautiful Feishu Whiteboard 最值得学的地方，不是它那 35 套配色有多好看。

真正有价值的是它解决了一个被很多人忽视的问题，AI Agent 生成视觉内容时，自由度过高反而是质量杀手。

很多人以为让 AI 画白板，关键是 prompt 写得够不够详细。但实际上，prompt 再详细，如果 Agent 不知道飞书白板不支持 opacity，它还是会画出一个渲染失败的效果。

Beautiful Feishu Whiteboard 的做法是，不靠 prompt 约束 Agent，靠规则和模板约束。把能做的和不能做的提前讲清楚，把配色方案预先定义好，把环境检查做成脚本。Agent 的任务不是「发挥创意」，而是在规则内高效执行。

这个思路不只适用于飞书白板。

它适用于所有「让 AI Agent 生成视觉内容」的场景。PPT、信息图、海报、网页设计，这些领域的共同难题不是 AI 不够聪明，是 AI 不知道边界在哪。谁能先把边界摸清楚、封装成规则，谁就能让 Agent 稳定产出质量。

340 个 Star 对于这种垂直工具来说已经是不错的信号。

但我更看重的不是 Star 数。是 Zara 在 README 里写的那句「hard won, on board verified knowledge」。

说真的，这句话背后，是在飞书白板上画了无数次、渲染失败无数次、导出 bug 撞了无数次之后，才沉淀出来的工程判断。

这种判断，比 Star 数值钱。