@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.28c4f05 → 0.1.0-dev.4e64c13

package/shared/lark-cli/lark-im/references/lark-im-reactions.md

@@ -0,0 +1,232 @@
+# im reactions
+
+This reference is the annotation target for the read-only IM reaction APIs available in this sandbox:
+
+- `im.reactions.list`
+- `im.reactions.batch_query`
+
+It focuses on:
+
+- What each reaction read method does
+- The request/response shape you need when calling the raw API commands
+- The complete `emoji_type` list used in reaction payloads and filters
+
+> **Important:** These raw API commands accept structured input through `--params '<json>'` and `--data '<json>'`. They do not expose typed flags such as `--message-id` or `--reaction-type` directly.
+
+## Command Overview
+
+| Method | HTTP | Path | Purpose |
+|---|---|---|---|
+| `im.reactions.list` | `GET` | `/open-apis/im/v1/messages/{message_id}/reactions` | List reaction records on one message |
+| `im.reactions.batch_query` | `POST` | `/open-apis/im/v1/messages/reactions/batch_query` | Query reactions for multiple messages in one request |
+
+## Common Notes
+
+- `message_id` is always an IM message ID such as `om_xxx`
+- `reaction_id` is the unique record ID of a reaction
+- `reaction_type.emoji_type` is the enum-like emoji identifier used by the read APIs
+- Reaction APIs return **reaction records**, not only aggregated counts
+- When the operator is a human user, the returned ID type may depend on `user_id_type`
+
+## Inspect Schema
+
+```bash
+lark-cli schema im.reactions
+lark-cli schema im.reactions.list --format pretty
+```
+
+If your local build has already exposed the batch API in `schema`, also check:
+
+```bash
+lark-cli schema im.reactions.batch_query --format pretty
+```
+
+## list
+
+List reaction records on one message.
+
+```bash
+lark-cli im reactions list --params '{"message_id":"om_xxx"}'
+lark-cli im reactions list --params '{"message_id":"om_xxx","reaction_type":"SMILE"}'
+lark-cli im reactions list --params '{"message_id":"om_xxx","page_size":50}'
+lark-cli im reactions list --params '{"message_id":"om_xxx","page_token":"<PAGE_TOKEN>"}'
+lark-cli im reactions list --params '{"message_id":"om_xxx","user_id_type":"open_id"}'
+```
+
+### Request Parameters (`--params`)
+
+| Parameter | Required | Description |
+|---|---|---|
+| `message_id` | Yes | Message ID (`om_xxx`) |
+| `reaction_type` | No | Filter by one emoji type such as `SMILE` or `LAUGH` |
+| `page_size` | No | Number of records per page. Default is 20 |
+| `page_token` | No | Pagination token from the previous page |
+| `user_id_type` | No | Returned operator ID type when `operator_type=user`: `open_id`, `union_id`, or `user_id` |
+
+### Response Shape
+
+```json
+{
+  "items": [
+    {
+      "reaction_id": "ZCaCIjUBVVWSrm5L-3ZTw_xxx",
+      "operator": {
+        "operator_id": "ou_xxx",
+        "operator_type": "user"
+      },
+      "action_time": "1663054162546",
+      "reaction_type": {
+        "emoji_type": "SMILE"
+      }
+    }
+  ],
+  "has_more": true,
+  "page_token": "YhljsPiGfUgnVAg9urvRFd-BvSqRLxxxx"
+}
+```
+
+### Top-Level Fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `items` | `array<object>` | Reaction records for the current page |
+| `has_more` | `boolean` | Whether more pages are available |
+| `page_token` | `string` | Token for the next page when `has_more=true` |
+
+### `items[]` Fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `reaction_id` | `string` | Unique ID of this reaction record |
+| `operator` | `object` | Identity of the user or app that added the reaction |
+| `action_time` | `string` | Unix timestamp in milliseconds |
+| `reaction_type` | `object` | Reaction payload. The key field is `emoji_type` |
+
+### `operator` Fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `operator.operator_id` | `string` | Operator ID. If `operator_type=user`, the returned ID type follows `user_id_type`; if `operator_type=app`, this is the app ID |
+| `operator.operator_type` | `string` | `user` or `app` |
+
+## batch_query
+
+Query reactions for multiple messages in one request.
+
+```bash
+lark-cli im reactions batch_query \
+  --params '{"user_id_type":"open_id"}' \
+  --data '{
+    "queries":[
+      {"message_id":"om_xxx"},
+      {"message_id":"om_yyy","page_token":"<PAGE_TOKEN>"}
+    ],
+    "page_size_per_message":10,
+    "reaction_type":"LAUGH"
+  }'
+```
+
+### Request
+
+#### `--params`
+
+| Parameter | Required | Description |
+|---|---|---|
+| `user_id_type` | No | Returned user ID type in operator info: `open_id`, `union_id`, or `user_id` |
+
+#### `--data`
+
+| Field | Required | Description |
+|---|---|---|
+| `queries` | Yes | Array of target messages |
+| `queries[].message_id` | No | Message ID to query |
+| `queries[].page_token` | No | Continuation token for that message |
+| `page_size_per_message` | No | Max reactions returned per message |
+| `reaction_type` | No | Filter by one emoji type |
+
+### Response
+
+The meta definition contains three top-level result groups:
+
+| Field | Meaning |
+|---|---|
+| `success_msg_reaction_details` | Per-message reaction detail records |
+| `success_msg_reaction_counts` | Per-message aggregated reaction counts |
+| `fail_msg_reaction_details` | Query failures for individual messages |
+
+#### `success_msg_reaction_details`
+
+Each `message_reaction_items[]` element includes:
+
+- `reaction_id`
+- `operator`
+- `action_time`
+- `emoji_type`
+
+#### `success_msg_reaction_counts`
+
+Each aggregated count record includes:
+
+- `message_id`
+- `reaction_count[].reaction_type`
+- `reaction_count[].count`
+
+#### `fail_msg_reaction_details`
+
+Each failed message record includes:
+
+- `message_id`
+- `fail_reason`
+
+Supported `fail_reason` values from meta:
+
+- `invalid`
+- `invalid_page_token`
+- `no_permission`
+
+## `emoji_type` Field
+
+Reaction emoji identifiers are used in slightly different field names across the read APIs:
+
+- `im.reactions.list`: request filter uses `reaction_type`, response uses `reaction_type.emoji_type`
+- `im.reactions.batch_query`: request filter uses top-level `reaction_type`, detail results use `message_reaction_items[].emoji_type`, aggregated results use `reaction_count[].reaction_type`
+
+## Complete `emoji_type` List
+
+The following list is synchronized from the official Feishu reaction emoji documentation:
+
+- Source page: `https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce`
+- Markdown source: `https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce.md`
+
+Current count in the fetched source: `185`.
+
+```text
+OK, THUMBSUP, THANKS, MUSCLE, FINGERHEART, APPLAUSE, FISTBUMP, JIAYI
+DONE, SMILE, BLUSH, LAUGH, SMIRK, LOL, FACEPALM, LOVE
+WINK, PROUD, WITTY, SMART, SCOWL, THINKING, SOB, CRY
+ERROR, NOSEPICK, HAUGHTY, SLAP, SPITBLOOD, TOASTED, GLANCE, DULL
+INNOCENTSMILE, JOYFUL, WOW, TRICK, YEAH, ENOUGH, TEARS, EMBARRASSED
+KISS, SMOOCH, DROOL, OBSESSED, MONEY, TEASE, SHOWOFF, COMFORT
+CLAP, PRAISE, STRIVE, XBLUSH, SILENT, WAVE, WHAT, FROWN
+SHY, DIZZY, LOOKDOWN, CHUCKLE, WAIL, CRAZY, WHIMPER, HUG
+BLUBBER, WRONGED, HUSKY, SHHH, SMUG, ANGRY, HAMMER, SHOCKED
+TERROR, PETRIFIED, SKULL, SWEAT, SPEECHLESS, SLEEP, DROWSY, YAWN
+SICK, PUKE, BETRAYED, HEADSET, EatingFood, MeMeMe, Sigh, Typing
+Lemon, Get, LGTM, OnIt, OneSecond, VRHeadset, YouAreTheBest, SALUTE
+SHAKE, HIGHFIVE, UPPERLEFT, ThumbsDown, SLIGHT, TONGUE, EYESCLOSED, RoarForYou
+CALF, BEAR, BULL, RAINBOWPUKE, ROSE, HEART, PARTY, LIPS
+BEER, CAKE, GIFT, CUCUMBER, Drumstick, Pepper, CANDIEDHAWS, BubbleTea
+Coffee, Yes, No, OKR, CheckMark, CrossMark, MinusOne, Hundred
+AWESOMEN, Pin, Alarm, Loudspeaker, Trophy, Fire, BOMB, Music
+XmasTree, Snowman, XmasHat, FIREWORKS, 2022, REDPACKET, FORTUNE, LUCK
+FIRECRACKER, StickyRiceBalls, HEARTBROKEN, POOP, StatusFlashOfInspiration, 18X, CLEAVER, Soccer
+Basketball, GeneralDoNotDisturb, Status_PrivateMessage, GeneralInMeetingBusy, StatusReading, StatusInFlight, GeneralBusinessTrip, GeneralWorkFromHome
+StatusEnjoyLife, GeneralTravellingCar, StatusBus, GeneralSun, GeneralMoonRest, MoonRabbit, Mooncake, JubilantRabbit
+TV, Movie, Pumpkin, BeamingFace, Delighted, ColdSweat, FullMoonFace, Partying
+GoGoGo, ThanksFace, SaluteFace, Shrug, ClownFace, HappyDragon
+```
+
+## References
+
+- [lark-im](../README.md) - all IM commands
+- Official emoji doc: `https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce`

