@amaster.ai/pi-lark 0.1.9 → 0.1.10

package/skills/lark-base/references/lark-base-template-center.md

@@ -0,0 +1,195 @@
+# Base 模板中心
+
+模板中心是一个**公开的 Base 模板库**。当用户想“用一个现成的模板快速搭一个多维表格”时，这套命令帮助 AI 找到最合适的模板，最终通过 `+base-copy` 复制成用户自己的新 Base。
+
+三个命令：
+
+- `+template-categories`：列出所有模板分类，用于把用户意图对齐到某个类目。
+- `+template-list`：列出某个分类下的模板（不传分类则返回“推荐”类目）。
+- `+template-search`：按关键词搜索模板。
+
+## 何时使用模板中心
+
+满足以下特征时走模板中心：用户有**创建新 Base 的意图**，但**没有指向已有对象的锚点**（没有 Base URL、没有“我的/最近访问的表”、没有具体已存在的 Base 名）。
+
+典型触发：
+
+- “帮我建一个 CRM 多维表格”
+- “有没有适合项目管理的模板”
+- “找个 OKR 跟进的 Base 模板照着做”
+
+**不要**走模板中心的情况（即使用户嘴上说“模板”）：
+
+- 用户给了 Base/Wiki 链接或 token → 走 `+url-resolve`。
+- 用户说“我之前那张表 / 我的模板 / 最近访问的” → 走 `+title-resolve` 或转 `lark-drive` 搜索。
+- 用户要从零定义字段 schema，而不是套现成模板 → 走 `+base-create --table-name --fields`。
+
+模板中心是独立的公开数据集，**不能**用 `drive +search` 找到，`drive +search` 只搜用户自己可访问的云空间对象。
+
+## 推荐命令
+
+```bash
+# 列出所有模板分类
+lark-cli base +template-categories --as user
+
+# 列出某个分类下的模板（不传 --category-key 则返回“推荐”类目）
+lark-cli base +template-list --category-key template_center_tab_ai --limit 10 --as user
+
+# 按关键词搜索模板
+lark-cli base +template-search --keyword "项目管理" --limit 10 --as user
+
+# 翻页：把上一页返回的 offset 原样传给 --offset
+lark-cli base +template-search --keyword "AI" --limit 10 --offset <上一页返回的 offset> --as user
+
+# 选定模板后，用模板 token 复制成用户自己的新 Base
+lark-cli base +base-copy --base-token <模板 token> --name "<新 Base 名>" --as user
+```
+
+## 工作流
+
+模板中心有两条路径，按用户意图明确程度二选一，不要盲目全用。
+
+### 路径 A：分类浏览（意图偏宽泛时首选）
+
+用户只给了一个大方向（如“项目管理”“市场营销”），先按分类收敛，再在类目里挑模板。
+
+1. `+template-categories` 列出全部分类，拿到 `categories[].key` 和 `name`。
+2. AI 把用户意图匹配到最贴近的一个分类 `name`，取它的 `key`。
+3. `+template-list --category-key <key>` 列出该类目下的模板。
+4. 读每个模板的 `name` / `introduction` / `scenarios`，挑出最符合用户场景的那个，拿它的 `token`。
+5. 用 `+base-copy --base-token <token>` 基于模板复制出新 Base（见下文“基于模板创建”）。
+
+```bash
+# 1. 看有哪些分类
+lark-cli base +template-categories --as user
+
+# 2~3. 匹配到“AI 应用”类目后，列出该类目模板
+lark-cli base +template-list --category-key template_center_tab_ai --limit 10 --as user
+```
+
+匹配不到贴切分类，或用户意图本身就跨类目 / 很具体时，改走路径 B。
+
+### 路径 B：关键词搜索（意图有具体词时首选）
+
+用户给了明确、可检索的词（如“财务报销”“直播复盘”“AI 客服”），直接搜，不必先看分类。
+
+1. `+template-search --keyword "<词>"` 搜模板。
+2. 同样读 `name` / `introduction` / `scenarios` 选模板，拿 `token`。
+3. `+base-copy` 复制。
+
+```bash
+lark-cli base +template-search --keyword "项目管理" --limit 10 --as user
+```
+
+关键词不能为空；空搜会被拒绝。用户只有“大方向”而没有具体检索词时，用路径 A 的分类浏览更稳。
+
+### 分类 vs 搜索怎么选
+
+| 用户意图 | 走哪条 |
+|---|---|
+| 只有大类方向（“市场营销类的”“办公用的”） | 路径 A，先 `+template-categories` 收敛 |
+| 有具体、可检索的业务词（“报销”“OKR”“直播”） | 路径 B，直接 `+template-search` |
+| 大方向下没挑到合适的 | A 之后再用 B 换关键词补搜 |
+
+## 翻页
+
+`+template-list` 和 `+template-search` 都是游标翻页：
+
+- `--limit`：每页数量，默认 10，范围 1-100；`--page-size` 是等价别名。
+- `--offset`：翻页游标，来自上一次响应的 `offset` 字段。**首次请求不要传**。
+- 响应里 `has_more=true` 表示还有下一页，把响应的 `offset` 原样传给下一次 `--offset`。`has_more=false` 或 `offset` 为空字符串表示没有更多。
+
+`--offset` 是服务端返回的不透明游标，不要解析它、不要自己拼造。
+
+```bash
+lark-cli base +template-search --keyword "AI" --limit 10 --offset <上一页返回的 offset> --as user
+```
+
+## 数据结构
+
+### TemplateCategory（分类对象）
+
+`+template-categories` 返回 `categories[]`，每个元素：
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `key` | string | 分类唯一标识，形如 `template_center_tab_ai`（`template_center_tab_` 前缀 + 类目名）。传给 `+template-list --category-key` 用的就是它 |
+| `name` | string | 分类展示名，如 `AI 应用` / `办公通用`。AI 匹配用户意图时看这个 |
+
+### Template（模板对象）
+
+`+template-list` / `+template-search` 返回 `templates[]`，每个元素：
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `token` | string | 模板的 Base token，是模板的唯一标识。基于模板创建时作为 `+base-copy --base-token` 的入参 |
+| `name` | string | 模板名称，如 `工作汇报` |
+| `introduction` | string | 模板介绍，说明模板用途、内容结构和适用方向。AI 判断模板是否契合用户需求主要看它 |
+| `scenarios` | string[] | 适用场景列表，如 `["工作汇报","月报","项目进展"]`，用于快速判断场景匹配度 |
+| `developer` | string | 模板开发者，如 `飞书` |
+| `link` | string | 模板预览链接，可展示给用户，但复制模板用 `token` 而不是 `link` |
+| `created_at` / `updated_at` | string | 创建 / 更新时间 |
+
+列表 / 搜索响应还带分页字段：
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `has_more` | boolean | 是否还有下一页 |
+| `offset` | string | 下一页游标；无更多时为空字符串 |
+
+**约定**：模板的唯一标识就叫 `token`（模板 Base token），不要在输出或转述里改名成 `id` 或 `key`；`key` 是分类的标识（`category_key`）。
+
+### 模板列表/模版搜索-响应示例
+
+```json
+{
+  "code": 0,
+  "data": {
+    "has_more": true,
+    "offset": "1",
+    "templates": [
+      {
+        "created_at": "2025-12-03T02:53:34Z",
+        "developer": "Base Team",
+        "introduction": "📊 品牌调研问卷  \n高效收集用户反馈，助力品牌优化决策  \n\n核心功能点  \n1 预设多维度调研问题模板  \n2 支持自定义问题类型与逻辑跳转  \n3 实时数据统计与可视化分析  \n\n适合场景  \n1 新品上市前市场需求调研  \n2 品牌形象与用户满意度评估  \n3 竞品对比与消费者偏好分析",
+        "link": "https://example.com/base/<template_token>",
+        "name": "品牌调研问卷",
+        "scenarios": ["运营管理", "市场营销"],
+        "token": "<template_token>",
+        "updated_at": "2026-06-22T08:18:58Z"
+      }
+    ]
+  },
+  "msg": ""
+}
+```
+
+读取模板列表时重点看：
+
+- `templates[].name`：模板名称；基于模板创建 Base 且用户没有指定新名称时，直接作为 `+base-copy --name`。
+- `templates[].token`：模板 Base token；复制时传给 `+base-copy --base-token`。
+- `templates[].link`：模板预览链接；可以展示给用户帮助确认，但复制时不要用 link 代替 token。
+- `templates[].introduction` / `templates[].scenarios`：用于判断模板是否匹配用户业务场景。
+- `data.offset`：下一页游标；只有 `has_more=true` 时才继续传给 `--offset`。
+
+## 基于模板创建 Base
+
+模板中心只负责“找到模板”，它本身不创建 Base。选定模板后，用模板的 `token` 复制出用户自己的新 Base：
+
+```bash
+lark-cli base +base-copy --base-token <模板 token> --name "<新 Base 名>" --as user
+```
+
+- `--name` 用用户想要的新 Base 名；不传则沿用模板名。
+- 只有用户明确说“只要结构 / 不要内容”时，才加 `--without-content`。
+- `+base-copy` 的返回和权限说明见 SKILL.md 中 `+base-copy` 的相关规则。
+
+## 注意事项
+
+- 三个命令都是只读，默认 `--as user`，所需权限 `base:template:read`。
+- 模板中心是公开数据集，不能用 `drive +search` 找到；用户要“我的/最近访问/已有 Base”不要走这里。
+- 分类先于列表：`+template-list` 的 `--category-key` 必须来自 `+template-categories` 的返回，不要凭空猜类目 key。
+- `+template-search` 不支持空关键词，会被拒绝；用户只有大方向、无具体检索词时改走分类浏览。
+- 模板的唯一标识是 `token`（模板 Base token），不要改名成 `id` 或 `key`。
+- `--offset` 是服务端返回的不透明游标，翻页时原样回传，不要解析或自行构造。
+- 模板中心只查模板、不创建 Base；创建一律走 `+base-copy --base-token <token>`，不要用模板 token 去调 `+base-get` 之类的当前用户 Base 命令。

