@wagemule/daemon 0.1.0 → 0.1.3

package/dist/skills/larksuite/lark-drive/references/lark-drive-create-folder.md

@@ -0,0 +1,73 @@
+# drive +create-folder（创建云空间文件夹）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+在飞书云空间中创建一个新文件夹。该 shortcut 对原生 `drive files create_folder` 做了一层更适合日常使用的封装：`--folder-token` 可省略，此时会在调用者根目录创建；如果使用 `--as bot`，创建成功后 CLI 会尝试把新文件夹的可管理权限自动授予当前 CLI 用户。
+
+## 命令
+
+```bash
+# 在根目录创建文件夹
+lark-cli drive +create-folder \
+  --name "周报归档"
+
+# 在指定父文件夹下创建子文件夹
+lark-cli drive +create-folder \
+  --folder-token <PARENT_FOLDER_TOKEN> \
+  --name "2026-W16"
+
+# 预览底层调用
+lark-cli drive +create-folder \
+  --folder-token <PARENT_FOLDER_TOKEN> \
+  --name "分析资料" \
+  --dry-run
+```
+
+## 返回值
+
+成功后会返回一个 JSON 对象，常见字段包括：
+
+- `folder_token`：新建文件夹 token，可直接用于后续 `drive +move`、`drive +upload` 等命令
+- `url`：新建文件夹链接（如果接口返回）
+- `name`：文件夹名称
+- `parent_folder_token`：父文件夹 token；为空字符串表示创建在根目录
+- `permission_grant`（可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
+
+> [!IMPORTANT]
+> 如果文件夹是**以应用身份（bot）创建**的，如 `lark-cli drive +create-folder --as bot`，在创建成功后 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 转给自己，必须单独确认。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--name` | 是 | 文件夹名称，不能为空，最长 256 字节 |
+| `--folder-token` | 否 | 父文件夹 token；省略时表示在调用者根目录创建 |
+
+## 行为说明
+
+- **根目录创建**：不传 `--folder-token` 时，shortcut 会向 API 显式传空字符串 `folder_token=""`，让后端按“根目录”语义创建
+- **bot 自动授权**：只有在 `--as bot` 时，结果才会额外带上 `permission_grant`
+- **原生 API 仍可用**：如果用户明确要求按底层 API 字段调用，仍可继续使用 `lark-cli drive files create_folder`
+
+## 推荐场景
+
+- 用户说“在云空间新建一个文件夹 / 目录”时，优先使用 `drive +create-folder`
+- 用户给了父文件夹链接或 token，需要在其下继续分层建目录时，传 `--folder-token`
+- 如果后续还要上传文件、移动文件、建子目录，优先复用返回值里的 `folder_token`
+
+> [!CAUTION]
+> `drive +create-folder` 是**写入操作**，执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/dist/skills/larksuite/lark-drive/references/lark-drive-create-shortcut.md

@@ -0,0 +1,103 @@
+
+# drive +create-shortcut
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+在目标文件夹中为一个现有 Drive 文件创建快捷方式。
+
+## 命令
+
+```bash
+# 为普通文件创建快捷方式
+lark-cli drive +create-shortcut \
+  --folder-token <TARGET_FOLDER_TOKEN> \
+  --file-token <FILE_TOKEN> \
+  --type file
+
+# 为新版文档创建快捷方式
+lark-cli drive +create-shortcut \
+  --folder-token <TARGET_FOLDER_TOKEN> \
+  --file-token <DOCX_TOKEN> \
+  --type docx
+
+# 为电子表格创建快捷方式
+lark-cli drive +create-shortcut \
+  --folder-token <TARGET_FOLDER_TOKEN> \
+  --file-token <SHEET_TOKEN> \
+  --type sheet
+
+# 仅预览即将发起的请求，不真正执行
+lark-cli drive +create-shortcut \
+  --folder-token <TARGET_FOLDER_TOKEN> \
+  --file-token <DOCX_TOKEN> \
+  --type docx \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--folder-token` | 是 | 目标父文件夹 token |
+| `--file-token` | 是 | 源文件 token，表示被引用的原始文件 |
+| `--type` | 是 | 源文件类型，推荐值：`file`、`docx`、`doc`、`sheet`、`bitable`、`mindnote`、`slides` |
+
+## 输入规则
+
+- 该 shortcut 的最小输入是 `--folder-token` + `--file-token` + `--type`
+- CLI 层会把 `--file-token` 和 `--type` 组装为底层 API 所需的 `refer_entity`
+- `--file-token` 必须是 Drive 文件 token，不要直接传 wiki 节点 token
+- 如果来源是 `/wiki/...` 链接，必须先按 [`lark-drive`](../SKILL.md) 中的 wiki 解析流程拿到真实 `obj_token`，再创建快捷方式
+- 目标位置必须是云空间文件夹；这个 shortcut 不是“复制文件内容”，而是“在另一个文件夹里挂一个引用入口”
+
+## 类型说明
+
+| 类型 | 说明 |
+|------|------|
+| `file` | 普通文件 |
+| `docx` | 新版云文档 |
+| `doc` | 旧版云文档 |
+| `sheet` | 电子表格 |
+| `bitable` | 多维表格 |
+| `mindnote` | 思维笔记 |
+| `slides` | 幻灯片 |
+
+## 行为说明
+
+- 成功时会调用 `POST /open-apis/drive/v1/files/create_shortcut`
+- 该 shortcut 继承通用能力，可配合 `--as user|bot|auto`、`--format`、`--jq`、`--dry-run` 使用
+- `--dry-run` 只输出请求方法、路径、身份和请求体预览，不会真正创建快捷方式
+- 这是写入操作；执行前应确认目标文件夹和源文件都准确无误
+
+## 限制
+
+- 该接口不支持并发调用
+- 调用频率上限为 5 QPS，且 10000 次/天
+- 不支持跨租户、跨地域创建快捷方式
+- 不支持跨品牌创建快捷方式
+- 如果目标父文件夹单层挂载数量超过限制，会返回 `1062507`
+
+## 权限要求
+
+- 当前调用身份需要能访问源文件
+- 当前调用身份需要对目标文件夹有编辑权限
+- 如果权限不足，常见表现为 `1061004 forbidden`
+
+## 常见错误
+
+| 错误码 / 错误信息 | 原因 | 处理建议 |
+|------|------|------|
+| `1061002 params error` | 缺少必填参数，或 `--file-token` / `--type` 组合无法构成有效源文件信息 | 检查 `--file-token`、`--type` 是否完整且匹配；如显式传了 `--folder-token`，再确认其值有效 |
+| `1061003 not found` | 源文件或目标文件夹不存在 | 重新确认 token 是否正确、资源是否已删除 |
+| `1061004 forbidden` | 对源文件没有访问权限，或对目标文件夹没有编辑权限 | 切换到有权限的身份，或先授予文档 / 文件夹权限 |
+| `1061005 auth failed` | 身份类型或 access token 不正确 | 检查 `--as` 使用的身份及当前登录态 |
+| `1061007 file has been delete` | 源文件已删除 | 确认原文件仍存在，再重新执行 |
+| `1062507 parent node out of sibling num` | 目标文件夹单层挂载数超过上限 | 清理目标目录，或换一个父文件夹 |
+| `1061045 resource contention occurred, please retry` | 平台内部资源争抢 | 稍后重试，不要并发重复调用 |
+| `1064510 cross tenant and unit not support` | 跨租户或跨地域请求 | 改为在同租户、同地域范围内操作 |
+| `1064511 cross brand not support` | 跨品牌请求 | 改为在同品牌环境内操作 |
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,79 @@
+
+# drive +delete
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+删除云空间内的文件或文件夹。删除后资源会进入回收站。
+
+> [!CAUTION]
+> 这是**高风险写操作**。CLI 层要求显式传 `--yes`；如果用户已经明确要求删除且目标明确，直接执行并带上 `--yes`。
+
+## 命令
+
+```bash
+# 删除普通文件
+lark-cli drive +delete \
+  --file-token <FILE_TOKEN> \
+  --type file \
+  --yes
+
+# 删除在线文档
+lark-cli drive +delete \
+  --file-token <DOCX_TOKEN> \
+  --type docx \
+  --yes
+
+# 删除文件夹（异步操作，会自动有限轮询任务状态）
+lark-cli drive +delete \
+  --file-token <FOLDER_TOKEN> \
+  --type folder \
+  --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 需要删除的文件或文件夹 token |
+| `--type` | 是 | 文件类型，可选值：`file`、`docx`、`bitable`、`doc`、`sheet`、`mindnote`、`folder`、`shortcut`、`slides` |
+| `--yes` | 是 | 确认执行高风险删除操作 |
+
+## 行为说明
+
+- **普通文件删除**：同步操作，成功时直接返回 `deleted=true`
+- **文件夹删除**：异步操作，接口返回 `task_id`，shortcut 会先做有限轮询；如果在轮询窗口内完成，则直接返回成功结果
+- **轮询超时不是失败**：文件夹删除内置最多轮询 30 次、每次间隔 2 秒；如果轮询结束任务仍未完成，会返回 `task_id`、`status`、`ready=false`、`timed_out=true` 和 `next_command`
+- **继续查询**：当看到 `next_command` 时，改用 `lark-cli drive +task_result --scenario task_check --task-id <TASK_ID>` 继续查询
+- **状态值**：`task_check` 的服务端状态通常是 `success`、`fail`、`process`
+
+## 推荐续跑方式
+
+```bash
+# 第一步：先直接删除文件夹
+lark-cli drive +delete \
+  --file-token <FOLDER_TOKEN> \
+  --type folder \
+  --yes
+
+# 如果返回 ready=false / timed_out=true，再继续查
+lark-cli drive +task_result \
+  --scenario task_check \
+  --task-id <TASK_ID>
+```
+
+## 限制
+
+- 该 shortcut 仅支持云空间文件或文件夹，不支持 wiki 文档
+- 该接口不支持并发调用
+- 调用频率上限为 5 QPS 且 10000 次/天
+
+## 权限要求
+
+- 删除文件时，调用身份需要满足以下其一：
+- 是文件所有者，并且拥有该文件所在父文件夹的编辑权限
+- 不是文件所有者，但拥有该父文件夹的 owner 或 full access 权限
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,31 @@
+
+# drive +download
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+从飞书云空间下载文件到本地。
+
+## 命令
+
+```bash
+# 下载到指定路径
+lark-cli drive +download --file-token boxbc_xxx --output ./report.pdf
+
+# 只提供 token，默认保存为当前目录下同名文件
+lark-cli drive +download --file-token boxbc_xxx
+```
+
+## URL 解析
+
+从飞书文件 URL 提取 token：
+
+```
+https://xxx.feishu.cn/drive/file/boxbc_xxx
+                                  ^^^^^^^^^
+                                  file_token
+```
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/dist/skills/larksuite/lark-drive/references/lark-drive-export-download.md

