@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-skills/lark-doc/references/lark-doc-fetch.md

@@ -0,0 +1,120 @@
+
+# docs +fetch（获取飞书云文档）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+## 命令
+
+```bash
+# 获取文档内容（默认输出 Markdown 文本）
+lark-cli docs +fetch --doc "https://xxx.feishu.cn/docx/Z1FjxxxxxxxxxxxxxxxxxxxtnAc"
+
+# 直接传 token
+lark-cli docs +fetch --doc Z1FjxxxxxxxxxxxxxxxxxxxtnAc
+
+# 知识库 URL 也支持
+lark-cli docs +fetch --doc "https://xxx.feishu.cn/wiki/Z1FjxxxxxxxxxxxxxxxxxxxtnAc"
+
+# 分页获取（大文档）
+lark-cli docs +fetch --doc Z1FjxxxxxxxxxxxxxxxxxxxtnAc --offset 0 --limit 50
+
+# 人类可读格式输出
+lark-cli docs +fetch --doc Z1FjxxxxxxxxxxxxxxxxxxxtnAc --format pretty
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc` | 是 | 文档 URL 或 token（支持 `/docx/` 和 `/wiki/` 链接，系统自动提取 token） |
+| `--offset` | 否 | 分页偏移 |
+| `--limit` | 否 | 分页大小 |
+| `--format` | 否 | 输出格式：json（默认，含 title、markdown、has_more 等字段） \| pretty |
+
+## 重要：图片、文件、画板的处理
+
+**文档中的图片、文件、画板需要通过独立的 media shortcut 单独获取。**
+
+### 识别格式
+
+返回的 Markdown 中，媒体文件以 HTML 标签形式出现：
+
+- **图片**：
+  ```html
+  <image token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" width="1833" height="2491" align="center"/>
+  ```
+
+- **文件**：
+  ```html
+  <view type="1">
+    <file token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" name="skills.zip"/>
+  </view>
+  ```
+
+- **画板**：
+  ```html
+  <whiteboard token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc"/>
+  ```
+- 画板编辑：详见 [SKILL.md](../SKILL.md#重要说明画板编辑)
+
+### 获取步骤
+
+1. 从 HTML 标签中提取 `token` 属性值
+2. 如果目标是图片/文件素材，且用户只是想查看/预览，调用 [`lark-doc-media-preview`](lark-doc-media-preview.md)（`docs +media-preview`）：
+   ```bash
+   lark-cli docs +media-preview --token "提取的token" --output ./preview_media
+   ```
+3. 如果用户明确要下载，或目标是 `<whiteboard token="..."/>`，调用 [`lark-doc-media-download`](lark-doc-media-download.md)（`docs +media-download`）：
+   ```bash
+   lark-cli docs +media-download --token "提取的token" --output ./downloaded_media
+   ```
+
+## Wiki URL 处理策略
+
+知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、多维表格等不同类型的文档。当不确定类型时，**不能直接假设是云文档**，必须先查询实际类型。
+
+### 处理流程
+
+1. **先调用 lark-wiki 解析 wiki token**
+2. **从返回的 `node` 中获取 `obj_type`（实际文档类型）和 `obj_token`（实际文档 token）**
+3. **根据 `obj_type` 调用对应工具**：
+
+| obj_type | 工具 | 说明 |
+|----------|------|------|
+| `docx` | `lark-doc-fetch` | 云文档 |
+| `sheet` | `lark-sheet` | 电子表格 |
+| `bitable` | `lark-base` | 多维表格 |
+| 其他 | 告知用户暂不支持 | — |
+
+## 重要：任务卡片（task 标签）
+
+`docs +fetch` 默认不会查询/展开文档中内嵌的任务详情（例如任务标题、状态、负责人等）。
+它会在返回的 Markdown 中保留任务引用，并返回任务 ID（GUID），例如：
+
+```html
+<task task-id="30597dc9-262e-4597-97f4-f8efcd1aeb95"></task>
+```
+
+如果用户需要查看该任务的详情，需要用返回的 `task-id` 再调用任务 CLI 查询：
+
+```bash
+lark-cli task tasks get --as user --params '{"task_guid":"30597dc9-262e-4597-97f4-f8efcd1aeb95"}'
+```
+
+## 工具组合
+
+| 需求 | 工具 |
+|------|------|
+| 获取文档文本 | `docs +fetch` |
+| 预览图片/文件素材 | `docs +media-preview` |
+| 下载图片/文件/画板 | `docs +media-download` |
+| 创建新文档 | `docs +create` |
+| 更新文档内容 | `docs +update` |
+
+## 参考
+
+- [lark-doc-create](lark-doc-create.md) — 创建文档
+- [lark-doc-update](lark-doc-update.md) — 更新文档
+- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
+- [lark-doc-media-download](lark-doc-media-download.md) — 下载素材/画板缩略图
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-doc/references/lark-doc-media-download.md

@@ -0,0 +1,50 @@
+
+# docs +media-download（下载文档素材/画板缩略图）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+下载文档中的图片/文件素材（`file_token`），或下载画板缩略图（`whiteboard_id`）。当 `--output` 不带扩展名时，会根据响应的 `Content-Type` 自动补全扩展名。
+
+## 选择规则
+
+- 用户明确说“下载素材”时，使用 `docs +media-download`
+- 用户只是想查看、预览图片或文件素材时，优先使用 [`docs +media-preview`](lark-doc-media-preview.md)
+- 如果目标明确是画板 / whiteboard / 画板缩略图，继续使用 `docs +media-download --type whiteboard`；`+media-preview` 不支持画板
+
+## 命令
+
+```bash
+# 下载图片/文件素材（默认 type=media）
+lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset
+
+# 指定输出文件名（带扩展名则不会自动补全）
+lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset.png
+
+# 下载画板缩略图（whiteboard token）
+lark-cli docs +media-download --type whiteboard --token "wbcnxxxxxxxx" --output ./whiteboard
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token <token>` | 是 | 资源 token：素材为 `file_token`，画板为 `whiteboard_id` |
+| `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 |
+| `--type <type>` | 否 | `media`（默认）或 `whiteboard` |
+
+## token 从哪里来
+
+- 若你是从文档内容里提取：`lark-doc-fetch` 返回的 Markdown 里可能包含：
+  - 图片：`<image token="..." .../>`
+  - 文件：`<file token="..." name="..."/>`
+  - 画板：`<whiteboard token="..."/>`
+
+## 排障
+
+- 如果报错返回的信息包含 `HTTP 403`，且目标是图片/文件素材，可以改成调用 [`docs +media-preview`](lark-doc-media-preview.md) 看是否能先预览内容
+
+## 参考
+
+- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）
+- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-doc/references/lark-doc-media-insert.md

@@ -0,0 +1,51 @@
+
+# docs +media-insert（文档末尾插入图片/文件）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+把“创建空 block → 上传文件 → 设置 token”三步合并成一个命令，在**文档末尾**插入本地图片或文件。
+
+## 命令
+
+```bash
+# 插入图片（默认）
+lark-cli docs +media-insert --doc doxcnXXX --file ./image.png
+
+# doc 支持直接传 docx URL（自动提取 document_id）
+lark-cli docs +media-insert --doc "https://xxx.feishu.cn/docx/doxcnXXX" --file ./image.png
+
+# 如果上一步是 create-doc，优先传返回值里的 doc_id
+# 不要把 /wiki/... 形式的 doc_url 直接传给 docs +media-insert
+lark-cli docs +media-insert --doc doxcnReturnedByCreateDoc --file ./image.png
+
+# 插入文件（非图片）
+lark-cli docs +media-insert --doc doxcnXXX --file ./spec.pdf --type file
+
+# 图片对齐与描述（caption）
+lark-cli docs +media-insert --doc doxcnXXX --file ./arch.png --align center --caption "架构图"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc <id>` | 是 | 文档 ID 或 docx URL（仅支持 `/docx/<document_id>` 形式自动提取；**不支持 `/wiki/...` URL 自动提取**） |
+| `--file <path>` | 是 | 本地文件路径（文件大于 20MB 时自动切换分片上传） |
+| `--type <type>` | 否 | `image`（默认）或 `file` |
+| `--align <align>` | 否 | 仅图片：`left` / `center`（默认）/ `right` |
+| `--caption <text>` | 否 | 仅图片：图片描述 |
+
+> [!IMPORTANT]
+> 如果上一步是 [`lark-doc-create`](lark-doc-create.md)，并且它在知识库/知识空间场景下返回的是 `/wiki/...` 形式的 `doc_url`，后续调用 `docs +media-insert` 时应优先传 `doc_id`，不要直接传这个 `doc_url`。
+
+## 输出
+
+命令成功后会输出 JSON，包含：`document_id`、`block_id`、`file_token`、`file_name`、`type`。
+
+> [!CAUTION]
+> 这是**写入操作**（会修改文档内容）—— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（可用于确认插入后的结果、以及提取媒体 token）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-doc/references/lark-doc-media-preview.md

@@ -0,0 +1,41 @@
+
+# docs +media-preview（预览文档素材）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+优先用于查看、预览文档中的图片或文件素材（`file_token`）。命令会把素材保存到本地路径，便于后续打开查看内容。
+
+## 选择规则
+
+- 用户说“看一下素材 / 图片 / 附件”“预览一下”时，优先使用 `docs +media-preview`
+- 用户明确说“下载”时，使用 [`docs +media-download`](lark-doc-media-download.md)
+- 如果目标明确是画板 / whiteboard / 画板缩略图，不要使用 `+media-preview`，改用 `docs +media-download --type whiteboard`
+
+## 命令
+
+```bash
+# 预览图片/文件素材
+lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset
+
+# 指定输出文件名（带扩展名则不会自动补全）
+lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset.png
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token <token>` | 是 | 素材 token，即 `file_token` |
+| `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 |
+
+## token 从哪里来
+
+- 若你是从文档内容里提取：`lark-doc-fetch` 返回的 Markdown 里可能包含：
+  - 图片：`<image token="..." .../>`
+  - 文件：`<file token="..." name="..."/>`
+
+## 参考
+
+- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）
+- [lark-doc-media-download](lark-doc-media-download.md) — 明确下载素材，或下载画板缩略图
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-doc/references/lark-doc-search.md

@@ -0,0 +1,213 @@
+
+# docs +search（云空间搜索：文档 / Wiki / 电子表格）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+基于 Search v2 接口 `POST /open-apis/search/v2/doc_wiki/search`，以**用户身份**统一搜索云空间对象。
+
+虽然接口名是 `doc_wiki/search`，但命中结果不只限于文档 / Wiki，也会返回 `SHEET`、`BITABLE`、`FOLDER` 等云空间对象。因此它适合作为云空间对象的资源发现入口：先定位文档、知识库节点、电子表格、多维表格、文件夹，以及用户以“表格 / 报表”方式描述的相关对象，再切回对应业务 skill 做对象内部操作。
+
+该 shortcut 会：
+
+- 未指定范围字段时，自动补齐 `doc_filter` / `wiki_filter`
+- 自动将 `--filter` 中的公共字段同步到搜索范围对应的 filter；`folder_tokens` 仅发到 `doc_filter`，`space_ids` 仅发到 `wiki_filter`
+- 支持在 `filter.open_time` / `filter.create_time` 中使用 ISO 8601 时间，并自动转换为 Unix 秒
+- 在返回结果中为 `*_time` 字段补充 `*_time_iso`（便于阅读）
+- `title_highlighted` / `summary_highlighted` 可能包含高亮标签（如 `<h>` / `<hb>`）
+
+## 命令
+
+> **关键约束：搜索关键词必须通过 `--query` 传递。**
+> 正确：`lark-cli docs +search --query "方案"`
+> 错误：`lark-cli docs +search 方案`
+> `+search` 不接受“搜索词位置参数”这种写法；如果把关键词直接跟在命令后面，不会进入 `query`，会变成空搜或返回不符合预期的结果。
+
+```bash
+# 关键词搜索
+lark-cli docs +search --query "季度总结"
+
+# 搜标题里带“评测结果”的电子表格 / 文档
+lark-cli docs +search --query "评测结果"
+
+# 标题包含关键词（默认按关键词检索，不做精确标题匹配）
+lark-cli docs +search --query "方案"
+
+# 使用服务端标题限定语法
+lark-cli docs +search --query 'intitle:方案'
+
+# 精确短语匹配
+lark-cli docs +search --query '"季度 总结"'
+
+# 逻辑或 / 排除
+lark-cli docs +search --query '方案 OR 草稿'
+lark-cli docs +search --query '方案 -草稿'
+
+# 标题精确短语匹配
+lark-cli docs +search --query 'intitle:"季度总结"'
+
+# 按最近打开时间过滤
+lark-cli docs +search \
+  --query "方案" \
+  --filter '{"open_time":{"start":"2025-09-24T00:00:00+08:00","end":"2025-12-24T23:59:59+08:00"}}'
+
+# 按文档所有者过滤（creator_ids 传文档所有者 open_id，不是邮箱 / user_id）
+lark-cli docs +search \
+  --query "季度总结" \
+  --filter '{"creator_ids":["ou_7890123456abcdef"]}'
+
+# 只搜索指定类型
+lark-cli docs +search \
+  --query "评测结果" \
+  --filter '{"doc_types":["SHEET","DOCX"]}'
+
+# 只在指定文件夹下搜索文档（folder_token 通常来自 /drive/folder/<token>）
+lark-cli docs +search \
+  --query "方案" \
+  --filter '{"folder_tokens":["fld_123456"]}'
+
+# 只搜标题，不搜正文 / 摘要
+lark-cli docs +search \
+  --query "周报" \
+  --filter '{"only_title":true}'
+
+# 只搜评论，不搜标题 / 正文
+lark-cli docs +search \
+  --query "延期原因" \
+  --filter '{"only_comment":true}'
+
+# 只搜索指定群会话里分享过的文档（chat_id 最多 20 个）
+lark-cli docs +search \
+  --query "方案" \
+  --filter '{"chat_ids":["oc_1234567890abcdef"]}'
+
+# 只搜索指定分享者分享过的文档（sharer_ids 传分享者 open_id，最多 20 个）
+lark-cli docs +search \
+  --query "复盘" \
+  --filter '{"sharer_ids":["ou_7890123456abcdef"]}'
+
+# 按创建时间过滤并指定排序方式
+lark-cli docs +search \
+  --query "方案" \
+  --filter '{"create_time":{"start":"2026-01-01","end":"2026-03-31"},"sort_type":"CREATE_TIME"}'
+
+# 组合多个筛选条件
+lark-cli docs +search \
+  --query "项目复盘" \
+  --filter '{"creator_ids":["ou_7890123456abcdef"],"doc_types":["DOCX","SHEET"],"only_title":true,"sort_type":"OPEN_TIME","open_time":{"start":"2026-01-01T00:00:00+08:00"}}'
+
+# 只在指定知识空间下搜 Wiki
+lark-cli docs +search \
+  --query "研发规范" \
+  --filter '{"space_ids":["space_1234567890fedcba"]}'
+
+# 空搜（不传 query 或传空字符串）：按最近浏览等默认规则返回
+lark-cli docs +search
+
+# 人类可读格式输出
+lark-cli docs +search --query "OKR" --format pretty
+
+# 返回原始 JSON，并用 page_token 翻页
+lark-cli docs +search --query "方案" --format json
+lark-cli docs +search --query "方案" --format json --page-token '<PAGE_TOKEN>'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--query <text>` | 否 | 搜索关键词。**支持高级 Boolean 语法**以提升搜索精度：<br>1. 使用空格表示 AND（如 `方案 设计`）。<br>2. 使用 `OR` 表示逻辑或（如 `方案 OR 草稿`）。<br>3. 使用 `-` 表示排除（如 `方案 -草稿`）。<br>4. 使用双引号 `""` 表示精确匹配短语。<br>5. 使用 `intitle:` 限定关键词出现在标题中（如 `intitle:总结` 或 `intitle:"季度 总结"`）。不传/空字符串表示空搜。**凡是有关键词，都要显式通过 `--query` 传递，不要写成位置参数。** |
+| `--filter <json>` | 否 | JSON 对象。公共字段默认同时应用到 `doc_filter` / `wiki_filter`；若传 `folder_tokens`，则只发 `doc_filter`；若传 `space_ids`，则只发 `wiki_filter`；两者不能同时传 |
+| `--page-size <n>` | 否 | 每页数量（默认 15，最大 20） |
+| `--page-token <token>` | 否 | 翻页标记（配合 `has_more` 使用） |
+| `--format` | 否 | 输出格式：json（默认） \| pretty |
+
+## `--query` 高级语法
+
+以下语法由服务端搜索能力处理，适合把过滤逻辑尽量下推到搜索侧：
+
+- 空格表示 AND：`方案 设计`
+- `OR` 表示逻辑或：`方案 OR 草稿`
+- `-` 表示排除：`方案 -草稿`
+- 双引号表示精确短语：`"季度 总结"`
+- `intitle:` 表示标题限定：`intitle:总结`
+- 标题精确短语：`intitle:"季度总结"`
+
+## `--filter` 字段速查
+
+`--filter` 是一个 JSON 对象。大多数字段默认会同时作用于 `doc_filter` 和 `wiki_filter`；其中 `folder_tokens` 只用于文档侧，`space_ids` 只用于 Wiki 侧。
+
+### 字段归属
+
+- `doc_filter` / `wiki_filter` 公共字段：`creator_ids`、`doc_types`、`chat_ids`、`sharer_ids`、`only_title`、`only_comment`、`open_time`、`sort_type`、`create_time`
+- `doc_filter` 独有字段：`folder_tokens`
+- `wiki_filter` 独有字段：`space_ids`
+- 如果传 `folder_tokens`，shortcut 只发送 `doc_filter`
+- 如果传 `space_ids`，shortcut 只发送 `wiki_filter`
+- 如果同时传 `folder_tokens` 和 `space_ids`，shortcut 直接报错，不支持同时查询文档文件夹范围和知识空间范围
+
+| 字段 | 作用范围 | 类型 | 说明 |
+|------|----------|------|------|
+| `creator_ids` | 文档 + Wiki | `string[]` | 所有者列表，**必须传 open_id**，不是 `user_id` / `union_id` / 邮箱。比如 `["ou_xxx"]`。如果只有姓名，先用 `lark-contact` 查 open_id |
+| `doc_types` | 文档 + Wiki | `string[]` | 资源类型过滤。常用值：`DOC`、`DOCX`、`SHEET`、`BITABLE`、`FILE`、`WIKI`、`SLIDES`、`FOLDER`、`CATALOG`、`SHORTCUT` |
+| `chat_ids` | 文档 + Wiki | `string[]` | 群会话 ID 列表，只搜索这些会话里分享过的文档，最多 20 个。通常传群 `chat_id`（如 `oc_xxx`）；如果用户只给群名，先用 `lark-im` 定位群 |
+| `sharer_ids` | 文档 + Wiki | `string[]` | 分享者列表，**必须传分享者 open_id**，最多 20 个。适合“某人分享过的文档”；如果只有姓名，先用 `lark-contact` 查 open_id |
+| `folder_tokens` | 仅文档 | `string[]` | 只搜索指定云空间文件夹下的文档；值通常来自文件夹 URL `/drive/folder/<folder_token>` |
+| `space_ids` | 仅 Wiki | `string[]` | 只搜索指定知识空间下的 Wiki 节点 |
+| `only_title` | 文档 + Wiki | `boolean` | 只搜标题。注意这不是“标题精确等于”，只是把搜索范围限制在标题 |
+| `only_comment` | 文档 + Wiki | `boolean` | 只搜评论。用法类似 `only_title`，只是把搜索范围限制在评论区；默认 `false` |
+| `open_time` | 文档 + Wiki | `object` | 最近打开时间范围，支持 `{ "start": "...", "end": "..." }`。shortcut 支持 ISO 8601 / `YYYY-MM-DD` / Unix 秒，并自动转成秒级时间戳 |
+| `sort_type` | 文档 + Wiki | `string` | 排序方式。常用值：`DEFAULT_TYPE`、`OPEN_TIME`、`EDIT_TIME`、`EDIT_TIME_ASC`、`CREATE_TIME` |
+| `create_time` | 文档 + Wiki | `object` | 文档 / Wiki 创建时间范围，结构与 `open_time` 相同 |
+
+### 字段使用建议
+
+- `creator_ids`：适合“找某个人创建的文档 / 表格 / Wiki”。如果用户只给姓名，不要猜 ID，先查这个人的 `open_id`。
+- `doc_types`：只在用户**明确指定资源类型**时使用，适合先把资源类型缩小。显式类型词可按以下方式映射：`表格 / 电子表格 / spreadsheet -> ["SHEET"]`、`多维表格 / base / bitable -> ["BITABLE"]`、`知识库 / wiki -> ["WIKI"]`、`文件夹 -> ["FOLDER"]`、`普通文档` 或明确要求“只看文档类型、不要表格 / Wiki” -> `["DOC","DOCX"]`。不要因为用户口头说“文档”就默认补 `DOC` / `DOCX`，因为“文档”在很多场景里只是对云空间对象的泛称。
+- `chat_ids`：适合“搜某个群里分享过的文档”“看某个群会话里的方案”。如果用户只给群名，先切到 `lark-im` 用群搜索能力拿到 `chat_id`，再回到 `docs +search`。
+- `sharer_ids`：适合“找某人分享过的文档”“看某个同事转给我的资料”。如果用户只给姓名，不要猜 ID，先用 `lark-contact` 查分享者 `open_id`。
+- `folder_tokens`：适合“在某个云空间文件夹里搜文档”。它不是知识空间 `space_id`，两者不要混用。
+- `only_title`：适合“标题里包含某个词”的场景；如果用户明确表达标题限定，也可以直接在 `--query` 里使用 `intitle:`。如果用户要“标题精确等于”，优先使用 `intitle:"完整标题"`，必要时再做客户端精确确认。
+- `only_comment`：适合“评论里提到某个词”“只找评论区讨论过某件事”。它和 `only_title` 一样，都是把搜索范围缩小到特定区域，但这里限制到评论区。
+- `open_time`：适合“最近打开过 / 最近看过”的描述；如果用户说相对时间，先换算成明确绝对时间再传。
+- `sort_type`：`CREATE_TIME_ASC` 在协议里标注“暂不支持”，`ENTITY_CREATE_TIME_ASC` / `ENTITY_CREATE_TIME_DESC` 已废弃，默认不要主动使用。
+- `create_time`：适合“今年新建的”“上个月创建的”这类条件；不写 `start` / `end` 时，协议默认窗口是“请求时间往前 1 年”到“请求时间”。
+
+### 常见 `--filter` JSON 片段
+
+```json
+{"creator_ids":["ou_7890123456abcdef"]}
+{"doc_types":["SHEET","DOCX"]}
+{"chat_ids":["oc_1234567890abcdef"]}
+{"sharer_ids":["ou_7890123456abcdef"]}
+{"folder_tokens":["fld_123456"]}
+{"only_title":true}
+{"only_comment":true}
+{"open_time":{"start":"2026-01-01T00:00:00+08:00","end":"2026-03-31T23:59:59+08:00"},"sort_type":"OPEN_TIME"}
+{"create_time":{"start":"2026-01-01","end":"2026-03-31"},"sort_type":"CREATE_TIME"}
+{"space_ids":["space_1234567890fedcba"]}
+```
+
+## 结果判别
+
+- `result_meta.doc_types == SHEET`：电子表格，后续切到 `lark-sheets`
+- 其他类型：继续按对应 skill 或 API 处理
+
+## 决策规则
+
+- 参数传递：只要用户给了搜索关键词，就必须显式使用 `--query "<关键词>"`。不要生成 `lark-cli docs +search 方案`、`lark-cli docs +search xxx（搜索关键词）` 这种位置参数写法。
+- 查询语义：必须优先利用 --query 的高级语法（如 intitle:、""、-）将过滤逻辑下推给服务端。当用户要求“标题精确等于 X”时，直接使用 --query "intitle:\"X\""，严禁先进行模糊搜索再做客户端二次筛选。只有在遇到服务端语法无法覆盖的复杂本地比对场景时，才允许在客户端过滤，且比对前必须先去掉 title_highlighted 里的高亮标签。
+- 实体补全：如果用户要按“某个群里分享的文档”搜索，先用 `lark-im` 拿 `chat_id` 再填 `chat_ids`；如果用户要按“某人分享的文档”搜索，先用 `lark-contact` 拿 `open_id` 再填 `sharer_ids`。
+- 零结果回退：如果因为用户的显式类型约束加了 `doc_types` 且结果为 0，可以提示“按指定类型没搜到”；只有在不违背用户明确约束的前提下，才建议放宽类型重试。
+- 入口选择：用户说“找表格标题”“找名为 `X` 的电子表格”“搜某个报表”时，也默认走 `docs +search`。不要误用 `sheets +find` 做跨文件搜索。
+- 分页策略：默认只返回**第一页**，并说明 `has_more` / `page_token`。只有当用户明确要求“全部结果”“继续翻页”“全量扫描”“所有结果”“完整列表”时，才继续翻页。
+- 翻页上限：即使用户要求全量，单轮也最多先拉 **5 页**（按默认 `page-size=20` 约等于最多 100 条结果）。达到上限后，先回报当前进度和是否还有更多页，再让用户决定是否继续下一批。
+- 总数口径：`total` 是 OpenAPI 的搜索结果总数，不一定等于客户端二次筛选后的精确数量。凡是依赖本地过滤、去重、精确标题匹配的场景，都不要默认承诺“精确总数”。
+- 原始返回：如果用户要求“直接返回接口数据 / 原始返回”，优先使用 `--format json`，不要额外做精确标题过滤或摘要重写。
+- 时间表达：用户如果说“3 到 6 个月前”“最近半年内”等相对时间，先转换成明确的绝对时间，再写入 `filter.open_time` / `filter.create_time`。
+- 跨 skill handoff：如果搜索的目标是某个 spreadsheet，返回命中的标题、URL、token 等定位信息后，应切换到 `lark-sheets` 继续后续操作，不要把 `docs +search` 当成对象内部查询。
+
+## 权限
+
+| 操作 | 所需 scope |
+|------|-----------|
+| 搜索云空间对象（含文档 / Wiki / 表格资源发现） | `search:docs:read` |