package/skills/lark-calendar/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-calendar
 version: 1.0.0
-description: "飞书日历：管理日历日程和会议室。查看/搜索日程、创建/更新日程、管理参会人、查询忙闲和推荐时段、预定会议室。当用户需要查看日程安排、创建/修改会议、查询/预定会议室时使用。不负责：查询过去的视频会议记录（走 lark-vc）、待办任务（走 lark-task）。"
+description: "飞书日历：管理日历日程和会议室。查看/搜索日程、创建/更新日程、管理参会人、查询忙闲和推荐时段、预定会议室。当用户需要查看日程安排、创建/修改会议、查询/预定会议室时使用。不负责：查询过去的视频会议记录（走 lark-meeting）、待办任务（走 lark-task）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -42,6 +42,7 @@ lark-cli calendar +agenda --as bot
 | [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（无明确时间时禁止直接调用，需先走 +suggestion） |
 | [`+rsvp`](references/lark-calendar-rsvp.md) | 回复日程（接受/拒绝/待定） |
 | [`+suggestion`](references/lark-calendar-suggestion.md) | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 |
+| [`+transfer`](references/lark-calendar-transfer.md) | 把日程组织者转让给另一个用户或机器人；不可逆，需 `--yes` |
 
 ### `+get` — 单日程详情
 
@@ -127,14 +128,16 @@ lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
 
 | 用户意图 | 路由到 |
 |----------|--------|
-| 查询过去的会议（"昨天的会议""上周的会"） | [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md)（会议数据含即时会议，仅查日程会遗漏） |
+| 查询过去的会议（"昨天的会议""上周的会"） | [`../lark-meeting/SKILL.md`](../lark-meeting/SKILL.md)（会议数据含即时会议，仅查日程会遗漏） |
+| 今天有哪些会议| 需要合并两部分内容：[`../lark-meeting/SKILL.md`](../lark-meeting/SKILL.md) 中的 `vc +search` 查询今天已结束的会议， `calendar +agenda` 查询进行中或未开始的日程。|
 | 查询日历/日程或未来时间的会议 | 本 skill |
 | 按关键词搜索日程 | 本 skill（`+search-event`） |
 | 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
-| 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再 [`vc +detail`](../lark-vc/references/lark-vc-detail.md) → [`note +detail`](../lark-note/references/lark-note-detail.md) / [`minutes +detail`](../lark-minutes/references/lark-minutes-detail.md) |
+| 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再进入 [`lark-meeting`](../lark-meeting/SKILL.md)：[`vc +detail`](../lark-meeting/references/lark-vc-detail.md) → [`note +detail`](../lark-meeting/references/lark-note-detail.md) / [`minutes +detail`](../lark-meeting/references/lark-minutes-detail.md) |
 | 预约/改约日程、调整时间、添加/更换会议室、查会议室 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
 | 仅编辑日程字段（标题/描述）或增删参会人（不涉及时间和会议室） | 先定位 `event_id`，再读 [+update](references/lark-calendar-update.md) 执行变更 |
 | 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |
+| 转让日程组织者（「把这个日程交给 XX」「组织者改成 XX」「这个会转给我」「bot 建完还给我」） | 读 [+transfer](references/lark-calendar-transfer.md)；`--as` 用**当前组织者**身份，`--to-user-id` 传接收人，用户和机器人任意互转 |
 
 ## 任务类型分流
 
@@ -165,8 +168,8 @@ lark-cli calendar <resource> <method> [flags]
 # 查询用户主日历
 lark-cli calendar calendars primary
 
-# 获取日程分享链接
-lark-cli calendar events share_info --calendar-id <calendar_id> --event-id <event_id>
+# 获取日程详情及 app_link
+lark-cli calendar events get --calendar-id <calendar_id> --event-id <event_id>
 
 # 删除日程
 lark-cli calendar events delete --calendar-id <calendar_id> --event-id <event_id>
@@ -196,7 +199,7 @@ lark-cli im +chat-search --query <query> --as user
 
 ## 不在本 skill 范围
 
-- 查询过去的视频会议记录 → [lark-vc](../lark-vc/SKILL.md)
+- 查询过去的视频会议记录 → [lark-meeting](../lark-meeting/SKILL.md)
 - 待办任务管理 → [lark-task](../lark-task/SKILL.md)
 - 通讯录 → [lark-contact](../lark-contact/SKILL.md)
 - 即时通讯 → [lark-im](../lark-im/SKILL.md)

package/skills/lark-calendar/references/lark-calendar-transfer.md

@@ -0,0 +1,89 @@
+# calendar +transfer
+
+把一个日程的**组织者（organizer）**转让给另一个用户或机器人。用户和机器人之间可以任意互转。
+
+## 命令
+
+```bash
+# 转让给某人（原组织者保留为参与人）
+lark-cli calendar +transfer --event-id <event_id> --to-user-id ou_xxx --yes
+
+# 转让并把原组织者从参与人中移除
+lark-cli calendar +transfer --event-id <event_id> --to-user-id ou_xxx --remove-original-organizer --yes
+
+# 指定日历
+lark-cli calendar +transfer --calendar-id <calendar_id> --event-id <event_id> --to-user-id ou_xxx --yes
+
+# 重复性日程：必须显式确认整个序列一起转让
+lark-cli calendar +transfer --event-id <event_id> --to-user-id ou_xxx --transfer-series --yes
+
+# 预览请求，不实际执行
+lark-cli calendar +transfer --event-id <event_id> --to-user-id ou_xxx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--event-id <id>` | **是** | 日程 ID（`uid_originalTime` 形式） |
+| `--to-user-id <ou_...>` | **是** | 接收人 open_id，成为新组织者；用户和机器人都可以 |
+| `--calendar-id <id>` | 否 | 日程所在日历 ID（省略则使用主日历） |
+| `--remove-original-organizer` | 否 | 转让后把原组织者移出参与人；默认保留。日程在共享日历上时服务端一定会移除 |
+| `--transfer-series` | 否 | 确认整个重复性序列一起转让；重复性日程必填 |
+| `--yes` | **是**（非 dry-run） | 高敏写操作确认 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 转让方向
+
+转出方和接收方是两个**互相独立**的参数，四种组合都支持：
+
+- **转出方**由 `--as` 决定，必须是日程**当前组织者**的身份。bot 组织的日程用 `--as bot`，用户自己的日程用 `--as user`。用非组织者身份调用会返回 403。
+- **接收方**由 `--to-user-id` 决定，传谁的 open_id 就转给谁，是人还是机器人不影响命令写法。
+
+| 方向 | 命令 |
+|------|------|
+| user → user | `--as user --to-user-id <对方用户 open_id>` |
+| user → bot | `--as user --to-user-id <bot 的 open_id>` |
+| bot → user | `--as bot --to-user-id <用户 open_id>` |
+| bot → bot | `--as bot --to-user-id <另一个 bot 的 open_id>` |
+
+**取接收人 open_id**：
+
+```bash
+# 用户
+lark-cli contact +search-user --query <姓名> --as user
+# 机器人：从它所在群的成员列表里取 bots[] 中的 open_id
+lark-cli im +chat-members-list --chat-id <chat_id> --member-types bot
+```
+
+机器人的 open_id 同样是 `ou_` 开头；不要传 `cli_` 开头的 app_id，那是应用 ID，不是日程参与人身份。
+
+无论哪个方向，转让都要求转出方和接收方**同租户**，且接收方能通过高管模式的协作校验。
+
+## 重复性日程
+
+后端按 `uid` 定位日程，忽略 `original_time`，**无法只转让某一次实例**。因此传入任何一个实例或例外的 `event_id`，都会把整个序列（含所有例外）一起转让。
+
+是重复性日程且未加 `--transfer-series` 时命令直接失败（`failed_precondition`），不会发出转让请求。收到这个错误时**先向用户确认"整个重复日程都转让"**，得到确认后再带 `--transfer-series` 重跑；不要自动重试。已确认时加 `--transfer-series` 会跳过这次预读。
+
+## 返回中的 `original_organizer_removed`
+
+**共享日历不属于任何组织者，转让时服务端会强制把原组织者移出日程；主日历则会把原组织者保留为参与人。** 转让接口成功时不返回这个结果，所以命令只在能确定时才输出该字段：
+
+| 情况 | 返回 |
+|------|------|
+| 带 `--remove-original-organizer` | `original_organizer_removed: true` |
+| 省略 `--calendar-id`（主日历） | `original_organizer_removed: false` |
+| 传了 `--calendar-id` 且未传 `--remove-original-organizer` | **不返回该字段**，stderr 给一条 note 说明共享日历会强制移除 |
+
+字段缺失时**不要**告诉用户"原组织者已保留为参与人"，也不要断言已被移除。需要确认就转让后读一次日程看参与人，或一开始就显式传 `--remove-original-organizer`。
+
+## 提示
+
+- 转让不可逆，且会连同日程上的会议纪要、笔记和附件一起移交给新组织者。
+- 需要 `calendar:calendar.event:transfer` 权限；转让前的重复性预读需要 `calendar:calendar.event:read`（带 `--transfer-series` 时不读）。
+
+## 参考
+
+- [lark-calendar](../SKILL.md) -- skill 入口与路由
+- [重复性日程操作规范](lark-calendar-recurring.md)

package/skills/lark-doc/references/lark-doc-fetch.md

@@ -127,7 +127,7 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
 |`<whiteboard>`|提取 `token`，使用 `docs +media-download`|
 |`<sheet>`、`<cite file-type="sheets">`|提取 `token` 和 `sheet-id`，转到 [`lark-sheets`](../../lark-sheets/SKILL.md)|
 |`<bitable>`、`<cite file-type="bitable">`|提取 `token` 和 `table-id`，转到 [`lark-base`](../../lark-base/SKILL.md)|
-|`<vc-transcribe-tab>`|提取 `vc-node-id`，使用 [`lark-note`](../../lark-note/SKILL.md) 的 `note +detail`|
+|`<vc-transcribe-tab>`|提取 `vc-node-id`，使用 [`lark-meeting`](../../lark-meeting/SKILL.md) 的 `note +detail`|
 |`<synced_reference>`|提取 `src-token` 和 `src-block-id`，读取源文档并定位 block|
 
 ## 参考

package/skills/lark-drive/references/lark-drive-add-comment.md

@@ -165,10 +165,10 @@ lark-cli drive +add-comment \
 - 未传 `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。全文评论支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终可解析为 `doc`/`docx`/`file` 的 wiki URL。
 - **Drive file 评论**：仅支持白名单扩展名的普通文件。当前支持：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。
 - **Drive file 暂不支持**：`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件会被 CLI 拒绝，并提示“当前还不支持这种类型的评论”。这些类型虽然可能接受 OpenAPI 请求，但在页面评论展示上存在问题。
-- **Drive file 只支持全文评论**：file 目标不支持局部评论，不允许传 `--block-id` 或 `--selection-with-ellipsis`。
+- **Drive file 只支持全文评论**：file 目标不支持局部评论，不允许传 `--block-id`。
 - 传 `--block-id` 时，shortcut 创建**局部评论（划词评论）**；该模式支持 `docx`、`sheet`、`slides`、Base / bitable，以及最终可解析为这些类型的 wiki URL。
 - **Sheet 评论**：当 `--doc` 为 sheet URL 或 wiki 解析为 sheet 时，使用 `--block-id "<sheetId>!<cell>"` 指定单元格（如 `a281f9!D6`）；sheet 没有全文评论，`--full-comment` 不可用。
-- **Slide 评论**：当 `--doc` 为 slides URL、`--type slides`，或 wiki 解析为 slides 时，必须传 `--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>"`。此时 `--full-comment` 和 `--selection-with-ellipsis` 不可用。
+- **Slide 评论**：当 `--doc` 为 slides URL、`--type slides`，或 wiki 解析为 slides 时，必须传 `--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>"`。此时 `--full-comment` 不可用。
 - **Base 记录局部评论**：Base 不支持全局评论，所有评论都挂在记录上；裸 token 可传 `--type bitable` 或 `--type base`，推荐 `bitable`。定位信息必须是 file token（base token）+ `--block-id "<table-id>!<record-id>!<view-id>"`，其中 table/record/view ID 通常分别以 `tbl`/`rec`/`vew` 开头；view_id 只决定被提及时点击通知打开哪个视图，不影响评论挂载点，但必须传。ID 获取参考 [`lark-base`](../../lark-base/SKILL.md)。
 - **Slide 参数映射示例**：`--block-id` 由 PPT XML 元素类型和元素 `id` 组成。例如：
     - `<slide id="pkk">` 对应 `--block-id slide!pkk`，表示给整页评论。

package/skills/lark-im/SKILL.md

@@ -109,7 +109,9 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 | [`+chat-messages-list`](references/lark-im-chat-messages-list.md) | List messages in a chat or P2P conversation; user/bot; accepts --chat-id or --user-id, resolves P2P chat_id, supports time range, --order asc/desc sorting, auto-pagination |
 | [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by --query keyword and/or --member-ids; user/bot; e.g. look up chat_id by group name; supports type filters, sorting, auto-pagination, and --exclude-muted (user identity only) |
 | [`+chat-update`](references/lark-im-chat-update.md) | Update group chat name or description; user/bot; updates a chat's name or description |
+| [`+message-read-users`](references/lark-im-message-read-status.md) | List users who read one message; user/bot; identity-specific scopes; supports bounded auto-pagination |
 | [`+messages-mget`](references/lark-im-messages-mget.md) | Batch get messages by IDs; user/bot; fetches up to 50 om_ message IDs, formats sender names, expands thread replies |
+| [`+messages-read-status`](references/lark-im-message-read-status.md) | Batch query whether the current user read 1–50 messages; user-only; returns readable items and invalid message IDs |
 | [`+messages-reply`](references/lark-im-messages-reply.md) | Reply to a message (supports thread replies); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key |
 | [`+messages-resources-download`](references/lark-im-messages-resources-download.md) | Download an image or file attached to a message; user/bot |
 | [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user or bot identity; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch_query |
@@ -169,10 +171,11 @@ lark-cli im <resource> <method> [flags] # 调用 API
 
 ### messages
 
+  - `read_status` — 批量查询当前用户对消息的已读状态。Identity: `user` only (`user_access_token`); accepts up to 50 message IDs and returns readable items plus invalid message IDs.[Must-read](references/lark-im-message-read-status.md)
   - `delete` — 撤回消息。Identity: supports `user` and `bot`; for `bot` calls, the bot must be in the chat to revoke group messages; to revoke another user's group message, the bot must be the owner, an admin, or the creator; for user P2P recalls, the target user must be within the bot's availability.
   - `forward` — 转发消息。Identity: supports `user` and `bot`.
   - `merge_forward` — 合并转发消息。Identity: `bot` only (`tenant_access_token`).
-  - `read_users` — 查询消息已读信息。Identity: `bot` only (`tenant_access_token`); the bot must be in the chat, and can only query read status for messages it sent within the last 7 days.
+  - `read_users` — 查询消息已读信息。Identity: supports `user` and `bot`; the caller must still be in the chat. A user can query messages they sent within the last 7 days, while a bot can query only messages sent by that bot within the last 7 days.[Must-read](references/lark-im-message-read-status.md)
   - `urgent_app` — 发送应用内加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
   - `urgent_phone` — 发送电话加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
   - `urgent_sms` — 发送短信加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
@@ -229,10 +232,13 @@ lark-cli im <resource> <method> [flags] # 调用 API
 | `chat.managers.delete_managers` | `im:chat.managers:write_only` |
 | `chat.moderation.get` | `im:chat.moderation:read` |
 | `chat.moderation.update` | `im:chat:moderation:write_only` |
+| `+messages-read-status` | user: `im:message:readonly` (recommended), `im:message`, or `im:message:get_as_user` |
+| `+message-read-users` | user: `im:message:readonly` (recommended), `im:message`, `im:message:basic`, or `im:message:get_as_user`; bot: `im:message:readonly` |
+| `messages.read_status` | `im:message:readonly` (recommended), `im:message`, or `im:message:get_as_user` |
 | `messages.delete` | `im:message:recall` |
 | `messages.forward` | `im:message` |
 | `messages.merge_forward` | `im:message` |
-| `messages.read_users` | `im:message:readonly` |
+| `messages.read_users` | user: `im:message:readonly` (recommended), `im:message`, `im:message:basic`, or `im:message:get_as_user`; bot: `im:message:readonly` |
 | `messages.urgent_app` | `im:message.urgent` |
 | `messages.urgent_phone` | `im:message.urgent:phone` |
 | `messages.urgent_sms` | `im:message.urgent:sms` |

package/skills/lark-im/references/lark-im-message-read-status.md

@@ -0,0 +1,96 @@
+# IM message read status
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first for authentication and global parameters.
+
+Use two focused shortcuts for message read-status queries:
+
+- `im +messages-read-status` queries whether the current user has read 1–50 messages.
+- `im +message-read-users` lists users who have read one message and supports automatic pagination.
+
+Both underlying OpenAPIs support user identity through a user access token (UAT). `+message-read-users` additionally supports bot identity through a tenant access token (TAT).
+
+## Identity and scopes
+
+| Shortcut | Identity | Scope |
+|---|---|---|
+| `+messages-read-status` | user only | `im:message:readonly` (recommended), `im:message`, or `im:message:get_as_user` |
+| `+message-read-users` | user | `im:message:readonly` (recommended), `im:message`, `im:message:basic`, or `im:message:get_as_user` |
+| `+message-read-users` | bot | `im:message:readonly` |
+
+For `+message-read-users`, the caller must still be in the chat. A user can query only messages they sent within the last seven days, while a bot can query only messages sent by that bot within the last seven days.
+The user scopes in the table are alternatives; the CLI preflight uses `im:message:readonly` because it is the least-privileged regular OAuth scope supported by this endpoint.
+
+## Batch query the current user's read status
+
+```bash
+# Preview one request
+lark-cli im +messages-read-status \
+  --message-ids om_xxx,om_yyy \
+  --as user \
+  --dry-run
+
+# Execute with a user access token
+lark-cli im +messages-read-status \
+  --message-ids om_xxx,om_yyy \
+  --as user \
+  --json
+```
+
+The command accepts 1–50 comma-separated `om_` message IDs. The three scopes above are alternatives; any one is sufficient, and the CLI recommends the least-privileged OAuth scope `im:message:readonly`. The response keeps the OpenAPI response unchanged:
+
+- `items[].message_id` and `items[].is_read` contain statuses the server could determine.
+- `invalid_message_ids` contains messages that do not exist, are not visible to the current user, or do not support this query. The API deliberately does not expose a more specific reason.
+
+## List users who read one message
+
+```bash
+# Fetch one page as the current user
+lark-cli im +message-read-users \
+  --message-id om_xxx \
+  --as user \
+  --json
+
+# Fetch every page as a bot, bounded to ten pages by default
+lark-cli im +message-read-users \
+  --message-id om_xxx \
+  --user-id-type open_id \
+  --page-all \
+  --as bot \
+  --json
+```
+
+Pagination flags:
+
+- `--page-size`: 1–100, default 100.
+- `--page-token`: start from a known cursor.
+- `--page-all`: continue until the endpoint is exhausted.
+- `--page-limit`: maximum pages with `--page-all`; default 10, range 1–1000.
+- `--page-delay`: delay in milliseconds between pages; default 200, and 0 disables the delay.
+
+The command preserves each server item, including `user_id_type`, `user_id`, `timestamp`, and `tenant_key`. Pagination metadata reports whether the endpoint was exhausted and retains the next token when a bounded run can be resumed.
+
+## Raw API commands
+
+When Registry MR !128 is published, the corresponding raw commands remain available:
+
+```bash
+lark-cli im messages read_status --data '{"message_ids":["om_xxx"]}' --as user
+lark-cli im messages read_users --params '{"message_id":"om_xxx","user_id_type":"open_id"}' --as user
+```
+
+Prefer the shortcuts for flag validation, identity-specific scope hints, and read-users auto-pagination.
+
+## Troubleshooting
+
+| Symptom | Meaning | Action |
+|---|---|---|
+| `--as bot is not supported` for read status | The batch endpoint requires user identity | Switch to `--as user` |
+| Missing `im:message:readonly` or `im:message` | A regular OAuth scope has not been granted | Follow the CLI authorization hint to grant one supported scope |
+| Missing a user read scope | No supported regular OAuth scope has been granted | Grant `im:message:readonly` and retry |
+| Bot permission denied | The application lacks a bot scope | Open the `console_url` from the typed error and enable the requested scope |
+| Empty read-user list | No user has read the message, or sender/time constraints are not met | Verify chat membership, the message sender, and the seven-day window |
+
+## References
+
+- [lark-im](../SKILL.md)
+- [lark-shared](../../lark-shared/SKILL.md)

package/skills/lark-mail/references/lark-mail-draft-create.md

@@ -24,37 +24,37 @@
 
 ```bash
 # 创建 HTML 草稿（推荐）
-lark-cli mail +draft-create --to alice@example.com --subject '周报' \
+lark-cli mail +draft-create --to 'alice@example.com' --subject '周报' \
   --body '<p>本周进展：</p><ul><li>完成 A 模块</li></ul>'
 
 # 不带收件人的 HTML 草稿（用户之后可自行添加）
 lark-cli mail +draft-create --subject '周报' --body '<p>草稿内容</p>'
 
 # 带附件和内嵌图片的 HTML 草稿（推荐：直接用相对路径，自动解析）
-lark-cli mail +draft-create --to alice@example.com --subject '预览图' --body '<p>见附件和图：<img src="./logo.png" /></p>' --attach ./report.pdf
+lark-cli mail +draft-create --to 'alice@example.com' --subject '预览图' --body '<p>见附件和图：<img src="./logo.png" /></p>' --attach './report.pdf'
 
 # 纯文本草稿（仅在内容极简时使用）
-lark-cli mail +draft-create --to alice@example.com --subject '简短通知' --body '收到，谢谢'
+lark-cli mail +draft-create --to 'alice@example.com' --subject '简短通知' --body '收到，谢谢'
 
 # Dry Run（仅打印请求，不执行）
-lark-cli mail +draft-create --to alice@example.com --subject '测试' --body 'test' --dry-run
+lark-cli mail +draft-create --to 'alice@example.com' --subject '测试' --body 'test' --dry-run
 ```
 
 ## 参数
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--to <emails>` | 否 | 完整收件人列表，多个用逗号分隔。支持 `Alice <alice@example.com>` 格式。省略时草稿不带收件人（之后可通过 `+draft-edit` 添加） |
+| `--to '<email>'` | 否 | 完整收件人列表。多个收件人请重复传 `--to`，每次只放一个地址，参数值用单引号包住。支持 `Alice <alice@example.com>` 格式。省略时草稿不带收件人（之后可通过 `+draft-edit` 添加） |
 | `--subject <text>` | 是 | 草稿主题 |
 | `--body <text>` | 二选一 | 邮件正文。推荐使用 HTML 获得富文本排版；也支持纯文本（自动检测）。使用 `--plain-text` 可强制纯文本模式。支持 `<img src="./local.png" />` 相对路径自动解析为内嵌图片（仅支持相对路径，不支持绝对路径）。与 `--body-file` 互斥 |
 | `--body-file <path>` | 二选一 | 从文件读取邮件正文 HTML（相对路径，仅限 cwd 子树）。与 `--body` 互斥。文件大小上限 32 MB |
 | `--from <email>` | 否 | 发件人邮箱地址（EML From 头）。使用别名（send_as）发信时，设为别名地址并配合 `--mailbox` 指定所属邮箱。省略时使用邮箱主地址 |
 | `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。当发件人（`--from`）与邮箱不同时使用，如通过别名或 send_as 地址发信。可通过 `accessible_mailboxes` 查询可用邮箱 |
-| `--cc <emails>` | 否 | 完整抄送列表，多个用逗号分隔 |
-| `--bcc <emails>` | 否 | 完整密送列表，多个用逗号分隔。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
+| `--cc '<email>'` | 否 | 完整抄送列表。多个抄送请重复传 `--cc`，每次只放一个地址，参数值用单引号包住 |
+| `--bcc '<email>'` | 否 | 完整密送列表。多个密送请重复传 `--bcc`，每次只放一个地址，参数值用单引号包住。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
 | `--plain-text` | 否 | 强制纯文本模式，忽略 HTML 自动检测。不可与 `--inline` 同时使用。纯文本模式下也会自动追加纯文本签名（HTML 签名经 `PlainTextFromHTML` 转换，内联图片丢弃） |
-| `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔。相对路径。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
-| `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--attach '<path>'` | 否 | 附件文件路径。多个附件请重复传 `--attach`，每次只放一个相对路径，参数值用单引号包住；按传入顺序追加。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
+| `--inline '<json>'` | 否 | 高级用法：手动指定内嵌图片 CID 映射。多个 inline 图片请重复传 `--inline`，每次只放一个 JSON object，并用单引号包住：`'{"cid":"mycid","file_path":"./logo.png"}'`。`file_path` 必须是相对路径；CID 应唯一，例如随机十六进制字符串；在 body 中用 `<img src="cid:mycid">` 引用。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。不可与 `--plain-text` 同时使用 |
 | `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到正文末尾。运行 `mail +signature` 查看可用签名。与 `--no-signature` 互斥 |
 | `--no-signature` | 否 | 跳过默认签名自动追加。与 `--signature-id` 互斥，同时使用时返回参数校验错误（退出码 2） |
 | `--priority <level>` | 否 | 邮件优先级：`high`、`normal`、`low`。省略或 `normal` 时不设置优先级 |
@@ -94,7 +94,7 @@ lark-cli mail +draft-create --to alice@example.com --subject '测试' --body 'te
 
 ```bash
 # 1. 创建草稿
-lark-cli mail +draft-create --to alice@example.com --subject 'Q1 报告' --body '请查收附件中的报告。' --attach ./q1-report.pdf --format json
+lark-cli mail +draft-create --to 'alice@example.com' --subject 'Q1 报告' --body '请查收附件中的报告。' --attach './q1-report.pdf' --format json
 
 # 2. 发送草稿
 lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}'
@@ -107,13 +107,13 @@ lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_
 ```bash
 # 推荐：直接使用相对路径，自动解析为内嵌图片
 lark-cli mail +draft-create \
-  --to alice@example.com \
+  --to 'alice@example.com' \
   --subject '通讯稿' \
   --body '<h1>你好</h1><img src="./banner.png" />'
 
 # 高级用法：手动指定 CID（CID 为唯一标识符，可用随机十六进制字符串）
 lark-cli mail +draft-create \
-  --to alice@example.com \
+  --to 'alice@example.com' \
   --subject '通讯稿' \
   --body '<h1>你好</h1><img src="cid:c7d8e9f0a1b2c3d4e5f6">' \
   --inline '[{"cid":"c7d8e9f0a1b2c3d4e5f6","file_path":"./banner.png"}]'