From 407d6e9dcb4441cfbc7e82e90919f91b78e389b3 Mon Sep 17 00:00:00 2001 From: mobaijie Date: Fri, 26 Jun 2026 19:46:22 +0800 Subject: [PATCH] feat(authorization): enhance lark-drive skill with permission auth, title rename guidance, and batch_query template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update description to clarify title rename via Drive files patch and permission check via permission.members auth - Add quick-decision table for high-frequency Drive tasks (title rename, permission check, export download, folder pull) - Clarify 修改标题 section: title is Drive metadata, not lark-doc body edit - Add batch_query template in API Resources section for bulk metadata fetch with URL - Refine 重要 note to allow skipping schema lookup when template is already provided --- skills/lark-drive/SKILL.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md index 393e13811..de11f2c4a 100644 --- a/skills/lark-drive/SKILL.md +++ b/skills/lark-drive/SKILL.md @@ -1,7 +1,7 @@ --- name: lark-drive version: 1.0.0 -description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。" +description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、导出与导出产物下载、创建文件夹、复制/移动/删除、查看元数据、评论、权限判断/治理、标题修改/重命名、版本和本地文件导入。改 docx/sheet/base/file/folder 的标题必须走 Drive files patch，不走 lark-doc 正文编辑；判断当前用户是否有 view/edit 权限走 Drive permission.members auth。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档正文编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。" metadata: requires: bins: ["lark-cli"] @@ -18,6 +18,15 @@ metadata: ## 快速决策 +- 高频 Drive 任务先走下表；只有参数结构不确定、错误提示要求，或进入复杂治理/长流程时才继续读 reference / schema。 + +| 用户意图 | 直接路径 | +|---|---| +| 修改标题 / 重命名 docx、sheet、bitable/base、file、folder、wiki 底层对象 | `lark-cli drive files patch --file-token --type --data '{"new_title":"<标题>"}' --as user`；这是标题元数据修改，不要切到 `lark-doc` 正文更新 | +| 判断当前用户是否有查看/编辑/分享等权限 | `lark-cli drive permission.members auth --params '{"token":"","type":"","action":"edit"}' --as user --format json`；先测用户问的 action，不要为简单判断读取权限治理 workflow | +| 用导出任务产物 `file_token` 下载 | 若 `file_token` 来自刚完成的 `drive +export` 结果，直接 `drive +export-download --file-token --output-dir --as user`；若 token 是示例/占位/已过期，先用源文档 token 执行 `drive +export --token --doc-type --file-extension --as user` 获取新鲜 `file_token` | +| 单向镜像 Drive 文件夹到本地 | 先确保本地目录存在，再执行 `lark-cli drive +pull --folder-token --local-dir --if-exists ` | + - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要“权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--created-by-me`，原始创建者语义）、"我负责/owner 的"（→ `--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。 @@ -39,7 +48,7 @@ metadata: - `drive +inspect` / `drive +upload` 遇到 `not found`、`permission denied`、`missing scope` 时，默认停止重试；只有 `rate limit` 或临时网络错误才适合有限重试。 ## 修改标题 -- 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型 +- 使用 `drive files patch` 命令，通过 `new_title` 字段修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型。标题是 Drive 元数据，不要用 `lark-doc docs +update` 改正文块。 ## 核心概念 @@ -155,7 +164,12 @@ lark-cli schema drive.. # 调用 API 前必须先查看参 lark-cli drive [flags] # 调用 API ``` -> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。 +> **高频原生命令速查：** +> - 批量获取 docx / file / sheet / bitable / folder 等元数据并带访问 URL，直接用： +> `lark-cli drive metas batch_query --as user --data '{"request_docs":[{"doc_token":"","doc_type":"docx"},{"doc_token":"","doc_type":"file"}],"with_url":true}'` +> `request_docs[].doc_type` 常用值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`、`slides`。只要是"批量获取元数据/标题/owner/URL"，不要读源码或 registry 反推结构；结构不确定时再运行 `lark-cli schema drive.metas.batch_query`。 +> +> **重要**：使用原生 API 时，如果本节没有给出现成模板，或参数结构、枚举、风险等级不确定，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。 > > **高频原生命令：** 读取 Drive 文件夹清单时使用 `drive files list`，必须按 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md) 的模板通过 `--params` 传 `folder_token` / `page_token`，并手动处理分页；不要把 `--page-all` 输出直接交给 JSON 解析脚本。