feishu-preview

语言 / Language: 中文 | English

中文文档

这是什么？

feishu-preview 是一个 Claude Code AI 技能 + CLI 工具，覆盖飞书 Mermaid 图表的完整工作流：

写图表 → 检查兼容性 → 自动修正 → 本地预览 → 同步到飞书

解决的核心问题：

飞书使用的 Mermaid 渲染引擎（v8）与标准 Mermaid（v10+）存在语法差异，导致：

在 VS Code / 其他工具里预览正常，推送到飞书后图表报错或空白
不知道哪里语法有问题，只能盲改反复测试
本地预览效果和飞书实际效果不一致

本工具通过 飞书官方的 whiteboard-cli 渲染引擎 生成本地预览，保证「所见即所得」。

快速上手（2 步）

第一步：安装插件

在 Claude Code 里运行：

/plugin marketplace add andyliu/feishu-preview

CLI 工具和 Claude Code 技能定义一并安装，后续版本更新自动完成，无需手动操作。

需要 Node.js ≥ 16。没有的话先去 nodejs.org 下载安装。

安装后首次运行任意命令时，工具会自动检查依赖（如 lark-cli）并交互式引导安装。无需手动执行额外步骤。

第二步：使用

Claude Code 自然语言（推荐）

安装后，在 Claude Code 对话里直接说：

检查 docs/my-diagram.md 的飞书兼容性
预览 docs/my-diagram.md
同步 docs/my-diagram.md 到飞书文档

Claude Code 会自动调用工具，引导你完成每一步。

CLI 命令（直接调用）

# 写完图表后，检查飞书兼容性
feishu-preview check docs/my-diagram.md

# 发现问题？一键自动修正
feishu-preview convert docs/my-diagram.md -w

# 生成本地精确预览（与飞书渲染一致）
feishu-preview preview docs/my-diagram.md

# 查看飞书同步状态
feishu-preview status docs/my-diagram.md

全部命令

命令	说明
`feishu-preview doctor`	检查并安装所有必要依赖（lark-cli 等），交互式引导
`feishu-preview check <file>`	检查飞书兼容性，只读，exit 1 表示有问题
`feishu-preview convert <file> -w`	原地修正源文件中所有不兼容语法
`feishu-preview convert <file> -o out.md`	修正后输出到新文件（不改源文件）
`feishu-preview preview <file>`	精确预览：用飞书官方引擎渲染为 PNG（默认）
`feishu-preview preview <file> --fast`	仅语法调试：Mermaid CDN 渲染，结果与飞书不符，不可用于视觉验证
`feishu-preview status <file>`	查看 `.feishu-index.json` 中的同步状态

预览模式说明

模式	命令	渲染引擎	特点
精确模式（默认）	`feishu-preview preview file.md`	`@larksuite/whiteboard-cli`，每张图渲染为 PNG	与飞书实际效果完全一致；同步前必须用此模式确认；首次运行需联网下载
调试模式（`--fast`，⚠️ 非视觉验证）	`feishu-preview preview file.md --fast`	Mermaid.js v10 CDN，交互式 SVG	仅用于排查 Mermaid 语法错误（浏览器控制台显示详细报错）；渲染引擎与飞书不同，结果不可作为视觉依据

精确模式生成的 HTML 中，PNG 以 base64 内嵌，可离线分享。

飞书兼容性问题说明

以下是飞书 Mermaid 与标准写法的已知差异，feishu-preview check / convert 会自动处理：

问题	标准写法	飞书要求	原因
换行符	`<br/>`	`<br>`	飞书解析器不接受 XML 自闭合标签
Note 内的小于号	`x < 300s`	`x ＜ 300s`（全角）	解析器把 `<` 视为 HTML 标签开始，`<` 同样无效
状态图版本	`stateDiagram-v2`	`stateDiagram`	飞书仅支持旧版布局引擎
多行引用块	`> 第一行\n> 第二行`	`> 第一行<br>第二行`	飞书把多行 `>` 直接拼接，不加空格，导致句子粘连
节点双引号	`A["文字"]`	保持不变	飞书接受双引号；改成单引号反而报 `PS` token 错误

同步状态文件 `.feishu-index.json`

同步到飞书后，工具会在 .md 文件同目录生成 .feishu-index.json，记录每个图表对应的飞书 whiteboard token，方便后续迭代更新（无需删旧建新）。

