@wagemule/daemon 0.1.2 → 0.1.4

package/dist/skills/larksuite/lark-drive/references/lark-drive-task-result.md

@@ -0,0 +1,302 @@
+
+# drive +task_result
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询异步任务结果。该 shortcut 聚合了导入、导出、移动/删除文件夹、Wiki 节点 / 文档迁入 Wiki 等多种异步任务的结果查询，统一接口方便调用。
+
+> [!IMPORTANT]
+> 对于 `import` 场景，如果使用 `--as bot` 且这次查询**已经拿到最终在线文档目标**（`ready=true` 且返回了最终 `token` / `url`），CLI 会**再次尝试为当前 CLI 用户自动授予该资源的 `full_access`（可管理权限）**。
+>
+> 此时结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
+> - `status = granted`：当前 CLI 用户已获得该导入结果的可管理权限
+> - `status = skipped`：本地没有可用的当前用户 `open_id`，或最终结果缺少可授权的在线文档目标，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
+> - `status = failed`：导入结果已就绪，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文档
+>
+> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”。
+>
+> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+## 命令
+
+```bash
+# 查询导入任务结果
+lark-cli drive +task_result \
+  --scenario import \
+  --ticket <IMPORT_TICKET>
+
+# 查询导出任务结果
+lark-cli drive +task_result \
+  --scenario export \
+  --ticket <EXPORT_TICKET> \
+  --file-token <SOURCE_DOC_TOKEN>
+
+# 查询移动/删除文件夹任务状态
+lark-cli drive +task_result \
+  --scenario task_check \
+  --task-id <TASK_ID>
+
+# 查询 Wiki 移动任务结果（wiki +move 异步超时后的续跑）
+lark-cli drive +task_result \
+  --scenario wiki_move \
+  --task-id <TASK_ID>
+
+# 查询 Wiki 删除知识空间任务结果（wiki +delete-space 异步超时后的续跑）
+lark-cli drive +task_result \
+  --scenario wiki_delete_space \
+  --task-id <TASK_ID>
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--scenario` | 是 | 任务场景，可选值：`import` (导入任务)、`export` (导出任务)、`task_check` (移动/删除文件夹任务)、`wiki_move` (Wiki 移动任务)、`wiki_delete_space` (Wiki 删除知识空间任务) |
+| `--ticket` | 条件必填 | 异步任务 ticket，**import/export 场景必填** |
+| `--task-id` | 条件必填 | 异步任务 ID，**task_check / wiki_move / wiki_delete_space 场景必填** |
+| `--file-token` | 条件必填 | 导出任务对应的源文档 token，**export 场景必填** |
+
+## 场景说明
+
+| 场景 | 说明 | 所需参数 |
+|------|------|----------|
+| `import` | 文档导入任务（如将本地文件导入为云文档） | `--ticket` |
+| `export` | 文档导出任务（如云文档导出为 PDF/Word） | `--ticket`、`--file-token` |
+| `task_check` | 文件夹移动/删除任务 | `--task-id` |
+| `wiki_move` | Wiki 移动任务（`wiki +move` 的 docs-to-wiki 异步流程，超时后续跑用） | `--task-id` |
+| `wiki_delete_space` | Wiki 删除知识空间任务（`wiki +delete-space` 的异步流程，超时后续跑用） | `--task-id` |
+
+## 返回结果
+
+### Import 场景返回
+
+```json
+{
+  "scenario": "import",
+  "ticket": "<IMPORT_TICKET>",
+  "type": "sheet",
+  "ready": true,
+  "failed": false,
+  "job_status": 0,
+  "job_status_label": "success",
+  "job_error_msg": "success",
+  "token": "<IMPORTED_DOC_TOKEN>",
+  "url": "https://example.feishu.cn/sheets/<IMPORTED_DOC_TOKEN>",
+  "extra": ["2000"],
+  "permission_grant": {
+    "status": "granted",
+    "perm": "full_access",
+    "member_type": "openid",
+    "user_open_id": "<CURRENT_USER_OPEN_ID>",
+    "message": "Granted the current CLI user full_access (可管理权限) on the new spreadsheet."
+  }
+}
+```
+
+**字段说明：**
+- `ready`: 是否已经导入完成，可直接使用 `token` / `url`
+- `failed`: 是否已经失败
+- `job_status`: 服务端返回的原始状态码
+- `job_status_label`: 便于阅读的状态标签，例如 `success` / `processing`
+- `token`: 导入后的文档 token
+- `url`: 导入后的文档链接
+- `permission_grant`: 仅 `--as bot` 且这次查询已经拿到最终在线文档目标时返回，用于说明是否已自动为当前 CLI 用户授予可管理权限；如果当前仍是 `ready=false`，则不会返回这个字段
+
+### Export 场景返回
+
+```json
+{
+  "scenario": "export",
+  "ticket": "<EXPORT_TICKET>",
+  "ready": true,
+  "failed": false,
+  "file_extension": "pdf",
+  "type": "doc",
+  "file_name": "docName",
+  "file_token": "<EXPORTED_FILE_TOKEN>",
+  "file_size": 34356,
+  "job_error_msg": "success",
+  "job_status": 0,
+  "job_status_label": "success"
+}
+```
+
+**字段说明：**
+- `ready`: 是否已经完成导出，可直接使用 `file_token`
+- `failed`: 是否已经失败
+- `job_status`: 服务端返回的原始状态码
+- `job_status_label`: 便于阅读的状态标签，例如 `success` / `processing`
+- `file_token`: 导出文件的 token，用于下载
+- `file_extension`: 导出文件扩展名
+- `file_size`: 导出文件大小（字节）
+
+### Task_check 场景返回
+
+```json
+{
+  "scenario": "task_check",
+  "task_id": "<TASK_ID>",
+  "status": "success",
+  "ready": true,
+  "failed": false
+}
+```
+
+**字段说明：**
+- `status`: 任务状态，`success`=成功，`failed`=失败，`pending`=处理中
+- `ready`: 是否已经完成
+- `failed`: 是否已经失败
+
+### Wiki_move 场景返回
+
+```json
+{
+  "scenario": "wiki_move",
+  "task_id": "<TASK_ID>",
+  "ready": true,
+  "failed": false,
+  "status": 0,
+  "status_msg": "success",
+  "wiki_token": "wikcnXXX",
+  "node_token": "wikcnXXX",
+  "space_id": "<TARGET_SPACE_ID>",
+  "obj_token": "<OBJ_TOKEN>",
+  "obj_type": "docx",
+  "parent_node_token": "",
+  "node_type": "origin",
+  "origin_node_token": "",
+  "title": "项目计划",
+  "has_child": false,
+  "node": {
+    "space_id": "<TARGET_SPACE_ID>",
+    "node_token": "wikcnXXX",
+    "obj_token": "<OBJ_TOKEN>",
+    "obj_type": "docx",
+    "parent_node_token": "",
+    "node_type": "origin",
+    "origin_node_token": "",
+    "title": "项目计划",
+    "has_child": false
+  },
+  "move_results": [
+    {
+      "status": 0,
+      "status_msg": "success",
+      "node": { "...": "同上" }
+    }
+  ]
+}
+```
+
+**字段说明：**
+- `ready`: 所有 `move_results[].status` 都为 `0` 时为 `true`
+- `failed`: 任一 `move_results[].status` 小于 `0` 时为 `true`
+- `status` / `status_msg`: 第一个 move_result 的状态码 / 标签（无结果时回退为 `1` / `processing`）
+- `wiki_token` / `node_token`: 移入 Wiki 后的目标节点 token（首个结果有 `node.node_token` 时镜像到顶层，便于下游脚本使用）
+- `space_id`、`obj_token`、`obj_type`、`title` 等：从首个 `move_results[0].node` 平铺到顶层，方便直接引用
+- `move_results`: 保留完整列表（适用于一次任务移动多个文档的场景）
+
+### Wiki_delete_space 场景返回
+
+```json
+{
+  "scenario": "wiki_delete_space",
+  "task_id": "<TASK_ID>",
+  "ready": true,
+  "failed": false,
+  "status": "success",
+  "status_msg": "success"
+}
+```
+
+**字段说明：**
+- `ready`: `status=success` 时为 `true`
+- `failed`: `status=failure` 或 `failed` 时为 `true`；未知非成功状态（如 `processing`）视为进行中
+- `status`: 服务端返回的原始 `delete_space_result.status`
+- `status_msg`: 优先使用 `delete_space_result.status_msg`，否则回落到 `status`，再回落到 `processing`
+
+## 使用场景
+
+### 配合 +import 使用
+
+```bash
+# 1. 创建导入任务
+lark-cli drive +import --file ./data.xlsx --type sheet
+# 若任务很快完成：直接返回 token / url
+# 若内置轮询超时：返回 ready=false、ticket 和 next_command
+
+# 2. 轮询导入结果
+lark-cli drive +task_result --scenario import --ticket <IMPORT_TICKET>
+# 如果这里返回 ready=true 且使用 --as bot，结果还会包含 permission_grant
+```
+
+### 配合 +move 使用
+
+```bash
+# 1. 移动文件夹（异步操作）
+lark-cli drive +move --file-token <FOLDER_TOKEN> --type folder --folder-token <TARGET_FOLDER_TOKEN>
+# 若轮询窗口内完成：直接返回 ready=true
+# 若内置轮询结束仍未完成：返回 ready=false、task_id 和 next_command
+
+# 2. 轮询移动结果
+lark-cli drive +task_result --scenario task_check --task-id <TASK_ID>
+```
+
+### 配合 wiki +move 使用
+
+```bash
+# 1. 把 Drive 文档迁入 Wiki（异步任务可能返回 task_id）
+lark-cli wiki +move --obj-type docx --obj-token <DOC_TOKEN> --target-space-id <TARGET_SPACE_ID>
+# 若内置轮询窗口内完成：直接返回 ready=true 和 wiki_token
+# 若轮询窗口结束仍未完成：返回 ready=false、task_id、timed_out=true 和 next_command
+
+# 2. 续跑查询 Wiki 移动结果（next_command 即下面这条）
+lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID> --as user
+```
+
+> **身份保持一致**：续跑命令的 `--as` 必须与原 `wiki +move` 调用一致；`wiki +move` 的 `next_command` 已自动带上正确的 `--as`。
+
+### 配合 wiki +delete-space 使用
+
+```bash
+# 1. 删除知识空间（高风险写操作，必须显式带 --yes；接口可能同步返回空 task_id，也可能返回异步 task_id）
+lark-cli wiki +delete-space --space-id <SPACE_ID> --yes
+# 若同步返回：直接 ready=true
+# 若轮询窗口结束仍未完成：返回 ready=false、task_id、timed_out=true 和 next_command
+
+# 2. 续跑查询 Wiki 删除结果（next_command 即下面这条）
+lark-cli drive +task_result --scenario wiki_delete_space --task-id <TASK_ID> --as user
+```
+
+### 配合 +export 使用
+
+```bash
+# 1. 发起导出
+lark-cli drive +export --token <SOURCE_DOC_TOKEN> --doc-type docx --file-extension pdf
+# 若轮询窗口内完成：直接下载本地文件
+# 若内置轮询结束仍未完成：返回 ready=false、ticket 和 next_command
+
+# 2. 继续查询导出结果
+lark-cli drive +task_result --scenario export --ticket <EXPORT_TICKET> --file-token <SOURCE_DOC_TOKEN>
+
+# 3. 拿到 file_token 后下载
+lark-cli drive +export-download --file-token <EXPORTED_FILE_TOKEN>
+```
+
+## 权限要求
+
+| 场景 | 所需 scope |
+|------|-----------|
+| import | `drive:drive.metadata:readonly` |
+| export | `drive:drive.metadata:readonly` |
+| task_check | `drive:drive.metadata:readonly` |
+| wiki_move | `wiki:space:read` |
+| wiki_delete_space | `wiki:space:read` |
+
+> [!NOTE]
+> `import` 场景在 `--as bot` 且任务最终就绪时，还可能额外尝试一次协作者授权；如果 `permission_grant.status = failed`，请根据失败信息检查应用是否具备相应的文档协作者授权能力。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/dist/skills/larksuite/lark-drive/references/lark-drive-upload.md

