feishu-whiteboard-pro

Name: feishu-whiteboard-pro
Author: LcpMarvel

一个用于打造真正"经过设计"的飞书 / Lark（飞书）白板的 Claude Code / agent skill——不只是配色
好看，而是讲究构图：清晰的视觉焦点、真实的层次、刻意的留白。它产出的是飞书文档里一块可编辑的真实白板，
而不是一张截图。

它构建于 beautiful-feishu-whiteboard
（沿用并重新校准其配色与 SVG 白板介质规则）之上，补上了原项目缺失的那一层：如何保住
内容事实、如何构图，以及如何用证据判断结果到底好不好。

相比一个"配色板库"它多了什么

介质本身被刻意限制——单一字体、只有原生矩形 / 圆 / 连接线，没有渐变、滤镜、透明度、动效。所以这里的"好看"
指的是构图、层次、节奏、配色克制与留白。这个 skill 把两个原本靠临场发挥的软步骤变成了关卡（gate）：

路由任务（创建 / 修改 / 评审）
   │
   ├─▶ 关卡 0 · 内容事实契约   事实 / 推断 / 不可发明项；每条连接线都是一条关系声明
   ▼
关卡 1 · 设计简报            任务模式 + 阅读路径 + 原型 + 焦点 + 视觉系统 + 反套路
   ▼
对照骨架构图               原型坐标 + 固定字号阶梯 + 8px 间距网格
   │
   ▼
渲染前预测缺陷（fit-check）  确定性：标签过宽 / 挤占间距 / 出血，在渲染前就抓出来
   │
   ▼
渲染 → 修正确性             溢出 / 重叠 / 裁切 / 手画箭头
   │
   ▼
关卡 2 · 设计评审           证据有效性 + 内容忠实度 + 五轴；重要交付由新鲜上下文独立终审
   ▼
按请求写入飞书 → 看实时效果 → 交付

fit-check（scripts/fit-check.mjs）—— 在渲染前检查文字适配、出血、
死区和明确的媒介违规，并可输出 JSON。允许的 transform 会明确降级为渲染目检，不假装已经
机械验证。确定性，不耗模型。
独立终审 —— 对重要交付，把原请求、事实/设计契约、SVG、渲染图、检查结果和可选飞书实板
证据交给全新上下文，只返回 recapture / rebuild / fix / ship，避免作者自我合理化。

示例

七张标杆样板，每张都过了双关卡（fit-check 0 error / 0 warning、设计评审过关）并在真实飞书白板上渲染过。它们覆盖不同原型
与配色板——其中一张还用的是现场生成的配色——但都出自同一条流水线，所以构图与配色是解耦的。把对应的
.svg（在 examples/ 里）当作起手骨架打开，坐标都已经是评审过关的。

四张复杂板子，四种不同配色：


放射式系统图 · Riso Brut	对比矩阵 · Riptide Cobalt
时间线 · Coral	层级图 · 现场生成配色

三张基础板子，共用一套配色（Riso Brut）：


系统图	流程 + 分叉 / 汇合	泳道时序

配色 —— 精选锚点，或现场生成

这里的配色是一套设计系统，不是色卡清单：每套配色都给颜色分配角色（画布、墨色、强调色、面板）并附用途
说明和投放剂量，让 agent 知道每种颜色该怎么用，而不只是有哪些 hex。

一组精挑的锚点。 CATALOG.md 列出从克制到大胆的锚点配色；按气质和正式度挑一套。
每套就是一个 templates/<slug>/design.md，并且是唯一真相源——目录表由它们经 scripts/build-catalog.mjs
生成。
没有合适的就现场生成。 如果没有锚点契合简报，skill 会按 templates/GENERATE.md
生成一套——先确认视觉依据和使用场景，再定画布/墨色/强调色角色、OKLCH 明暗与对比度。纯白、
纯黑、冷中性、暖纸和饱和底都可以是明确选择，不再把暖奶油底当成普适答案。它产出的
frontmatter 形态和锚点完全一致，所以照样能换肤、也能存成新模板。
上面那张层级图用的就是现场生成的 “Steel Infra” 配色。
随时换肤。 换配色只改颜色、不动构图。

前置条件

Node 20+
@larksuite/whiteboard-cli —— 通过 npx 使用，自动下载，无需安装
发布到真实飞书时才需要：lark-cli 与飞书账号。
安装 npm install -g @larksuite/cli，然后 lark-cli config init（扫码）和 lark-cli auth login

运行 scripts/preflight.sh 检查本地渲染；只有准备写入飞书时才运行
bash scripts/preflight.sh --publish 检查 lark-cli 授权。授权暂不可用不会阻塞本地 SVG + PNG。

安装

用 skills CLI —— 它会识别你的 agent（Claude Code、Cursor、
Codex…）并把 skill 软链到正确的目录：

# 全局（用户级），所有项目可用：
npx skills add -g LcpMarvel/feishu-whiteboard-pro

# …或项目级，只装进当前仓库：
npx skills add LcpMarvel/feishu-whiteboard-pro

不安装、只试一次：npx skills use LcpMarvel/feishu-whiteboard-pro。

手动安装（clone + 软链）

git clone https://github.com/LcpMarvel/feishu-whiteboard-pro.git

# Claude Code（用户级 skills）：
ln -s "$(pwd)/feishu-whiteboard-pro" ~/.claude/skills/feishu-whiteboard-pro

重启会话；之后只要你让它创建或打磨飞书白板、信息图、图表或可视化讲解，skill 就会触发。

仓库结构

路径	作用
`SKILL.md`	门控流水线与编排
`references/`	创建、修改、评审三条按需工作流
`COMPOSITION.md`	原型库（坐标骨架）、字号阶梯、间距网格、反套路清单——核心
`CRITIQUE.md`	证据/事实门 + 五轴设计评分 + 有界终审说明
`agents/whiteboard-finish-reviewer.md`	只读独立终审契约
`RULES.md`	飞书 SVG 白板介质的硬性限制，实测验证
`templates/`	一组精选配色板（每套一个 `design.md`）——唯一真相源
`CATALOG.md`	选色表，由 `templates/` 经 `scripts/build-catalog.mjs` 生成
`templates/GENERATE.md`	没有锚点契合时，如何生成一套（同 frontmatter 形态）新配色
`examples/`	七张按原型分类的标杆样板（可编辑 `.svg` + 渲染图）
`scripts/`	`fit-check.mjs`（渲染前检查）、`check-repo.mjs`（离线回归）、`build-catalog.mjs`、`preflight.sh`
`tests/fit-check.test.mjs`	检查器的最小回归测试

致谢与许可

MIT。精选并蒸馏过的一部分配色与介质规则改编自
beautiful-feishu-whiteboard，作者
Zara Zhang（@zarazhangrui） —— © Zara Zhang，MIT。构图、评审、
fit-check、门控流水线与配色生成层为原创新增。设计判断的思路受 impeccable / frontend-design skill 启发
（未拷贝代码）。详见 LICENSE。