@wagemule/daemon 0.1.0 → 0.1.3

package/dist/skills/larksuite/lark-vc-agent/references/lark-vc-agent-meeting-events.md

@@ -0,0 +1,247 @@
+
+# vc +meeting-events
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询当前 bot 在一场正在进行的视频会议中收到的会中事件列表。该命令是**读操作**。对进行中会议，要求 bot 当前仍在会中；对已结束会议，存在一个**结束后 5 分钟内的宽限窗口**，只要 bot 曾经在这场会里出现过，仍可继续拉取事件。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-events`（调用 `GET /open-apis/vc/v1/bots/events`）。
+
+## 命令
+
+```bash
+# 默认用法：全量拉取当前可见事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-all --format pretty
+
+# 指定时间范围，并拉全该时间窗内当前可见事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --page-all --format pretty
+
+# 基于上一次保存的 page_token 继续查新增事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-token <last_page_token> --page-all --format pretty
+
+# 调试或控制返回体大小时，显式只查一页
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-size 20 --format json
+
+# 预览 API 调用（不实际请求）
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-id <id>` | 是 | 会议 ID（长数字 ID，不是 9 位会议号） |
+| `--start <time>` | 否 | 起始时间，支持 ISO 8601 / `YYYY-MM-DD` / Unix 秒 |
+| `--end <time>` | 否 | 结束时间，支持 ISO 8601 / `YYYY-MM-DD` / Unix 秒 |
+| `--page-token <token>` | 否 | 从指定分页游标继续拉取下一页 |
+| `--page-size <n>` | 否 | 单页模式每页大小。CLI 会自动夹紧到 `20-100`；传 `--page-all` 时固定使用 `100` |
+| `--page-all` | 否 | 自动分页，直到没有更多页面为止（内部有安全上限） |
+| `--format <fmt>` | 否 | 输出格式：json (CLI 默认) / pretty（本 skill 推荐默认） / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 输入必须是 meeting_id，不是 9 位会议号
+
+`--meeting-id` 必须是会议的长数字 ID。它通常来自：
+- `+meeting-join` 返回体中的 `meeting.id`
+- `+search` 结果中的 `id`
+
+**不要**把 9 位会议号（`--meeting-number`）传给这个命令。
+
+### 2. 仅支持 user 身份
+
+该命令仅支持 `user` 身份。
+
+### 3. bot 必须在会中，或在会议结束后的 5 分钟宽限窗口内曾经在会中
+
+这是查询“bot 在会中观察到的事件”的接口。若 bot 已离会、未入会、或会议已经无法再判断 bot 身份，后端通常会报：
+- `bot is not in meeting, no permission`
+
+因此，最稳妥的调用顺序通常是：
+
+```bash
+# 先入会
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 记录返回的 meeting.id
+
+# 再查询事件
+lark-cli vc +meeting-events --meeting-id <meeting.id>
+```
+
+更精确地说，后端当前的判断规则是：
+
+- **会议进行中**：要求 bot **当前仍在会中**
+- **会议已结束后的 5 分钟内**：只要 bot **曾经在这场会中出现过**，仍可拉取事件
+- **会议结束超过 5 分钟**：按会议结束处理，通常不再返回事件流
+- **bot 从未真实入会过**：即使会议仍在进行或刚结束，也会返回 `10005 bot is not in meeting`
+
+### 4. 自动分页规则
+
+- **先分清两层默认值**：
+  - shortcut 本身：不传 `--page-all` 时，只查 1 页。
+  - 本 skill 的默认策略：除非用户明确要求只看一页，或你确实需要控制返回体大小，否则默认**必须主动带 `--page-all`**，把当前可见事件尽量一次拉全。
+- 传 `--page-all`：开启自动分页，直到没有更多页面为止。
+- `--page-all` 时，CLI 固定使用最大 `page_size=100`。
+
+执行准则：
+
+- **默认命令模板**：`lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty`
+- 如果你发现自己执行成了不带 `--page-all` 的单页查询，而响应里又出现 `has_more=true` / `more available` / 非空 `page_token`，应立刻意识到这只是部分结果。
+- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --meeting-id <meeting.id> --page-token <returned_page_token> --page-all --format pretty`
+- 只有在用户明确要求“就看第一页”“先不要翻页”时，才不要默认带 `--page-all`
+- 只要你是基于 `+meeting-events` 来回答一场**正在进行中的会议内容**，就不能直接复用上一次查询结果。无论用户是在问“现在是谁在说话”“刚刚发生了什么”“最新事件有哪些”，还是让你“总结一下这个会议讲什么”，都必须先重新执行一次 `+meeting-events`，确认拿到的是最新事件流，再回答用户。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。
+
+### 5. pretty / json 输出差异
+
+- `--format pretty`：输出会议主题、会议时间和逐条时间线，适合快速理解“发生了什么”，也是本 skill 的默认推荐格式。
+- `--format json`：保留完整原始 `events[]` 结构——参会人 open_id、聊天原文、share_doc、分页字段都在原始响应里，适合提取字段、联动其他命令或做进一步程序处理。
+
+**选型原则**：只要目标是告诉用户“发生了什么”，默认就用 `--page-all --format pretty`；只有在需要完整原始消息流和结构化字段时，才改用 `json`。
+
+> **注意**：pretty 输出中的正文文本会做单行转义，真实换行会显示为 `\n`，避免打乱时间线布局。
+
+### 6. 内容理解模式：共享文档不能只看标题
+
+当用户意图是：
+
+- “总结这个会议”
+- “这个会议讲了什么”
+- “有哪些结论 / 待办 / 关键讨论”
+- “共享文档里在讲什么”
+
+不要只基于事件时间线直接回答。此时 `+meeting-events` 只是**线索发现器**，不是最终信息源。
+
+执行准则：
+
+- 这类问题默认先用 `lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format json` 拉取最新事件流。
+- 如果事件中出现共享文档线索，例如：
+  - `magic_share_started`
+  - `share_doc.title`
+  - `share_doc.url`
+- 必须继续读取共享文档内容，再生成总结，不能只根据“开始共享了某文档”这条事件和文档标题来概括会议内容。
+- 若存在多个共享文档，优先读取**最近一次共享**的文档。
+- 若文档读取失败，必须明确说明“以下总结仅基于会中事件流，未成功读取共享文档内容”。
+
+### 7. 关于 `page_token` 的返回与续拉
+
+- 不管这次是只查 1 页，还是通过 `--page-all` 已经把当前可见事件都拿完，都应把最后拿到的 `page_token` 一并保留下来并返回给用户。
+- 只要响应里出现 `has_more=true`、pretty 里出现 `more available`，或返回了非空 `page_token`，就必须先判断当前结果是否完整；默认情况下，这意味着你还需要继续分页。
+- 如果没有使用 `--page-all`，但出现了上述分页信号，默认应继续用返回的 `page_token` 拉下一页，而不是直接结束。只有在用户明确不要继续翻页时，才可以停止并明确说明当前结果不完整。
+- 下次继续“查新增事件”时，应优先复用上一次保存的 `page_token`，而不是从头全量再拉一次。
+- 只有在用户明确要求“从头回放全部事件”时，才忽略历史 `page_token`，重新从第一页开始。
+- 但如果用户要你回答的是**当前这场会正在讲什么**，而不是“上一次之后新增了什么”，也要先做一次新的事件查询，再决定是否需要基于旧 `page_token` 继续补拉。
+
+## 返回结构
+
+常见顶层字段：
+
+| 字段 | 说明 |
+|------|------|
+| `events` | 事件列表 |
+| `has_more` | 是否还有下一页 |
+| `page_token` | 下一页游标 |
+
+事件 `event_type` 常见类型：
+
+| event_type | 含义 |
+|-----------|------|
+| `participant_joined` | 有参会人加入会议 |
+| `participant_left` | 有参会人离开会议 |
+| `chat_received` | 收到会中聊天消息 |
+| `transcript_received` | 收到转写文本 |
+| `magic_share_started` | 开始共享内容 / 文档 |
+| `magic_share_ended` | 结束共享 |
+
+## pretty 输出示例
+
+```text
+会议主题：张三的视频会议
+会议时间：2026-04-17 15:28:52（进行中）
+
+[00:00:33] 明日之虾BOE(ou_xxx) 加入了会议
+[00:00:41] 张三(ou_xxx): [text] 6666
+[00:00:44] 张三(ou_xxx) 开始共享《智能纪要：飞书20251022-140223 2026年3月9日》
+           URL: https://...
+[00:01:32] 张三(ou_xxx): [reaction] JIAYI
+```
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+search` 结果中的 `id` |
+| `start` / `end` | 用户给出的时间范围；如未给出则默认取全量可见事件 |
+| `page-token` | 上一页或上一次查询结果中保存的 `page_token`；建议持久化保存，便于下次继续拉取新增事件 |
+
+## Agent 组合场景
+
+### 场景 1：入会后查看会中发生了什么
+
+```bash
+# 第 1 步：加入会议，记录返回的 meeting.id
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：查询事件流
+lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty
+```
+
+### 场景 2：过滤某段时间内的事件
+
+```bash
+lark-cli vc +meeting-events \
+  --meeting-id <meeting.id> \
+  --start 2026-04-17T15:00:00+08:00 \
+  --end 2026-04-17T16:00:00+08:00 \
+  --page-all \
+  --format pretty
+```
+
+### 场景 3：基于上一次的 `page_token` 继续查新增事件
+
+```bash
+# 上一次查询结束后，保留最后返回的 page_token
+# 这次直接从该游标继续拉新增事件
+lark-cli vc +meeting-events \
+  --meeting-id <meeting.id> \
+  --page-token <last_page_token> \
+  --page-all \
+  --format pretty
+```
+
+适用规则：
+
+- 当用户说“继续看新事件”“看上次之后新增了什么”时，优先使用上一次保存的 `page_token`。
+- 如果这次返回里仍有 `has_more=true`、pretty 里出现 `more available`，或又返回了新的 `page_token`，说明新增事件还没拉完，应继续分页，而不是把当前页误当成完整增量结果。
+- 只有在用户明确要求“从头回放全部事件”时，才忽略已有 `page_token`，重新从第一页开始。
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-id is required` | 未传入 `--meeting-id` | 传入长数字 `meeting.id` |
+| `10005 bot is not in meeting` | bot 从未真实入会该会议；或会议已结束但 bot 从未在会中出现过 | 先 `+meeting-join --meeting-number <9位号>` 真实入会再查；如果会议已经结束且当时 bot 没进过会，本接口也拉不到数据。**如果只是想看参会人快照，改用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants`**（不依赖 bot 身份参会） |
+| `20001 meeting_status_MEETING_END` | 会议已结束且已超出后端允许的 5 分钟宽限窗口 | 本接口不再适合继续拉取事件。若要拿纪要文档或逐字稿 token，用 `lark-cli vc +notes --meeting-ids <meeting.id>`；若要拿 AI 产物（summary / todos / chapters）或导出逐字稿文件，先用 `lark-cli vc +recording --meeting-ids <meeting.id>` 拿 `minute_token`，再用 `lark-cli vc +notes --minute-tokens <minute_token>`；参会人请用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants` |
+| `20002 meeting not exist` | `meeting_id` 错误，或会议实例当前已不可获取（常见于把 9 位会议号当 meeting_id 传） | 确认传入的是长数字 `meeting_id`，不是 9 位会议号 |
+| `HTTP 404` / `HTTP 500` | 服务端当前无法找到或处理该会议实例 | 换一个正在进行且 bot 可见的 meeting_id，或排查后端问题 |
+
+## 提示
+
+- 这是**会中事件流**查询，不适合拿来搜历史会议记录；搜历史会议请用 `+search`。
+- 如果会议已经结束，不要卡在 `+meeting-events`：  
+  - 想拿纪要文档或逐字稿 token：用 `lark-cli vc +notes --meeting-ids <meeting.id>`
+  - 想拿 AI 产物（summary / todos / chapters）或导出逐字稿文件：先用 `lark-cli vc +recording --meeting-ids <meeting.id>` 拿 `minute_token`，再用 `lark-cli vc +notes --minute-tokens <minute_token>`
+- 事件列表是否完整，取决于 bot 何时入会、何时离会，以及后端当前可见的会中事件范围。对于已结束会议，通常只在**结束后 5 分钟内**、且 bot **曾经在会中**时还能继续拉到事件。
+- 查询"谁参加过某会议"请用 `vc meeting get --params '{"meeting_id":"<id>","with_participants":true}'`——这是参会人**快照** API，不依赖 bot 是否参会，对已结束会议也可查；**不要** 用 `+meeting-events` 做参会人查询。
+
+## 参考
+
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 先真实入会
+- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.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-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,133 @@
+
+# vc +meeting-join
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+通过 9 位会议号加入一场正在进行的视频会议（bot join）。这是一次**写操作**，会实际让当前身份加入会议。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-join`（调用 `POST /open-apis/vc/v1/bots/join`）。
+
+## 命令
+
+```bash
+# 仅指定会议号（无密码）
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 指定会议号 + 密码
+lark-cli vc +meeting-join --meeting-number 123456789 --password 8888
+
+# 输出格式
+lark-cli vc +meeting-join --meeting-number 123456789 --format json
+
+# 预览 API 调用（不实际加入会议）
+lark-cli vc +meeting-join --meeting-number 123456789 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-number <no>` | 是 | 会议号，必须为 **9 位纯数字** |
+| `--password <pw>` | 否 | 会议密码，仅在该会议设置了入会密码时传入 |
+| `--format <fmt>` | 否 | 输出格式：json (默认) / pretty / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 仅支持 user 身份
+
+该命令仅支持 `user` 身份。
+
+### 2. 会议号格式严格校验
+
+`--meeting-number` 必须是 9 位纯数字，否则本地校验直接报错：
+`--meeting-number must be exactly 9 digits`。
+
+常见错误来源：
+- 把会议链接整条粘进来（应仅取尾部的 9 位数字）
+- 把 `meeting_id`（长数字 ID）当成会议号传入（两者不是同一个东西）
+
+### 3. 会议必须已开始且允许入会
+
+- 会议必须处于**进行中**状态，bot 无法加入尚未开始或已结束的会议。
+- 若会议设置了**等候室 / 入会审批**，bot 可能需要主持人放行后才真正入会。
+- 若返回 `HTTP 403: no permission`（错误码 `121003`），不要只理解成“账号没权限”。这类报错更常见的原因是：会议参数或会控配置当前不满足入会条件，例如会议号填错、密码未传或错误、会议尚未开始、等候室 / 入会审批未放行、会议禁止外部/特定身份加入等。应先确认这些配置项，再重试。
+
+### 4. 机器人入会后对其他参会人可见
+
+这是一次真实入会操作，机器人会立即出现在参会人列表中，其他参会人可见，并产生会议日志。误入错会的社交成本高于技术成本——执行前优先确认 9 位会议号的来源（用户输入 / 会议链接末尾），不要臆造。参数格式有疑问时可用 `--dry-run` 预览请求体。
+
+## 输出结果
+
+接口返回会议基本信息，字段视具体响应而定，常见字段：
+
+| 字段 | 说明 |
+|------|------|
+| `meeting.id` | 会议 ID（可后续传给 `+meeting-leave --meeting-id`） |
+| `meeting.meeting_no` | 会议号（与入参一致） |
+| `meeting.topic` | 会议主题 |
+| `meeting.start_time` | 会议开始时间 |
+
+> **重要**：拿到 `meeting.id` 后务必保留，退出会议（`+meeting-leave`）需要使用它，而不是会议号。
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-number` | 会议号由主持人分享；也可从会议链接尾部解析 9 位数字 |
+| `password` | 若会议设置了入会密码，由主持人提供 |
+
+## Agent 组合场景
+
+### 场景 1：加入会议 → 离开会议（最小闭环）
+
+```bash
+# 第 1 步：加入会议，记录返回的 meeting.id
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：完成任务后，使用上一步返回的 meeting.id 离开会议
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+```
+
+### 场景 2：加入会议 → 会后拉取纪要 / 录制
+
+```bash
+# 第 1 步：加入并参会
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：离会
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+
+# 第 3 步：会议结束后，查询录制（拿到 minute_token）
+lark-cli vc +recording --meeting-ids <meeting.id>
+
+# 第 4 步：查询会议纪要（总结 / 待办 / 章节 / 逐字稿）
+lark-cli vc +notes --meeting-ids <meeting.id>
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-number must be exactly 9 digits` | 会议号不是 9 位纯数字 | 检查是否误传了会议链接或 meeting_id |
+| 会议密码错误 | `--password` 错误或未提供 | 向主持人确认会议密码 |
+| 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中 |
+| `HTTP 403: no permission` / `121003` | 入会前置条件不满足，通常不是单纯 scope 问题 | 依次确认：1）会议允许智能体加入；2）会议号正确；3）如有密码，已正确传入 `--password`；4）会议已开始；5）等候室 / 入会审批已放行；6）会议未禁止当前身份加入（如限制外部、限制 bot、仅特定成员可入会）；确认后重试 |
+| 入会被拒绝 | 等候室 / 入会审批 / 限制外部入会 | 联系主持人放行或调整会议设置 |
+
+## 提示
+
+- 仅在 Agent 需要**真实加入**会议（例如参会机器人、会中助手）时使用；只拉取会议数据不需要入会。
+- 入会会让机器人立即出现在参会列表；若要回退，直接 `+meeting-leave` 即可。参数格式不确定时可选 `--dry-run` 预览，但不是必经步骤。
+- 执行成功后，立即记录返回的 `meeting.id`，用于后续 `+meeting-leave` / `+meeting-events`。
+
+## 参考
+
+- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 对应的离会命令
+- [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-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,111 @@
+
+# vc +meeting-leave
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+通过 `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 --meeting-id 69xxxxxxxxxxxxx28
+
+# 输出格式
+lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --format json
+
+# 预览 API 调用（不实际离会）
+lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-id <id>` | 是 | 会议 ID（**不是 9 位会议号**） |
+| `--format <fmt>` | 否 | 输出格式：json (默认) / pretty / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 入参是 meeting_id，不是会议号
+
+`--meeting-id` 必须是会议的长数字 ID，通常由 `+meeting-join` 返回体中的 `meeting.id` 提供，也可从 `+search` 结果中的 `id` 字段获取。**传 9 位会议号会失败**。
+
+### 2. 仅支持 user 身份
+
+该命令仅支持 `user` 身份。只能让当前身份自己离会，无法强制移出其他参会人。
+
+### 3. 当前身份必须在会议中
+
+必须先通过 `+meeting-join` 或其他方式在该会议中，否则接口会报错。
+
+### 4. 离会立即生效，对其他参会人可见
+
+机器人会立刻从参会列表消失；若会议启用了录制/纪要，bot 的参会时段到此截止。确认任务完成再调用；如需要重新入会，再跑 `+meeting-join` 即可（非真正"不可逆"）。
+
+## 输出结果
+
+接口成功返回时，默认输出：`Left meeting <meeting-id> successfully.`。
+`--format json` 返回 API 原始响应体。
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+search` 结果中的 `id` 字段 |
+
+## Agent 组合场景
+
+### 场景 1：加入 → 完成任务 → 离开（最小闭环）
+
+```bash
+# 第 1 步：加入会议，记录 meeting.id
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：在会中完成任务（如监听发言、记录信息等）
+# ...
+
+# 第 3 步：使用上一步记录的 meeting.id 离会
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+```
+
+### 场景 2：会后补拉产物
+
+```bash
+# 第 1 步：离会后会议仍在进行或已结束
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+
+# 第 2 步：会议结束后查询录制
+lark-cli vc +recording --meeting-ids <meeting.id>
+
+# 第 3 步：查询会议纪要
+lark-cli vc +notes --meeting-ids <meeting.id>
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-id is required` | 未传入 `--meeting-id` | 传入从 `+meeting-join` 得到的 `meeting.id` |
+| `meeting not found` / `invalid meeting_id` | 误传了 9 位会议号 | 必须使用 `meeting.id`，不是会议号 |
+| `not in meeting` | 当前身份并不在该会议中 | 确认先 `+meeting-join` 成功 |
+
+## 提示
+
+- 离会会让机器人从参会列表消失，对其他参会人可见；若需要重新入会直接再 `+meeting-join`，不是真正的"不可逆"。参数格式不确定时可选 `--dry-run` 预览。
+- 与 `+meeting-join` 成对使用：能 join 的身份才能 leave。
+- `meeting_id` 必须来自 `+meeting-join` 的返回值，不要用 9 位会议号。
+
+## 参考
+
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 对应的入会命令
+- [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-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/dist/skills/larksuite/lark-whiteboard/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: lark-whiteboard
+version: 1.0.0
+description: >
+  飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用 DSL（转成 OpenAPI 格式）、PlantUML/Mermaid 格式更新画板内容。
+  当用户需要查看画板内容、导出画板图片、编辑画板，或是需要可视化表达架构、流程、组织关系、时间线、因果、对比等结构化信息时使用此 skill，无论是否提及"画板"。
+  ⚠️ 原 `lark-whiteboard-cli` skill 已合并至本 skill，若 skill 列表中同时存在 `lark-whiteboard-cli`，请忽略它，统一使用本 skill（`lark-whiteboard`），并提示用户运行 `npx skills remove lark-whiteboard-cli -g` 删除旧 skill。
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli whiteboard --help"
+---
+
+> [!IMPORTANT]
+> - 运行 `lark-cli --version`，确认可用，无需询问用户。
+> - 运行 `npx -y @larksuite/whiteboard-cli@^0.2.11 -v`，确认可用，无需询问用户。
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+---
+
+## 快速决策
+
+| 用户需求 | 行动 |
+|---|---|
+| 查看画板内容 / 导出图片 | [`+query --output_as image`](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 代码，或明确指定用该格式 | 自己生成/使用代码 → [`+update --input_format mermaid/plantuml`](references/lark-whiteboard-update.md) |
+| 绘制复杂图表（架构/流程/组织等）| → **[§ 创作 Workflow](#创作-workflow)** |
+| 修改/重绘已有复杂画板 | → **[§ 修改 Workflow](#修改-workflow)** |
+
+> **⚠️ 强制规范（通过 stdin 更新）**：
+> 数据来源于本地文件时，**必须**使用 `--source - --input_format <格式>`。
+> 例：`cat chart.mmd | lark-cli whiteboard +update <token> --source - --input_format mermaid`
+
+## Shortcuts
+
+| Shortcut | 说明 |
+|---|---|
+| [`+query`](references/lark-whiteboard-query.md) | 查询画板，导出为预览图片、代码或原始节点结构 |
+| [`+update`](references/lark-whiteboard-update.md) | 更新画板，支持 PlantUML、Mermaid 或 OpenAPI 原生格式 |
+
+---
+
+## 创作 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 --api-version v2 --doc <URL> --as user`，从返回的 `<whiteboard token="xxx"/>` 提取 |
+| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --api-version v2 --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：判断修改策略**
+
+```
++query --output_as code
+  ├─ 返回 Mermaid/PlantUML 代码
+  │   → 在原代码上修改 → +update --input_format mermaid/plantuml
+  ├─ 无代码（DSL 或其他方式绘制的画板）
+  │   ├─ 只改文字/颜色 → +query --output_as raw → 手动改 JSON → +update --input_format raw
+  │   └─ 重绘/结构调整 → +query --output_as image → 看图后进入 [§ 渲染 & 写入画板]
+  └─ 用户有明确要求 → 以用户要求优先
+```
+
+---
+
+## 渲染 & 写入画板
+
+### 渲染路由
+
+**先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。
+
+**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
+
+| 图表类型 | 身份 | 路径 |
+|---|---|---|
+| 思维导图、时序图、类图、饼图、甘特图 | 任何身份 | [`routes/mermaid.md`](routes/mermaid.md) |
+| 其他图表 | `Claude` / `Gemini` / `GPT` / `GLM` | [`routes/svg.md`](routes/svg.md) |
+| 其他图表 | `Doubao` / `Seed` / `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           ← 渲染结果
+```
+
+### 写入画板
+
+> [!CAUTION]
+> **写入前强制 dry-run**：向已有内容的画板写入时，必须先加 `--overwrite --dry-run` 探测。
+> 输出含 `XX whiteboard nodes will be deleted` → 必须向用户确认后才能执行。
+
+```bash
+# 第一步：dry-run 探测
+npx -y @larksuite/whiteboard-cli@^0.2.11 -i <产物文件> --to openapi --format json \
+  | lark-cli whiteboard +update \
+    --whiteboard-token <Token> \
+    --source - --input_format raw \
+    --idempotent-token <10+字符唯一串> \
+    --overwrite --dry-run --as user
+
+# 第二步：确认后执行
+npx -y @larksuite/whiteboard-cli@^0.2.11 -i <产物文件> --to openapi --format json \
+  | lark-cli whiteboard +update \
+    --whiteboard-token <Token> \
+    --source - --input_format raw \
+    --idempotent-token <10+字符唯一串> \
+    --overwrite --as user
+```
+
+> `--idempotent-token` 最少 10 字符，建议用时间戳+标识拼接（如 `1744800000-board-1`），避免重试导致重复写入。
+> 如需应用身份上传，将 `--as user` 替换为 `--as bot`。