diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md index b4785ad8ab..f34e286f3a 100644 --- a/skills/lark-drive/SKILL.md +++ b/skills/lark-drive/SKILL.md @@ -12,6 +12,8 @@ metadata: **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md),其中包含认证、权限处理** +> **认证诊断边界:** 读取共享认证规则不等于需要预查认证状态。普通 Drive 任务直接执行目标命令;仅当用户明确要求检查登录态或身份,或目标命令返回明确的认证、scope 或权限错误时,才运行 `lark-cli auth status` 或 `lark-cli whoami`。`invalid token`、`not found`、`unsupported type` 等确定性资源错误应停止或纠正输入,不触发认证诊断。 + > **术语说明:** 飞书云空间也常被称为"云盘"、"云存储"、"网盘"或"我的空间",这些说法通常指的是同一个产品,是飞书官方的云端文件存储与管理中心。 > **导入分流规则:** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable,必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`;`lark-base` 只负责导入完成后的表内操作。 @@ -21,7 +23,7 @@ metadata: ## 快速决策 - 用户要把**已有 Wiki 节点移出知识库,放到 Drive 文件夹或“我的空间”根目录**:切到 `lark-wiki`,使用 `lark-cli wiki +move-to-drive`;不要把 Wiki token 直接交给 `drive +move`。这是会改变文档归属和权限继承的写操作,执行前确认源节点与目标位置。 -- 用户要**复制文档 / 创建副本 / 另存为副本**时,使用 `lark-cli drive files copy`。先用 `lark-cli schema drive.files.copy --format json` 确认参数;如果来源是 wiki URL/token,先用 `lark-cli drive +inspect` 获取底层 `token` 和 `type`,不要把 wiki token 直接当 `file_token`。`params.file_token` 传源文档 token,`data.folder_token` 传目标文件夹 token,`data.name` 传副本名称,`data.type` 传源文件类型(如 `docx` / `sheet` / `bitable` / `slides`)。示例:`lark-cli drive files copy --params '{"file_token":""}' --data '{"folder_token":"","name":"","type":"docx"}'`。如返回 `confirmation_required`,按 `lark-shared` 高风险审批协议向用户确认后,在原命令末尾追加 `--yes` 重试。 +- 用户要**复制文档 / 创建副本 / 另存为副本**时,读取 [`references/lark-drive-copy.md`](references/lark-drive-copy.md),按其中参数来源使用 `lark-cli drive files copy`;非 wiki 的普通复制不要先跑 schema、inspect 或全量 list。 - 用户要**识别飞书 / doubao 云空间 URL 的类型和 token**时,可以先按 URL 路径形态做轻量判断;当路径已明确指向 docx / sheet / bitable / slides / file / folder 等资源时,可直接提取对应 token/type。传入 wiki URL、需要识别标题或 canonical URL、URL/token 有歧义,或后续操作依赖底层真实资源时,再使用 `lark-cli drive +inspect --url ''` 进行识别;具体用法、失败处理和边界见 [`references/lark-drive-inspect.md`](references/lark-drive-inspect.md)。 - 高风险写操作(删除、公开权限修改、owner 转移、版本删除/回滚、批量移动/覆盖/同步)必须同时满足三个条件才执行:目标已解析为该操作可直接使用的执行对象,执行细节已明确到可直接调用命令(例如删除的 file-token/type、公开权限修改的共享范围、owner 转移的目标 owner、版本删除/回滚的 version id、移动/覆盖/同步的目标位置和冲突策略),且用户在本轮明确确认执行这些具体目标和执行细节。用户只说“删除没用的文件”“开放/共享给大家”“改成开放”“覆盖/移动这些”只表示目标状态;先只读发现并列出候选、权限档位或执行方案,停止等待用户确认。 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**,或要”权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”,必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md),再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。 @@ -183,7 +185,7 @@ lark-cli drive [flags] # 调用 API ### files - - `copy` — 复制文件;在线文档创建副本的首选能力,完整参数见上方“快速决策”,不要用 `drive +export` / `drive +import` 绕行复制 + - `copy` — 复制文件;在线文档创建副本的首选能力,参数来源见 [`references/lark-drive-copy.md`](references/lark-drive-copy.md),不要用 `drive +export` / `drive +import` 绕行复制 - `create_folder` — 新建文件夹 - `list` — 获取文件夹下的清单;使用前阅读 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md) - `patch` — 修改文件标题 diff --git a/skills/lark-drive/references/lark-drive-copy.md b/skills/lark-drive/references/lark-drive-copy.md new file mode 100644 index 0000000000..e484994bcc --- /dev/null +++ b/skills/lark-drive/references/lark-drive-copy.md @@ -0,0 +1,37 @@ +# Drive 文件复制 + +用于复制在线文档、创建副本、另存为副本,或把文件复制到用户指定的 Drive 文件夹。 + +## 直接路径 + +1. 定位源文件: + - 已给 docx/sheet/bitable/slides/file URL 时,直接从 URL 路径取源 `file_token`,并按路径确定 `type`。 + - 已给完整标题时,用 `lark-cli drive +search --query "<标题或合法短查询>" --as user --format json` 定位候选;`--query` 最长 30 个字符,过长标题先用稳定核心标题查询。只有候选提供完整、未截断的标题且能与用户给定标题精确匹配到唯一源文件时才继续;`title_highlighted` 可能被截断,不能单独证明完整标题相等。缺少完整标题或候选仍不唯一时,停止并请用户提供 URL/token;不要取首项、改用全量 `drive files list`,或使用搜索结果之外的隐藏 token。 + - `drive +search` 结果里的 `token` 是源 `file_token`;`result_meta.doc_types` 或同等类型字段给出源类型,复制时使用小写类型值,如 `DOCX` -> `docx`。 +2. 复制源文件: + - `--file-token` 传源文件 token。 + - `--data` JSON 至少包含 `folder_token`、`name`、`type`。 + - 用户指定目标文件夹 URL/token 时,`folder_token` 传该文件夹 token。 + - 用户没有指定目标文件夹时,传 `folder_token:""`,表示复制到当前调用用户的 Drive 根目录;不要为了猜父目录执行 `drive files list`。 +3. 使用复制结果: + - 响应中的 `file.token` 是新副本 token,后续读取或正文编辑必须使用这个 token。 + - 不要再按副本标题搜索来找目标文档。 + +## 命令形态 + +```bash +lark-cli drive files copy \ + --as user \ + --file-token \ + --data '{"folder_token":"","name":"","type":"docx"}' \ + --format json +``` + +把示例中的空 `folder_token` 换成用户明确指定的目标文件夹 token;不要换成源文件 token 或 wiki token。 + +## 边界 + +- 普通 docx/sheet/bitable/slides/file 复制不需要先跑 `schema drive.files.copy`、`drive +inspect`、`drive metas batch_query` 或 `drive files list`。 +- wiki URL/token 不是底层 file token;只有来源是 wiki 时才先用 `drive +inspect` 解包出底层 `token` 和 `type`。 +- `data.type` 必须与源文件实际类型一致;类型不确定时优先用搜索结果字段或 URL 路径,不要猜。 +- 如果返回 `confirmation_required`,按 `lark-shared` 高风险审批协议确认后,在同一 copy 命令追加 `--yes` 重试。