package/shared/lark-cli/lark-minutes/README.md

@@ -0,0 +1,51 @@
+# minutes (v1)
+
+## 身份
+
+所有 minutes 命令默认使用 `--as user`。
+
+## Shortcuts
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+download`](references/lark-minutes-download.md) | 下载妙记音视频媒体文件 |
+
+- 使用 Shortcut 前，必须先读其对应 reference 文档。
+
+## 意图路由
+
+| 用户意图 | 命令 |
+|---------|------|
+| 下载妙记音视频文件、获取媒体下载链接 | `+download` |
+| 妙记基础信息：标题 / 时长 / 封面 / 链接 / 所有者 | `minutes minutes get` |
+
+## 核心概念
+
+- **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，通过 `minute_token` 标识。
+- **妙记 Token（minute_token）**：妙记的唯一标识符，可从妙记 URL 末尾提取（如 `https://*.feishu.cn/minutes/obcnxxx` 中的 `obcnxxx`）。如果 URL 中包含额外参数（如 `?xxx`），截取路径最后一段。
+
+## 核心场景
+
+### 查看妙记基础信息
+
+1. 当用户只需要确认某条妙记的标题、封面、时长、所有者、URL 等基础信息时，使用 `minutes minutes get`。
+2. 从妙记 URL 末尾提取 `minute_token`，再调用 `minutes minutes get`。
+3. 用户意图不明确时，默认先给基础元信息，帮助确认是否命中目标妙记。
+
+### 下载妙记音视频文件
+
+下载妙记的录音 / 录像媒体文件，或获取有效期 1 天的下载链接（只读操作）。使用前必须先阅读 [references/lark-minutes-download.md](references/lark-minutes-download.md)。
+
+## API Resources
+
+沙箱内本域仅以下原生 API 可用：
+
+```bash
+lark-cli minutes <resource> <method> [flags]
+```
+
+### minutes
+
+- `get` — 获取妙记信息
+
+> **权限错误**：如果返回 `[2091005] permission deny`，表示用户没有对应妙记文件的阅读权限，需提示用户联系妙记 owner 申请权限。

