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

package/shared/lark-cli/lark-contact/references/lark-contact-search-user.md

@@ -0,0 +1,121 @@
+# +search-user
+
+## 适用范围
+
+- ✅ 已知姓名 / 邮箱 / 「聊过的人」想找出 open_id
+- ✅ 已知一组 open_id 想批量校验或回填字段(`--user-ids`,最多 100,支持 `me`)
+- ✅ 按聊天关系 / 在职状态 / 租户边界 / 企业邮箱等维度筛选员工
+- ❌ 已知 open_id 想发消息 → 直接走 `lark-im`,不经过本命令
+
+## 关键 flag
+
+`--query` / `--queries` / `--user-ids` / bool filter 至少传一个。bool filter 显式传 `=false` 会报错——不传等于不过滤。
+
+| Flag | 作用 |
+|---|---|
+| `--query <text>` | 关键词(姓名 / 邮箱 / 手机号),≤ 50 rune |
+| `--queries <csv>` | 多个关键词并行搜,**最多 20 条**;与 `--query` / `--user-ids` 互斥;输出新 shape(见下) |
+| `--user-ids <csv>` | open_id 列表,≤ 100;支持 `me` 表示自己;与 `--query` 同传时把搜索范围限定在该集合 |
+| `--has-chatted` | 仅搜聊过天的 |
+| `--has-enterprise-email` | 仅搜有企业邮箱的 |
+| `--exclude-external-users` | 仅搜同租户(排除外部联系人) |
+| `--left-organization` | 仅搜已离职的 |
+| `--lang <locale>` | 覆盖 `localized_name` 的语种(如 `zh_cn` / `en_us` / `ja_jp`) |
+| `--page-size <n>` | 单页大小 1-30,默认 20 |
+
+## 常用例子
+
+```bash
+# 按姓名搜,看候选确认是哪个张三
+lark-cli contact +search-user --query "张三" --has-chatted
+
+# 按完整邮箱搜(命中通常唯一,适合作后续命令的输入)
+lark-cli contact +search-user --query "alice@example.com"
+
+# 查看自己
+lark-cli contact +search-user --user-ids me
+
+# 批量回填:已知一组 open_id,取姓名 / 邮箱 / 部门
+lark-cli contact +search-user --user-ids "ou_a,ou_b,ou_c" --format json
+
+# 多 filter 组合:同租户的、有企业邮箱的「王」姓员工
+lark-cli contact +search-user --query "王" --exclude-external-users --has-enterprise-email
+
+# filter-only 枚举:列出所有"聊过天的离职同事"(无关键词)
+lark-cli contact +search-user --has-chatted --left-organization
+```
+
+## 批量并行查询 (fanout)
+
+一次查多个名字:
+
+```bash
+lark-cli contact +search-user --queries "Alice,Bob,张三"
+```
+
+- 每行 user 带 `matched_query`,标识来自哪个 query
+- `queries[]` 每个输入一条 `{query, error?, has_more}`,失败的有 `error`
+- 部分失败不影响其它 query;全部失败才 exit 非 0
+
+```bash
+# bool filter 对每个 query 都生效
+lark-cli contact +search-user --queries "Alice,Bob" --has-chatted
+
+# 与 --query / --user-ids 互斥
+lark-cli contact +search-user --queries "a" --query "b"   # ❌ exit 2
+```
+
+约束:
+- 最多 20 条; 每条 ≤ 50 字符
+- 重复条目静默去重;全空 csv (`,,,`) 报错
+
+## 同名 disambiguation
+
+搜常见姓名常返回多条同名结果。后续操作若有副作用(发消息、邀请会议等),把候选列给用户挑;**不要擅自选**。
+
+筛选信号(可信度从高到低):`chat_recency_hint`(近期联系过) > `enterprise_email` 前缀 > `department` 关键词。`localized_name` 同名时无区分作用。
+
+```bash
+# 用 jq 按部门精筛
+lark-cli contact +search-user --query "张三" \
+  --jq '.data.users[] | select(.department | contains("<部门关键词>"))'
+```
+
+## 注意事项
+
+- **不会自动翻页**。`has_more=true` 表示需要 refine query。
+- **`--lang` 只影响输出展示名**,不影响匹配字段。
+- **`--query` 与 `--user-ids` 同时设**:`--user-ids` 限定搜索范围,`--query` 在该集合内匹配。
+
+## 输出字段 contract
+
+跨租户用户(`is_cross_tenant=true`)的业务字段可能为空字符串,需做空值兜底。
+
+| 字段 | 类型 | 说明 | 跨租户 |
+|---|---|---|---|
+| `open_id` | string | 稳定标识,后续命令的输入 | 始终非空 |
+| `localized_name` | string | 按 `--lang` / brand 选出的展示名 | 始终非空(兜底为 open_id) |
+| `email` | string | 个人邮箱 | 可能为空 |
+| `enterprise_email` | string | 企业邮箱 | 可能为空 |
+| `is_activated` | bool | 是否已激活飞书账号(未激活也可投递消息,但用户可能看不到) | 可能 false |
+| `is_cross_tenant` | bool | 是否跨租户用户(同公司=false,外部联系人=true) | — |
+| `p2p_chat_id` | string | 与当前用户的 P2P 会话 ID(`oc_...`);空表示从未私聊过。可作为接受 `--chat-id` 的 IM 命令的输入 | 可能为空 |
+| `has_chatted` | bool | `p2p_chat_id != ""` 的派生字段 | — |
+| `department` | string | 部门路径,服务端可能用 `-` 拼层级,层级数不固定。**按可子串匹配的字符串处理** | 可能为空 |
+| `signature` | string (optional) | 用户个性签名;空时字段不出现 | 可能不出现 |
+| `chat_recency_hint` | string | 最近联系的提示文案,仅供展示 | 可能为空 |
+| `match_segments` | string[] | 关键词命中的字符串片段,用于高亮展示;无命中则为空数组 | — |
+
+### `--queries` 模式额外字段
+
+`data.users[]` 每条多 `matched_query` (string),指明本行来自哪个 query。
+
+`data.queries[]` 按输入顺序、dedup 后每个 query 一条:
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `query` | string | 该输入 |
+| `error` | string (optional) | 失败原因;成功时不出现 |
+| `has_more` | bool | 该 query 还有更多结果 |
+
+fanout 模式无顶层 `data.has_more`。

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