{
  "my-diagram.md": {
    "doc_url": "https://your-org.feishu.cn/docx/Xxxxx",
    "last_synced": "2026-04-20T10:00:00Z",
    "whiteboards": {
      "2.1 设备注册时序": "FY0FwuSKShMWuZbMjX0czKk6nLh"
    }
  }
}

⚠️ 此文件包含文档 URL 和 token，已加入 .gitignore，不要提交到 Git。

环境要求

依赖	用途	安装方式
Node.js ≥ 16	运行所有脚本	nodejs.org
Claude Code	使用自然语言技能	claude.ai/code
`feishu-preview`	本工具	`/plugin marketplace add andyliu/feishu-preview`
`@larksuite/whiteboard-cli`	精确预览模式（npx 自动拉取）	无需手动安装
`lark-cli`	飞书文档同步（仅推送时需要）	`npm install -g @larksuite/lark-cli`

feishu-preview 本身零 npm 运行时依赖，只使用 Node.js 内置模块。

项目结构

feishu-preview/
├── .claude-plugin/
│   └── marketplace.json         # Claude Code 插件市场描述
├── plugins/
│   └── feishu-preview/
│       ├── .claude-plugin/
│       │   └── plugin.json      # 插件元数据
│       ├── bin/
│       │   ├── feishu-preview   # CLI 入口（feishu-preview 命令）
│       │   ├── render-preview.js  # Markdown → HTML 预览生成器
│       │   └── feishu-compat.js   # Mermaid 飞书兼容性转换器
│       └── skills/
│           └── feishu-preview/
│               └── SKILL.md     # Claude Code 技能定义
└── package.json

最佳实践

目录结构

把图表文档放在独立目录，便于管理 .feishu-index.json：

docs/
└── diagrams/
    ├── device-flow.md          # 源文件（含 Mermaid，这是唯一可编辑的地方）
    ├── device-flow.preview.html  # 自动生成，gitignore，勿提交
    └── .feishu-index.json        # 记录飞书 token，gitignore，勿提交

标准工作流

每次修改图表后，按以下顺序执行，不要跳步：

1. 编写/修改 Mermaid 代码
2. feishu-preview check    → 检查兼容性
3. feishu-preview convert -w → 有问题则修正
4. feishu-preview preview  → 精确预览确认效果（必须，同步前最后防线）
5. 告诉 Claude Code "同步到飞书"

本地 .md 是唯一真相来源

永远不要在飞书 Whiteboard 编辑器里直接修改 Mermaid——飞书不提供导出功能，修改后将无法同步回本地，等于丢失版本控制
所有修改都在本地 .md 文件进行，飞书文档只是展示层

Git 提交规范

# ✅ 应该提交
git add docs/diagrams/device-flow.md

# ❌ 不要提交（已在 .gitignore）
# docs/diagrams/device-flow.preview.html
# docs/diagrams/.feishu-index.json

每个 H2 标题对应一个图表

飞书 whiteboard 以标题为锚点定位，建议每张图表前保留清晰的 H2 标题，便于迭代更新时精确定位：

## 2.1 设备注册时序

```mermaid
sequenceDiagram
    ...
```

精确预览 vs 调试模式

场景	命令
同步前的最终视觉确认	`feishu-preview preview file.md`（精确模式，必须）
图表报错，需要看详细报错信息	`feishu-preview preview file.md --fast`（调试专用，结果不代表飞书效果）

常见问题

Q：精确预览时图表显示空白或红色错误框？

切换快速模式排查语法：feishu-preview preview file.md --fast，浏览器控制台会输出详细的 Mermaid 错误信息。修复后再切回精确模式确认效果。

Q：推送到飞书后想更新图表怎么操作？

修改本地 .md → feishu-preview check → feishu-preview convert -w → feishu-preview preview 确认效果 → Claude Code 说「同步到飞书」。

Q：stateDiagram-v2 降级为 stateDiagram 会丢失功能吗？

不会影响绝大多数图表。两者语法兼容，区别仅在于内部布局引擎，常用的状态、转换、note、并发写法均支持。

English Documentation

What Is This?

feishu-preview is a Claude Code AI skill + CLI tool covering the full Mermaid-in-Feishu workflow:

Write diagrams → Check compatibility → Auto-fix → Local preview → Sync to Feishu

Core problems solved:

Feishu uses a Mermaid rendering engine (v8) that differs from standard Mermaid (v10+), causing:

Diagrams that look fine locally but show errors or go blank in Feishu
No way to know which syntax is incompatible without blind trial-and-error
Local preview doesn’t match what Feishu actually renders

This tool uses Feishu’s own official whiteboard-cli rendering engine for local preview, giving you true WYSIWYG accuracy.

Quick Start (2 steps)

Step 1: Install the Plugin

In Claude Code, run:

/plugin marketplace add andyliu/feishu-preview

This installs both the CLI and the Claude Code skill definition in one step. Future updates are applied automatically at startup — no manual reinstall needed.

Requires Node.js ≥ 16. Download from nodejs.org if needed.

On first use, the tool automatically checks for required dependencies (such as lark-cli) and walks you through installing any that are missing. No extra steps needed.

Step 2: Use It

Claude Code natural language (recommended)

Just talk to Claude Code:

Check docs/my-diagram.md for Feishu compatibility
Preview docs/my-diagram.md
Sync docs/my-diagram.md to Feishu

Claude Code will call the tools automatically and guide you through each step.

CLI commands (direct use)

# Check for Feishu-incompatible syntax after writing
feishu-preview check docs/my-diagram.md

# Issues found? Auto-fix in-place
feishu-preview convert docs/my-diagram.md -w

# Generate accurate local preview (same engine as Feishu)
feishu-preview preview docs/my-diagram.md

# View sync status
feishu-preview status docs/my-diagram.md

All Commands

Command	Description
`feishu-preview doctor`	Check and install required dependencies (lark-cli etc.), interactive guided setup
`feishu-preview check <file>`	Check Feishu compatibility (read-only; exit 1 = issues found)
`feishu-preview convert <file> -w`	Fix all incompatible syntax in-place
`feishu-preview convert <file> -o out.md`	Fix and write to a new file (source unchanged)
`feishu-preview preview <file>`	Accurate preview: render via Feishu’s own engine (default)
`feishu-preview preview <file> --fast`	Syntax debug only: Mermaid CDN render — output does NOT match Feishu, not for visual verification
`feishu-preview status <file>`	Show sync state from `.feishu-index.json`

Preview Modes

Mode	Command	Engine	Notes
Accurate (default)	`feishu-preview preview file.md`	`@larksuite/whiteboard-cli`, renders each diagram as PNG	Matches Feishu exactly; required before syncing; network needed on first run
Debug (`--fast`, ⚠️ not for visual verification)	`feishu-preview preview file.md --fast`	Mermaid.js v10 CDN, interactive SVG	Syntax debugging only — browser console shows parse errors; different engine from Feishu, output cannot be used as visual reference

In accurate mode, PNGs are base64-embedded in the HTML output — shareable offline.

Feishu Compatibility Issues

Known differences between standard Mermaid and Feishu’s engine, all handled automatically by check / convert:

Issue	Standard	Feishu requires	Why
Line break	`<br/>`	`<br>`	Feishu’s parser rejects XML self-closing tags
Less-than in Notes	`x < 300s`	`x ＜ 300s` (fullwidth)	Parser treats `<` as HTML tag start; `<` is also broken
State diagram version	`stateDiagram-v2`	`stateDiagram`	Feishu only supports the older layout engine
Multi-line blockquotes	`> line1\n> line2`	`> line1<br>line2`	Feishu concatenates `>` lines with no separator, causing words to run together
Node double-quotes	`A["text"]`	unchanged	Feishu accepts double-quotes; single-quotes trigger a `PS` token error

Sync State File `.feishu-index.json`

After syncing to Feishu, the tool writes .feishu-index.json alongside your .md file, recording each diagram’s whiteboard token for future incremental updates (no need to delete and re-create).

{
  "my-diagram.md": {
    "doc_url": "https://your-org.feishu.cn/docx/Xxxxx",
    "last_synced": "2026-04-20T10:00:00Z",
    "whiteboards": {
      "2.1 Device Registration Sequence": "FY0FwuSKShMWuZbMjX0czKk6nLh"
    }
  }
}

⚠️ This file contains doc URLs and tokens. It’s already in .gitignore — do not commit it.

Requirements