package/shared/lark-cli/lark-minutes/references/lark-minutes-download.md

@@ -0,0 +1,130 @@
+
+# minutes +download
+
+
+下载妙记的音视频媒体文件到本地，或获取有效期 1 天的下载链接。只读操作。
+
+本 skill 对应 shortcut：`lark-cli minutes +download`。
+
+## 命令
+
+```bash
+# 下载妙记（默认布局，落到 ./minutes/{minute_token}/<server-filename>）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx
+
+# 指定输出文件（单 token，文件路径）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --output ./meeting.mp4
+
+# 指定输出目录（单/批量均可，目录路径）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --output-dir ./downloads
+
+# 仅获取下载链接（有效期 1 天），不下载文件
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --url-only
+
+# 批量下载多个妙记（默认布局，逐个落到 ./minutes/{minute_token}/）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx,obcnyyyyyyyyyyyyyyyyyyyy
+
+# 批量下载到同一指定目录
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx,obcnyyyyyyyyyyyyyyyyyyyy --output-dir ./downloads
+
+# 预览 API 调用
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--minute-tokens <tokens>` | 是 | 妙记 Token，逗号分隔支持批量（最多 50 个） |
+| `--output <path>` | 否 | 输出文件路径（单 token）。若传入的是已存在目录，等价于 `--output-dir`。与 `--output-dir` 互斥 |
+| `--output-dir <dir>` | 否 | 输出目录（单/批量均可）。与 `--output` 互斥 |
+| `--overwrite` | 否 | 覆盖已存在的输出文件 |
+| `--url-only` | 否 | 仅返回下载链接，不下载文件 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+> **默认落点**：未指定 `--output` / `--output-dir` 时，文件落到 `./minutes/{minute_token}/<server-filename>`。文件名沿用服务端 Content-Disposition / Content-Type 推断，Agent 可从 `saved_path` 字段读取实际路径。
+
+## 核心约束
+
+### 1. 妙记必须已完成转写
+
+音视频文件仅在妙记转写完成后可下载。如果妙记尚未准备好，API 会返回 `2091003` 错误。
+
+### 2. 下载链接有效期 1 天
+
+`--url-only` 返回的链接有效期为 1 天，过期后需重新获取。
+
+### 3. 频率限制
+
+API 限流 5 次/秒，批量下载时需注意控制频率。
+
+### 4. 所需权限
+
+| 身份 | 所需权限 |
+|------|---------|
+| user | `minutes:minutes.media:export` |
+
+## 输出结果
+
+### 下载模式（默认）
+
+单 token：
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "artifact_type": "recording",
+  "saved_path": "/path/to/minutes/obcnxxxxxxxxxxxxxxxxxxxx/访谈一则.m4a",
+  "size_bytes": 52428800
+}
+```
+
+批量：`downloads` 数组，每条与上面结构一致，失败项带 `error` 字段。
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 妙记 Token（用于 Agent 索引） |
+| `artifact_type` | 固定为 `"recording"` |
+| `saved_path` | 文件保存的本地路径（绝对路径） |
+| `size_bytes` | 文件大小（字节） |
+
+### URL 模式（--url-only）
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "download_url": "https://..."
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 妙记 Token |
+| `download_url` | 媒体文件下载链接（有效期 1 天） |
+
+## 如何获取 minute_token
+
+| 来源 | 获取方式 |
+|------|---------|
+| 妙记 URL | 从 URL 末尾提取，如 `https://sample.feishu.cn/minutes/obcnxxxxxxxxxxxxxxxxxxxx` → `obcnxxxxxxxxxxxxxxxxxxxx` |
+| 妙记元信息查询 | `lark-cli minutes minutes get --params '{"minute_token": "obcn..."}'` |
+
+## 常见错误与排查
+
+| 错误现象 | 错误码 | 根本原因 | 解决方案 |
+|---------|--------|---------|---------|
+| 参数无效 | 2091001 | minute_token 格式不正确 | 检查 token 是否完整（24 位） |
+| 资源不存在 | 2091002 | token 不存在 | 确认 minute_token 正确 |
+| 妙记尚未准备好 | 2091003 | 转写未完成 | 等待转写完成后重试 |
+| 资源已删除 | 2091004 | 妙记已被删除 | 确认妙记文件仍然存在 |
+| 权限不足 | 2091005 | 无阅读权限 | 检查是否有该妙记的访问权限 |
+
+## 提示
+
+- 音视频文件可能较大，下载无固定超时限制（由用户 Ctrl+C 控制取消）。
+- 单 token 模式下 `--output` 若传入已存在目录（如 `--output ./existing-dir`），等价于 `--output-dir`，文件落入该目录（cp 语义）。
+- 批量模式下 `--output` 不接受已存在的文件路径（会报错），应改用 `--output-dir`。
+
+## 参考
+
+- [lark-minutes](../README.md) — 妙记全部命令