@@ -0,0 +1,50 @@
+
+# drive +export-download
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+根据导出任务产物的 `file_token` 下载本地文件。通常与 `drive +task_result --scenario export` 配合使用。
+
+## 命令
+
+```bash
+# 使用服务端返回的文件名下载到当前目录
+lark-cli drive +export-download \
+  --file-token "<EXPORTED_FILE_TOKEN>"
+
+# 下载到指定目录
+lark-cli drive +export-download \
+  --file-token "<EXPORTED_FILE_TOKEN>" \
+  --output-dir ./exports
+
+# 指定本地文件名
+lark-cli drive +export-download \
+  --file-token "<EXPORTED_FILE_TOKEN>" \
+  --file-name "weekly-report.pdf" \
+  --output-dir ./exports
+
+# 允许覆盖
+lark-cli drive +export-download \
+  --file-token "<EXPORTED_FILE_TOKEN>" \
+  --overwrite
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 导出完成后的产物 token |
+| `--file-name` | 否 | 覆盖默认文件名 |
+| `--output-dir` | 否 | 本地输出目录，默认当前目录 |
+| `--overwrite` | 否 | 覆盖已存在文件 |
+
+## 使用顺序
+
+1. 用 `drive +export` 发起导出
+2. 如果返回 `ticket` / `next_command`，用 `drive +task_result --scenario export --ticket <ticket> --file-token <source_token>` 继续查
+3. 查到 `file_token` 后，用 `drive +export-download` 下载
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,119 @@
+
+# drive +export
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+把 `doc` / `docx` / `sheet` / `bitable` 导出到本地文件。这个 shortcut 内置有限轮询：
+
+- 如果导出任务在轮询窗口内完成，会直接下载到本地目录
+- 如果轮询结束仍未完成，会返回 `ticket`、`ready=false`、`timed_out=true` 和 `next_command`
+- 后续继续查结果时，改用 `drive +task_result --scenario export`
+- 拿到 `file_token` 后，改用 `drive +export-download`
+
+## 命令
+
+```bash
+# 导出新版文档为 pdf，默认保存到当前目录
+lark-cli drive +export \
+  --token "<DOCX_TOKEN>" \
+  --doc-type docx \
+  --file-extension pdf
+
+# 导出旧版文档为 docx
+lark-cli drive +export \
+  --token "<DOC_TOKEN>" \
+  --doc-type doc \
+  --file-extension docx
+
+# 导出 docx 为 markdown
+# 注意：markdown 只支持 docx，底层走 /open-apis/docs/v1/content
+lark-cli drive +export \
+  --token "<DOCX_TOKEN>" \
+  --doc-type docx \
+  --file-extension markdown
+
+# 导出电子表格为 xlsx
+lark-cli drive +export \
+  --token "<SHEET_TOKEN>" \
+  --doc-type sheet \
+  --file-extension xlsx \
+  --output-dir ./exports
+
+# 指定本地文件名（会按导出格式自动补扩展名）
+lark-cli drive +export \
+  --token "<DOCX_TOKEN>" \
+  --doc-type docx \
+  --file-extension pdf \
+  --file-name "weekly-report.pdf" \
+  --output-dir ./exports
+
+# 导出电子表格或多维表格为 csv 时，必须传 sub_id
+lark-cli drive +export \
+  --token "<SHEET_OR_BITABLE_TOKEN>" \
+  --doc-type "<sheet|bitable>" \
+  --file-extension csv \
+  --sub-id "<SUB_ID>" \
+  --output-dir ./exports
+
+# 导出多维表格为 .base 快照（只支持 bitable）
+lark-cli drive +export \
+  --token "<BITABLE_TOKEN>" \
+  --doc-type bitable \
+  --file-extension base \
+  --output-dir ./exports
+
+# 允许覆盖已存在文件
+lark-cli drive +export \
+  --token "<DOCX_TOKEN>" \
+  --doc-type docx \
+  --file-extension pdf \
+  --overwrite
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token` | 是 | 源文档 token |
+| `--doc-type` | 是 | 源文档类型：`doc` / `docx` / `sheet` / `bitable` |
+| `--file-extension` | 是 | 导出格式：`docx` / `pdf` / `xlsx` / `csv` / `markdown` / `base` |
+| `--sub-id` | 条件必填 | 当 `sheet` / `bitable` 导出为 `csv` 时必填 |
+| `--file-name` | 否 | 覆盖默认本地文件名；如未带扩展名，会按 `--file-extension` 自动补齐 |
+| `--output-dir` | 否 | 本地输出目录，默认当前目录 |
+| `--overwrite` | 否 | 覆盖已存在文件 |
+
+## 关键约束
+
+- `markdown` 只支持 `docx`
+- `base` 只支持 `bitable`
+- `sheet` / `bitable` 导出为 `csv` 时必须带 `--sub-id`
+- shortcut 内部固定有限轮询：最多 10 次，每次间隔 5 秒
+- 轮询超时不是失败；会返回 `ticket`、`timed_out=true` 和 `next_command`，供后续继续查询
+
+## 推荐续跑方式
+
+```bash
+# 第一步：先尝试直接导出
+lark-cli drive +export \
+  --token "<DOCX_TOKEN>" \
+  --doc-type docx \
+  --file-extension pdf \
+  --file-name "weekly-report.pdf"
+
+# 如果返回 ready=false / timed_out=true，再继续查
+lark-cli drive +task_result \
+  --scenario export \
+  --ticket "<TICKET>" \
+  --file-token "<DOCX_TOKEN>"
+
+# 查到 file_token 后下载
+lark-cli drive +export-download \
+  --file-token "<EXPORTED_FILE_TOKEN>" \
+  --file-name "weekly-report.pdf" \
+  --output-dir ./exports
+```
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,154 @@
+# drive +import
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+将本地文件（如 Word、TXT、Markdown、Excel 等）导入并转换为飞书在线云文档（docx、sheet、bitable）。底层统一通过 `POST /open-apis/drive/v1/import_tasks` 接口创建导入任务，并在 shortcut 内做有限次数轮询 `GET /open-apis/drive/v1/import_tasks/:ticket`。
+
+> [!IMPORTANT]
+> 当用户说“把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable 文档”时，第一步必须使用 `drive +import --type bitable`。
+> 这是 Drive 导入场景，不是 `lark-base` 的建表 / 写记录场景。
+> 只有导入完成并拿到新文档的 `token` / `url` 后，后续字段、记录、视图等表内操作才切换到 `lark-cli base +...`。
+
+## 命令
+
+```bash
+# 导入 Word 为新版文档 (docx)
+lark-cli drive +import --file ./report.docx --type docx
+lark-cli drive +import --file ./legacy.doc --type docx
+
+# 导入 Markdown 为新版文档 (docx)
+lark-cli drive +import --file ./README.md --type docx
+
+# 导入纯文本为新版文档 (docx)
+lark-cli drive +import --file ./notes.txt --type docx
+
+# 导入 HTML 为新版文档 (docx)
+lark-cli drive +import --file ./page.html --type docx
+
+# 导入 Excel 为电子表格 (sheet)
+lark-cli drive +import --file ./data.xlsx --type sheet
+
+# 导入 Excel 97-2003 (.xls) 为电子表格 (sheet)
+lark-cli drive +import --file ./legacy.xls --type sheet
+
+# 导入 CSV 为电子表格 (sheet)
+lark-cli drive +import --file ./data.csv --type sheet
+
+# 导入 Excel 为多维表格 / Base (bitable)
+lark-cli drive +import --file ./crm.xlsx --type bitable --name "客户台账"
+
+# 导入 .base 快照为多维表格 / Base (bitable)（文件不能超过 20MB）
+lark-cli drive +import --file ./snapshot.base --type bitable --name "快照还原"
+
+# 导入到指定文件夹，并指定导入后的文件名
+lark-cli drive +import --file ./data.csv --type bitable --folder-token <FOLDER_TOKEN> --name "导入数据表"
+
+# 预览底层调用链（上传 -> 创建任务 -> 轮询）
+lark-cli drive +import --file ./README.md --type docx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file` | 是 | 本地文件路径，根据文件后缀名自动推断 `file_extension`；文件需满足对应格式的导入大小限制，超过 20MB 且仍在允许范围内时会自动切换分片上传 |
+| `--type` | 是 | 导入目标云文档格式。可选值：`docx` (新版文档)、`sheet` (电子表格)、`bitable` (多维表格) |
+| `--folder-token` | 否 | 目标文件夹 token，不传则请求中的 `point.mount_key` 为空字符串，Import API 会将其解释为导入到云空间根目录 |
+| `--name` | 否 | 导入后的在线云文档名称，不传默认使用本地文件名去掉扩展名后的结果 |
+
+## 行为说明
+
+- **完整执行流程**：此 shortcut 内部封装了完整流程：
+  1. 自动上传源文件获取 `file_token`：
+     - 20MB 及以下：调用素材上传接口 `POST /open-apis/drive/v1/medias/upload_all`
+     - 超过 20MB：自动切换为分片上传 `upload_prepare -> upload_part -> upload_finish`
+  2. 调用 `import_tasks` 接口发起导入任务，自动根据本地文件提取扩展名并构造挂载点（`mount_point`）参数
+  3. 自动轮询查询导入任务状态；如果在内置轮询窗口内完成，则直接返回导入结果；如果仍未完成，则返回 `ticket`、当前状态和后续查询命令
+- **默认根目录行为**：不传 `--folder-token` 时，shortcut 会保留空的 `point.mount_key`，Lark Import API 会将其视为“导入到调用者根目录”。
+
+### 支持的文件类型转换
+
+本地文件扩展名与目标云文档类型的对应关系如下：
+
+| 本地文件扩展名 | 可导入为 | 说明 |
+|--------------|---------|------|
+| `.docx`, `.doc` | `docx` | Microsoft Word 文档 |
+| `.txt` | `docx` | 纯文本文件 |
+| `.md`, `.markdown`, `.mark` | `docx` | Markdown 文档 |
+| `.html` | `docx` | HTML 文档 |
+| `.xlsx` | `sheet`, `bitable` | Microsoft Excel 表格 |
+| `.xls` | `sheet` | Microsoft Excel 97-2003 表格 |
+| `.csv` | `sheet`, `bitable` | CSV 数据文件 |
+| `.base` | `bitable` | 多维表格快照文件 |
+
+> [!IMPORTANT]
+> 用户口头说的 “Base” / “多维表格” / “bitable”，在命令里统一对应 `--type bitable`。
+>
+> 文件扩展名与目标文档类型必须匹配，否则会返回验证错误：
+> - 文档类文件（.docx, .doc, .txt, .md, .html）**只能**导入为 `docx`
+> - `.xlsx` / `.csv` 文件**只能**导入为 `sheet` 或 `bitable`
+> - `.xls` 文件**只能**导入为 `sheet`
+> - `.base` 文件**只能**导入为 `bitable`
+> - 例如：`.csv` 文件不能导入为 `docx`，`.md` 文件不能导入为 `sheet`
+
+> [!IMPORTANT]
+> 如果在线文档是**以应用身份（bot）导入创建**的，如 `lark-cli drive +import --as bot`，当某次结果**已经返回最终在线文档目标**后，CLI 会**尝试为当前 CLI 用户自动授予该资源的 `full_access`（可管理权限）**。
+>
+> 这个自动授权有两种触发时机：
+> - `drive +import` 的内置轮询窗口内已经完成，直接在 `+import` 中进行自动授权
+> - `drive +import` 先返回 `ready=false` / `timed_out=true`，之后你再执行 `lark-cli drive +task_result --scenario import --ticket <TICKET>`，当该查询第一次拿到最终在线文档目标时会自动授权
+>
+> 只有在已经拿到最终在线文档目标的那次结果里，才会返回 `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 转给自己，必须单独确认。
+
+### 文件大小限制
+
+除扩展名与目标类型匹配外，`drive +import` 还会在本地上传前校验格式级大小限制：
+
+| 本地文件扩展名 | 导入目标 | 大小上限 |
+|--------------|---------|---------|
+| `.docx`, `.doc` | `docx` | 600MB |
+| `.txt` | `docx` | 20MB |
+| `.md`, `.mark`, `.markdown` | `docx` | 20MB |
+| `.html` | `docx` | 20MB |
+| `.xlsx` | `sheet`, `bitable` | 800MB |
+| `.csv` | `sheet` | 20MB |
+| `.csv` | `bitable` | 100MB |
+| `.xls` | `sheet` | 20MB |
+| `.base` | `bitable` | 20MB |
+
+- 如果文件超出对应上限，shortcut 会在真正上传前直接返回验证错误。
+- “超过 20MB 自动切换分片上传”只表示上传链路会切到 multipart，不代表所有格式都允许导入超过 20MB 的文件。
+
+- 若导入任务执行失败，会返回失败时的 `job_status` 及错误信息。
+- 若内置轮询超时但任务仍在处理中，shortcut 会成功返回，并带上：
+  - `ready=false`
+  - `timed_out=true`
+  - `next_command`：可直接复制执行的后续查询命令，例如 `lark-cli drive +task_result --scenario import --ticket <TICKET>`
+- 若使用 `--as bot` 且内置轮询窗口内已经拿到最终在线文档，输出还会额外带上 `permission_grant`，用于说明是否已自动为当前 CLI 用户授予可管理权限。
+- 若使用 `--as bot` 但当前只返回 `ready=false`，此时还不会返回 `permission_grant`；应继续执行返回值里的 `next_command`，等 `drive +task_result --scenario import` 拿到最终文档后再触发自动授权。
+- 如果文件扩展名不被支持，执行时将抛出验证错误。
+
+### 超时后的继续查询
+
+当 `+import` 的内置轮询窗口结束但任务尚未完成时，使用返回结果中的 `ticket` 继续查询：
+
+```bash
+lark-cli drive +task_result --scenario import --ticket <TICKET>
+```
+
+如果这里最终返回 `ready=true` 且使用的是 `--as bot`，结果还会额外带上 `permission_grant`，用于说明是否已自动为当前 CLI 用户授予可管理权限。
+
+> [!CAUTION]
+> `drive +import` 是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数