@@ -0,0 +1,101 @@
+
+# drive +upload
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+上传本地文件到飞书云空间。目标位置可以是 Drive 文件夹，也可以是 wiki 节点。
+
+## 快速决策
+- 用户要在 Drive 里上传、创建、读取、覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../../lark-markdown/SKILL.md)。
+
+## 命令
+
+```bash
+# 上传到 Drive 文件夹
+lark-cli drive +upload --file ./report.pdf --folder-token fldbc_xxx
+
+# 上传到 wiki 节点
+lark-cli drive +upload --file ./report.pdf --wiki-token wikcn_xxx
+
+# 不指定目标时，上传到调用者的 Drive 根目录
+lark-cli drive +upload --file ./report.pdf
+
+# 自定义上传后的文件名
+lark-cli drive +upload --file ./report.pdf --name "季度总结.pdf"
+
+# 覆盖已存在文件（原地覆盖，保留 file_token）
+lark-cli drive +upload --file ./report.pdf --file-token boxcn_existing_file
+
+# 原生命令（高级/分片上传）：预上传 + 完成上传
+lark-cli drive files upload_prepare --data '{
+  "file_name": "report.pdf",
+  "parent_type": "explorer",
+  "parent_node": "fldbc_xxx",
+  "size": 1048576,
+  "file_token": "boxcn_existing_file"
+}'
+lark-cli drive files upload_finish --data '{
+  "upload_id": "<UPLOAD_ID>",
+  "block_num": 1
+}'
+
+# 查看完整参数定义
+lark-cli schema drive.files.upload_prepare
+```
+
+> [!IMPORTANT]
+> 如果文件是**以应用身份（bot）新建上传**的，如 `lark-cli drive +upload --as bot` 在上传成功后，CLI 会**尝试为当前 CLI 用户自动授予该文件的 `full_access`（可管理权限）**。
+>
+> 如果这次调用传了 `--file-token`，表示是在**覆盖已有文件**，CLI **不会**额外修改该文件权限。
+>
+> 以应用身份上传时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
+> - `status = granted`：当前 CLI 用户已获得该文件的可管理权限
+> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
+> - `status = failed`：文件已上传成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文件
+>
+> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”。
+>
+> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+> [!TIP]
+> 当底层上传接口返回版本号时，shortcut 会在结果里额外透出 `version`。
+
+## 目标位置选择（关键）
+
+- 上传到 Drive 文件夹：传 `--folder-token <folder_token>`，shortcut 会发送 `parent_type=explorer`
+- 上传到 wiki 节点：传 `--wiki-token <wiki_token>`，shortcut 会发送 `parent_type=wiki`
+- 上传到 Drive 根目录：`--folder-token` 和 `--wiki-token` 都不传
+- 覆盖已有文件：额外传 `--file-token <existing_file_token>`；shortcut 会把它原样透传到底层 `upload_all` / `upload_prepare`，让后端按覆盖语义写入
+- bot 模式下，`--file-token` 覆盖只改文件内容；不会额外给当前 CLI 用户补 `full_access`
+- 不要传空目标值：`--folder-token ""` / `--wiki-token ""` 会被视为参数错误；如需上传到 Drive 根目录，应直接省略这两个参数
+- 不要传空 `--file-token`：如需新建上传，直接省略该参数；显式传空字符串会报错
+- `--folder-token` 和 `--wiki-token` 互斥，不要同时传
+- `--wiki-token` 传的是 **wiki node token**，不是 `space_id`
+
+Shortcut 参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file` | 是 | 本地文件路径 |
+| `--file-token` | 否 | 已存在文件的 token；传入后按“覆盖已有文件”语义上传 |
+| `--folder-token` | 否 | 目标文件夹 token；与 `--wiki-token` 互斥；省略时默认为 Drive 根目录；显式传空字符串会报错 |
+| `--wiki-token` | 否 | 目标 wiki 节点 token；与 `--folder-token` 互斥；会映射为 `parent_type=wiki`、`parent_node=<wiki_token>`；显式传空字符串会报错 |
+| `--name` | 否 | 上传后的文件名；默认使用本地文件名 |
+
+参数（预上传 `--data` JSON body）：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `file_name` | 是 | 文件名 |
+| `parent_type` | 是 | 父节点类型；上传到文件夹 / 根目录时用 `"explorer"`，上传到 wiki 节点时用 `"wiki"` |
+| `parent_node` | 是 | 父节点 token；`explorer` 时传文件夹 token（根目录可为空字符串），`wiki` 时传 wiki node token |
+| `size` | 是 | 文件大小（字节） |
+| `file_token` | 否 | 已存在文件 token；传入后覆盖该文件内容 |
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,145 @@
+---
+name: lark-event
+version: 1.0.0
+description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume <EventKey>` (covers IM message receive, reactions, chat member changes, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses."
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli event --help"
+---
+
+# Lark Events
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) first for authentication, `--as user/bot` switching, `Permission denied` handling, and safety rules.
+
+## Core commands
+
+| Command | Purpose |
+|------|------|
+| `lark-cli event list [--json]` | List all subscribable EventKeys |
+| `lark-cli event schema <EventKey> [--json]` | Show an EventKey's params and output schema |
+| `lark-cli event consume <EventKey> [flags]` | Blocking consume; events → stdout NDJSON |
+| `lark-cli event status [--json] [--fail-on-orphan]` | Inspect the local bus daemon status |
+| `lark-cli event stop [--all] [--force]` | Stop the bus daemon |
+
+
+## Common flags
+
+| Flag | Description |
+|---|---|
+| `--param key=value` / `-p` | Business params (repeatable; comma-separated for multi-value). Unknown keys fail with valid names listed inline |
+| `--jq <expr>` | jq expression to filter / transform each event; empty output skips the event |
+| `--max-events N` | Exit after N events. Default 0 = unlimited |
+| `--timeout D` | Exit after duration D (e.g. `30s`, `2m`). Default 0 = no timeout. Whichever of `--max-events` / `--timeout` fires first wins |
+| `--output-dir <dir>` | Write each event as a file (relative paths only; prevents traversal) |
+| `--quiet` | Suppress stderr diagnostics. **AI should not use this** — it silences the ready marker |
+| `--as user\|bot\|auto` | Identity for the session (see lark-shared) |
+
+
+## Examples
+
+```bash
+# Default: stream every event for the key (no filter, no projection)
+lark-cli event consume im.message.receive_v1 --as bot
+
+# Grab one sample event to inspect payload shape
+lark-cli event consume im.message.receive_v1 --max-events 1 --timeout 30s --as bot
+
+# Run for 10 minutes then auto-exit
+lark-cli event consume im.message.receive_v1 --timeout 10m --as bot
+
+# Consume multiple EventKeys concurrently (one shape per process, no dispatcher)
+lark-cli event consume im.message.receive_v1          --as bot > receive.ndjson &
+lark-cli event consume im.message.reaction.created_v1 --as bot > reaction.ndjson &
+wait
+
+```
+
+## Call flow
+
+1. `lark-cli event list --json` → pick a legal key
+2. `lark-cli event schema <key> --json` → read `resolved_output_schema` + `jq_root_path` to determine field paths
+3. `lark-cli event consume <key> [--jq '<expr>']` → consume
+
+## Subprocess contract
+
+### Ready marker
+
+`event consume`'s stderr emits a fixed line `[event] ready event_key=<key>`. **Parent processes should block on stderr until this line appears, then start reading stdout.** Do not fall back to `sleep`.
+
+### stdin EOF = graceful exit
+
+`event consume` treats stdin close as a shutdown signal (wired for AI subprocess callers). `< /dev/null` / `nohup` / systemd's default `StandardInput=null` will cause an immediate graceful exit (stderr `reason: signal`). To keep running:
+
+- Feed stdin a source that never EOFs: `< <(tail -f /dev/null)`
+- Or run bounded: `--max-events N` / `--timeout D`
+
+### Exit codes & reason
+
+On exit, the last stderr line is `[event] exited — received N event(s) in Xs (reason: ...)`.
+
+| exit code | reason | Trigger |
+|---|---|---|
+| 0 | `reason: limit` | `--max-events` reached |
+| 0 | `reason: timeout` | `--timeout` reached |
+| 0 | `reason: signal` | Ctrl+C / SIGTERM / stdin EOF |
+| non-0 | `Error: ...` (no `exited` line) | Startup / runtime failure (permissions, network, params, config) |
+
+Orchestrators should treat `reason: limit/timeout/signal` (all exit 0) as "business completion" and non-zero as "failure".
+
+### Never `kill -9`
+
+**Avoid `kill -9` on consume processes**: for EventKeys with a **PreConsume hook** (those that register server-side subscriptions via OAPI), `kill -9` skips the OAPI unsubscribe and leaks server-side subscriptions (symptoms: "subscription already exists" on restart, duplicate event delivery). Prefer SIGTERM or closing stdin.
+
+### One consume, one EventKey (multi-key = multi-shell)
+
+The command takes exactly one positional argument; `k1,k2` and wildcards are unsupported. Listening to N keys means N subprocesses — this is **intentional**:
+
+- One shape per process stdout; no dispatcher logic required in the AI
+- Fault isolation (one key failing doesn't affect others)
+- Independent `--as` / `--jq` / `--max-events` / `--timeout` per key
+
+All N consumers share a single bus daemon (UDS local IPC), so the overhead is small
+
+## Writing jq via schema
+
+`event schema <key> --json` is the source of truth for writing `--jq`. Four things to look at:
+
+**(1) Where fields start** — see `jq_root_path`
+
+- Value `"."` → fields are at the top level, write `.chat_id`
+- Value `".event"` → fields are inside a V2 envelope, write `.event.chat_id`
+
+**(2) Field list and types** — see `resolved_output_schema.properties.<name>`
+
+Each field carries `type` / `description`, and some also have `format`. Snippet (from `event schema im.message.receive_v1 --json`):
+
+```json
+{
+  "chat_id":     {"type":"string", "format":"chat_id",      "description":"Chat ID, prefixed with oc_"},
+  "sender_id":   {"type":"string", "format":"open_id",      "description":"Sender open_id, prefixed with ou_"},
+  "create_time": {"type":"string", "format":"timestamp_ms", "description":"Send time as ms-epoch string"}
+}
+```
+
+**(3) Field semantics** — see the `format` tag
+
+Lark-defined semantic tags (**not** JSON Schema's standard `format`). Common values: `open_id` / `chat_id` / `message_id` / `timestamp_ms` / `email`. Purpose: distinguish "same string type, different meanings" fields so you can reverse-lookup via API or convert formats.
+
+**(4) Decoded state** — read the field's `description`
+
+`event consume` runs Process hooks that may pre-decode some payload fields (flattening V2 envelopes, rendering `.content` to plain text, etc.) — behavior differs from raw OAPI. **Always read the field's `description` before writing jq**, especially for generic field names like `content` / `data` / `body` / `payload`.
+
+**Why it matters**: blindly applying `fromjson` to an already-decoded text field makes jq error on every event and silently drop it — the consumer looks alive but emits nothing, with only a single `WARN` line buried on stderr. (This is the general behavior: any jq runtime error skips the event with a one-line WARN; the loop does not abort.)
+
+**Don't shortcut the schema**: when projecting `event schema --json` with jq, do not strip `.description` from `properties` — that's the field that tells you whether a field is already decoded. Dump the full property objects, not just keys.
+
+---
+
+**Aside**: `--param`'s valid parameters also live in the schema — the `params` section lists `name` / `type` / `required` / `enum` / `default` / `description`; **section missing = this key accepts no `--param`**.
+
+## Topic index
+
+| Topic | Reference | Coverage |
+|---|---|---|
+| IM | [`references/lark-event-im.md`](references/lark-event-im.md) | Catalog of 11 IM EventKeys + shape notes (flat vs V2 envelope) + `im.message.receive_v1` field gotchas (`sender_id` is open_id only; `.content` is plain text except for `interactive` cards) + common jq recipes (filter by chat_type / message_type / sender) |

package/dist/skills/larksuite/lark-event/references/lark-event-im.md

@@ -0,0 +1,86 @@
+# IM Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+>
+> **Heads-up for AI agents**: this key's `.content` is **NOT** the raw OAPI payload shape your training data may suggest. `lark-cli` runs a Process hook (`convertlib`) that flattens the V2 envelope and **pre-renders** `.content` to human-readable text for `text` / `post` / `image` / `file` / `audio` / etc. Only `interactive` (cards) keeps the raw JSON string. Don't blindly `fromjson`.
+
+## Key catalog (11)
+
+| EventKey | Purpose |
+|---|---|
+| `im.message.receive_v1` | Receive IM messages |
+| `im.message.message_read_v1` | User read a bot's **p2p** message (group messages don't fire this) |
+| `im.message.reaction.created_v1` | Reaction added to a message |
+| `im.message.reaction.deleted_v1` | Reaction removed from a message |
+| `im.chat.updated_v1` | Chat settings changed (owner, avatar, name, permissions, etc.) |
+| `im.chat.disbanded_v1` | Chat disbanded |
+| `im.chat.member.bot.added_v1` | Bot added to a chat |
+| `im.chat.member.bot.deleted_v1` | Bot removed from a chat |
+| `im.chat.member.user.added_v1` | User joined a chat (including topic chats) |
+| `im.chat.member.user.deleted_v1` | User left voluntarily **or** was removed |
+| `im.chat.member.user.withdrawn_v1` | Pending chat invite withdrawn (inviter canceled; user never actually joined) |
+
+> **Shape**: `im.message.receive_v1` is the only flat key (fields at `.xxx`); the other 10 are V2-enveloped (fields at `.event.xxx`).
+
+## Gotchas (`im.message.receive_v1`)
+
+**sender_id is open_id only**: the event payload carries no display name. Call the contact API separately if you need the sender's name.
+
+**`.content` shape depends on `message_type`** (this key uses a flat Custom schema; see [`events/im/message_receive.go`](../../../events/im/message_receive.go)):
+
+| message_type | `.content` shape | How to read |
+|---|---|---|
+| `text` / `post` / `image` / `file` / `audio` / `sticker` / `share_chat` / `share_user` / `media` / `system` | Human-readable text (convertlib-processed; `@mentions` resolved to display names) | Use `.content` directly |
+| `interactive` (card) | Raw card JSON string (structured actions can't be losslessly flattened) | `.content \| fromjson` to get the card object |
+
+**Do not blindly `fromjson`** — for non-interactive messages it fails with `jq: fromjson cannot be applied to "hello"` because `.content` isn't JSON-encoded.
+
+```bash
+# text: .content is plain text — no fromjson needed
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="text") | .content'
+
+# interactive: .content is a JSON string — fromjson to parse
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="interactive") | .content | fromjson'
+```
+
+## On-demand filter recipes
+
+> **Default = no `--jq`.** Run `lark-cli event consume im.message.receive_v1 --as bot` to see every message. The recipes below are only for cases where the user has asked to narrow the stream.
+
+### 1. Filter by chat type (p2p vs group)
+
+`chat_type` is an enum with values `p2p` / `group`.
+
+```bash
+# p2p only (direct messages)
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.chat_type=="p2p") | {from: .sender_id, msg: .content}'
+
+# group only
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.chat_type=="group") | {chat: .chat_id, from: .sender_id, msg: .content}'
+```
+
+### 2. Filter by message type
+
+```bash
+# text only — content is plain human-readable text
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="text") | .content'
+
+# interactive (card) only — parse the card body
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="interactive") | .content | fromjson'
+```
+
+### 3. Filter by sender (only one user's messages)
+
+```bash
+# example: only messages from the given open_id
+lark-cli event consume im.message.receive_v1 --as bot\
+  --jq 'select(.sender_id=="ou_xxxxxxxxxxxxxxxxxxxxxxxxxx") | {msg_id: .message_id, text: .content}'
+```
+
+Get your own open_id via `lark-cli contact +get-user --as user`; other users' via `lark-cli contact +search-user`.