Dependency	Purpose	Install
Node.js ≥ 16	Run all scripts	nodejs.org
Claude Code	Natural language skill interface	claude.ai/code
`feishu-preview`	This tool	`/plugin marketplace add andyliu/feishu-preview`
`@larksuite/whiteboard-cli`	Accurate preview mode (auto-fetched via npx)	Not needed manually
`lark-cli`	Feishu document sync (push only)	`npm install -g @larksuite/lark-cli`

feishu-preview itself has zero npm runtime dependencies — only Node.js built-ins.

Project Structure

feishu-preview/
├── .claude-plugin/
│   └── marketplace.json           # Claude Code plugin marketplace manifest
├── plugins/
│   └── feishu-preview/
│       ├── .claude-plugin/
│       │   └── plugin.json        # Plugin metadata
│       ├── bin/
│       │   ├── feishu-preview     # CLI entry point (the feishu-preview command)
│       │   ├── render-preview.js  # Markdown → HTML preview generator
│       │   └── feishu-compat.js   # Mermaid Feishu compatibility converter
│       └── skills/
│           └── feishu-preview/
│               └── SKILL.md       # Claude Code skill definition
└── package.json

Best Practices

Directory Layout

Keep diagram documents in a dedicated directory so .feishu-index.json is co-located:

docs/
└── diagrams/
    ├── device-flow.md            # Source file — the only place you edit Mermaid
    ├── device-flow.preview.html  # Auto-generated, gitignored, do not commit
    └── .feishu-index.json        # Feishu whiteboard tokens, gitignored, do not commit

Standard Workflow — Never Skip Steps

Every time you edit a diagram, follow this order without skipping:

1. Write / edit Mermaid code in the .md file
2. feishu-preview check      → detect compatibility issues
3. feishu-preview convert -w → auto-fix issues if any
4. feishu-preview preview    → accurate visual verification (required — last check before sync)
5. Tell Claude Code "sync to Feishu"

Local .md Is the Single Source of Truth

Never edit Mermaid content directly in Feishu’s Whiteboard editor — Feishu provides no export function, so any change made there cannot be synced back. You lose version control permanently.
All edits happen in the local .md file. Feishu is display-only.

Git Hygiene

# ✅ Commit this
git add docs/diagrams/device-flow.md

# ❌ Do not commit (already in .gitignore)
# docs/diagrams/device-flow.preview.html
# docs/diagrams/.feishu-index.json

One H2 Heading Per Diagram

Feishu uses headings as anchors for whiteboard placement. Keep a clear H2 heading before each diagram to enable precise iterative updates:

## 2.1 Device Registration Sequence

```mermaid
sequenceDiagram
    ...
```

Accurate Mode vs Debug Mode

When	Command
Final visual verification before sync	`feishu-preview preview file.md` (accurate — required)
Diagram fails to render, need parse error details	`feishu-preview preview file.md --fast` (debug only — output does not represent Feishu)

FAQ

Q: Diagram is blank or shows a red error box in accurate mode?

Switch to fast mode for debugging: feishu-preview preview file.md --fast. The browser console will show detailed Mermaid error messages. Fix the syntax, then switch back to accurate mode to confirm.

Q: I pushed a diagram and want to update it — how?

Edit local .md → feishu-preview check → feishu-preview convert -w → feishu-preview preview to confirm → tell Claude Code “sync to Feishu”.

Q: Does downgrading stateDiagram-v2 to stateDiagram lose functionality?

No impact for most diagrams. The two variants use different internal layout engines but share the same syntax. Common features — states, transitions, notes, concurrency — all work in both.

feishu-preview

feishu-preview

中文文档

这是什么？

快速上手（2 步）

第一步：安装插件

第二步：使用

全部命令

预览模式说明

飞书兼容性问题说明

同步状态文件 .feishu-index.json

环境要求

项目结构

最佳实践

目录结构

标准工作流

本地 .md 是唯一真相来源

Git 提交规范

每个 H2 标题对应一个图表

精确预览 vs 调试模式

常见问题

相关链接

English Documentation

What Is This?

Quick Start (2 steps)

Step 1: Install the Plugin

Step 2: Use It

All Commands

Preview Modes

Feishu Compatibility Issues

Sync State File .feishu-index.json

Requirements

Project Structure

Best Practices

Directory Layout

Standard Workflow — Never Skip Steps

Local .md Is the Single Source of Truth

Git Hygiene

One H2 Heading Per Diagram

Accurate Mode vs Debug Mode

FAQ

Links

同步状态文件 `.feishu-index.json`

Sync State File `.feishu-index.json`