@amaster.ai/pi-lark 0.1.6 → 0.1.8

package/skills/lark-drive/references/lark-drive-comments-guide.md

@@ -1,80 +0,0 @@
-# Drive 评论查询、统计与回复指南
-
-> 前置条件：先阅读 [`../SKILL.md`](../SKILL.md) 的“评论能力入口”，添加评论参数细节见 [`lark-drive-add-comment.md`](lark-drive-add-comment.md)，获取评论列表优先使用 [`lark-drive-list-comments.md`](lark-drive-list-comments.md)，reaction 见 [`lark-drive-reactions.md`](lark-drive-reactions.md)。
-
-## 评论模式
-
-- `drive +add-comment` 支持全文评论和局部评论。
-- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc` / `docx` / `file` 的 wiki URL。
-- 局部评论：传 `--block-id` 时启用；`docx` 支持文本定位或 block id，`sheet` 支持 `<sheetId>!<cell>`，`slides` 支持 `<slide-block-type>!<xml-id>`，wiki URL 解析到这些类型时也支持对应局部评论。
-- Drive file 只支持全文评论，不支持局部评论。支持扩展名：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件暂不支持。
-- Review / 审阅 / 校对 / 逐条指出问题场景优先使用局部评论，不要把多个可定位问题汇总成一条全文评论。
-- `drive +add-comment` 的 `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。
-- `slides` 评论要求显式传 `--block-id <slide-block-type>!<xml-id>`；CLI 会将其拆分后写入 `anchor.block_id` 和 `anchor.slide_block_type`。其中 `<xml-id>` 是 PPT XML 协议中的元素 `id`；不支持 `--selection-with-ellipsis` 和 `--full-comment`。
-- 评论写入内容里的文本不能直接出现 `<`、`>`；提交前应转义为 `&lt;`、`&gt;`。`drive +add-comment` 会对 `type=text` 文本元素自动兜底转义；直接调用原生评论 API 时需要自行转义。
-- 如果 wiki 解析后不是 `doc` / `docx` / `file` / `sheet` / `slides`，不要用 `+add-comment`。
-
-## 查询默认口径
-
-优先使用 `drive +list-comments`，不要优先手写 `drive file.comments list`。shortcut 默认 `--solved-status false`，即仅查询未解决评论。即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确提到包含已解决评论，仍然按默认口径查询未解决评论；仅当用户明确要求包含已解决评论时，才传 `--solved-status all`。只查已解决评论时传 `--solved-status true`。
-
-```bash
-# 默认查询：仅未解决评论
-lark-cli drive +list-comments --url '<DOC_URL>'
-
-# 全部评论：包含已解决和未解决
-lark-cli drive +list-comments --url '<DOC_URL>' --solved-status all
-
-# 已解决评论
-lark-cli drive +list-comments --url '<DOC_URL>' --solved-status true
-
-# 裸 wiki token
-lark-cli drive +list-comments --token '<WIKI_TOKEN>' --type wiki
-
-```
-
-## 评论卡片与统计
-
-- `drive file.comments list` 返回的 `items` 是评论卡片列表，每个 `item` 对应用户界面中的一张评论卡片，不是平铺的互动消息列表。
-- 创建第一条评论时会同时创建该卡片里的第一条 reply；真正承载正文的是 `item.reply_list.replies`，其中第一条 reply 在用户视角下就是这张卡片里的“评论本身”。
-- 统计“评论数”或“评论卡片数”：统计 `items` 长度；全量统计时对所有分页返回的 `items` 长度累加。
-- 统计“回复数”：统计所有 `item.reply_list.replies` 长度之和，再减去 `items` 长度。
-- 统计“总互动数”：统计所有 `item.reply_list.replies` 长度之和，包含每张评论卡片里的首条评论。
-- 如果 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中；需要继续调用 `drive file.comment.replys list` 拉全后，再做全量回复数或总互动数统计。
-
-## 排序
-
-- 只有当用户明确提到“最新评论”“最后评论”“最早评论”时，才需要按 `create_time` 排序。
-- 排序前必须拉完所有评论分页，不能只取第一页。
-- “最新评论”/“最后评论”：按 `create_time` 降序取第一条。
-- “最早评论”：按 `create_time` 升序取第一条。
-- 用户只说“第一条评论”时，直接使用 `drive file.comments list` 返回的第一条，不需要额外排序。
-
-## 回复限制
-
-- 回复前先检查目标评论状态。
-- `is_whole=true` 的全文评论不支持回复；遇到时提示“全文评论不支持回复”。
-- `is_solved=true` 的已解决评论不支持回复；遇到时提示“该评论已被解决，无法回复”。
-- 当目标评论不能回复时，只提示限制，不要自动替用户寻找其他可回复评论。
-
-## batch_query 与 list
-
-- `drive file.comments batch_query` 用于已知评论 ID 后的批量查询，需要传入具体评论 ID 列表。
-- `drive +list-comments` 用于分页获取评论列表；如果要统计全量评论数、遍历包含已解决评论在内的所有评论、获取全量最新评论或最后 N 条评论，请先传 `--solved-status all` 并拉完所有分页。它会处理 URL、wiki token 和 token/type 匹配问题。
-- `drive file.comments list` 是原生命令。需要 shortcut 未暴露的字段时才使用。
-
-## 评论定位字段
-
-- 需要根据评论定位到文档正文位置时（例如根据评论 review 文档、区分多处相同引用文本、把评论落点映射到 `docs +fetch` 的 block），先确认目标是 `file_type=docx`，再阅读 [`lark-drive-comment-location.md`](lark-drive-comment-location.md)，并使用 `drive +list-comments --need-relation`。
-- `--need-relation` 仅 docx 生效；其他文档类型会静默忽略。
-
-## 原生 API
-
-需要更底层地直接调用评论 V2 协议时，先查看 schema，再调用原生命令。全文评论省略 `anchor`，局部评论传 `anchor.block_id`。
-
-```bash
-lark-cli schema drive.file.comments.create_v2
-lark-cli drive file.comments create_v2 \
-  --params '{"file_token":"<DOC_TOKEN>"}' \
-  --data '{"file_type":"docx","reply_elements":[{"type":"text","text":"全文评论内容"}]}'
-```