package/shared/lark-cli/lark-sheets/README.md

@@ -0,0 +1,173 @@
+# sheets
+
+## 术语约定
+
+下列词在本 skill 各文档中可能交替出现，但**指同一对象**；解析用户口语时按此映射，不要当成不同概念：
+
+| 标准用语 | 同义 / 口语（均指同一对象） | 说明 |
+| --- | --- | --- |
+| 工作表（sheet） | 子表、tab、标签页 | spreadsheet 内的单张表；`sheet_id` 是其稳定标识 |
+| 电子表格（spreadsheet） | 工作簿、表格 | 顶层容器；由 `--url` 或 `--spreadsheet-token` 定位 |
+| reference_id | id | **表内对象**的稳定标识，即各对象主键 flag 接受的值（见下表） |
+
+各类只读对象命令用各自的主键 flag 过滤定位（命名不统一，按此表对照，不要凭直觉拼）：
+
+| 对象 | 主键 flag | 对象 | 主键 flag |
+| --- | --- | --- | --- |
+| 工作表 sheet | `--sheet-id` | 条件格式规则 | `--rule-id` |
+| 图表 chart | `--chart-id` | 筛选视图 | `--view-id` |
+| 透视表 pivot | `--pivot-table-id` | 迷你图（按组） | `--group-id` |
+| 浮动图片 | `--float-image-id` | | |
+
+## 场景 → 命令速查（拿不准命令名先查这里，别按直觉拼）
+
+把高频**只读**意图映射到**真实存在**的 shortcut。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。**选定命令后先读"参考"列指向的 reference**：命令名对得上不代表用法对，读取分页 / 定位尤其容易漏掉 reference 里的防错规则。
+
+| 你要做的事 | ✅ 正确写法 | 参考 |
+| --- | --- | --- |
+| 读数据（纯值 / CSV） | `+csv-get`（范围用 `--range`） | `lark-sheets-read-data` |
+| 按列类型结构化读出（喂 DataFrame / round-trip） | `+table-get` | `lark-sheets-read-data` |
+| 读值 + 公式 / 样式 / 批注 / 数据验证 | `+cells-get --include value,formula,style,comment,data_validation` | `lark-sheets-read-data` |
+| 看某区域下拉框（数据验证）的选项 | `+dropdown-get`（范围用 `--range`） | `lark-sheets-read-data` |
+| 查找 / 定位文本 | `+cells-search`（关键字用 `--find`） | `lark-sheets-search-replace` |
+| 看子表结构（合并 / 行高列宽 / 冻结 / 隐藏 / 分组） | `+sheet-info` | `lark-sheets-sheet-structure` |
+| 看工作簿 / 子表清单 | `+workbook-info` | `lark-sheets-workbook` |
+| 取当前文档 revision（版本号） | `+revision-get` | `lark-sheets-workbook` |
+| 复核某次（AI）编辑改了什么 / 取两个版本间的变更 | `+changeset-get --start-revision <编辑前版本>`（省略 `--end-revision` 取到最新；版本差 ≤ 20） | `lark-sheets-changeset` |
+| 看历史版本列表 | `+history-list` | `lark-sheets-history` |
+| 查回滚任务的当前状态 | `+history-revert-status --transaction-id <id>` | `lark-sheets-history` |
+| 公式健康自检（扫全表 / 子表的公式错误） | `+formula-verify` | `lark-sheets-formula-verify` |
+| 看已有图表配置 | `+chart-list` | `lark-sheets-chart` |
+| 看条件格式规则 | `+cond-format-list` | `lark-sheets-conditional-format` |
+| 看筛选器配置 | `+filter-list` | `lark-sheets-filter` |
+| 看筛选视图 | `+filter-view-list` | `lark-sheets-filter-view` |
+| 看透视表配置 | `+pivot-list` | `lark-sheets-pivot-table` |
+| 看迷你图 | `+sparkline-list` | `lark-sheets-sparkline` |
+| 看浮动图片 | `+float-image-list` | `lark-sheets-float-image` |
+
+> ⚠️ **定位 flag**：`+cells-get` / `+csv-get` / `+dropdown-get` 用 `--range`；**读取附加信息**一律走 `+cells-get --include …`，**没有** `--with-styles` 这类 flag；**看合并单元格**用 `+sheet-info` 的 `merged_cells`，不要在 `+cells-get` 里找 merge flag。
+> ⚠️ **要按名称 / 关键词在云空间里找某个表格文件**（不是读某张已知表的内容）：当前沙箱不可用（lark-drive 域仅开放只读查询，不含按名称搜索能力）；需用户直接提供表格的 URL / token，再回本 skill 读内容。
+
+## 执行要点（读取 / 陷阱）
+
+端到端只读工作流：了解结构（`+workbook-info`）→ 读数据 → 理解语义 → 按需读对象配置 / 自检公式。
+
+### 读取：按需求选路径（细则见 `lark-sheets-read-data`）
+
+| 用户需求 | 读取路径 |
+|---|---|
+| "查一下 / 看看 / 统计 / 汇总"等只读 | `+csv-get` 读到上下文（大表按 `--range` 行窗口分批读） |
+| 需要按列类型结构化读出（喂 DataFrame） | `+table-get` |
+| 需要公式 / 样式 / 批注 / 数据验证 | `+cells-get --include …` |
+| 需要看某区域下拉选项 | `+dropdown-get` |
+
+> 读大表先按 `lark-sheets-read-data` 确认真实数据末行、注意分页标志（`has_more` / `truncated`），不要一口气拉全表撑爆上下文。
+
+### 用脚本配合 CLI 时
+
+- **只读 stdout**：CLI 数据走 stdout、诊断走 stderr；解析 JSON 别 `2>&1`（警告混入会解析失败），用管道或单独重定向 stdout。
+- **喂 CLI 的 CSV / JSON 用 UTF-8 无 BOM**；临时文件放系统临时目录、勿落项目目录。
+- **命令失败先读 stderr 再调整**，别原样重发。
+
+### 易漏陷阱
+
+- **隐藏行列**：`+csv-get` 默认含隐藏行列；设 `--skip-hidden=true` 只看可见，但返回行序号与实际行号不再对应。
+- **跨 sheet 对象**：图表 / 条件格式 / 透视表 / 浮动图片可能分布在多个子表，读取前先 `+workbook-info` 掌握全局。
+- **大数字精度**：15 位以上的身份证 / 参考号做去重 / 比较时禁止用 `+csv-get` 的显示值（会显示成科学计数、误判重复），改用 `+cells-get` 取原始精确值（见 `lark-sheets-read-data`）。
+
+## References
+
+先按操作对象进入对应工具参考查具体 shortcut 与调用细节。所有参考仅覆盖只读命令。
+
+| Reference | 描述 |
+| --- | --- |
+| [Lark Sheet Read Data](references/lark-sheets-read-data.md) | 读取飞书表格中的单元格数据（`+csv-get` / `+cells-get` / `+table-get` / `+dropdown-get`）。当用户需要"看看数据"、"分析数据"、"统计/汇总"，或需要查看公式、样式、批注、数据验证下拉选项时使用。 |
+| [Lark Sheet Search](references/lark-sheets-search-replace.md) | 在飞书表格中搜索 / 定位文本（`+cells-search`），支持限定范围、大小写匹配、精确匹配、正则表达式。当用户需要"查找"、"搜索"、"定位"某个值时使用。不要用于理解表格结构（应读取数据）、不要把操作动作关键词（如"汇总金额"）当作搜索词。 |
+| [Lark Sheet Sheet Structure](references/lark-sheets-sheet-structure.md) | 查看飞书表格的子表结构与布局（`+sheet-info`）：行高、列宽、隐藏行列、合并单元格、行列分组、冻结等布局信息。 |
+| [Lark Sheet Workbook](references/lark-sheets-workbook.md) | 查看飞书表格的工作簿结构（`+workbook-info` 子表列表及元数据）与当前 revision（`+revision-get`）。当用户提到"看看这个表格有什么"、"表格结构"、"有哪些 sheet"、"当前版本号"时使用。 |
+| [Lark Sheet Changeset](references/lark-sheets-changeset.md) | 读取两个版本（CS revision）之间的 changeset（原始变更操作清单，`+changeset-get`），用于复核某次编辑——尤其是 AI 编辑——是否真实满足用户诉求。当用户需要"看看这次改了什么"、"核对 AI 改动"、"对比两个版本的变更"时使用。 |
+| [Lark Sheet History](references/lark-sheets-history.md) | 查询飞书表格的历史版本列表（`+history-list`）与回滚任务的异步状态（`+history-revert-status`）。当用户需要查看一张表的编辑历史版本列表、或查询某次回滚的进行中/成功/失败状态时使用。 |
+| [Lark Sheet Formula Verify](references/lark-sheets-formula-verify.md) | 公式健康自检入口（`+formula-verify`）。对指定子表（或整本工作簿）扫描公式与单元格值，聚合所有 Excel 错误（#REF! / #DIV/0! / #VALUE! / #NAME? / #NULL! / #NUM! / #N/A）与编译失败清单，输出统一 JSON。需要核对一张表里公式是否零错误时使用。 |
+| [Lark Sheet Chart](references/lark-sheets-chart.md) | 查看飞书表格中已有图表的配置（`+chart-list`）：类型、数据源、样式。 |
+| [Lark Sheet Pivot Table](references/lark-sheets-pivot-table.md) | 查看飞书表格中已有数据透视表的配置（`+pivot-list`）：结构、数据源、展开后的占用区域与状态。 |
+| [Lark Sheet Conditional Format](references/lark-sheets-conditional-format.md) | 查看飞书表格中已有条件格式规则的配置（`+cond-format-list`）：规则类型、范围、样式。 |
+| [Lark Sheet Filter](references/lark-sheets-filter.md) | 查看飞书表格中已有筛选器（filter）的配置（`+filter-list`）：范围、规则、条件。 |
+| [Lark Sheet Filter View](references/lark-sheets-filter-view.md) | 查看飞书表格中已有筛选视图（filter view）的配置（`+filter-view-list`）：视图名、范围、规则。 |
+| [Lark Sheet Sparkline](references/lark-sheets-sparkline.md) | 查看飞书表格中已有迷你图组的配置（`+sparkline-list`）：类型、数据源、样式。 |
+| [Lark Sheet Float Image](references/lark-sheets-float-image.md) | 查看飞书表格中已有浮动图片的配置（`+float-image-list`）：位置、大小、层级。 |
+
+## 公共 flag 速查
+
+各 reference 的每个 shortcut 标题下用一行徽章标注该 shortcut 支持的公共 / 系统 flag，例如：
+
+- `_公共四件套 · 系统：--dry-run_` — URL/token + sheet 定位（两组各**必给一个**，详见下方「公共 flag」），加 `--dry-run`
+- `_公共：URL/token（无 sheet 定位） · 系统：--dry-run_` — 只接 URL/token，常见于 `+workbook-info` / `+revision-get` / `+changeset-get` / `+history-list` 等不强制 sheet 定位的 shortcut
+
+徽章里只列名字。type / 必填 / 描述都在本段统一声明：
+
+### 公共 flag（定位资源）
+
+**公共四件套** = `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`，分成两组 XOR，**每组都必须给且只能给一个**（XOR = 二选一必填，不是"可选"）：
+
+1. **spreadsheet 定位（必填）**：`--url` 与 `--spreadsheet-token` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --url or --spreadsheet-token`；两个都给 → 互斥冲突。
+   - **`--url` 解析 `/sheets/`、`/spreadsheets/` 与 `/wiki/` 三种链接**（从路径里抽出 token；也可以直接把裸 token 传给 `--spreadsheet-token`）。其它形态的链接不会被解析成表格 token。
+   - **`/wiki/` 知识库链接可直接传 `--url`**：会自动定位到链接背后的电子表格；若该链接背后不是电子表格（而是文档 / 多维表格等），则报错。
+2. **sheet 定位（公共四件套 shortcut 必填）**：`--sheet-id` 与 `--sheet-name` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --sheet-id or --sheet-name`。
+   - ⚠️ **不确定 sheet 名时禁止直接猜 `Sheet1`**：除非用户对话明确说出 sheet 名 / id，或上下文（之前的工具调用 / URL 锚点 `?sheet=xxx`）已经出现过具体值，否则**第一步先调 `+workbook-info --url "..."`**（或 `--spreadsheet-token`）拿 `sheets[].sheet_id` / `sheets[].title` 列表再选。中文环境下子表常叫"数据" / "Sheet"（无数字）/ "工作表 1" / 业务名，猜 `Sheet1` 大概率撞 `sheet not found`。
+   - ⚠️ **`--range` 里的 `Sheet1!` 前缀不能替代 sheet 定位**：即使写了 `--range 'Sheet1!A1:B2'`，仍**必须**额外传 `--sheet-id` 或 `--sheet-name`，否则照样报上面的错。
+   - ⚠️ **A1 reference 含 `!`**（`--range`）**：整段用单引号包裹**，如 `--range 'Sheet1!A1:B2'`——单引号能挡住 bash 的 history expansion（`!` 被拦成 `event not found`；双引号挡不住；别改用 `set +H`）。sheet 名含特殊字符（`-` / 空格 / 非 ASCII）需在内部按 A1 标准再包一层单引号时，用 `'\''` 转义保持外层单引号。
+   - **例外**：徽章标为 `_公共：URL/token（无 sheet 定位）…_` 的 shortcut（如 `+workbook-info` / `+revision-get` / `+changeset-get` / `+history-list` / `+history-revert-status`）**不接受也不需要** sheet 定位，只给一组 spreadsheet 定位即可。`+table-get` 的 `--sheet-id` / `--sheet-name` 可选（省略读全部子表）。
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--url` | string | 二选一必填（与 `--spreadsheet-token`） | spreadsheet 或 wiki URL |
+| `--spreadsheet-token` | string | 二选一必填（与 `--url`） | spreadsheet token |
+| `--sheet-id` | string | 二选一必填（与 `--sheet-name`；仅公共四件套 shortcut） | 工作表 reference_id |
+| `--sheet-name` | string | 二选一必填（与 `--sheet-id`；仅公共四件套 shortcut） | 工作表名称 |
+
+**统一调用范式**（公共四件套 shortcut 的所有示例都遵循此形状，两组定位缺一不可）：
+
+```bash
+lark-cli sheets <shortcut> <workbook 定位> <sheet 定位> <其它 flag>
+#   workbook 定位：--url "..."        或 --spreadsheet-token "..."           （二选一，必给）
+#   sheet 定位：    --sheet-id "$SID"  或 --sheet-name "<真实表名>"            （二选一，必给；占位符不要原样填）
+# 例：lark-cli sheets +csv-get --url "https://.../sheets/shtXXX" --sheet-name "<真实表名>" --range "A1:F30"
+# 注意：真实表名不要直接填 "Sheet1"——大多数表的子表不叫这个；先 +workbook-info 拿 sheets[].title 再代入。
+```
+
+### 系统 flag
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--dry-run` | bool | 否 | 零副作用：仅打印请求路径与参数模板，不发起调用 |
+| `--yes` | bool | 是（仅 `high-risk-write`） | 二次确认；不带时退出码 10，需重新带 `--yes` 确认高风险写操作 |
+
+- **envelope**：所有 shortcut 返回统一外层结构 `{ok, identity, data, ...}`。正文里 `envelope.data` 指业务数据层（如 `+csv-get` 的 `annotated_csv`）。
+
+## API（沙箱内仅以下原生 API 调用可用）
+
+绝大多数只读需求都被上面的 shortcut 覆盖；shortcut 没覆盖到时，**仅**以下原生 `<service> <resource> <method>` 组合在本沙箱内可用，不要再自行拼其它 service/api 组合去试：
+
+### spreadsheets
+
+- `get` — 读取电子表格的元数据（等价于 `+workbook-info` 的底层调用）
+
+```bash
+lark-cli sheets spreadsheets get
+```
+
+### spreadsheet.sheets
+
+- `find` — 在电子表格里查找单元格（等价于 `+cells-search` 的底层调用）
+
+```bash
+lark-cli sheets spreadsheet.sheets find
+```
+
+### spreadsheet.sheet.filters
+
+- `get` — 读取某个子表的筛选器信息（等价于 `+filter-list` 的底层调用）
+
+```bash
+lark-cli sheets spreadsheet.sheet.filters get
+```