@@ -0,0 +1,67 @@
+# docs
+
+## 能力范围（本沙箱仅开放以下只读命令）
+
+本沙箱环境下，docs 域仅提供三个只读的快捷命令，文档读取默认使用 `--as user`：
+
+```bash
+# 读取文档内容（默认 XML，simple；若 URL 存在 #share-... 锚点，优先按锚点局部读取，不要全文拉取）
+lark-cli docs +fetch --doc "文档URL或token"
+
+# 列出文档历史版本
+lark-cli docs +history-list --doc "文档URL或token" --page-size 20
+
+# 按关键词搜云文档
+lark-cli docs +search --query "<关键词>"
+```
+
+其余 docs 能力（创建 / 编辑 / 追加正文、图片与附件的插入·预览·下载、封面资源、思维笔记、
+画板更新、字数统计、历史回滚等写 / 管理操作）在本沙箱**不作为可用入口**，不要尝试拼这些命令。
+
+## 前置条件 — 执行操作前必读
+
+**执行对应操作前，MUST 先用 Read 工具读取以下文件：**
+
+1. **读取文档（`docs +fetch`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
+2. **查看历史版本（`docs +history-list`）** → 必读 [`lark-doc-history.md`](references/lark-doc-history.md)（分页与返回字段）
+
+**未读完对应文件就执行相应操作会导致参数选择错误。**
+
+## 快速决策
+
+- 找文档 / 导入导出走 [`lark-drive`](../lark-drive/README.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；只需要 block 直达链接或按范围精读时，用 `docs +fetch --detail with-ids` 局部读取
+- block 直达链接格式：`文档基础 URL#block_id`；没有 block_id 时局部 fetch `with-ids`
+- 用户想查看文档的历史版本列表（`revision_id` / `edit_time` / 版本名）→ 用 `docs +history-list`，先读 [`lark-doc-history.md`](references/lark-doc-history.md)
+- 拿到 spreadsheet URL/token 后 → 切到 `lark-sheets` 做对象内部操作
+- 文档内容中出现嵌入的 `<sheet>` / `<bitable>` / `<cite file-type="sheets|bitable">` 标签时 → **必须主动提取 token 并切到对应域下钻读取内部数据**，不能只呈现标签本身：`<sheet>` 走 `lark-sheets`，`<bitable>`（多维表格 / Base）走 `lark-base`
+
+| 标签 / 属性 | 提取字段 | 切到技能 |
+|-|-|-|
+| `<sheet token="..." sheet-id="...">` | `token` -> spreadsheet_token, `sheet-id` | [`lark-sheets`](../lark-sheets/README.md) |
+| `<bitable token="..." table-id="...">` | `token` -> base_token, `table-id` | [`lark-base`](../lark-base/README.md) |
+| `<cite type="doc" file-type="sheets" token="..." sheet-id="...">` | 同 `<sheet>` | [`lark-sheets`](../lark-sheets/README.md) |
+| `<cite type="doc" file-type="bitable" token="..." table-id="...">` | 同 `<bitable>` | [`lark-base`](../lark-base/README.md) |
+| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch` 读取 src-token 文档，定位 block |
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown / im-markdown; `im-markdown` only after fetch for `lark-im`) |
+| `+search` | 按关键词搜云文档（默认匹配标题与正文）；见下方「`+search`」节 |
+| [`+history-list`](references/lark-doc-history.md) | List document history versions (`revision_id` / `edit_time` / version name) |
+
+## `+search` —— 按关键词搜云文档
+
+```bash
+lark-cli docs +search --query "<关键词>" --as user
+lark-cli docs +search --query "<关键词>" --page-size 20 --as user
+```
+
+- `--query` 是搜索关键词
+- `--page-size` 默认 15、最大 20；配 `--page-token` 翻页
+- `--filter` 接 JSON 对象做条件过滤
+- 与 [lark-drive](../lark-drive/README.md) 的 `+search` 共用同一后端搜索接口；要按文件类型 /
+  归属 / 时间窗过滤时用 drive 那个，它的过滤器更全

package/shared/lark-cli/lark-doc/references/lark-doc-fetch.md

@@ -0,0 +1,138 @@
+
+# docs +fetch（获取飞书云文档）
+
+## 命令
+
+```bash
+# 获取文档（默认 XML，simple）
+lark-cli docs +fetch --doc "https://xxx.feishu.cn/docx/Z1Fj...tnAc"
+
+# Markdown 格式
+lark-cli docs +fetch --doc Z1Fj...tnAc --doc-format markdown
+
+# 带 block ID（用于后续 block 级更新）
+lark-cli docs +fetch --doc Z1Fj...tnAc --detail with-ids
+
+# 只拿目录
+lark-cli docs +fetch --doc Z1Fj...tnAc --scope outline --max-depth 3
+
+# 按 block id 区间精读
+lark-cli docs +fetch --doc Z1Fj...tnAc --scope range --start-block-id blkA --end-block-id blkB --detail with-ids
+
+# URL 带 #share 选区锚点时自动局部读取
+lark-cli docs +fetch --doc 'docURL#share-anchor'
+
+# 读整个章节（以标题 id 为锚点，自动展开到下一个同级/更高级标题前）
+lark-cli docs +fetch --doc Z1Fj...tnAc \
+  --scope section --start-block-id <标题id> --detail with-ids
+
+# 按关键词定位（多关键词用 | 分隔，任一命中即返回）
+lark-cli docs +fetch --doc Z1Fj...tnAc \
+  --scope keyword --keyword "部署|发布|上线"
+```
+
+## 选 `--detail`（每块详细度）
+
+| 意图 | `--detail` | 说明 |
+|------|-----------|------|
+| **只读**：浏览或总结文档内容 | `simple`（默认） | 简洁 XML/Markdown，不含 block ID、样式属性、引用元数据 |
+| **定位**：需要 block ID 与其他业务交互 | `with-ids` | 包含 block ID（如 `<p id="blkcnXXXX">`），可用于拼接 `文档URL#block_id` 形式的直达链接，或与其他业务交互时定位 block |
+| **完整结构**：需要样式属性 / 引用元数据 / 完整结构 | `full` | 包含 block ID + 样式属性 + 引用元数据，提供完整文档结构信息 |
+
+## 选 `--scope`（读取范围）
+
+`--scope` 和 `--detail` 正交可组合。**省略 `--scope` 即读整篇；获取一小节时优先用局部读取。**
+
+| 模式 | 何时用 | 关键参数 | 行为要点 |
+|-|-|-|-|
+| `outline` | 不知道结构，先看目录 | `--max-depth`（标题层级上限） | 扁平列出所有标题，**包括嵌在容器里的内嵌标题**（如 callout 里的 h3）；这些 id 可直接作后续 `section` / `range` 端点 |
+| `section` | 读某个标题对应的整节 | `--start-block-id`（必填） | 顶层标题 → 展开到下一同级/更高级标题前；容器内节点（含内嵌标题） → 按"最小包容单元"返回容器/表格切片，不做 heading 扩展；顶层非标题块 → 仅该块 |
+| `range` | 已知精确起止 | `--start-block-id` / `--end-block-id` 至少一个；`-1` = 读到末尾 | 两端同顶层 → 顶层序列切片；两端同一容器 → 容器整体；两端同一表格 → 瘦身切片；**跨顶层 → 端点所在顶层块整块输出，不做瘦身** |
+| `keyword` | 只有模糊关键词 | `--keyword`（**多级自动 fallback**：子串 → 归一化 → 分词形变 → RE2 正则；`\|` 分隔多分支 OR） | 每处命中按"最小包容单元"输出；**自动去重**（同容器多命中 → 单个容器，同表格多行命中 → 合并切片） |
+
+> 💡 **多关键词用 `\|` 拼接（OR 语义，任一命中即返回）**：例 `"部署\|发布\|上线"`，三词任一命中都进结果，适合**同义词/别名/多业务术语**一次召回（如 `bug\|缺陷\|故障`）。
+
+**设置 `--scope` 时共用** `--context-before` / `--context-after` / `--max-depth`。
+
+- `--max-depth`：`outline` = 标题层级上限（3 = h1~h3）；其它模式 = 被选块的子树遍历深度（`-1` 不限，`0` 仅块自身）。
+- `--context-before/--context-after`：**只对整块顶层单元生效**；命中落在容器/表格内（返回容器或切片）时 before/after 被忽略，需要更大范围改用 `section` / `range` 显式指定。
+
+**决策顺序**（核心原则：**局部获取优于全量获取**，根据需求形态选起点，必要时多步组合收敛范围）：
+1. 需求**直接给出待查的具体术语/错误码/标识** → 直接走 `keyword` 粗匹配（多级 fallback 自动覆盖形变），需要更大上下文时用返回的 `top-block-id` 走 `section` / `range`
+2. 需求**指向某个章节/标题**（"修改 XX 章"、"总结第 3 节"、"关于 xx 的内容"）→ 先 `outline --max-depth 3` 拿目录 → `section --start-block-id <标题id>` 精读
+3. 已知**精确起止 / 跨节连续区间** → `range`
+4. **结构未知且无明确关键词/章节线索** → `outline` 探测，再回到 2/3
+5. **兜底**：仅在确需整篇时才省略 `--scope`；不要为省事直接读整篇
+
+## 局部读取的输出结构：`<fragment>` 与 `<excerpt>`
+
+设置 `--scope` 时返回的 `content` 被一个 `<fragment>` 节点包裹，属性包含 `mode` / `requested-start` / `requested-end` / `keyword`（按需）。子节点只有两种形态：
+
+- **顶层块**：完整块直接作为 `<fragment>` 的子节点，无额外包裹。
+- **`<excerpt top-block-id="..." parent-block-path="...">`**：非顶层节选（容器整体 / 表格瘦身切片）。
+  - `top-block-id`：所在顶层块 id，想看该块全貌时作 `section` / `range` 锚点再拉一次。
+  - `parent-block-path`：从顶层块到 excerpt 内容直接父节点的 id 路径，`/` 分隔（表格切片时即表格自身 id）。
+
+**看到 `<excerpt>` 即意味着这是节选**，不能假设看到了该顶层块的全貌。
+
+**表格默认瘦身**：即便 `<table>` 本身是顶层块也只返回 thead + 命中 tr。想拿整张表 → `range --start-block-id <table-id> --end-block-id <table-id>`；切片范围恰好覆盖全部 tr 时 SDK 自动升级为整块、不包 `<excerpt>`。
+
+## 返回值
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "document": {
+      "document_id": "doxcnXXXX",
+      "revision_id": 12,
+      "content": "<title>标题</title><p>文档内容...</p>",
+      "reference_map": {
+        "<block_type>": {
+          "<ref>": {
+            "<real-attr-key>": "<real-attr-value>"
+          }
+        }
+      },
+      "tips": "<safe replay or degradation guidance>"
+    }
+  }
+}
+```
+
+`content` 的格式由 `--doc-format` 决定。`reference_map` 是正文引用数据的结构化 sidecar：一级键 `block_type` 表示引用所在的块类型，二级键 `ref` 对应正文中的临时引用；每个引用的值是由 `real-attr-key` 和 `real-attr-value` 组成的真实属性映射，具体属性由块类型决定。没有提取数据时，`reference_map` 可能为空。`content` 和 `reference_map` 属于同一份响应，保留或回放内容时应配套处理。`tips` 给出安全回放或降级提示。`im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用。设置 `--scope` 时会被 `<fragment>` 包裹，详见上文"局部读取的输出结构"。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc` | 是 | 文档 URL 或 token（支持 `/docx/` 和 `/wiki/`） |
+| `--doc-format` | 否 | `xml`（默认）\| `markdown` \| `im-markdown`（仅用于获取内容后在 `lark-im` 场景下使用） |
+| `--detail` | 否 | `simple`（默认）\| `with-ids` \| `full` |
+| `--revision-id` | 否 | 文档版本号，`-1` = 最新（默认） |
+| `--scope` | 否 | `outline` \| `range` \| `keyword` \| `section`（省略 = 读整篇） |
+| `--start-block-id` | 否 | `range`/`section` 起始/锚点 id（`section` 必填） |
+| `--end-block-id` | 否 | `range` 结束 id；`-1` 表示读到末尾 |
+| `--keyword` | 否 | `keyword` 模式关键词，**4 层自动 fallback**（子串 → 归一化 → 分词形变 → RE2 正则）；`\|` 分隔多分支 OR |
+| `--context-before` | 否 | 命中前拉几个兄弟块（仅对顶层单元生效，默认 `0`） |
+| `--context-after` | 否 | 命中后拉几个兄弟块（仅对顶层单元生效，默认 `0`） |
+| `--max-depth` | 否 | `outline` = 标题层级上限；其它 = 子树深度（`-1` 不限，默认） |
+| `--format` | 否 | `json`（默认）\| `pretty` |
+
+## 图片、文件、画板的处理
+
+**文档中的素材以 XML 标签形式出现：**
+
+```xml
+<img token="..." url="https://..." width="..." height="..."/>
+<source token="..." url="https://..." name="skills.zip"/>
+<whiteboard token="..."/>
+```
+
+- `<img>` / `<source>` 带 `url` 时，直接用该 URL 下载即可（普通 HTTP GET），无需走 shortcut。
+- 没有 `url`（或目标是 `<whiteboard>`）的素材，本沙箱不提供下载 / 预览类命令；只需把标签里的 `token` 等信息如实呈现给用户。
+
+## 嵌入电子表格 / 多维表格
+
+返回中可能含 `<sheet>`、`<bitable>`、`<cite file-type="sheets|bitable">`。内部数据无法通过 `docs +fetch` 获取，需提取 token 后切到对应域下钻：`<sheet>`（电子表格）切 [`lark-sheets`](../../lark-sheets/README.md)；`<bitable>`（多维表格 / Base）把 `token` 当 `base_token` 切 [`lark-base`](../../lark-base/README.md)。详见 [README.md 快速决策](../README.md) 路由表。

package/shared/lark-cli/lark-doc/references/lark-doc-history.md

@@ -0,0 +1,61 @@
+# docs +history-list（历史版本列表）
+
+用于查看 Docx 的历史版本列表（分页），读取每个版本的 `revision_id`、`history_version_id`、
+`edit_time`、版本名等信息。本沙箱只开放只读的 `+history-list`，不提供回滚（写操作）能力。
+
+`entries[].edit_time` 是 RFC3339 时间字符串（例如 `2026-06-22T12:24:45Z`）。按时间匹配时先把它
+解析为时间值，再比较先后关系或时间差——**不要**把它当 Unix 秒数直接比大小。
+
+## 用法
+
+`+history-list` 是分页接口：先拉第一页，只有 `has_more=true` 且还需要更多候选时才继续传
+`--page-token` 翻页。
+
+- 按 `revision_id` 定位版本：逐页筛选 `entries[].revision_id` 相同的记录。未命中时必须继续翻页
+  至 `has_more=false`；命中位于页尾时，继续读取下一页以收集相邻的同 `revision_id` 候选。多条
+  记录时结合 `edit_time` 选择；无法区分时请用户确认。
+- 按时间点定位版本：用 `entries[].edit_time` 匹配，选择不晚于目标时间的最近一条；用户明确要求
+  「最接近」时，选择时间差最小的一条。
+- `history_version_id` 对应服务端 `minor_history.version`。
+
+## 命令
+
+```bash
+# 列出历史版本
+lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20
+
+# 翻页
+lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20 --page-token "<page_token>"
+```
+
+## 参数
+
+| 命令 | 参数 | 必填 | 说明 |
+|-|-|-|-|
+| `+history-list` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
+| `+history-list` | `--page-size` | 否 | 返回条数，范围 `1-20`，默认 `20` |
+| `+history-list` | `--page-token` | 否 | 上一页返回的 `page_token` |
+
+## 返回值要点
+
+`+history-list` 返回：
+
+```json
+{
+  "entries": [
+    {
+      "revision_id": 42,
+      "history_version_id": "11",
+      "edit_time": "2026-06-22T12:24:45Z",
+      "type": 1,
+      "name": "版本名",
+      "description": "版本说明",
+      "editor_ids": ["ou_xxx"]
+    }
+  ],
+  "has_more": true,
+  "page_token": "page_token"
+}
+```
+
+是否还有下一页以返回里的 `has_more` 为准；`page_token` 只作为 `has_more=true` 时续跑下一页的游标。

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

@@ -0,0 +1,129 @@
+# drive (v1)
+
+## 能力范围（本沙箱仅开放 1 个快捷命令 + 3 个只读 API）
+
+快捷命令只有 `+search`（按关键词搜云空间，见下方专节）；其余能力是下面三个只读的原生 API 调用：
+
+| API 命令 | 用途 |
+|----------|------|
+| `drive files list` | 列出某个 Drive 文件夹或根目录的直接子项（可递归盘点目录树） |
+| `drive file.comments list` | 分页获取某个文档的评论列表 |
+| `drive file.view_records list` | 获取文档的访问者记录（view records） |
+
+其余 drive 能力（上传 / 下载 / 导入 / 导出 / 复制 / 移动 / 删除 / 新建文件夹、评论写入与回复、
+权限与协作者、密级标签、版本管理、封面、订阅等）在本沙箱**不作为可用入口**，不要尝试拼这些命令。
+
+### 文档类型与 Token（读取前提）
+
+不同类型的文档有不同的 URL 格式和 Token 处理方式。列取评论或访问记录前，必须先拿到正确的
+`file_token` 与对应 `file_type`。
+
+| URL 格式 | 示例 | Token 类型 | 处理方式 |
+|----------|------|-----------|----------|
+| `/docx/` | `https://example.larksuite.com/docx/doxcnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用（`file_type=docx`） |
+| `/doc/` | `https://example.larksuite.com/doc/doccnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用（`file_type=doc`） |
+| `/sheets/` | `https://example.larksuite.com/sheets/shtcnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用（`file_type=sheet`） |
+| `/page/` | `https://example.feishu.cn/page/N1BWmMrqndT5ZcamAIBcnvDLnOf/` | apps token | 妙搭 apps 类型；列评论时作为 `file_token`，`file_type=apps` |
+| `/drive/folder/` | `https://example.larksuite.com/drive/folder/fldcnxxxx` | `folder_token` | URL 路径中的 token 作为文件夹 token 使用 |
+
+## API Resources
+
+```bash
+lark-cli schema drive.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli drive <resource> <method> [flags]  # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+### files
+
+  - `list` — 获取文件夹下的清单；使用前阅读 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md)，按模板通过 `--params` 传参并手动处理分页；不要把 `--page-all` 输出直接交给 JSON 解析脚本。
+
+标准模板（读取普通文件夹的直接子项）：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","page_size":200}' \
+  --format json
+```
+
+读取当前用户 Drive 根目录的直接子项（`folder_token` 传空字符串）：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"","page_size":200}' \
+  --format json
+```
+
+### file.comments
+
+  - `list` — 分页获取某个文档的评论列表。
+
+  说明（近原样承接上游事实，不要臆造 flag，需要参数结构先 `lark-cli schema drive.file.comments.list`）：
+  - 返回的 `items` 是评论卡片列表，每个 `item` 对应用户界面中的一张评论卡片，不是平铺的互动消息列表。
+  - 真正承载正文的是 `item.reply_list.replies`，其中第一条 reply 在用户视角下就是这张卡片里的"评论本身"。
+  - 统计"评论数 / 评论卡片数"：统计 `items` 长度；全量统计时对所有分页返回的 `items` 长度累加。
+  - 是否还有下一页以返回里的 `has_more` 为准；`page_token` 只作为 `has_more=true` 时续跑下一页的游标。
+  - 如果 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中。
+
+### file.view_records
+
+  - `list` — 获取文档的访问者记录。查看 docx 最近访问记录、返回 open_id、最多 N 条时，建议优先使用 typed flags：`lark-cli drive file.view_records list --file-token <docx_token> --file-type docx --page-size <N> --viewer-id-type open_id --format json`；`--params` JSON 也支持，适合批量拼装、分页续跑或 raw 参数场景。
+
+## 典型错误与解决方案
+
+| 错误信息 | 原因 | 解决方案 |
+|----------|------|----------|
+| `not exist` | 使用了错误的 token | 检查 token 类型；wiki 链接背后是 docx/sheet/bitable 等不同对象，不能只按 `/wiki/<token>` 猜底层类型 |
+| `permission denied` | 没有相关操作权限 | 当前身份对该文档/文件没有读取权限；把 `error.hint` 转述给用户，不要自行补登录或改身份 |
+| `invalid file_type` | file_type 参数错误 | 根据实际 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable/apps） |
+
+## `+search` —— 按关键词搜云空间
+
+```bash
+lark-cli drive +search --query "<关键词>" --doc-types file --mine --as user
+lark-cli drive +search --query "<关键词>" --only-title --as user
+```
+
+要点：
+
+- **默认匹配标题与正文**；加 `--only-title` 才退化为仅标题匹配
+- `--query` 最长 30 字符（按 Unicode 码点算，中文每字算 1 个）；可以留空，配过滤器纯按条件浏览
+- `--query` 支持服务端高级语法 `intitle:` / `""` / `OR` / `-`，**优先下推给服务端**，
+  不要先模糊搜再在客户端二次过滤
+- `--doc-types` 逗号分隔，取值 `doc,sheet,bitable,mindnote,file,wiki,docx,folder`
+- `--mine` 是**服务端 owner 语义**，与 `--created-by-me`（原始创建者）不同，别混用
+- 时间窗过滤按动作分：`--created-since/until`（文档创建）、`--edited-since/until`（我编辑过）、
+  `--opened-since/until`（我打开过）、`--commented-since/until`（我评论过）；值支持 `7d` / `1m` /
+  `2026-04-01` / RFC3339
+- `--page-size` 1-20 默认 15，配 `--page-token` 翻页
+- `--folder-tokens` 与 `--space-ids` 互斥，分别限定云盘文件夹与 wiki 空间
+- `--sort` 取值 `default|edit_time|edit_time_asc|open_time|create_time`
+
+### 标题词 + 正文词要同时满足时
+
+用户同时给标题关键词和正文关键词、且要求同一资源同时满足两项时，**发一条联合搜索**：
+
+```bash
+lark-cli drive +search --query "标题词 正文词" --folder-tokens <FOLDER_TOKEN> --as user
+```
+
+把用户指定的 `--folder-tokens` / `--doc-types` 等过滤条件叠在同一条命令里。**不要**拆成
+「标题搜索 + 正文搜索」再自行拼交集，也**不要**把 `--only-title` 或 `intitle:` 当主候选路径——
+只有用户明确只查标题时才用它们。
+
+### 用户要 N 条结果时
+
+**N 是输出上限，不等于 `--page-size N`。** 逐页按返回里的 `title` 与 `summary_highlighted`
+保留同时满足两项条件的候选；有效候选不足 N 且 `has_more=true` 时，保持同一 query 与过滤条件、
+用 `--page-token` 继续，**最多检查 3 页**。摘要不足以判断正文条件时，只对标题已匹配的候选
+**串行**读正文，确认一个再处理下一个，找到 N 条即停——不要并发拉正文。检查 3 页仍不足就返回
+已确认结果，并建议用户调整标题词 / 正文词 / 搜索范围，不要无界扫描。
+
+### 分页与放宽范围
+
+- 默认只返回第一页，并说明 `has_more` 与下一页命令。用户明确要「全部 / 全量 / 继续翻」才继续。
+- 上面的标题词 + 正文词联合搜索最多检查 3 页；其他场景单轮翻页上限 5 页。
+- 扩展 query 时优先保留用户已指定的空间、文件夹、群聊、人员、时间和类型等过滤条件；
+  确需放宽检索范围时，先向用户说明原因并征得确认。
+- 结果被截断时不要据此回答「一共有多少」，先翻页或收窄条件。