feat：移除了弹窗，服务器添加sls
This commit is contained in:
@ -0,0 +1,60 @@
|
||||
# whiteboard +export（导出画板）
|
||||
|
||||
> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
导出画板内容，支持导出为预览图片、SVG 矢量图、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|----------------------|----|------------------------------------------------------------------------|
|
||||
| `--whiteboard-token` | 是 | 画板 token，需要拥有画板的读权限 |
|
||||
| `--output-type` | 是 | 输出格式：`preview`（预览图片）、`svg`（SVG 矢量图）、`source`（PlantUML/Mermaid 代码）、`raw`（OpenAPI 原生画板节点格式） |
|
||||
| `--output` | 否 | 输出路径。当 `--output-type preview` 时必填，推荐传入无后缀文件路径（如 `./preview`）；当 `--output-type svg/source/raw` 时可选，不填则直接输出到终端 |
|
||||
| `--overwrite` | 否 | 覆盖已存在的文件，默认为 false |
|
||||
|
||||
## 输出格式
|
||||
|
||||
- `preview`：预览图片。推荐 `--output ./preview` 这类无后缀文件路径，CLI 会按实际图片类型保存为 `./preview.png` 或 `./preview.jpg`。如果 `--output` 是目录，会保存为该目录下的 `whiteboard_<whiteboard-token>.png/.jpg`；如果显式写了后缀，需要和实际图片类型匹配。`--overwrite` 检查的是补齐后缀后的最终路径，例如返回 PNG 时 `--output ./preview` 对应覆盖 `./preview.png`。
|
||||
- `svg`：导出画板为标准 SVG 矢量图。可用于 SVG 编辑后回写画板（见 [`routes/svg-edit.md`](../routes/svg-edit.md)）。注意：导出为纯视觉快照，思维导图层级、表格结构、连接器绑定等语义信息会丢失。
|
||||
- `source`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
|
||||
- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)。
|
||||
|
||||
## 示例
|
||||
|
||||
### 示例 1：导出画板为预览图片
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output-type preview \
|
||||
--output ./preview
|
||||
```
|
||||
|
||||
### 示例 2：提取画板中的代码并直接输出
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output-type source
|
||||
```
|
||||
|
||||
### 示例 3：导出画板为 SVG 矢量图
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output-type svg \
|
||||
--output ./whiteboard.svg \
|
||||
--as user
|
||||
```
|
||||
|
||||
### 示例 4：导出画板原始节点结构到文件
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output-type raw \
|
||||
--output ./nodes.json \
|
||||
--overwrite
|
||||
```
|
||||
@ -0,0 +1,122 @@
|
||||
# whiteboard +update（更新画板）
|
||||
|
||||
> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
更新画板内容，支持四种输入格式：
|
||||
|
||||
- `raw`：飞书 OpenAPI 原生画板节点格式，不推荐直接编辑。
|
||||
- `plantuml`：PlantUML 代码
|
||||
- `mermaid`：Mermaid 代码
|
||||
- `svg`：SVG 文本
|
||||
|
||||
输入内容可以通过管道从 stdin 读取，或通过 `--source` 指定文件。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|----------------------|----|--------------------------------------------|
|
||||
| `--whiteboard-token` | 是 | 画板 token，需要拥有画板的编辑权限 |
|
||||
| `--idempotent-token` | 否 | 幂等 token，确保更新操作幂等；最少 10 个字符，建议使用时间戳 + 场景标识拼接（如 `1744800000-board-1`）。同一次逻辑更新只生成一次该 token，重试时须原样复用；切勿在每次重试时重新生成时间戳或幂等 key，否则会重复写入 |
|
||||
| `--overwrite` | 否 | 覆盖更新，在更新前删除所有现有内容，默认为 false |
|
||||
| `--source` | 是 | 输入画板内容，支持使用 `@path` 从文件读取，或 `-` 从 stdin 读取 |
|
||||
| `--input_format` | 否 | 输入格式：`raw`、`plantuml`、`mermaid`、`svg`，默认为 `raw` |
|
||||
|
||||
### 以 raw (OpenAPI 原生画板节点格式) 创作
|
||||
|
||||
**不要以直接生成 json 语法的方式创作 raw 格式的飞书 OpenAPI 原生画板节点参数**
|
||||
|
||||
思维导图，时序图，类图，饼图，流程图等图表推荐使用 Mermaid/PlantUML 语法绘制。
|
||||
|
||||
而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。
|
||||
|
||||
## 示例
|
||||
|
||||
### 示例 1：使用 PlantUML 代码更新画板（从 stdin 读取）
|
||||
|
||||
```bash
|
||||
# 编写 PlantUML 代码
|
||||
cat > diagram.puml << 'EOF'
|
||||
@startuml
|
||||
Alice -> Bob: Hello
|
||||
Bob -> Alice: Hi
|
||||
@enduml
|
||||
EOF
|
||||
|
||||
# 通过管道传递给命令
|
||||
cat diagram.puml | lark-cli whiteboard +update \
|
||||
--whiteboard-token <画板Token> \
|
||||
--input_format plantuml --source -\
|
||||
--overwrite --as user
|
||||
```
|
||||
|
||||
### 示例 2：使用 Mermaid 代码更新画板（从文件读取）
|
||||
|
||||
```bash
|
||||
# 编写 Mermaid 代码
|
||||
cat > diagram.mmd << 'EOF'
|
||||
graph TD
|
||||
A[开始] --> B{判断}
|
||||
B -->|是| C[处理]
|
||||
B -->|否| D[结束]
|
||||
C --> D
|
||||
EOF
|
||||
|
||||
# 从文件读取并更新
|
||||
lark-cli whiteboard +update \
|
||||
--whiteboard-token <画板Token> \
|
||||
--input_format mermaid \
|
||||
--source @./diagram.mmd \
|
||||
--overwrite --as user
|
||||
```
|
||||
|
||||
### 示例 3：使用 whiteboard-cli 生成 OpenAPI 格式并写入画板
|
||||
|
||||
whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
|
||||
|
||||
```bash
|
||||
# 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 -i <产物文件> --to openapi --format json \
|
||||
| lark-cli whiteboard +update \
|
||||
--whiteboard-token <画板Token> \
|
||||
--source - --input_format raw \
|
||||
--idempotent-token <10+字符唯一串> \
|
||||
--as user
|
||||
```
|
||||
|
||||
### 示例 4：先生成产物文件，再从文件读取更新
|
||||
|
||||
whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
|
||||
|
||||
```bash
|
||||
# 生成 OpenAPI 格式到文件
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 -i <DSL 文件> --to openapi --format json -o ./temp.json
|
||||
|
||||
# 从文件读取并更新
|
||||
lark-cli whiteboard +update \
|
||||
--whiteboard-token <画板Token> \
|
||||
--idempotent-token <10+字符唯一串> \
|
||||
--input_format raw \
|
||||
--source @./temp.json \
|
||||
--overwrite --as user
|
||||
```
|
||||
|
||||
### 示例 5：使用 SVG 写入画板（从文件读取）
|
||||
|
||||
适用于从零创建（直接写入 SVG）和编辑现有画板（编辑工作流详见 [`../routes/svg-edit.md`](../routes/svg-edit.md)）。
|
||||
|
||||
```bash
|
||||
# 编写或导出 SVG 文件
|
||||
cat > diagram.svg << 'EOF'
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
|
||||
<rect x="10" y="10" width="80" height="40" fill="#4A90E2"/>
|
||||
<text x="50" y="35" text-anchor="middle" fill="#fff">Hello</text>
|
||||
</svg>
|
||||
EOF
|
||||
|
||||
# 从文件读取并更新
|
||||
lark-cli whiteboard +update \
|
||||
--whiteboard-token <画板Token> \
|
||||
--input_format svg \
|
||||
--source @./diagram.svg \
|
||||
--overwrite --as user
|
||||
```
|
||||
@ -0,0 +1,87 @@
|
||||
# 画板创作/修改工作流
|
||||
|
||||
## 创作 Workflow
|
||||
|
||||
> 此 workflow 用于**独立创作一个画板**。
|
||||
> 需要在文档中批量创建多个画板时，由 lark-doc 负责调度，见 `lark-doc` 技能的 `references/lark-doc-whiteboard.md`。
|
||||
|
||||
**Step 1：获取 board_token**
|
||||
|
||||
| 用户给了什么 | 怎么获取 |
|
||||
|---|---|
|
||||
| 直接给了 whiteboard token（`wbcnXXX`）| 直接使用 |
|
||||
| 文档 URL 或 doc_id，文档中已有画板 | `lark-cli docs +fetch --doc <URL> --as user`，从返回的 `<whiteboard token="xxx"/>` 提取 |
|
||||
| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --doc <doc_id> --command append --content '<whiteboard type="blank"></whiteboard>' --as user`，从响应 `data.new_blocks[0].block_token` 取得（`block_type == "whiteboard"` 的那条；参数详见 lark-doc SKILL.md）|
|
||||
|
||||
**Step 2：渲染 & 写入**
|
||||
|
||||
→ 进入 **[§ 渲染 & 写入画板](#渲染--写入画板)** 章节，按流程完成后直接返回结果给用户。
|
||||
|
||||
---
|
||||
|
||||
## 修改 Workflow
|
||||
|
||||
**Step 1：获取 board_token**（同创作 Workflow Step 1）
|
||||
|
||||
**Step 2：判断修改策略**
|
||||
|
||||
```
|
||||
+export --output-type source
|
||||
├─ 返回 Mermaid/PlantUML 代码
|
||||
│ → 在原代码上修改 → +update --input_format mermaid/plantuml
|
||||
├─ 无代码（SVG/DSL 或其他方式绘制的画板）
|
||||
│ ├─ 需纯新增（思维导图、流程图、时序图、类图、饼图、甘特图）图表节点
|
||||
│ │ → +export --output-type preview → 看图 → +export --output-type raw → 确定新节点坐标和层级 → [§ 渲染 & 写入画板]
|
||||
│ └─ 其他改动（几何变动/增删元素/结构调整/混合编辑等）
|
||||
│ → [`../routes/svg-edit.md`](../routes/svg-edit.md)（视觉高保真还原，大部分场景适用）
|
||||
└─ 用户有明确要求 → 以用户要求优先
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 渲染 & 写入画板
|
||||
|
||||
### 渲染路由
|
||||
|
||||
**先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。
|
||||
|
||||
**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
|
||||
|
||||
按上到下匹配, 命中即停:
|
||||
|
||||
| 图表类型 | 身份 | 路径 |
|
||||
|--------------------|-------------------------------------|------------------------------------------------|
|
||||
| 思维导图、时序图、类图、饼图、甘特图 | 任何身份 | [`../routes/mermaid.md`](../routes/mermaid.md) |
|
||||
| 鱼骨图、金字塔图、流程图 | `Doubao` / `Seed` | [`../routes/dsl.md`](../routes/dsl.md) |
|
||||
| 其他图表 | `Claude` / `Gemini` / `GPT` / `GLM` / `Doubao` / `Seed` | [`../routes/svg.md`](../routes/svg.md) |
|
||||
| 其他图表 | `Other` | [`../routes/dsl.md`](../routes/dsl.md) |
|
||||
|
||||
> **⚠️ SVG 路径失败回退**：走 `routes/svg.md` 时，碰到以下情况之一 → **丢弃当前 SVG，改读 `routes/dsl.md` 从零重画，不要逐行修补**：
|
||||
> - 渲染命令直接报错（语法级崩溃，不是 `--check` 的 warn/error）
|
||||
> - 两轮改写仍无法消除 `--check` 的 `text-overflow` error
|
||||
> - 目测 PNG 视觉严重错乱（文字大面积溢出、元素重叠压住关键信息、布局整体崩溃）
|
||||
>
|
||||
> SVG 源码修补常常引入新 bug，换 DSL 从零重画往往更稳。这是 SVG 路径自由发挥的硬兜底，不要侵入 `routes/svg.md` 的创作流程。
|
||||
|
||||
### 产物规范
|
||||
|
||||
产物目录：`./diagrams/YYYY-MM-DDTHHMMSS/`（本地时间，不含冒号和时区后缀）。如用户指定路径，以用户为准。
|
||||
|
||||
目录内固定文件名：
|
||||
|
||||
```
|
||||
diagram.svg ← SVG 源码（SVG 路径）
|
||||
diagram.mmd ← Mermaid 源码（Mermaid 路径）
|
||||
diagram.json ← DSL 源文件（DSL 路径） / OpenAPI JSON（SVG 路径从 diagram.svg 导出）
|
||||
diagram.gen.cjs ← 坐标计算脚本（仅 DSL 脚本构建方式）
|
||||
diagram.png ← 渲染结果
|
||||
```
|
||||
|
||||
### 写入画板
|
||||
|
||||
写入画板时按最终产物类型选择 `+update --input_format`：
|
||||
|
||||
- Mermaid / PlantUML / SVG 产物直接用对应的 `mermaid` / `plantuml` / `svg` 写入。
|
||||
- 只有 DSL 产物或已明确需要 OpenAPI 原生节点格式时，才先用 `npx -y @larksuite/whiteboard-cli@^0.2.13 --to openapi --format json` 转换，再用 `raw` 写入。
|
||||
|
||||
具体命令示例、`--overwrite`、`--idempotent-token` 和 `--as user/bot` 的使用方式，统一参考 [`whiteboard +update`](./lark-whiteboard-update.md)。
|
||||
Reference in New Issue
Block a user