package/skills/lark-slides/references/examples.md

@@ -1,91 +0,0 @@
-# 完整操作示例
-
-本文档提供与 CLI schema 一致的调用示例，XML 内容均遵循 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
-
-> **重要**：新建 PPT 请使用 `slides +create --slides`，传入由 `<slide>` XML 字符串组成的 JSON 数组；每个元素必须是一页完整的 `<slide>`。复杂内容建议先创建空白 PPT，再通过 `xml_presentation.slide.create` 逐页添加。完整 `<presentation>` XML 可用于本地 lint 或读取，但不能直接作为 `+create` 的提交参数。
-
-## 目录
-
-- [示例 1：可靠创建 6 页 PPT](#示例-1可靠创建-6-页-ppt)
-- [示例 7: +replace-slide + block_insert 给已有页加图](#示例-7-replace-slide--block_insert-给已有页加图)
-- [示例 8: +replace-slide + block_replace 替换一个块](#示例-8-replace-slide--block_replace-替换一个块)
-
-## 示例 1：可靠创建 6 页 PPT
-
-### 1. 写入规划文件
-
-```bash
-DECK_DIR=".lark-slides/plan/reliable-six-page-ppt"
-mkdir -p "$DECK_DIR"
-
-# 按 planning-layer.md 写入 "$DECK_DIR/slide_plan.json"，
-# 至少记录 6 页的顺序和标题。
-```
-
-### 2. 为每页保存独立 XML
-
-每个文件都是完整的 `<slide>`。下面的循环会生成 6 个独立 XML 文件；实际项目中可将每页主体替换为规划内容。
-
-```bash
-titles=("主题与结论" "问题背景" "核心方法" "关键数据" "执行计划" "总结与行动")
-for i in {1..6}; do
-  printf -v page '%02d' "$i"
-  cat > "$DECK_DIR/slide-$page.xml" <<XML
-<slide xmlns="http://www.larkoffice.com/sml/2.0"><style><fill><fillColor color="rgb(248,250,252)"/></fill></style><data><shape type="rect" topLeftX="56" topLeftY="56" width="12" height="428"><fill><fillColor color="rgb(37,99,235)"/></fill></shape><shape type="text" topLeftX="100" topLeftY="160" width="760" height="90"><content textType="title" autoFit="normal-auto-fit"><p>${titles[$((i-1))]}</p></content></shape><shape type="text" topLeftX="100" topLeftY="290" width="700" height="70"><content textType="body" autoFit="normal-auto-fit"><p>页面主体内容。</p></content></shape></data></slide>
-XML
-done
-```
-
-### 3. 逐页运行 lint
-
-提交前检查每个独立 XML。`summary.error_count` 必须为 `0`，否则先修复 XML 或布局问题。
-
-```bash
-for slide_xml in "$DECK_DIR"/slide-0{1,2,3,4,5,6}.xml; do
-  python3 skills/lark-slides/scripts/xml_text_overlap_lint.py \
-    --input "$slide_xml" | tee "${slide_xml%.xml}.lint.json"
-done
-
-test "$(jq -s 'map(.summary.error_count) | add' "$DECK_DIR"/slide-0{1,2,3,4,5,6}.lint.json)" = "0"
-```
-
-### 4. 使用 `+create` 创建 6 页 PPT
-
-`--slides` 接收由 6 个完整 `<slide>` XML 字符串组成的 JSON 数组；使用 `jq --rawfile` 避免手动处理 XML 引号和换行。
-
-```bash
-lark-cli slides +create --as user \
-  --title "可靠创建 6 页 PPT" \
-  --slides "$(jq -n \
-    --rawfile s1 "$DECK_DIR/slide-01.xml" \
-    --rawfile s2 "$DECK_DIR/slide-02.xml" \
-    --rawfile s3 "$DECK_DIR/slide-03.xml" \
-    --rawfile s4 "$DECK_DIR/slide-04.xml" \
-    --rawfile s5 "$DECK_DIR/slide-05.xml" \
-    --rawfile s6 "$DECK_DIR/slide-06.xml" \
-    '[$s1, $s2, $s3, $s4, $s5, $s6]')" \
-  > "$DECK_DIR/create.json"
-create_status=$?
-
-if [ "$create_status" -ne 0 ]; then
-  exit "$create_status"
-fi
-
-if ! PRESENTATION_ID=$(jq -er '.data.xml_presentation_id | strings | select(length > 0)' "$DECK_DIR/create.json"); then
-  echo "missing non-empty data.xml_presentation_id in $DECK_DIR/create.json" >&2
-  exit 1
-fi
-echo "$PRESENTATION_ID" > "$DECK_DIR/xml_presentation_id"
-```
-
-如果创建中途失败，先保存已经返回的 `xml_presentation_id`，再回读确认实际已创建页数。
-
-### 5. 用 `+xml-get` 回读全文 XML
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PRESENTATION_ID" \
-  --output "$DECK_DIR/readback.xml" \
-  --json | tee "$DECK_DIR/readback.json"
-```
-

package/skills/lark-slides/references/lark-slides-replace-pages.md

@@ -1,95 +0,0 @@
-# slides +replace-pages（多页整页重建）
-
-批量替换已有演示文稿里的多个页面，保持原 `xml_presentation_id` 和原 Slides 链接不变。适合多页版式大改、坐标重排、整页视觉重建；单个文本框、图片或 shape 的局部编辑仍优先用 [`+replace-slide`](lark-slides-replace-slide.md)。
-
-> 重要：这是多步编排，不是后端原子事务。CLI 对每页执行“先创建新页到旧页前，再删除旧页”；创建失败时旧页会保留。删除失败时可能出现新旧页同时存在，需要按返回结果继续处理。
-
-## 命令
-
-```bash
-lark-cli slides +replace-pages \
-  --as user \
-  --presentation <slides_url_or_xml_presentation_id> \
-  --pages @pages.json
-```
-
-## 参数
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
-| `--pages` | 是 | JSON 数组，每项包含 `slide_id` 和 `content`；支持 literal、`@file`、stdin `-` |
-| `--dry-run` | 否 | 基于 `slide_id` 输入输出替换计划，不执行 create/delete |
-| `--continue-on-error` | 否 | 默认失败即停；开启后继续处理后续页，并在结果中标记失败项 |
-| `--validate-only` | 否 | 只校验输入并生成替换计划，不执行 Slides get/create/delete |
-
-## pages.json
-
-```json
-[
-  {
-    "slide_id": "slide_short_id_1",
-    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"
-  },
-  {
-    "slide_id": "slide_short_id_2",
-    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"
-  }
-]
-```
-
-规则：
-
-- 每项必须提供 `slide_id`；不支持 `slide_number`。
-- `content` 必须是完整 `<slide>...</slide>` XML。
-- 同一批次不能重复 `slide_id`。
-- CLI 不会回读整份 presentation；如果 `slide_id` 已失效，create/delete 阶段会返回对应错误。
-
-## Dry Run
-
-```bash
-lark-cli slides +replace-pages --as user \
-  --presentation "$PID" \
-  --pages @pages.json \
-  --dry-run
-```
-
-输出包含 `xml_presentation_id`、`pages_count`、`plan`，以及每页的 `old_slide_id`、`insert_before_slide_id` 和动作 `create_before_then_delete_old`。Dry-run 只基于输入的 `slide_id` 构造计划，不会调用 `xml_presentations.get`，也不会执行 create/delete。
-
-## 成功输出
-
-```json
-{
-  "xml_presentation_id": "xxx",
-  "pages_count": 2,
-  "status": "completed",
-  "summary": {
-    "replaced": 2,
-    "failed": 0,
-    "total": 2
-  },
-  "results": [
-    {
-      "old_slide_id": "old3",
-      "new_slide_id": "new3",
-      "status": "replaced"
-    }
-  ],
-  "revision_id": 123
-}
-```
-
-如果使用 `--continue-on-error` 且任一页面失败，CLI 会继续处理后续页，但最终以 partial failure 非零退出；stdout 仍保留完整 `results`，顶层 `ok` 为 `false`，`status` 为 `partial_failure`。
-
-`status` 可能为：
-
-- `replaced`：新页创建成功，旧页删除成功。
-- `create_failed`：新页创建失败，旧页保留。
-- `delete_failed`：新页已创建，但旧页删除失败。
-
-## 使用建议
-
-1. 大幅改写前先 `slides +xml-get` 保存当前 XML，并记录要替换页面的 `slide_id`。
-2. 生成只含 `slide_id` 的 `pages.json` 后先跑 `--dry-run` 或 `--validate-only`。
-3. 默认不要开 `--continue-on-error`，除非能接受部分页面已替换。
-4. 替换后再回读全文 XML 并截图检查，确认页序、视觉和文本没有破损。

package/skills/lark-slides/references/lark-slides-whiteboard.md

@@ -1,331 +0,0 @@
-# Whiteboard 画板元素
-
-`<whiteboard>` 放在 `<data>` 内，内部可放 **SVG** 或 **Mermaid**，用于绘制流程图、时序图、架构图、散点图、漏斗图、自定义图标、装饰图案等 `<chart>` 和 `<shape>` 难以覆盖的视觉内容。
-
-普通柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图和组合图应优先使用原生 `<chart>`。除非用户明确要求像素级自定义，或图表类型确实不受 `<chart>` 支持，否则不要用 `<whiteboard>` + SVG / Mermaid 重画这些标准图表。
-
-> 前置条件：使用本文档前先阅读 [lark-slides SKILL.md](../SKILL.md)。
-
----
-
-## `<chart>` 还是 `<whiteboard>`？
-
-**先判断内容类型，再进入本文档：**
-
-| 场景 | 推荐元素 |
-|------|---------|
-| 有结构化数据序列的柱/条/折线/面积/雷达/饼/环/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
-| 散点图、漏斗图（`<chart>` 不支持）或其他非原生数据视觉 | `<whiteboard>` SVG |
-| 流程图、时序图、架构图、类图、ER 图等拓扑图 | `<whiteboard>` Mermaid 或 SVG |
-| 自定义图标、徽标、示意性图形（需要 path/polygon 精确控制） | `<whiteboard>` SVG |
-| 进度条、波浪背景、装饰图案、像素级自定义可视化 | `<whiteboard>` SVG |
-
-> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG / Mermaid 手绘——原生渲染更省力、结构更稳定，也更容易被回读和后续编辑。
-
----
-
-## whiteboard 公共属性
-
-| 属性 | 必需 | 说明 |
-|------|------|------|
-| `topLeftX` | 是 | 左上角 X 坐标（slide 坐标系，slide 默认宽 960） |
-| `topLeftY` | 是 | 左上角 Y 坐标（slide 坐标系，slide 默认高 540） |
-| `width` | 是 | 画板宽度（像素） |
-| `height` | 是 | 画板高度（像素） |
-
-> SVG 模式下 `<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`；内容大小由子元素包围盒决定，`width`/`height`/`viewBox` 不影响渲染（仅当元素属性使用百分比值时需要 `viewBox` 提供计算基准）。Mermaid 模式不需要额外属性。
-
-SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标系无关。
-
----
-
-## SVG 还是 Mermaid？
-
-选择分三步：**先排除原生 `<chart>`，再判断 whiteboard 类型，最后看当前模型身份**。
-
-### 第一步：先确认是否应该使用 `<chart>`
-
-如果内容是柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图或组合图，返回使用原生 `<chart>`，不要继续套用本文档的 SVG / Mermaid 路径。
-
-### 第二步：whiteboard 类型优先判断
-
-以下类型**推荐 Mermaid**，自动布局、代码简洁；如需精确匹配品牌配色或自定义节点样式，可改用 SVG：
-
-| 图表类型 | Mermaid 关键字 |
-|----------|--------------|
-| 流程图、决策树、架构图 | `flowchart TD` / `flowchart LR` |
-| 时序图 | `sequenceDiagram` |
-| 类图 | `classDiagram` |
-| 甘特图 | `gantt` |
-| 状态图 | `stateDiagram-v2` |
-| 思维导图 | `mindmap` |
-| ER 图 | `erDiagram` |
-
-### 第三步：非原生图表与装饰元素按模型身份选路径
-
-上表以外的场景（散点图、漏斗图、进度条、时间线、波浪背景、星点纹理等）需要精确控制坐标和配色，SVG 表达力更强，但各模型生成 SVG 的能力有差异：
-
-| 模型身份 | 路径 |
-|----------|------|
-| Claude / Gemini / GPT / GLM | **SVG** — 精确控制坐标、颜色、透明度 |
-| Doubao / Seed / Other | **Mermaid** — 用 `gantt`、`flowchart` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
-
-> **先自报身份再选路径**：在决定使用 SVG 之前，确认当前模型属于哪一类。不要跳过这一步。
-
----
-
-## 模式一：SVG
-
-### ⚠️ 设计品质要求
-
-在 slide 里嵌入 `<whiteboard>` 的目的是**表达原生 `<chart>` 或基础 `<shape>` 难以覆盖的视觉关系**，不是把标准数据图表手绘一遍。
-
-- **不要只用矩形加文字应付**：通篇纯白底色 + 方块 + 黑字等于白做，这是不及格输出
-- **非原生数据视觉必须有坐标系**：散点、漏斗等仍要有必要的坐标轴、刻度、数值标注或分段说明，不要只画点或色块
-- **字号必须有层级**：标题 ≠ 标签 ≠ 数值，混用同一字号会消灭视觉焦点
-- **配色要与 slide 主题呼应**：深色 slide 背景下图表用透明底或深色卡片；浅色背景下避免再加纯白底块
-- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、清晰分组、节点状态等细节拉开与默认模板的差距
-- **写 SVG 前先判断背景亮度**：背景亮度 < 30% 时，装饰元素"对比不足"比"过强"危害更大，宁重勿轻；
-- **装饰层次用亮度跳跃，不用线性叠透明度**：`α=0.04→0.08→0.12` 的等差递增在深色底上几乎看不出差异（相邻层亮度差 ≈20）；正确做法是非线性跳跃如 `0.10→0.40→0.70→1.0`，相邻层亮度差 ≥60。
-
-### 语法
-
-```xml
-<whiteboard width="400" height="300" topLeftX="500" topLeftY="120">
-  <svg xmlns="http://www.w3.org/2000/svg">
-    <rect x="50" y="50" width="80" height="200" rx="4" fill="rgba(59,130,246,0.85)"/>
-    <text x="90" y="270" text-anchor="middle" font-size="12" fill="rgba(100,116,139,1)">ABC</text>
-  </svg>
-</whiteboard>
-```
-
-`<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`；`width`/`height`/`viewBox` 无需填写，若元素属性使用百分比值则需额外声明 `viewBox`。
-
-### ⚠️ 渲染包围盒规则
-
-whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内容区域，自适应缩放到容器。
-
-`<svg>` 上的 `width`、`height`、`viewBox` 不影响内容区域的计算，但 `viewBox` 有一个实际用途：**为百分比属性提供计算基准**。若元素使用 `width="50%"` 等百分比值，必须声明 `viewBox` 才能正确解析；绝对坐标元素则无需关心。推荐统一使用绝对坐标，避免引入百分比依赖。
-
-### 支持的 SVG 元素
-
-| 元素 | 说明 | 典型用途 |
-|------|------|---------|
-| `<rect>` | 矩形，支持 `rx` 圆角 | 卡片、进度条、分段色块 |
-| `<circle>` | 圆 | 节点、装饰点、环形图 |
-| `<ellipse>` | 椭圆 | 自定义轮廓图形 |
-| `<line>` | 直线 | 轴线、分隔线、连接线 |
-| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、曲线、弧形 |
-| `<text>` | 文本，支持中文 | 标签、数值 |
-| `<polygon>` | 多边形 | 箭头、星形、面积填充 |
-| `<g>` | 分组 | 批量变换、语义分组 |
-| `<linearGradient>` | 线性渐变定义，配合 `fill="url(#id)"` 使用 | 渐变背景、渐变填充 |
-
-**颜色：** 统一用 `rgba(R,G,B,A)`，对深浅背景都友好。  
-**虚线：** `stroke-dasharray="4,4"` 用于网格线 / 坐标轴。  
-**变换：** `transform="translate(x,y)"` / `rotate(deg cx cy)` / `scale(n)` 均支持。
-
----
-### 元素计算
-
-SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围包括散点、漏斗、装饰性点阵、等间距圆、重复图案等；普通柱状图、折线图、饼图仍应回到原生 `<chart>`。
-
-> **主动去算**：写 SVG 之前先运行脚本，把输出当注释贴在 `<svg>` 开头，再照着填坐标。估值几乎每次都需要反复调整，跳过这步反而更慢。
-
-**散点图 / 装饰性点阵范式**
-
-```python
-W, H = 360, 260
-origin_x, origin_y = 50, 216  # 左下角，SVG Y 轴向下
-cw, ch = 290, 184
-
-points = [(12, 40), (28, 80), (45, 65)]
-x_min, x_max, y_min, y_max = 0, 50, 0, 100
-for i, (xv, yv) in enumerate(points):
-    x = round(origin_x + (xv - x_min) / (x_max - x_min) * cw)
-    y = round(origin_y - (yv - y_min) / (y_max - y_min) * ch)
-    print(f"point-{i}: cx={x} cy={y}")
-```
-
-**装饰性元素（等间距范式）**
-
-```python
-n, total_w, cy, r = 8, 340, 40, 4
-step = total_w / (n - 1)
-for i in range(n):
-    print(f"circle-{i}: cx={round(i * step)} cy={cy} r={r}")
-```
-
-**最大包围盒 → whiteboard 尺寸**
-
-所有元素坐标算完后，汇总出整体包围盒，直接作为 whiteboard 的 `width`/`height`：
-
-```python
-# 每个元素登记 (x, y, w, h)，含 stroke 外扩
-elements = [
-    (10, 20, 80, 160),   # item-0
-    (107, 10, 80, 170),  # item-1
-    (204, 40, 80, 140),  # item-2
-    (0, 0, 300, 1),      # x-axis
-]
-
-xs = [x for x, y, w, h in elements]
-ys = [y for x, y, w, h in elements]
-x2 = [x + w for x, y, w, h in elements]
-y2 = [y + h for x, y, w, h in elements]
-
-wb_w = max(x2) - min(xs)
-wb_h = max(y2) - min(ys)
-print(f"whiteboard width={wb_w} height={wb_h}")
-```
-
-输出即 `<whiteboard width=... height=...>` 的值，无需手动估算。
-
----
-### 布局模式
-
-**全屏装饰层**
-```xml
-<whiteboard width="960" height="540" topLeftX="0" topLeftY="0">
-  <svg xmlns="http://www.w3.org/2000/svg">
-    ...
-  </svg>
-</whiteboard>
-```
-
-> ⚠️ 全屏装饰 whiteboard 必须放在所有 `<shape>` / `<img>` / `<table>` 之前，否则会遮挡文字内容。XML 中元素位置越靠后，渲染层级越高。
-
-**侧栏图表（与文字 shape 并排）**
-```xml
-<!-- 左侧文字 -->
-<shape type="text" topLeftX="60" topLeftY="120" width="500" height="340">...</shape>
-<!-- 右侧图表 -->
-<whiteboard width="340" height="340" topLeftX="580" topLeftY="120">
-  <svg xmlns="http://www.w3.org/2000/svg">
-    ...
-  </svg>
-</whiteboard>
-```
-
-**底部装饰条**
-```xml
-<whiteboard width="960" height="100" topLeftX="0" topLeftY="440">
-  <svg xmlns="http://www.w3.org/2000/svg">
-    ...
-  </svg>
-</whiteboard>
-```
-
----
-
-### 禁止使用的 SVG 特性
-
-以下特性在 slide `<whiteboard>` 渲染端不支持或行为不可预测，必须避免：
-
-| 禁止 | 原因 | 替代方案 |
-|------|------|---------|
-| `<radialGradient>` | 渲染失败 | 用 `<linearGradient>` 或 `rgba()` 透明度模拟深浅层次 |
-| `<filter>`（阴影、模糊等） | 渲染失败 | 用半透明 `<rect>` 叠加模拟阴影 |
-| `<clipPath>` / `<mask>` | 渲染失败 | 调整元素坐标和尺寸自然裁切 |
-| `<pattern>` | 渲染失败 | 手动铺 `<circle>` / `<rect>` 点阵 |
-| `skewX` / `skewY` / `matrix(...)` | 空间扭曲，降级渲染 | 用 `rotate` + `translate` 替代 |
-| `<image>` 外链 URL | 不支持外链 | 先上传得到 file_token，再用 `<img>` 元素 |
-
----
-
-
-## 模式二：Mermaid
-
-### 语法
-
-```xml
-<whiteboard topLeftX="72" topLeftY="60" width="816" height="360">
-  <mermaid>
-    <![CDATA[
-        flowchart TD
-            A[检查 lark-cli 与 jq] --> B[编写每页 slide XML]
-            B --> C[通过 jq 生成 slides JSON]
-            C --> D[执行 slides +create]
-            D --> E[读取 xml_presentation_id]
-            E --> F[回读并验证创建结果]
-    ]]>
-  </mermaid>
-</whiteboard>
-```
-
-**关键点：**
-- 内容用 `<![CDATA[...]]>` 包裹——Mermaid 语法里的 `[`、`>`、`-->` 是 XML 特殊字符，CDATA 避免转义问题
-- whiteboard 只需 `topLeftX`、`topLeftY`、`width`、`height`
-
-### 支持的 Mermaid 图表类型
-
-| 类型 | 关键字 | 适用场景 |
-|------|--------|---------|
-| 流程图 | `flowchart TD` / `flowchart LR` | 业务流程、决策树、工作流 |
-| 时序图 | `sequenceDiagram` | 系统交互、API 调用链 |
-| 甘特图 | `gantt` | 项目计划、里程碑 |
-| 类图 | `classDiagram` | 对象关系、架构设计 |
-| ER 图 | `erDiagram` | 数据库结构 |
-| 状态图 | `stateDiagram-v2` | 状态机、生命周期 |
-| 思维导图 | `mindmap` | 主题梳理、知识架构 |
-| 用户旅程 | `journey` | 用户体验路径 |
-
-### Mermaid 布局建议
-
-Mermaid 图表会自动撑满 whiteboard 区域。建议：
-- 流程图留足高度，节点较多时适当增加 height（比如 400-480）
-- 避免一页放超过 15 个节点，内容太密时考虑分页
-- 推荐尺寸参考：
-
-| 图表类型 | 建议 width | 建议 height |
-|---------|-----------|------------|
-| 流程图（5-8 节点） | 720-816 | 300-400 |
-| 时序图（3-5 参与者） | 720-816 | 320-420 |
-| 甘特图 | 816 | 280-360 |
-| 思维导图 | 816 | 380-480 |
-
----
-
-## 注意事项 & 已知问题
-
-### z-order（SVG 模式）
-
-whiteboard 在 XML 中的位置决定渲染层级：在 shape 前 → 在下层；在 shape 后 → 在上层。全屏装饰 whiteboard 应放在所有 shape 之前。
-
-### Mermaid CDATA 必要性
-
-Mermaid 语法包含 `[`、`>`、`-->`，不用 CDATA 直接写会破坏 XML 解析。始终使用 `<![CDATA[ ... ]]>`。
-
----
-
-## 快速自检清单
-
-**SVG 模式——结构检查：**
-- [ ] `<svg>` 声明了 `xmlns="http://www.w3.org/2000/svg"`
-- [ ] whiteboard 的 `width`/`height` 由所有元素的最大包围盒（含 stroke 外扩）计算得出，不手动估值
-- [ ] `topLeftX + width ≤ 960`，`topLeftY + height ≤ 540`
-- [ ] 无 `<radialGradient>` / `<filter>` / `<clipPath>`
-- [ ] 文字 `y` 坐标为 baseline 位置，最小值 ≥ font-size（避免被裁切）
-
-**SVG 模式——视觉品质检查：**
-- [ ] 非原生数据视觉有必要的坐标轴、网格线、数值标注或分段说明，没有"裸点"或无解释色块
-- [ ] 字号有层级：标题 > 数值 > 轴标签，非全部相同
-- [ ] 单一数据系列用同一颜色，多系列用不同颜色且对比充足
-- [ ] 轴标签与图表元素互不遮挡，留有足够空间
-- [ ] 坐标推导有注释（写明 originX/Y、chartW/H、数据映射公式）
-
-**Mermaid 模式：**
-- [ ] 内容包在 `<![CDATA[...]]>` 内
-- [ ] CDATA 结束符 `]]>` 不出现在 Mermaid 代码本身中
-- [ ] `topLeftX + width ≤ 960`，`topLeftY + height ≤ 540`
-- [ ] 节点数量合理（单图不超过 15-20 个节点）
-
-**通用：**
-- [ ] XML 标签全部闭合，属性引号完整
-- [ ] 如果失败，检查是否是偶发 5001000，重试一次
-
----
-
-## 参考
-
-- [lark-slides SKILL.md](../SKILL.md)