diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md index 0ab6a4637..9ade4176c 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: "飞书云空间(云盘/云存储):管理云空间(云盘/云存储)中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题(docx、sheet、bitable、file、folder、wiki);也负责把本地 Word/Markdown/Excel/CSV/PPTX 以及 Base 快照(.base)导入为飞书在线云文档(docx、sheet、bitable、slides)。当用户需要上传或下载文件、整理云空间(云盘/云存储)目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件,或要把本地文件导入成新版文档、电子表格、多维表格/Base/幻灯片 时使用。\"云空间\"、\"云盘\"和\"云存储\"是同一概念,用户说\"云盘\"、\"云存储\"、\"网盘\"、\"我的空间\"时均路由到本 skill。" +description: "飞书云空间(云盘/云存储):管理云空间(云盘/云存储)中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题(docx、sheet、bitable、file、folder、wiki);也负责把本地 Word/Markdown/Excel/CSV/PPTX 以及 Base 快照(.base)导入为飞书在线云文档(docx、sheet、bitable、slides)。当用户需要上传或下载文件、整理云空间(云盘/云存储)目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件,或要把本地文件导入成新版文档、电子表格、多维表格/Base/幻灯片时使用。涉及云空间/知识库/文档库的知识资产盘点、整理、治理,也从本 skill 进入。\"云空间\"、\"云盘\"和\"云存储\"是同一概念,用户说\"云盘\"、\"云存储\"、\"网盘\"、\"我的空间\"时均路由到本 skill。" metadata: requires: bins: ["lark-cli"] @@ -18,7 +18,8 @@ metadata: ## 快速决策 -- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间(云盘/云存储)对象**,优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"(→ `--mine`,实为 owner 语义)、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag,避免手写嵌套 JSON。 +- 用户要**搜文档 / 知识库 / 电子表格 / 多维表格 / 云空间(云盘/云存储)对象**,优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"(→ `--mine`,实为 owner 语义)、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag,避免手写嵌套 JSON。 +- 用户要**盘点/整理/治理云空间、知识库或文档库资产**,读取 [`lark-drive-knowledge-overview.md`](references/lark-drive-knowledge-overview.md) 做范围和 recipe 路由。 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable,第一步必须使用 `lark-cli drive +import --type bitable`。 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档,使用 `lark-cli drive +import --type docx`。 - 用户要把本地 `.pptx` 导入成飞书幻灯片,使用 `lark-cli drive +import --type slides`;当前 PPTX 导入上限是 500MB。 @@ -27,9 +28,19 @@ metadata: - 用户要查看、下载、回滚或删除文件的**历史版本**,使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`;这组命令同时支持 `--as user` 和 `--as bot`,自动化场景优先 `--as bot`。 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格,使用 `lark-cli drive +import --type sheet`。 - 用户要在云空间(云盘/云存储)里新建文件夹,优先使用 `lark-cli drive +create-folder`。 -- 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时,仍然使用 `lark-cli drive +upload --wiki-token `;不要误切到 `wiki` 域命令。 +- 用户要把本地文件上传到知识库 / 文档库里的某个节点下时,仍然使用 `lark-cli drive +upload --wiki-token `;不要误切到 `wiki` 域命令。 - `lark-base` 只负责导入完成后的 Base 内部操作(表、字段、记录、视图),不要在“本地文件 -> Base”这一步提前切到 `lark-base`。 +## 知识资产整理 Workflow + +触发上面的知识资产场景后,按以下顺序加载 reference;不要把所有跨域细节塞进当前上下文: + +1. 先阅读 [`lark-drive-knowledge-overview.md`](references/lark-drive-knowledge-overview.md) 判断目标范围和 recipe。 +2. 需要标准中间产物时阅读 [`lark-drive-knowledge-artifacts.md`](references/lark-drive-knowledge-artifacts.md)。 +3. 涉及任何写操作或权限治理时阅读 [`lark-drive-knowledge-safety.md`](references/lark-drive-knowledge-safety.md)。 +4. 涉及知识库节点树、知识库成员、文档库 / my_library 时,切到 [`lark-wiki`](../lark-wiki/SKILL.md) 读取具体命令规则。 +5. 涉及文档正文读取或报告创建时,切到 [`lark-doc`](../lark-doc/SKILL.md);涉及 Sheets 台账时,切到 [`lark-sheets`](../lark-sheets/SKILL.md)。 + ## 修改标题 - 使用 `drive files patch` 命令,通过new_title字段可以修改标题,支持 docx、sheet、bitable、file、wiki、folder 类型 diff --git a/skills/lark-drive/references/lark-drive-knowledge-artifacts.md b/skills/lark-drive/references/lark-drive-knowledge-artifacts.md new file mode 100644 index 000000000..1d52c9f83 --- /dev/null +++ b/skills/lark-drive/references/lark-drive-knowledge-artifacts.md @@ -0,0 +1,176 @@ +# 知识资产整理 Artifact 协议 + +> 用途:让 inventory、organize、permission-audit 等 workflow 可串联、可恢复、可评测。字段保持最小稳定;缺失信息用空值、`warnings` 或 `unsupported_checks` 表达,不要编造。 + +## 目录约定 + +```text +./lark-drive-knowledge// + scope.json + inventory.json + organize-plan.json + permission-audit.json + execution-log.json + report.md +``` + +`run-id` 建议使用 `YYYYMMDD-HHMMSS-`,例如 `20260526-143000-wiki-space`. + +## scope.json + +记录用户目标和本次实际处理范围。 + +```json +{ + "run_id": "", + "requested_by_user": "", + "scope_type": "drive_folder|wiki_space|wiki_node|my_library|mixed", + "root": { + "url": "", + "space_id": "", + "folder_token": "", + "node_token": "" + }, + "limits": { + "max_depth": -1, + "page_limit": 0, + "content_read": "none|outline|targeted" + }, + "generated_at": "" +} +``` + +## inventory.json + +记录事实清单。所有后续分析优先消费它。 + +```json +{ + "run_id": "", + "summary": { + "total": 0, + "by_source": {}, + "by_type": {}, + "warnings_count": 0 + }, + "items": [ + { + "source": "drive|wiki|my_library", + "title": "", + "path": "", + "url": "", + "token": "", + "type": "folder|docx|doc|sheet|bitable|file|slides|mindnote|wiki|shortcut", + "space_id": "", + "node_token": "", + "obj_token": "", + "obj_type": "", + "folder_token": "", + "parent_token": "", + "depth": 0, + "has_child": false, + "owner": "", + "created_time": "", + "modified_time": "", + "evidence": [] + } + ], + "warnings": [], + "generated_at": "" +} +``` + +## organize-plan.json + +只表达计划,不代表已经执行。 + +```json +{ + "run_id": "", + "mode": "plan", + "summary": { + "actions_count": 0, + "requires_confirmation_count": 0 + }, + "actions": [ + { + "id": "act-001", + "action": "create_drive_folder|create_wiki_node|move_drive|move_wiki_node|create_drive_shortcut|create_wiki_shortcut", + "source": {}, + "target": {}, + "reason": "", + "evidence": [], + "risk": "read|write|high-risk-write", + "requires_confirmation": true, + "dry_run_command": "", + "execute_command": "" + } + ], + "blocked": [], + "warnings": [], + "generated_at": "" +} +``` + +第一版不生成 delete、overwrite、permission patch、owner transfer 动作。 + +## permission-audit.json + +记录权限审计事实、推断和能力边界。 + +```json +{ + "run_id": "", + "summary": { + "audited_items": 0, + "risk_findings": 0, + "unsupported_checks": [] + }, + "items": [ + { + "title": "", + "path": "", + "url": "", + "token": "", + "type": "", + "wiki_space_members": [], + "public_permission": {}, + "risk_findings": [ + { + "type": "", + "severity": "low|medium|high", + "fact": "", + "inference": "", + "suggestion": "", + "evidence": [], + "requires_confirmation": true + } + ], + "unsupported_checks": [] + } + ], + "warnings": [], + "generated_at": "" +} +``` + +## execution-log.json + +仅在用户明确确认执行 organize plan 后生成。 + +```json +{ + "run_id": "", + "plan_file": "", + "results": [ + { + "action_id": "act-001", + "status": "success|failed|skipped", + "command": "", + "result": {}, + "error": "" + } + ], + "generated_at": "" +} +``` diff --git a/skills/lark-drive/references/lark-drive-knowledge-inventory.md b/skills/lark-drive/references/lark-drive-knowledge-inventory.md new file mode 100644 index 000000000..671fb8c6c --- /dev/null +++ b/skills/lark-drive/references/lark-drive-knowledge-inventory.md @@ -0,0 +1,115 @@ +# 知识资产盘点 Workflow + +> 前置条件:先读 [`lark-drive-knowledge-overview.md`](lark-drive-knowledge-overview.md) 和 [`lark-drive-knowledge-artifacts.md`](lark-drive-knowledge-artifacts.md)。涉及 Wiki 或文档库时再读 [`../../lark-wiki/SKILL.md`](../../lark-wiki/SKILL.md)。 + +## 目标 + +对云空间文件夹、知识库、知识库子树或文档库做结构化盘点,生成 `inventory.json`,作为整理、权限审计和报告的事实底座。 + +## Step 1: 归一化范围 + +- 云空间文件夹 URL:提取 `folder_token`,或用 `drive +inspect` 确认类型。 +- 知识库 URL:用 `wiki +node-get` 或 `drive +inspect` 获取 `space_id`、`node_token`、`obj_type`、`obj_token`。 +- `my_library` / 文档库:固定走 `wiki +node-list --space-id my_library --as user`。 + +记录到 `scope.json`。 + +## Step 2: 盘点云空间文件夹 + +先查看 schema: + +```bash +lark-cli schema drive.files.list --format json +``` + +读取直接子项: + +```bash +lark-cli drive files list \ + --params '{"folder_token":"","page_size":200}' \ + --page-all --page-limit 0 --format json --as user +``` + +对返回的 `type=folder` 子项递归调用同一命令。记录字段: + +- `name` -> `title` +- `token` +- `type` +- `url` +- `parent_token` +- `owner_id` +- `created_time` +- `modified_time` + +如需按关键词或时间补充范围,可用 `drive +search`,但目录树以 `drive files list` 为准。 + +## Step 3: 盘点知识库或文档库 + +读取根层: + +```bash +lark-cli wiki +node-list \ + --space-id "" \ + --page-all --page-limit 0 --format json --as user +``` + +对 `has_child=true` 的节点递归: + +```bash +lark-cli wiki +node-list \ + --space-id "" \ + --parent-node-token "" \ + --page-all --page-limit 0 --format json --as user +``` + +必要时补节点详情: + +```bash +lark-cli wiki +node-get --node-token "" --format json --as user +``` + +记录字段: + +- `title` +- `node_token` +- `obj_token` +- `obj_type` +- `node_type` +- `parent_node_token` +- `has_child` +- `space_id` +- `owner`(如果详情返回) + +## Step 4: 可选读取内容结构 + +只有用户需要“按内容归类”“识别主题”“生成导航页”时才读取正文结构。优先读 outline,不全量读正文: + +```bash +lark-cli docs +fetch \ + --api-version v2 \ + --doc "" \ + --scope outline \ + --max-depth 3 \ + --doc-format markdown \ + --format json --as user +``` + +失败时保留结构盘点结果,并在 `warnings` 中标记 `content_outline_failed`。 + +## Step 5: 输出 inventory.json + +把所有条目写入 `./lark-drive-knowledge//inventory.json`。聊天回复只输出摘要: + +- 总数 +- 按 source/type 统计 +- 空标题数量 +- 重复标题候选数量 +- 未读取或失败的节点数量 +- artifact 路径 + +## 停止条件 + +- 没有权限读取根节点或根文件夹:停止并给出授权建议。 +- 分页失败或 cursor 不前进:保留已读结果,写入 `warnings`。 +- 结果规模过大:停止深挖正文,只输出结构清单并提示用户缩小范围。 +- 知识库和云空间混合范围不清楚:先让用户确认是否都处理。 diff --git a/skills/lark-drive/references/lark-drive-knowledge-organize.md b/skills/lark-drive/references/lark-drive-knowledge-organize.md new file mode 100644 index 000000000..a347719d1 --- /dev/null +++ b/skills/lark-drive/references/lark-drive-knowledge-organize.md @@ -0,0 +1,107 @@ +# 散乱知识整理 Workflow + +> 前置条件:先有 `inventory.json`,并阅读 [`lark-drive-knowledge-safety.md`](lark-drive-knowledge-safety.md)。第一版默认只生成整理计划,不直接执行。 + +## 目标 + +帮助用户把云空间文件夹、知识库或文档库下的散乱文档组织成更清晰的目录结构。输出 `organize-plan.json`。 + +## 输入 + +- 必需:`inventory.json` +- 可选:用户给出的目标分类规则,例如“按项目”“按业务线”“按系统”“按年份”“按文档类型” +- 可选:outline 读取结果,用于按内容主题分类 + +## 分析规则 + +优先基于事实字段: + +- 路径层级过深或过平。 +- 空标题、重复标题、相似标题。 +- 同一主题散落在多个目录。 +- 云空间文件夹中在线文档和普通文件混放。 +- 知识库 shortcut 复用或源文档散落。 +- 文档标题包含“旧版”“废弃”“草稿”“临时”等治理信号。 + +模型推断必须写入 `reason` 和 `evidence`,不能把推断当事实。 + +## 生成计划 + +允许生成的 action: + +| action | 说明 | +|-|-| +| `create_drive_folder` | 在 Drive 中创建目标文件夹 | +| `create_wiki_node` | 在知识库或文档库 / `my_library` 中创建目录节点 | +| `move_drive` | 移动 Drive 文件/文件夹 | +| `move_wiki_node` | 移动知识库节点 | +| `create_drive_shortcut` | 在 Drive 目标文件夹创建快捷方式 | +| `create_wiki_shortcut` | 在知识库中创建 shortcut 节点 | + +禁止生成的 action: + +- delete +- overwrite +- permission patch +- member remove +- owner transfer + +每个 action 必须包含: + +- source +- target +- reason +- evidence +- `requires_confirmation=true` +- dry-run command +- execute command + +## 命令模板 + +Drive 创建文件夹: + +```bash +lark-cli drive +create-folder --name "" --folder-token "" --dry-run --as user +``` + +Drive 移动: + +```bash +lark-cli drive +move --file-token "" --type "" --folder-token "" --dry-run --as user +``` + +Drive 快捷方式: + +```bash +lark-cli drive +create-shortcut --file-token "" --type "" --folder-token "" --dry-run --as user +``` + +Wiki 创建节点: + +```bash +lark-cli wiki +node-create --space-id "" --parent-node-token "" --title "" --obj-type docx --dry-run --as user +``` + +Wiki 移动节点: + +```bash +lark-cli wiki +move --node-token "<node_token>" --target-parent-token "<target_parent_node_token>" --dry-run --as user +``` + +Wiki shortcut: + +```bash +lark-cli wiki +node-create --space-id "<space_id>" --parent-node-token "<parent_node_token>" --node-type shortcut --origin-node-token "<source_node_token>" --title "<title>" --dry-run --as user +``` + +## 执行与验收 + +只有用户明确确认某个 `organize-plan.json` 后,才逐条执行。执行后写 `execution-log.json`,并重新跑 inventory 验证目标目录结构。 + +聊天回复要给出: + +- 计划文件路径 +- action 数量 +- 需要确认的高影响动作 +- 被阻塞的动作和原因 +- 下一步确认方式 diff --git a/skills/lark-drive/references/lark-drive-knowledge-overview.md b/skills/lark-drive/references/lark-drive-knowledge-overview.md new file mode 100644 index 000000000..6d7632a8a --- /dev/null +++ b/skills/lark-drive/references/lark-drive-knowledge-overview.md @@ -0,0 +1,59 @@ +# 知识资产整理 Workflow 总览 + +> **前置条件:** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +## 适用场景 + +- 盘点某个云空间文件夹、知识库、知识库节点或文档库下的文档和目录。 +- 整理散乱文档:归类、生成目录结构、移动计划、快捷方式计划、导航页建议。 +- 治理知识资产:重复、空标题、孤立、未归档、命名混乱、内容缺失或过期。 +- 审计权限风险:Wiki 空间成员、文档公开链接、组织外访问、分享/复制/下载设置。 + +## 目标范围模型 + +| 用户目标 | 视作 | 主入口 | +|-|-|-| +| 云空间文件夹 | Drive folder tree | `drive files list` / `drive +search` | +| 知识库 / 知识库节点 | Wiki space/node tree | `wiki +node-list` / `wiki +node-get` | +| 文档库 / my_library | Wiki personal library | `wiki +node-list --space-id my_library --as user` | +| 文档正文或标题结构 | Docs content | `docs +fetch --api-version v2` | +| 报告或台账 | Docs / Sheets | `docs +create` / `sheets +create` | + +不要把“文档库”当成 Drive 根目录;它应走 Wiki personal library。 + +## Recipe 路由 + +| 用户意图 | 读取文件 | 产物 | +|-|-|-| +| 盘点、梳理、导出清单、看目录结构 | [`lark-drive-knowledge-inventory.md`](lark-drive-knowledge-inventory.md) | `inventory.json` | +| 整理、归类、组织目录、生成移动计划 | [`lark-drive-knowledge-organize.md`](lark-drive-knowledge-organize.md) | `organize-plan.json` | +| 权限风险、公开链接、组织外访问、成员过多 | [`lark-drive-knowledge-permission-audit.md`](lark-drive-knowledge-permission-audit.md) | `permission-audit.json` | + +复合意图按链路执行: + +```text +盘点并整理 -> inventory -> organize +盘点并审计权限 -> inventory -> permission-audit +整理并输出报告 -> inventory -> organize -> report artifact +``` + +## 执行原则 + +- 大范围结果默认写入本地 artifact,不把完整清单塞进聊天。 +- 每次 run 使用独立目录:`./lark-drive-knowledge/<run-id>/`。 +- 工作流之间通过 artifact 串联,优先复用已有 `inventory.json`,不要无故重复爬取。 +- 所有判断必须区分事实、推断、建议;没有证据的内容写入 `warnings` 或 `unsupported_checks`。 +- 原生 API 调用前必须先运行 `lark-cli schema <service>.<resource>.<method>` 校验参数结构。 +- 写操作和权限治理必须遵守 [`lark-drive-knowledge-safety.md`](lark-drive-knowledge-safety.md)。 + +## 当前能力边界 + +| 能力 | 状态 | 说明 | +|-|-|-| +| 知识库节点盘点 | 支持 | 递归 `wiki +node-list` | +| 云空间文件夹盘点 | 支持 | 递归 `drive files list` | +| 文档标题结构读取 | 支持 | `docs +fetch --scope outline` | +| Wiki 空间成员审计 | 支持 | `wiki +member-list` | +| 文档公开权限审计 | 支持 | `drive permission.public get` | +| 单文档协作者全量枚举 | 暂不支持 | 当前 Drive permission members 只有 `auth/create/transfer_owner` | +| 自动删除、覆盖、降权、改权限 | 第一版不执行 | 只输出计划和建议 | diff --git a/skills/lark-drive/references/lark-drive-knowledge-permission-audit.md b/skills/lark-drive/references/lark-drive-knowledge-permission-audit.md new file mode 100644 index 000000000..09ab87703 --- /dev/null +++ b/skills/lark-drive/references/lark-drive-knowledge-permission-audit.md @@ -0,0 +1,109 @@ +# 权限风险审计 Workflow + +> 前置条件:先读 [`lark-drive-knowledge-overview.md`](lark-drive-knowledge-overview.md)、[`lark-drive-knowledge-artifacts.md`](lark-drive-knowledge-artifacts.md) 和 [`lark-drive-knowledge-safety.md`](lark-drive-knowledge-safety.md)。第一版只审计和建议,不自动改权限。 + +## 目标 + +审计 云空间 / 知识库 / 文档库范围内的权限风险,重点覆盖: + +- Wiki 空间成员和角色。 +- 文档公开权限、外部访问、链接分享、复制/下载/打印限制。 +- 当前能力无法验证的权限项。 + +## 当前能力边界 + +| 检查项 | 状态 | 命令 | +|-|-|-| +| Wiki 空间成员 | 支持 | `wiki +member-list` | +| 文档公开权限 | 支持 | `drive permission.public get`,仅限 schema 支持的文档类型 | +| Drive 文件夹公开权限 | 暂不支持 | `drive.permission.public.get` 不支持 `type=folder` | +| 当前用户/应用是否具备某权限 | 支持 | `drive permission.members auth` | +| 单文档显式协作者全量枚举 | 暂不支持 | 当前无 `drive.permission.members.list` | +| 自动关闭公开权限或降权 | 第一版不执行 | 只输出建议 | + +## Step 1: 输入范围 + +优先消费 `inventory.json`。如果用户只给一个 URL,先按 [`lark-drive-knowledge-inventory.md`](lark-drive-knowledge-inventory.md) 做最小盘点。 + +## Step 2: Wiki 空间成员审计 + +涉及知识库空间或文档库 / `my_library` 时: + +```bash +lark-cli wiki +member-list \ + --space-id "<space_id_or_my_library>" \ + --page-all --page-limit 0 --format json --as user +``` + +审计信号: + +- admin 数量异常多。 +- 成员包含部门、群或开放范围较大的 member_type。 +- 文档库成员结果缺失或不适用时写入 `warnings`,不要推断。 + +## Step 3: 文档公开权限审计 + +先查看 schema: + +```bash +lark-cli schema drive.permission.public.get --format json +``` + +只对 inventory 中 `type` 属于以下集合的条目查询: + +```text +doc, docx, sheet, bitable, file, wiki, mindnote, minutes, slides +``` + +`type=folder` 的 Drive 文件夹不要调用 `drive.permission.public get`。将该 item 写入 `unsupported_checks` 或 `warnings`,例如 `drive_folder_public_permission_unsupported`,并继续审计其他条目。 + +```bash +lark-cli drive permission.public get \ + --params '{"token":"<token>","type":"<type>"}' \ + --format json --as user +``` + +Token/type 选择: + +- 云空间文件:用 Drive `token` 和 `type=file`。 +- 云空间文件夹:不执行 `permission.public.get`,记录为未覆盖检查。 +- 知识库节点权限:优先用 `node_token` 和 `type=wiki`。 +- 底层文档权限:用 `obj_token` 和 `obj_type`。 + +如果某类 token 查询失败,不要中断全局审计;写入该 item 的 `warnings`。如果是 `type=folder`,不要把它当作 API 失败,而是写入 `unsupported_checks`。 + +## 风险规则 + +| 字段 | 高风险 | 中风险 | +|-|-|-| +| `link_share_entity` | `anyone_editable`, `anyone_readable` | `tenant_editable` | +| `external_access` | `true` 且链接或分享范围较宽 | `true` | +| `share_entity` | `anyone` | `same_tenant` | +| `security_entity` | `anyone_can_view` | `anyone_can_edit` | +| Wiki member role | admin 过多 | 部门/群成员需确认 | + +每条风险都必须写清楚: + +- `fact`:API 返回字段。 +- `inference`:为什么可能有风险。 +- `suggestion`:建议 owner 或管理员确认的动作。 +- `evidence`:token、URL、path、字段名和值。 +- `requires_confirmation=true`。 + +## 输出 + +写入 `permission-audit.json`,聊天回复只给摘要: + +- 审计对象数量。 +- 高/中/低风险数量。 +- 公开权限风险 Top N。 +- Wiki 成员风险摘要。 +- 未覆盖检查:必须包含 `explicit_collaborator_list`,说明当前 CLI 无法枚举单文档显式协作者列表。 +- 如果 inventory 中包含 `type=folder`,未覆盖检查必须包含 `drive_folder_public_permission`,说明 `drive.permission.public.get` 不支持 Drive 文件夹。 + +## 禁止事项 + +- 不自动调用 `permission.public.patch`。 +- 不自动调用 `permission.members.create`、`transfer_owner` 或任何成员删除/降权接口。 +- 不把“无法枚举协作者”说成“没有协作者风险”。 +- 不把模型推断写成事实。 diff --git a/skills/lark-drive/references/lark-drive-knowledge-safety.md b/skills/lark-drive/references/lark-drive-knowledge-safety.md new file mode 100644 index 000000000..0e732b964 --- /dev/null +++ b/skills/lark-drive/references/lark-drive-knowledge-safety.md @@ -0,0 +1,50 @@ +# 知识资产整理安全策略 + +> 默认安全级别:只读或计划优先。任何会改变用户文档、目录或权限的操作,都必须先生成计划并让用户明确确认。 + +## 动作分级 + +| 分级 | 示例 | 策略 | +|-|-|-| +| Read-only | 列目录、查元数据、读 outline、读公开权限 | 可直接执行 | +| Plan-only | 生成整理计划、权限治理建议、报告草稿 | 可直接执行 | +| Confirmed write | 创建文件夹、创建知识库节点、移动文档、创建快捷方式、新建报告 | 必须先展示计划,用户确认后执行 | +| High-risk write | 删除、覆盖、改权限、转移 owner、移除成员、公开权限 patch | 第一版 workflow 不执行 | +| Unsupported | 单文档协作者全量枚举 | 明确说明当前能力无法验证 | + +## 强制规则 + +- 盘点、整理建议、权限审计默认不修改任何资源。 +- `organize-plan.json` 不是执行授权;只有用户明确说执行某个 plan,才进入执行阶段。 +- 执行前必须展示 action 列表,包括 source、target、reason、risk、dry-run command。 +- 执行写操作前先跑对应 `--dry-run`;dry-run 通过不等于用户已确认真实执行。 +- 不自动执行 delete、overwrite、permission patch、member remove、owner transfer。 +- 权限治理第一版只输出风险和建议,不自动收敛权限。 +- 对无法确认的风险,写成 `unsupported_checks` 或 `requires_confirmation=true`,不要当作事实。 + +## 需要停下来问用户的情况 + +- 目标范围不明确,例如同时给出多个 folder/wiki URL 但未说明是否都处理。 +- 计划包含跨空间移动、跨 Drive/Wiki 移动或大量移动。 +- 目标目录已有同名节点/文件夹,无法判断是否复用。 +- 用户要求“直接整理好”,但计划还没有展示和确认。 +- 用户要求“治理权限”,但动作涉及改公开权限、移除成员、降权或转移 owner。 +- 节点数量或文件数量超出上下文可处理范围,需要改为文件产物或缩小范围。 + +## 权限风险表述 + +表述必须区分: + +- 事实:API 返回的字段,例如 `external_access=true`。 +- 推断:基于规则得到的风险,例如“可能允许组织外传播”。 +- 建议:下一步动作,例如“建议 owner 人工确认是否关闭外部访问”。 +- 未覆盖:当前 API/CLI 不能验证的项,例如“无法枚举单文档显式协作者列表”。 + +示例: + +```text +事实:link_share_entity=anyone_editable。 +推断:互联网获得链接的人可能可编辑,属于高风险公开权限。 +建议:请 owner 确认是否需要关闭链接分享或收敛为 tenant_readable。 +未覆盖:未检查显式协作者列表,因为当前 CLI 没有 permission.members.list。 +``` diff --git a/skills/lark-wiki/SKILL.md b/skills/lark-wiki/SKILL.md index b089b47c9..c88a46542 100644 --- a/skills/lark-wiki/SKILL.md +++ b/skills/lark-wiki/SKILL.md @@ -1,7 +1,7 @@ --- name: lark-wiki version: 1.0.0 -description: "飞书知识库:管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。" +description: "飞书知识库:管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。知识库 / 文档库的文档和目录盘点、整理、治理 workflow 统一从 lark-drive 进入;本 skill 只处理知识空间、成员和节点操作。" metadata: requires: bins: ["lark-cli"] @@ -24,6 +24,7 @@ metadata: ## 快速决策 +- 用户要**盘点、整理、治理知识库 / 文档库中的文档和目录**,不要在本 skill 里展开 workflow;切到 [`lark-drive`](../lark-drive/SKILL.md),按其 `lark-drive-knowledge-overview.md` 入口编排。 - 用户给的是知识库 URL(`.../wiki/<token>`),且后续要查成员/加成员/删成员:先调用 `lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'` 获取 `space_id`,后续成员接口统一使用 `space_id`。 - 用户要**删除**知识空间(`wiki +delete-space`)但只给了名称或 URL:**不能**把名称 / URL 原样传给 `--space-id`,必须先解析出真实 `space_id`。解析方式: - URL(`.../wiki/<token>`):`lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}' --format json`,读 `data.node.space_id`。