@yandy0725/pi-lark 0.1.0

package/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md

@@ -0,0 +1,141 @@
+
+# vc +meeting-join
+
+通过 9 位会议号让应用机器人加入一场正在进行的视频会议。这是一次**写操作**，会实际让应用机器人加入会议。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-join`（调用 `POST /open-apis/vc/v1/bots/join`）。
+
+> **不要把 9 位会议号等同于入会意图。** 用户给出 9 位会议号并询问“会议讲了什么 / 查会中事件”时，先用 `+meeting-list-active` 查当前 active meetings 并按 `meeting_no` 匹配；只有用户明确要求“入会 / 让应用机器人旁听 / 代我参会”时才调用本命令。
+
+## 命令
+
+```bash
+# 仅指定会议号（无密码）
+lark-cli vc +meeting-join --as bot --meeting-number 123456789
+
+# 指定会议号 + 密码
+lark-cli vc +meeting-join --as bot --meeting-number 123456789 --password 8888
+
+# 从邀请事件透传 call_id（参见「如何获取输入参数」）
+lark-cli vc +meeting-join --as bot --meeting-number 123456789 --call-id a08e06bf-9a41-44e4-a89c-a7871899e783
+
+# 输出格式
+lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json
+
+# 预览 API 调用（不实际加入会议）
+lark-cli vc +meeting-join --as bot --meeting-number 123456789 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-number <no>` | 是 | 会议号，必须为 **9 位纯数字** |
+| `--password <pw>` | 否 | 会议密码，仅在该会议设置了入会密码时传入 |
+| `--call-id <id>` | 否 | 从 `vc.bot.meeting_invited_v1` 邀请事件透传的 `call_id`，原样回传即可。Agent 主动入会或无邀请事件来源时不传 |
+| `--dry-run` | 否 | 预览 API 调用，不实际加入会议；会议号或身份不确定时先用它确认请求 |
+
+## 核心约束
+
+### 1. 使用应用身份
+
+这是应用机器人入会能力，使用 `--as bot`。不要用当前登录用户身份尝试让应用机器人入会。
+
+### 2. 会议号格式严格校验
+
+`--meeting-number` 必须是 9 位纯数字，否则本地校验直接报错：
+`--meeting-number must be exactly 9 digits`。
+
+常见错误来源：
+- 把会议链接整条粘进来（应仅取尾部的 9 位数字）
+- 把 `meeting_id`（长数字 ID）当成会议号传入（两者不是同一个东西）
+
+### 3. 会议必须已开始且允许入会
+
+- 会议必须处于**进行中**状态，应用机器人无法加入尚未开始或已结束的会议。
+- 若会议设置了**等候室 / 入会审批**，应用机器人可能需要主持人放行后才真正入会。
+- 若返回 `HTTP 403: no permission`（错误码 `121003`），不要只理解成“账号没权限”。这类报错更常见的原因是：会议参数或会控配置当前不满足入会条件，例如会议号填错、密码未传或错误、会议尚未开始、等候室 / 入会审批未放行、会议禁止外部/特定身份加入等。应先确认这些配置项，再重试。
+
+### 4. 机器人入会后对其他参会人可见
+
+这是一次真实入会操作，机器人会立即出现在参会人列表中，其他参会人可见，并产生会议日志。误入错会的社交成本高于技术成本——执行前优先确认 9 位会议号的来源（用户输入 / 会议链接末尾），不要臆造。参数格式有疑问时可用 `--dry-run` 预览请求体。
+
+## 输出结果
+
+接口返回会议基本信息，字段视具体响应而定，常见字段：
+
+| 字段 | 说明 |
+|------|------|
+| `meeting.id` | 会议 ID（可后续传给 `+meeting-leave --as bot --meeting-id`） |
+| `meeting.meeting_no` | 会议号（与入参一致） |
+| `meeting.topic` | 会议主题 |
+| `meeting.start_time` | 会议开始时间 |
+
+> **重要**：拿到 `meeting.id` 后务必保留，退出会议（`+meeting-leave`）需要使用它，而不是会议号。
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-number` | 会议号由主持人分享；也可从会议链接尾部解析 9 位数字 |
+| `password` | 若会议设置了入会密码，由主持人提供 |
+| `call-id` | 由 `vc.bot.meeting_invited_v1` 邀请事件的 `call_id` 字段携带，Agent 收到事件时透传过来；无邀请事件场景（如 Agent 主动入会）不传 |
+
+## Agent 组合场景
+
+### 场景 1：加入会议 → 监听会中事件
+
+```bash
+# 第 1 步：加入会议，记录返回的 meeting.id
+lark-cli vc +meeting-join --as bot --meeting-number 123456789
+
+# 第 2 步：使用返回的 meeting.id 查询会中事件
+lark-cli vc +meeting-events --as bot --meeting-id <meeting.id> --page-all --format pretty
+```
+
+如果 bot 已经在会中，也可以通过 active meeting 找回 `meeting_id`：
+
+```bash
+lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
+```
+
+### 场景 2：加入会议 → 会后进入 lark-vc 获取会议产物信息
+
+```bash
+# 第 1 步：加入并参会
+lark-cli vc +meeting-join --as bot --meeting-number 123456789
+
+# 第 2 步：会议结束后，先查询会议产物
+lark-cli vc +detail --meeting-ids <meeting.id>
+```
+
+后续按 `lark-vc` 的产物决策处理：根据 `note_display_type`、`note_id`、`minute_token` 和用户意图选择纪要正文、逐字稿或妙记。
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-number must be exactly 9 digits` | 会议号不是 9 位纯数字 | 检查是否误传了会议链接或 meeting_id |
+| 会议密码错误 | `--password` 错误或未提供 | 向主持人确认会议密码 |
+| 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中 |
+| `HTTP 403: no permission` / `121003` | 入会前置条件不满足，通常不是单纯 scope 问题 | 依次确认：1）会议允许智能体加入；2）会议号正确；3）如有密码，已正确传入 `--password`；4）会议已开始；5）等候室 / 入会审批已放行；6）会议未禁止当前身份加入（如限制外部、限制应用机器人、仅特定成员可入会）；确认后重试 |
+| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；仍失败再排查内测 privilege / 灰度 |
+| 入会被拒绝 | 等候室 / 入会审批 / 限制外部入会 | 联系主持人放行或调整会议设置 |
+
+## 提示
+
+- 仅在 Agent 需要**真实加入**会议（例如参会机器人、会中助手）时使用；只拉取会议数据不需要入会。
+- 入会会让机器人立即出现在参会列表；若用户要求退出 / 离开 / 结束参会，直接使用 `+meeting-leave --as bot --meeting-id <meeting.id>`。参数格式不确定时可选 `--dry-run` 预览，但不是必经步骤。
+- 执行成功后，立即记录返回的 `meeting.id`，用于后续 `+meeting-leave` / `+meeting-events`。
+
+## 参考
+
+- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 对应的离会命令
+- [lark-vc-agent-meeting-list-active](lark-vc-agent-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
+- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
+- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议记录
+- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
+- [lark-vc-detail](../../lark-vc/references/lark-vc-detail.md) — 获取会议详情
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-vc-agent/references/lark-vc-agent-meeting-leave.md

@@ -0,0 +1,105 @@
+
+# vc +meeting-leave
+
+通过 `meeting_id` 离开当前身份所在的视频会议（bot leave）。这是一次**写操作**，会实际把当前身份从会议中移出。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-leave`（调用 `POST /open-apis/vc/v1/bots/leave`）。
+
+## 命令
+
+```bash
+# 通过 meeting_id 离会
+lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28
+
+# 输出格式
+lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28 --format json
+
+# 预览 API 调用（不实际离会）
+lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-id <id>` | 是 | 会议 ID（**不是 9 位会议号**） |
+| `--dry-run` | 否 | 预览 API 调用，不实际离会；meeting_id 或身份不确定时先用它确认请求 |
+
+## 核心约束
+
+### 1. 入参是 meeting_id，不是会议号
+
+`--meeting-id` 必须是会议的长数字 ID，通常由 `+meeting-join --as bot` 返回体中的 `meeting.id` 提供，也可从应用身份 `+meeting-list-active --as bot --user-id <user_open_id>` 返回体中的 `meeting_id` 获取。**传 9 位会议号会失败**。
+
+### 2. 优先使用 bot 身份
+
+这是应用机器人离会能力，使用与入会或 active meeting 发现相同的 `--as bot`。只能让当前身份自己离会，无法强制移出其他参会人。
+
+### 3. 当前身份必须在会议中
+
+应用机器人必须已经在该会议中，否则接口会报错。如果 `meeting_id` 来自 `+meeting-list-active`，必须确认这是应用身份发现到的会议。
+
+### 4. 离会立即生效，对其他参会人可见
+
+机器人会立刻从参会列表消失；若会议启用了录制/纪要，bot 的参会时段到此截止。只有在用户明确要求退出 / 离开 / 结束参会时才调用；如需要重新入会，再跑 `+meeting-join` 即可（非真正"不可逆"）。
+
+## 输出结果
+
+接口成功返回时，默认输出：`Left meeting <meeting-id> successfully.`。
+`--format json` 返回 API 原始响应体。
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-id` | `+meeting-join --as bot` 返回的 `meeting.id`；或应用身份 `+meeting-list-active --as bot --user-id <user_open_id>` 返回的 `meeting_id` |
+
+## Agent 组合场景
+
+### 场景 1：加入 → 用户明确要求时离开
+
+```bash
+# 第 1 步：加入会议，记录 meeting.id
+lark-cli vc +meeting-join --as bot --meeting-number 123456789
+
+# 第 2 步：在会中处理用户请求（如监听发言、记录信息等）
+# ...
+
+# 第 3 步：仅在用户明确要求退出 / 离开 / 结束参会时，使用上一步记录的 meeting.id 离会
+lark-cli vc +meeting-leave --as bot --meeting-id <meeting.id>
+```
+
+### 场景 2：会后补拉产物（不需要离会）
+
+如果用户只是要求会议结束后拉录制、纪要或逐字稿，不要先调用 `+meeting-leave`；直接跨到 `lark-vc` 查询会后产物。
+
+```bash
+# 第 1 步：会议结束后进入 lark-vc 获取会议产物信息
+lark-cli vc +detail --meeting-ids <meeting.id>
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-id is required` | 未传入 `--meeting-id` | 传入从 `+meeting-join --as bot` 得到的 `meeting.id`，或应用身份 `+meeting-list-active` 返回的 `meeting_id` |
+| `meeting not found` / `invalid meeting_id` | 误传了 9 位会议号 | 必须使用 `meeting.id`，不是会议号 |
+| `not in meeting` | 当前身份并不在该会议中 | 确认先 `+meeting-join` 成功 |
+
+## 提示
+
+- 只有用户明确要求退出 / 离开 / 结束参会时才调用；离会会让机器人从参会列表消失，对其他参会人可见。若需要重新入会直接再 `+meeting-join`，不是真正的"不可逆"。参数格式不确定时可选 `--dry-run` 预览。
+- `+meeting-leave` 优先使用 `+meeting-join --as bot` 返回的 `meeting.id`，但不是每次 join 后都必须调用 leave。
+- `meeting_id` 如果来自 `+meeting-list-active`，必须来自应用身份，并确认应用机器人就在该会议中。不要用 9 位会议号。
+
+## 参考
+
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 对应的入会命令
+- [lark-vc-agent-meeting-list-active](lark-vc-agent-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
+- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
+- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
+- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
+- [lark-vc-detail](../../lark-vc/references/lark-vc-detail.md) — 获取会议详情
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-vc-agent/references/lark-vc-agent-meeting-list-active.md

@@ -0,0 +1,91 @@
+# vc +meeting-list-active
+
+列出当前进行中的会议，用来发现 `+meeting-events` 需要的长数字 `meeting_id`。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-list-active`（调用 `GET /open-apis/vc/v1/bots/user_active_meeting`）。
+
+## 命令
+
+```bash
+# 查询当前登录用户正在参加的会议
+lark-cli vc +meeting-list-active --as user --format json
+
+# 查询指定用户当前参加、且应用机器人也在会中的会议
+lark-cli vc +meeting-list-active --as bot --user-id ou_xxx --format json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--user-id <id>` | 应用身份必填 | 目标用户 open_id，格式为 `ou_...`。用户身份不传；应用身份直接透传给接口，不接受 internal user_id 或数字 ID |
+
+## 身份语义
+
+不要向用户暴露内部身份缩写；对用户只说“用户身份”或“应用身份”。
+
+| 身份 | 命令 | 返回范围 | 后续事件读取 |
+| ---- | ---- | -------- | ------------ |
+| 用户身份 | `--as user` | 当前登录用户正在参加的会议 | 继续 `+meeting-events --as user` |
+| 应用身份 | `--as bot --user-id <user_open_id>` | 目标用户正在参加、且应用机器人也在会中的会议 | 继续 `+meeting-events --as bot` |
+
+硬规则：`meeting_id` 从哪种身份路径拿到，后续 `+meeting-events` 就沿用哪种身份。不要把用户身份拿到的 `meeting_id` 改用应用身份查，也不要把应用身份拿到的 `meeting_id` 改用用户身份查，除非用户明确要求切换场景。
+
+应用身份返回空，不代表目标用户不在任何会议中，只能说明没有找到“目标用户在会中且应用机器人也在会中”的当前会。
+
+常见流程：
+
+```bash
+# 方式 1：先让应用机器人入会，直接从 join 响应拿 meeting.id
+lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json
+lark-cli vc +meeting-events --as bot --meeting-id <meeting.id> --page-all --format pretty
+
+# 方式 2：应用机器人已经在会中时，用应用身份发现 meeting_id
+lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
+
+# 方式 3：只回答当前登录用户所在会议发生了什么
+lark-cli vc +meeting-list-active --as user --format json
+lark-cli vc +meeting-events --as user --meeting-id <meeting_id> --page-all --format pretty
+```
+
+## 多会议选择
+
+- 如果返回多个会议，不要自动挑第一个。
+- 向用户展示每个候选的 `meeting_title` / `meeting_no` / `meeting_id`，等待用户选择。
+- 选择后继续使用发现该会议时的同一身份调用 `+meeting-events`。
+
+## 9 位会议号匹配
+
+用户提供 9 位会议号但没有明确要求应用机器人入会时，把会议号当作 active meeting 的筛选条件，而不是写操作指令。
+
+```bash
+# 用户问“我当前这个会讲了什么”
+lark-cli vc +meeting-list-active --as user --format json
+
+# 用户问“让应用机器人所在/可见的这个会讲了什么”
+lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
+```
+
+匹配规则：
+
+- 在返回会议中匹配 `meeting_no == <9位会议号>`。
+- 匹配到唯一会议：取该项的长数字 `meeting_id`，后续用同一身份调用 `+meeting-events`。
+- 匹配到多个会议：展示候选，让用户选择。
+- 没有匹配：说明当前身份没有发现该会议号对应的 active meeting；不要自动调用 `+meeting-join`，除非用户明确要求应用机器人入会。
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--user-id is required when --as bot` | 应用身份未传目标用户 | 传入目标用户 open_id |
+| 用户身份返回空列表 | 当前登录用户没有可见的进行中会议 | 确认用户是否在会中，或是否切错身份 |
+| 用户身份不支持 | 当前接口不支持用用户身份访问 | 不要反复执行 `auth login`。改用应用身份流程：先拿目标用户 open_id，再执行 `+meeting-list-active --as bot --user-id <user_open_id>`；同时按应用身份权限配置检查应用权限、安装、数据范围和灰度 |
+| 应用身份返回空列表 | 没有满足“目标用户在会中且应用机器人也在会中”的当前会 | 先让应用机器人入会，或确认 `user_id` 和会议状态 |
+| `--user-id` 格式错误 | 传入了 internal user_id 或其他非 `ou_...` 值 | 改传目标用户 open_id |
+| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；仍失败再排查内测 privilege / 灰度 |
+
+## 参考
+
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 让应用机器人真实入会并拿 `meeting.id`
+- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 使用 `meeting_id` 读取会中事件

package/skills/lark-whiteboard/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: lark-whiteboard
+version: 1.0.0
+description: >
+  飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用多种格式更新画板内容。
+  当用户需要查看画板内容、导出画板图片、编辑画板时使用此 skill。不负责：飞书云文档内容编辑（lark-doc）、文档内嵌电子表格/Base（lark-sheets / lark-base）。
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli whiteboard --help"
+---
+
+> [!IMPORTANT]
+> - 运行 `lark-cli --version`，确认可用，无需询问用户。
+> - 运行 `npx -y @larksuite/whiteboard-cli@^0.2.12 -v`，确认可用，无需询问用户。
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+---
+
+## 快速决策
+
+**身份**：画板操作默认使用 `--as user`。仅当需要以应用身份上传时使用 `--as bot`。
+
+| 用户需求                                    | 行动                                                                                            |
+|-----------------------------------------|-----------------------------------------------------------------------------------------------|
+| 查看画板内容 / 导出图片 / 导出 SVG 矢量图 | [`+query --output_as image/svg`](references/lark-whiteboard-query.md)                             |
+| 获取画板的 Mermaid/PlantUML 代码               | [`+query --output_as code`](references/lark-whiteboard-query.md)                              |
+| 检查画板是否由代码绘制                             | [`+query --output_as code`](references/lark-whiteboard-query.md)                              |
+| 仅微调节点文字/颜色                         | `+query --output_as raw` → 手动改 JSON → `+update --input_format raw`                            |
+| 用户**已提供** Mermaid/PlantUML/SVG 代码，或明确指定用该格式 | 自己生成/使用代码 → [`+update --input_format mermaid/plantuml/svg`](references/lark-whiteboard-update.md) |
+| 新建/创作复杂图表（架构/流程/组织等）                    | → **[§ 创作 Workflow](references/lark-whiteboard-workflow.md#创作-workflow)**                     |
+| 修改/重绘已有画板                               | → **[§ 修改 Workflow](references/lark-whiteboard-workflow.md#修改-workflow)**                     |
+
+## Shortcuts
+
+| Shortcut | 说明 |
+|---|---|
+| [`+query`](references/lark-whiteboard-query.md) | 查询画板，导出为预览图片、SVG 矢量图、代码或原始节点结构。 |
+| [`+update`](references/lark-whiteboard-update.md) | 更新画板，支持 PlantUML、Mermaid、SVG 或 OpenAPI 原生格式 |
+
+---
+
+## 不在本 skill 范围
+- 文档内容编辑 → lark-doc [lark-doc](../lark-doc/SKILL.md)
+- 在文档中创建画板 → [lark-doc-whiteboard.md](../lark-doc/references/lark-doc-whiteboard.md)
+- 表格 / Base 操作 → [lark-sheets](../lark-sheets/SKILL.md) / [lark-base](../lark-base/SKILL.md)

package/skills/lark-whiteboard/elements/connectors.md

@@ -0,0 +1,102 @@
+# 连线系统
+
+## 连线策略
+
+| 连线数 | 策略 |
+|--------|------|
+| ≤8 | 逐条画 |
+| 9-15 | 代表性连线（每层选 1-2 个节点连到下一层）|
+| >15 | 层到层连线，或回退精简分组 |
+
+一个节点有 3+ 条连线时：入线从 top，出线从 bottom，同侧多条线用不同方向分散。
+
+---
+
+## connector 必须放根 nodes 数组
+
+```typescript
+// 错误：connector 放在 frame children 里
+{ type: 'frame', children: [
+  { type: 'connector', ... }  // 会导致 Schema 报错或无法连线！
+]}
+
+// 正确：connector 放在根 nodes 数组
+const doc: WBDocument = {
+  version: 2,
+  nodes: [
+    { type: 'frame', id: 'box', ... },
+    { type: 'connector', ... },  // 必须和顶层 frame 平级
+  ],
+};
+```
+
+---
+
+## 箭头默认值
+
+- `endArrow` 省略时默认为 `'arrow'`（即连线末端默认带箭头）。
+- `startArrow` 省略时默认为 `'none'`（即连线起始端默认无箭头）。
+
+---
+
+## 连线技巧
+
+```typescript
+// 自动绕线（推荐）：仅需指定节点 id（引擎可自动推断最优出线方向），并使用 polyline 或 rightAngle 形状
+// 只要不传 waypoints，引擎会尝试自动避开障碍物并生成折线。
+{ type: 'connector', connector: {
+  from: 'a', to: 'b', // fromAnchor 和 toAnchor 也可以省略，让引擎自己找最短路径
+  lineShape: 'polyline', lineColor: '#000000', lineWidth: 2, endArrow: 'arrow' }}
+
+// 精确坐标（做注解箭头）
+{ type: 'connector', connector: {
+  from: { x: 150, y: 200 }, to: 'b', toAnchor: 'left',
+  lineShape: 'curve', lineColor: '#BBBFC4', lineWidth: 2,
+  lineStyle: 'dashed', endArrow: 'triangle' }}
+
+// 手动控制路径点 waypoints（仅在需要强制固定路线、或者自动路由不符合预期时使用）
+// 注意：一旦提供了 waypoints，引擎将严格尊重这些点，不再进行自动避障。
+{ type: 'connector', connector: {
+  from: { x: 300, y: 140 }, to: { x: 300, y: 340 },
+  waypoints: [{ x: 350, y: 140 }, { x: 350, y: 340 }],
+  lineShape: 'polyline', lineColor: '#000000', lineWidth: 2, endArrow: 'arrow' }}
+
+// 绘制坐标轴/数轴（必须使用 straight，防止刻度文字触发自动避障导致线条弯曲）
+{ type: 'connector', connector: {
+  from: { x: 100, y: 400 }, to: { x: 600, y: 400 },
+  lineShape: 'straight', lineColor: '#000000', lineWidth: 2, endArrow: 'arrow' }}
+```
+
+> [!IMPORTANT]
+> **1. 形状选用要求（核心）**，需明确 `lineShape` 类型：
+> - **`'polyline'`（圆角折线）**：**默认首选**。适用于流程图、架构图等绝大多数场景。支持引擎的**自动绕线与避障**功能（只需指定 `from` 和 `to`）。
+> - **`'rightAngle'`（直角折线）**：适用于明确要求“总线/直角规约”、树状层级严格对齐的场景，同样支持**自动绕线与避障**。
+> - **`'straight'`（直线）**：不受自动避障机制的影响，适用于**坐标轴、数轴、几何图形边框、直接指向关系**等要求线条绝对笔直、不允许出现任何绕行或弯曲的场景。
+> - **`'curve'`（曲线）**：适用于优雅的跨层连线（S型弯）、自由发散的脑图分支、或做注解箭头时。
+> - **注意**：你需要根据当前绘制的图表类型和上下文语境，选择最合适的 `lineShape`。不要盲目全部使用 `polyline`，例如在绘制坐标系时必须主动切换为 `straight`。
+> **2. 间距要求**：有 connector 连线的卡片间 gap 需 ≥ 40，否则箭头挤在缝里看不清。
+> **3. 顶层约束**：`connector` 必须直接放在 `WBDocument.nodes`，**严禁**嵌套在 `children` 内。建议在数据末尾统一声明连线。
+>
+> [!TIP]
+> **自动绕线 vs 手动控制**
+> - **优先依赖自动绕线**：对于 `'polyline'` 和 `'rightAngle'`，引擎会自动规划路径并尝试避开障碍物（`fromAnchor` 和 `toAnchor` 也可省略，引擎会自动推断最优出线方向），这是最推荐的方式。
+> - **何时手动算 waypoints**：**仅在必要时**（例如自动路由不符合预期，或者必须强制走特定形状绕开特定元素时），才需要通过 `waypoints` 手动接管坐标序列。
+>
+> **连线标签**
+> - **连线文字说明**：需要文字说明时，可用 `label` 标注。
+
+---
+
+## 锚点方向规则
+
+锚点（top/right/bottom/left）表示连线从节点的哪个边出发，方向含义与 CSS border 四边相同。
+
+**注意：由于目前自动绕线功能支持省略锚点让引擎自动推断，以下规则主要适用于你想强制控制出线方向，或者使用直线/曲线时的场景。**
+
+选择锚点时根据两个节点的相对位置：目标在下方用 `fromAnchor: 'bottom'` + `toAnchor: 'top'`，目标在右侧用 `fromAnchor: 'right'` + `toAnchor: 'left'`。如果手动指定了锚点，必须与节点的实际相对位置匹配，否则可能导致连线反向绕行。
+
+**锚点绑定的常见范式**：
+- **同层横向推进**（目标在正右）：`fromAnchor: "right"` -> `toAnchor: "left"`
+- **垂直下沉推进**（目标在正下）：`fromAnchor: "bottom"` -> `toAnchor: "top"`
+- **跨层斜切推进**（目标在左下或右下）：首选 **`fromAnchor: "bottom"` -> `toAnchor: "top"`**。由于线段自身带有重力倾向，从底部出线再弯曲进入下一层顶部，完美契合流水线的 S 型大弯，能画出最优雅顺滑的跨层曲线。**避免**使用左右锚点互相跨接。
+- **逆流回捞**（底部发散回指顶部原点）：首选 **`fromAnchor: "top"` -> `toAnchor: "bottom"`** 配合 `lineStyle: "dashed"`。

package/skills/lark-whiteboard/elements/content.md

@@ -0,0 +1,40 @@
+# 内容规划
+
+核心原则：**信息量匹配用户需求的详细程度。** 用户说"画一个简单架构图"就画简单的，说"画一个完整的微服务架构"才画复杂的。不要自作主张**过度展开**。
+
+**用户 prompt 简短/模糊时**（如"画个漏斗图"、"画个架构图"），不要只输出字面内容。应适当补充该领域合理的内容
+
+## 信息量参考
+
+| 用户需求 | 合理的信息量 |
+|---------|------------|
+| "画一个简单的 XX 架构图" | 3 层，每层 2-3 节点，无侧边栏 |
+| "画一个 XX 架构图"（普通请求） | 3-4 层，每层 3-4 节点 |
+| "画一个完整/详细的 XX 架构图" | 4-5 层，每层 4-6 节点，可加侧边栏（侧边栏最多 2-3 项）|
+| 流程图 | 6-10 步骤 + 1-2 个条件分支 |
+| 对比表 | 4-6 个维度，每格 1-2 行说明 |
+| 组织架构 | 3-4 层，每个父节点下 2-4 个子节点 |
+
+**节点文字**：标题 + 简短说明（如"用户服务\n注册登录和权限管理"），不要写长段落。说明 12 字以内为佳。
+
+## 分组
+
+每组 2-5 个节点。超过 5 个拆成子组。
+
+## 连线预判
+
+| 连线数 | 策略 |
+|--------|------|
+| ≤8 | 逐条画 |
+| 9-15 | 代表性连线 |
+| >15 | 层到层，或回退精简 |
+
+## 精简触发条件
+
+布局放不下时才精简：
+
+| 问题 | 精简方式 |
+|------|---------|
+| 节点文字放不下 | 缩短描述文字 |
+| 一行节点超过 5 个 | 拆成两排或合并同类 |
+| 连线交叉 | 减少连线数量 |

package/skills/lark-whiteboard/elements/image.md

@@ -0,0 +1,80 @@
+# 图片准备 (Image Preparation)
+
+> 本文件说明如何在画板 DSL 中使用图片节点。进入任何含图片的场景前，必须先完成图片准备流程。
+
+## 概述
+
+画板 DSL 支持 `type: 'image'` 节点，但图片不能直接使用 URL 或其他域的 token，**必须先上传到目标画板获取 `whiteboard` 域 media token**，然后在 DSL 中引用。
+
+**核心规则**：不管图片从哪来（本地文件、URL、文档中的 `docx_image` token、其他域的 Drive token），都必须通过 `docs +media-upload --parent-type whiteboard --parent-node <目标画板token>` 上传，拿到画板专属的 media token 后才能在 DSL 中使用。直接使用非 `whiteboard` 域的 token 会导致画板 API 报 500（错误码 2891001）或图片在文档中消失。
+
+## Step 0：图片准备流程
+
+### 1. 获取图片到本地
+
+根据图片来源选择对应方式：
+
+| 图片来源 | 获取方式 |
+|---------|---------|
+| 本地文件 | 直接使用 |
+| 网络 URL | `curl -L -o photo.jpg "<URL>"` |
+| 文档中的图片 token | `lark-cli docs +media-download --token <token> --output ./photo.png` |
+| 其他域的 Drive token | `lark-cli docs +media-download --token <token> --output ./photo.png` |
+
+**图片源选择（需要搜索图片时）**：
+
+| 图片源类型 | 说明 |
+|-------|------|
+| 免费版权图库 | 支持按关键词搜索，图片无版权风险（CC0 或类似协议），图库种类丰富（人物/动物/风景/美食/建筑等），关键词能精准匹配图片内容 |
+| 直接 URL | 用户提供或已知的图片链接，最可靠 |
+
+**选择图库的必要条件**：
+- **版权合规**：图片必须无版权纠纷风险，避免使用需要付费授权或有使用限制的图库
+- **关键词搜索**：支持按关键词搜索并返回相关图片，确保图片内容与主题匹配
+- **内容丰富**：图库图片种类多、数量大，能覆盖常见主题（宠物、美食、景点、产品等）
+
+**严禁使用随机占位图服务**：某些图库仅提供随机占位图，URL 中的关键词参数不会影响返回的图片内容，下载的图片与主题完全无关。
+
+### 2. 校验图片
+
+```bash
+ls -l *.jpg   # 确认每张文件大小不同；若大小相同则内容可能重复，需重新下载
+```
+
+**图片内容审查（必须执行）**：
+- 下载完成后，确认文件是真实图片而非 HTML 错误页：若某张图片大小 < 1KB，很可能是下载失败返回了 HTML 错误页，需重新下载
+- **图片内容正确性只能在渲染后验证**：生成 DSL 并本地渲染 PNG 后，必须查看渲染结果，确认每张图片内容与主题相关（如宠物主题的图片确实是宠物，而非建筑/风景等不相关内容）
+- 若发现图片内容与主题不符，必须用更精确的关键词重新下载并重新上传
+
+### 3. 上传到目标画板
+
+**必须**使用 `docs +media-upload --parent-type whiteboard` 上传：
+
+```bash
+lark-cli docs +media-upload --file ./photo1.jpg --parent-type whiteboard --parent-node <whiteboard_token>
+# 响应: { "file_token": "<media_token>", ... }
+```
+
+逐张上传，收集每个 media token：
+
+```bash
+lark-cli docs +media-upload --file ./photo1.jpg --parent-type whiteboard --parent-node <whiteboard_token>  # → <media_token_1>
+lark-cli docs +media-upload --file ./photo2.jpg --parent-type whiteboard --parent-node <whiteboard_token>  # → <media_token_2>
+lark-cli docs +media-upload --file ./photo3.jpg --parent-type whiteboard --parent-node <whiteboard_token>  # → <media_token_3>
+```
+
+### 4. 在 DSL 中引用
+
+```json
+{ "type": "image", "id": "img-1", "width": 240, "height": 160, "image": { "src": "<media_token_1>" } }
+```
+
+## 常见错误
+
+| 错误现象 | 原因 | 解决 |
+|---------|------|------|
+| 画板 API 返回 500（2891001） | 使用了非 `whiteboard` 域 token（如 `docx_image`、Drive file token） | 下载图片后用 `docs +media-upload --parent-type whiteboard` 重新上传 |
+| 画板 API 返回 500 | 图片上传到了其他画板 | 重新上传到目标画板 |
+| 画板在文档中图片消失 | 图片 token 的资源域与画板不匹配 | 确保图片通过 `--parent-type whiteboard --parent-node <画板token>` 上传 |
+| 图片裂开/无法显示 | token 无效或已过期 | 重新上传获取新 token |
+| 图片内容与主题无关 | 使用了随机占位图服务 | 改用免费版权图库服务 |