diff --git a/skill-template/domains/drive.md b/skill-template/domains/drive.md index 0c27761da..6b3f2f60e 100644 --- a/skill-template/domains/drive.md +++ b/skill-template/domains/drive.md @@ -4,7 +4,7 @@ ## 关键规则速览 - Wiki 链接里的 `/wiki/` 不是底层文件 token;优先用 `drive +inspect` 解包,完整规则见 [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md)。 -- 本地文件导入为在线文档统一走 `drive +import`:Excel / CSV / `.base` -> `--type bitable`,Office / Markdown / HTML / TXT -> `--type docx`,PPTX -> `--type slides`。 +- 本地文件导入为在线文档统一走 `drive +import`:目标是 Base / 多维表格时用 `--type bitable`(`.xlsx` / `.csv` / `.base`,`.xls` 不支持);目标是电子表格时用 `--type sheet`(`.xlsx` / `.xls` / `.csv`);Office / Markdown / HTML / TXT -> `--type docx`,PPTX -> `--type slides`。 - 原生 `.md` 文件内容读写、patch、diff 走 [`lark-markdown`](../lark-markdown/SKILL.md);把 Markdown 转成在线 docx 才走 `drive +import --type docx`。 - 评论默认只查未解决评论;review / 审阅场景优先局部评论。评论细节见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。 - 权限申请、安全标签、搜索等用户个人资源场景优先 `--as user`;bot 只能处理自己可见或已授权的资源。 @@ -12,7 +12,7 @@ ## 快速决策 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间对象**,优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"(`--mine`,owner 语义)、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag。 -- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable,第一步必须使用 `lark-cli drive +import --type bitable`。 +- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable,第一步必须使用 `lark-cli drive +import --type bitable`;`.xls` 不能直接导入为 bitable,需先转 `.xlsx` 或改导入为 sheet。 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档,使用 `lark-cli drive +import --type docx`。 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格,使用 `lark-cli drive +import --type sheet`。 - 用户要把本地 `.pptx` 导入成飞书幻灯片,使用 `lark-cli drive +import --type slides`;当前 PPTX 导入上限是 500MB。 @@ -39,6 +39,14 @@ - `drive +inspect` 是跨类型 URL 检视的首选入口;当它输出 `type` 和 `token` 后,后续命令使用该 canonical token。 - 原生 API 调用前先运行 `lark-cli schema drive..` 查看 `--params` / `--data` 结构;不要猜字段。 +## 原生 API 快速索引 + +- 评论订阅事件:`drive user.subscription`、`drive user.subscription_status`、`drive user.remove_subscription`。 +- 公开权限设置:`drive permission.public get|patch`;错误码和处理建议见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。 +- 协作者权限:`drive permission.members create|auth|transfer_owner`;授权当前应用访问文档见权限 guide,转移 owner 必须单独确认。 +- 元数据、统计、访问记录:`drive metas batch_query`、`drive file.statistics get`、`drive file.view_records list`。 +- 评论列表、解决状态、回复:`drive file.comments list|batch_query|patch`、`drive file.comment.replys *`;统计口径见评论 guide。 + ## 评论与权限 - 添加评论优先使用 [`drive +add-comment`](references/lark-drive-add-comment.md);查询、统计、回复限制和 reaction 规则见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) 与 [`lark-drive-reactions.md`](references/lark-drive-reactions.md)。 diff --git a/skill-template/skill-template.md b/skill-template/skill-template.md index 04eda8dd7..41689c755 100644 --- a/skill-template/skill-template.md +++ b/skill-template/skill-template.md @@ -31,6 +31,7 @@ lark-cli {{service}} [flags] # 调用 API ``` > **重要**:使用原生 API 时,必须先运行 `schema` 查看 `--data` / `--params` 参数结构,不要猜测字段格式。 +> 所需 scope 以 `lark-cli schema {{service}}..` 输出为准;skill 主文不展开完整权限表。 {{resource_sections}} {{/actions}} diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md index dc36c5d08..3957ce50d 100644 --- a/skills/lark-drive/SKILL.md +++ b/skills/lark-drive/SKILL.md @@ -17,7 +17,7 @@ metadata: ## 关键规则速览 - Wiki 链接里的 `/wiki/` 不是底层文件 token;优先用 `drive +inspect` 解包,完整规则见 [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md)。 -- 本地文件导入为在线文档统一走 `drive +import`:Excel / CSV / `.base` -> `--type bitable`,Office / Markdown / HTML / TXT -> `--type docx`,PPTX -> `--type slides`。 +- 本地文件导入为在线文档统一走 `drive +import`:目标是 Base / 多维表格时用 `--type bitable`(`.xlsx` / `.csv` / `.base`,`.xls` 不支持);目标是电子表格时用 `--type sheet`(`.xlsx` / `.xls` / `.csv`);Office / Markdown / HTML / TXT -> `--type docx`,PPTX -> `--type slides`。 - 原生 `.md` 文件内容读写、patch、diff 走 [`lark-markdown`](../lark-markdown/SKILL.md);把 Markdown 转成在线 docx 才走 `drive +import --type docx`。 - 评论默认只查未解决评论;review / 审阅场景优先局部评论。评论细节见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。 - 权限申请、安全标签、搜索等用户个人资源场景优先 `--as user`;bot 只能处理自己可见或已授权的资源。 @@ -25,7 +25,7 @@ metadata: ## 快速决策 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间对象**,优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"(`--mine`,owner 语义)、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag。 -- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable,第一步必须使用 `lark-cli drive +import --type bitable`。 +- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable,第一步必须使用 `lark-cli drive +import --type bitable`;`.xls` 不能直接导入为 bitable,需先转 `.xlsx` 或改导入为 sheet。 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档,使用 `lark-cli drive +import --type docx`。 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格,使用 `lark-cli drive +import --type sheet`。 - 用户要把本地 `.pptx` 导入成飞书幻灯片,使用 `lark-cli drive +import --type slides`;当前 PPTX 导入上限是 500MB。 @@ -83,6 +83,14 @@ Shortcut 是对常用操作的高级封装(`lark-cli drive + [flags]`) - `drive +inspect` 是跨类型 URL 检视的首选入口;当它输出 `type` 和 `token` 后,后续命令使用该 canonical token。 - 原生 API 调用前先运行 `lark-cli schema drive..` 查看 `--params` / `--data` 结构;不要猜字段。 +## 原生 API 快速索引 + +- 评论订阅事件:`drive user.subscription`、`drive user.subscription_status`、`drive user.remove_subscription`。 +- 公开权限设置:`drive permission.public get|patch`;错误码和处理建议见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。 +- 协作者权限:`drive permission.members create|auth|transfer_owner`;授权当前应用访问文档见权限 guide,转移 owner 必须单独确认。 +- 元数据、统计、访问记录:`drive metas batch_query`、`drive file.statistics get`、`drive file.view_records list`。 +- 评论列表、解决状态、回复:`drive file.comments list|batch_query|patch`、`drive file.comment.replys *`;统计口径见评论 guide。 + ## 评论与权限 - 添加评论优先使用 [`drive +add-comment`](references/lark-drive-add-comment.md);查询、统计、回复限制和 reaction 规则见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) 与 [`lark-drive-reactions.md`](references/lark-drive-reactions.md)。 diff --git a/skills/lark-drive/references/lark-drive-comments-guide.md b/skills/lark-drive/references/lark-drive-comments-guide.md index bdeda92e9..eafe16fd3 100644 --- a/skills/lark-drive/references/lark-drive-comments-guide.md +++ b/skills/lark-drive/references/lark-drive-comments-guide.md @@ -10,7 +10,7 @@ - 如果 Wiki URL 解包后不是 `doc` / `docx` / `file` / `sheet` / `slides`,不要使用 `+add-comment`。 - Drive 普通文件评论仅支持平台允许的文件类型,常见后缀包括 `.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`;普通文件只支持全文评论。 - `--content` 需要传 `reply_elements` JSON 数组字符串,例如 `--content '[{"type":"text","text":"正文"}]'`。 -- 如果直接调用原生评论 V2 API,先执行 `lark-cli schema drive.file.comments.create_v2`;全文评论省略 `anchor`,局部评论传 `anchor.block_id`。 +- 如果直接调用原生评论 V2 API,先执行 `lark-cli schema drive.file.comments.create_v2` 并优先参考 [`lark-drive-add-comment.md`](lark-drive-add-comment.md)。全文评论省略 `anchor`;doc/docx 局部评论传 `anchor.block_id`;sheet 评论使用 `anchor.block_id` + `sheet_col` + `sheet_row`;slides 评论使用 `anchor.block_id` + `slide_block_type`。 ## Review 场景