lark-whiteboard-runbook

一个面向 AI 编程助手的 agent skill：通过 lark-cli 将 Mermaid 图安全写入飞书文档画板，并完成回读与预览验证。

能做什么

• 接受 /wiki/ 或 /docx/ 飞书文档链接并解析实际文档 token
• 从 .mmd、Markdown 代码块或用户描述中准备 Mermaid
• 默认在文档末尾新建画板，不触碰已有内容
• 在明确授权后整体覆盖指定的已有画板
• 处理租户认证、高风险确认、幂等重试和多画板选择
• 回读 Mermaid source，并导出 JPG 预览进行最终验证

具体命令和排错结论集中维护在 lark-whiteboard-runbook.md；SKILL.md 只定义触发范围、工作流和安全边界。

安装

发布到 npm 后可直接安装：

npx lark-whiteboard-runbook

也可以从仓库运行安装器：

git clone https://github.com/dave-wind/lark-whiteboard-runbook.git
cd lark-whiteboard-runbook
node install.js

按 agent 安装或查看状态：

node install.js --agent codex
node install.js --agent claude
node install.js --agent opencode
node install.js --status
node install.js --list
node install.js --uninstall

安装器只复制 skill 运行所需的三个入口：SKILL.md、lark-whiteboard-runbook.md 和 agents/。

使用

在支持 skills 的 AI 编程助手中明确调用：

使用 $lark-whiteboard-runbook，把 architecture.md 里的第 2 个 Mermaid 图追加到这个飞书文档：https://example.feishu.cn/wiki/xxxxx

执行写入前，skill 会逐项确认：

1. 目标文档在线链接和编辑权限
2. Mermaid 来源或需要现写的图类型
3. 文档所在的飞书租户

默认行为是新建画板。覆盖已有画板必须提供具体画板并再次确认，因为 --overwrite 会清空整板。

源码仓库开发检查

以下测试资产只保留在源码仓库，不进入 npm 包或安装后的 skill。evals/prompts.md 保留 13 个行为回归案例，evals/evals.json 提供对应的机器可读数据集。修改后执行：

python3 evals/validate_dataset.py
node install.js --help
node install.js --status
npm pack --dry-run

静态验证不会调用飞书，也不会修改任何文档。需要测试真实写入时，按 evals/README.md 的风险分级，只使用可丢弃的测试文档，并把脱敏后的结果记录到随源码提交的 evals/results.md。package.json.files 白名单会确保整个 evals/ 目录不进入 npm 包。

SKILL.md 还应使用 Codex skill-creator 自带的 quick_validate.py 校验 frontmatter 和目录结构。

License

MIT