Skill: sadjjk/openclaw-feishu-docs-perm-auto (version 1.0.1)

--- name: openclaw-feishu-docs-perm-auto description: 自动为飞书文档添加用户权限。每次创建飞书文档（多维表格/文档/电子表格/文件夹/云空间文件/知识库节点等）后自动添加用户权限，或用户反馈文档无权限时补充添加权限。适用于 OpenClaw Agent。 license: MIT metadata: openclaw: emoji: 🔐 author: sadjjk version: "1.0.0" --- # 飞书文档权限自动添加 > 🎯 **一句话总结**：飞书应用创建的文档，用户默认无权限。这个 skill 帮你自动添加权限。 --- ## 前置条件 | 条件 | 说明 | |------|------| | 飞书开发者账号 | 需要有飞书开放平台的开发者权限 | | 企业自建应用 | 已创建或有权创建飞书应用 | | 应用权限 | 应用需开通 `docs:permission.member:create` 权限 | --- ## 变量速查表 | 变量名 | 来源 | 用途 | |--------|------|------| | `$APP_ID` | 配置文件 `channels.feishu.appId` | 应用标识 | | `$APP_SECRET` | 配置文件 `channels.feishu.appSecret` | 应用密钥 | | `$OWNER_OPEN_ID` | 配置文件或会话上下文 | 权限接收者 | | `$TENANT_TOKEN` | API 获取 | 请求鉴权 | | `$FILE_TOKEN` | 创建返回或 URL 解析 | 文档标识 | | `$DOC_TYPE` | URL 路径识别 | 文档类型 | --- ## 第一步：检查配置 ⚠️ ### 1.1 读取配置文件 配置文件位置：`~/.openclaw/openclaw.json` ### 1.2 检查必需字段 在 `channels.feishu` 下查找： | 字段名 | 说明 | 示例值 | 必需性 | |--------|------|--------|--------| | `appId` | 飞书应用 ID | `cli_xxxxxxxx` | ✅ 必需 | | `appSecret` | 飞书应用密钥 | `xxxxxxxx` | ✅ 必需 | | `ownerOpenId` | 用户的 open_id | `ou_xxx` | ⚪ 可选* | > *`ownerOpenId` 在配置文件中可选，但执行时必须有值。若配置文件缺失，从会话上下文提取（格式 `user:ou_xxx` → `ou_xxx`）。 配置示例： ```json { "channels": { "feishu": { "enabled": true, "appId": "cli_xxxxxxxx", "appSecret": "xxxxxxxx", "ownerOpenId": "ou_xxx" } } } ``` ### 1.3 检查应用权限 使用 `feishu_app_scopes()` 查询当前飞书应用已开通的权限列表。 检查返回结果中是否包含 `docs:permission.member:create`： - ✅ 有 → 权限正常，继续下一步 - ❌ 无 → 跳转到 [配置引导流程 C](#c-配置应用权限) > 💡 如检查出有权限，后续可跳过此步骤。 ### 1.4 判断逻辑 根据检查结果，按以下流程处理： ``` ┌─────────────────────────────────────────────────────────┐ │ 检查 appId + appSecret │ │ ├─ ❌ 缺失 → [配置引导流程 A] │ │ └─ ✅ 完整 ↓ │ │ 检查应用权限 docs:permission.member:create │ │ ├─ ❌ 缺失 → [配置引导流程 C] │ │ └─ ✅ 完整 ↓ │ │ 检查 ownerOpenId │ │ ├─ ✅ 配置文件有 → 进入第二步 │ │ ├─ ✅ 会话上下文有 → 提取使用，进入第二步 │ │ └─ ❌ 都没有 → [配置引导流程 B] │ └─────────────────────────────────────────────────────────┘ ``` --- ## 工具调用映射 🛠️ > 明确每个步骤应使用的工具，确保 Agent 能正确执行 | 步骤 | 操作 | 工具 | 说明 | |------|------|------|------| | 1.1 | 读取配置文件 | `read` | 读取 `~/.openclaw/openclaw.json` | | 1.3 | 检查应用权限 | `feishu_app_scopes` | 查询已开通权限列表 | | 2.2 | 获取 tenant_access_token | `exec` | 执行 curl 命令请求 API | | 2.3 | 解析文档 token | 内置逻辑 | 从 URL 或返回值中提取 | | 2.4 | 添加用户权限 | `exec` | 执行 curl 命令请求 API | | 配置写入 | 保存 ownerOpenId | `edit` | 更新 `openclaw.json` | **工具调用示例**： ```bash # 读取配置文件 read("~/.openclaw/openclaw.json") # 检查应用权限 feishu_app_scopes() # 获取 tenant_access_token exec('curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" ...') # 添加权限 exec('curl -s -X POST "https://open.feishu.cn/open-apis/drive/v1/permissions/..." ...') # 保存配置 edit("~/.openclaw/openclaw.json", oldText, newText) ``` --- ## 第二步：执行权限添加 📋 > 前置条件：第一步检查全部通过 ### 2.1 读取配置 **工具**：`read` ```bash APP_ID="读取到的appId" APP_SECRET="读取到的appSecret" OWNER_OPEN_ID="读取到的ownerOpenId" ``` ### 2.2 获取 tenant_access_token **工具**：`exec` **进度提示**：`[1/4] 获取访问令牌...` **请求**： ```bash curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \ -H "Content-Type: application/json" \ -d "{ \"app_id\": \"$APP_ID\", \"app_secret\": \"$APP_SECRET\" }" ``` **成功返回**： ```json { "code": 0, "msg": "ok", "tenant_access_token": "xxxx", "expire": 5535 } ``` **失败返回**： ```json { "code": 10003, "msg": "app id or app secret is invalid" } ``` **处理**： - ✅ 成功：提取 `tenant_access_token`，继续下一步 - ❌ 失败：提示用户检查 App ID 和 App Secret 是否正确 **token 缓存策略**： | token 类型 | 有效期 | 缓存建议 | |-----------|--------|----------| | `tenant_access_token` | 约 2 小时 | 缓存至会话变量，过期前 5 分钟刷新 | **缓存实现**： - 使用会话级变量存储：`CACHED_TENANT_TOKEN`, `TOKEN_EXPIRE_TIME` - 每次请求前检查：若 `now < TOKEN_EXPIRE_TIME - 300`，直接使用缓存 ### 2.3 获取云文档 token **进度提示**：`[2/4] 解析文档 token...` **来源**： 1. 创建飞书文档后返回的 token 或文档 URL 2. 从用户提供的文档链接解析 **URL 解析规则**： | 文档类型 | URL 示例 | |----------|----------| | 文件夹 | `https://xxx.feishu.cn/drive/folder/【token】` | | 文件 | `https://xxx.feishu.cn/file/【token】` | | 旧版文档 | `https://xxx.feishu.cn/docs/【token】` | | 新版文档 | `https://xxx.feishu.cn/docx/【token】` | | 电子表格 | `https://xxx.feishu.cn/【token】` | | 多维表格 | `https://xxx.feishu.cn/base/【token】` | | 知识空间 | `https://xxx.feishu.cn/wiki/settings/【token】` | | 知识库节点 | `https://xxx.feishu.cn/wiki/【token】` | > ⚠️ 复制 URL 时注意删除末尾多余的 `#` 符号。 **自动识别 doc_type**： | URL 路径特征 | doc_type | |-------------|----------| | `/drive/folder/` | `folder` | | `/file/` | `file` | | `/docs/` | `doc` | | `/docx/` | `docx` | | `/base/` | `bitable` | | `/wiki/` | `wiki` | | 其他（根路径） | `sheet` | **识别逻辑**： 1. 从 URL 提取 token（最后一个路径段，去除 `?` 和 `#` 后的内容） 2. 根据 URL 路径匹配 doc_type 3. 若无法匹配，提示用户提供文档类型 **变量定义**： - `FILE_TOKEN = 获取到的云文档 token` - `DOC_TYPE = 识别到的文档类型` ### 2.4 添加用户权限 **工具**：`exec` **进度提示**：`[3/4] 添加用户权限...` **请求**： ```bash curl -s -X POST "https://open.feishu.cn/open-apis/drive/v1/permissions/{FILE_TOKEN}/members/batch_create?type={DOC_TYPE}" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {tenant_access_token}" \ -d "{ \"members\": [{ \"member_type\": \"openid\", \"member_id\": \"$OWNER_OPEN_ID\", \"perm\": \"full_access\" }] }" ``` **参数说明**： | 参数 | 来源 | 示例 | |------|------|------| | `{FILE_TOKEN}` | 创建文档时返回或 URL 解析 | `xxxxx` | | `{DOC_TYPE}` | URL 路径自动识别 | `bitable` | | `{tenant_access_token}` | 上一步获取 | `t-xxx` | | `$OWNER_OPEN_ID` | ownerOpenId | `ou_xxx` | **doc_type 可选值**： | 值 | 文档类型 | |----|----------| | `bitable` | 多维表格 | | `docx` | 新版文档 | | `doc` | 旧版文档 | | `sheet` | 电子表格 | | `folder` | 文件夹 | | `file` | 云空间文件 | | `wiki` | 知识库节点 | **成功返回**： ```json { "code": 0, "msg": "Success", "data": { "members": [{ "member_id": "xxxx", "member_type": "openid", "perm": "full_access" }] } } ``` ### 2.5 执行结果反馈 **进度提示**：`[4/4] 完成！` **成功时**： ``` ✅ 权限添加成功！ 📄 文档：{文档标题或 token} 🔗 链接：{文档 URL} 👤 权限：完整权限 (full_access) 你现在可以直接访问和编辑这个文档了。 如果配置文件中没有ownerOpenId 并询问 是否需要将 ownerOpenId 写入配置文件中 ``` **失败时**： ``` ❌ 权限添加失败 原因：{错误信息} 解决方案：{具体步骤} 需要帮助？请提供以上信息。 ``` --- ## 使用示例 📝 ### 示例 1：创建多维表格后自动添加权限 **用户**：帮我创建一个多维表格叫「项目进度追踪」 **Agent 执行流程**： ``` [1/3] 创建多维表格... → 调用 feishu_bitable_create_app(name="项目进度追踪") → 返回 app_token: "bascnxxx" [2/3] 添加用户权限... → 触发 feishu-perm-auto skill → 检查配置：appId ✓ appSecret ✓ ownerOpenId ✓ → 获取 tenant_access_token → 调用权限 API 添加 full_access [3/3] 完成！ ``` **Agent 回复**： ``` ✅ 多维表格「项目进度追踪」已创建！ 🔗 链接：https://xxx.feishu.cn/base/bascnxxx 🔐 已自动为你添加完整权限，可直接访问和编辑 ``` --- ### 示例 2：用户反馈文档无权限 **用户**：这个文档我打不开，提示没权限 https://xxx.feishu.cn/docx/doxcnxxx **Agent 执行流程**： ``` [1/3] 解析文档信息... → URL 解析：[REDACTED_SECRET], doc_type=docx [2/3] 检查配置并添加权限... → 检查配置：appId ✓ appSecret ✓ ownerOpenId ✓ → 获取 tenant_access_token → 调用权限 API 添加 full_access [3/3] 完成！ ``` **Agent 回复**： ``` ✅ 权限添加成功！ 📄 文档：doxcnxxx 🔗 链接：https://xxx.feishu.cn/docx/doxcnxxx 👤 权限：完整权限 (full_access) 你现在可以直接访问和编辑这个文档了。 ``` --- ### 示例 3：首次使用，配置缺失 **用户**：帮我创建一个飞书文档 **Agent 执行流程**： ``` [1/2] 检查配置... → 读取 ~/.openclaw/openclaw.json → 发现 channels.feishu.appId 缺失 [2/2] 引导配置... ``` **Agent 回复**： ``` ⚠️ 还没配置飞书应用凭证，需要先设置一下： 📱 获取飞书应用凭证： 1. 打开浏览器，访问：https://open.feishu.cn/app 2. 登录你的飞书账号 3. 点击「创建企业自建应用」或选择已有应用 4. 在左侧菜单找到「凭证与基础信息」 5. 复制以下内容： - App ID（cli_ 开头的字符串） - App Secret（点击「查看」后显示） 请把 App ID 和 App Secret 发给我，格式如下： appId: cli_xxxxxxxx appSecret: xxxxxxxx ``` **用户回复后**： ``` 用户：appId: cli_aabbccdd appSecret: 1234567890abcdef Agent： [1/2] 验证凭证... → 获取 tenant_access_token 成功 ✓ [2/2] 保存配置... → 更新 ~/.openclaw/openclaw.json ``` **Agent 回复**： ``` ✅ 飞书应用配置成功！ 现在可以正常使用飞书功能了。需要我帮你创建文档吗？ ``` --- ### 示例 4：权限已存在（幂等处理） **用户**：给这个文档加权限 https://xxx.feishu.cn/base/bascnxxx **Agent 执行流程**： ``` [1/3] 解析文档信息... → [REDACTED_SECRET], doc_type=bitable [2/3] 添加权限... → 调用 API 返回错误码 99991661（成员已存在） [3/3] 幂等处理... → 视为成功，无需重复添加 ``` **Agent 回复**： ``` ✅ 权限已存在！ 📄 文档：bascnxxx 🔗 链接：https://xxx.feishu.cn/base/bascnxxx 👤 权限：完整权限 (full_access) 你已经有这个文档的完整权限了。 ``` --- ## 配置引导流程 🔧 > 当第一步检查发现配置缺失时，按以下流程引导用户配置。 ### A. 获取 App ID 和 App Secret ``` 📱 获取飞书应用凭证： 1. 打开浏览器，访问：https://open.feishu.cn/app 2. 登录你的飞书账号 3. 点击「创建企业自建应用」或选择已有应用 4. 在左侧菜单找到「凭证与基础信息」 5. 复制以下内容： - App ID（cli_ 开头的字符串） - App Secret（点击「查看」后显示） 请把 App ID 和 App Secret 发给我，格式如下： appId: cli_xxxxxxxx appSecret: xxxxxxxx ``` ### B. 获取 ownerOpenId **优先从会话上下文提取**：若上下文中出现 `user:ou_xxx` 格式，直接提取 `ou_xxx` 使用。 **否则引导用户获取**： 1. 登录 [API 调试台](https://open.feishu.cn/api-explorer)，找到发送消息接口 2. 在「查询参数」页签，将 `user_id_type` 设置为 `open_id` 3. 点击「快速复制 open_id」 详见：https://open.feishu.cn/document/faq/trouble-shooting/how-to-obtain-openid **用户回复后**： 1. 验证格式是否正确（以 `ou_` 开头） 2. 在当前会话中使用此 ownerOpenId ### C. 配置应用权限 ``` ⚠️ 在使用前，还需要给应用添加权限： 1. 在飞书开放平台，点击左侧「权限管理」 2. 搜索并开通以下权限： - docs:permission.member:create (添加云文档协作者) 3. 点击「发布版本」使权限生效 如果权限显示「待确认」，需要联系企业管理员审批。 ``` --- ## 权限级别说明 🔐 | 权限值 | 中文名 | 能做什么 | 适用场景 | |--------|--------|----------|----------| | `view` | 只读 | 只能查看，不能修改 | 分享给他人查看 | | `edit` | 可编辑 | 可以修改内容，不能管理权限 | 协作编辑 | | `full_access` | 完整权限 | 可以编辑、管理权限、删除 | 文档所有者（推荐） | > 💡 建议：给用户添加 `full_access` 权限，这样用户可以完全控制文档。 **权限选择建议**： | 场景 | 推荐权限 | 原因 | |------|----------|------| | 用户自己的文档 | `full_access` | 完全控制 | | 协作编辑 | `edit` | 避免误删 | | 只读分享 | `view` | 安全最小化 | > 💡 默认使用 `full_access`，但可在执行时询问用户需求。 --- ## 错误处理大全 ⚠️ | 错误码 | 错误信息 | 原因 | 解决方案 | 处理动作 | |--------|---------|------|----------|----------| | `10003` | app id or app secret is invalid | App ID 或 App Secret 错误 | 检查配置，确保复制正确 | 重新配置后重试 | | `99991661` | 成员已存在 | 用户已有权限 | 视为成功，无需处理 | 直接返回成功 | | `99991663` | Invalid access token | token 过期或无效 | 重新获取 tenant_access_token | 重新执行 2.2 | | `99991664` | Permission denied | 应用没有权限 | 引导配置应用权限 | 跳转配置引导 C | | `99991600` | token not found | 文档 token 不存在 | 检查 file_token 是否正确 | 确认后重试 | --- ## 最佳实践 💡 ### 配置管理 - ✅ 首次使用时引导用户配置 - ✅ 配置保存后，后续自动读取 - ⚠️ 不要在日志中输出 App Secret ### 错误处理 - ✅ 每一步都要检查返回的 code - ✅ 失败时给出清晰的错误原因 - ✅ 提供具体的解决方案和处理动作 ### 用户体验 - ✅ 每步输出进度提示 `[1/4] [2/4] [3/4] [4/4]` - ✅ 成功后返回文档链接 - ✅ 告诉用户权限已添加 - ✅ 提示用户可以直接访问 - ✅ 成功后询问用户是否需要将 ownerOpenId 写入配置文件 ### 安全考虑 - ⚠️ App Secret 不要硬编码在 skill 中 - ⚠️ 不要在回复中显示完整的 App Secret（只显示前4位 + `***`） - ⚠️ token 有效期约 2 小时，建议缓存避免频繁请求 **敏感信息脱敏**： | 信息类型 | 原始值 | 脱敏后 | |---------|--------|--------| | App Secret | `abc123xyz789` | `abc1***` | | tenant_access_token | `t-xxx123456` | `t-xxx***` | | ownerOpenId | `ou_abc123` | `ou_abc***` | **脱敏实现**： ```python def mask_secret(s, show=4): return s[:show] + '***' if len(s) > show else '***' ``` --- ## 相关链接 📎 | 资源 | 链接 | |------|------| | 飞书开放平台 | https://open.feishu.cn/app | | 权限配置指南 | https://open.feishu.cn/document/docs/permission/permission-member/batch_create | | 获取 Open ID | https://open.feishu.cn/document/faq/trouble-shooting/how-to-obtain-openid | --- ## 快速参考卡片 📌 ``` ┌─────────────────────────────────────────────────────────┐ │ 飞书权限添加快速参考 │ ├─────────────────────────────────────────────────────────┤ │ 1. 检查配置：~/.openclaw/openclaw.json │ │ - appId (必需) │ │ - appSecret (必需) │ │ - ownerOpenId (可选，会话上下文补充) │ │ - 应用权限: docs:permission.member:create (必需) │ ├─────────────────────────────────────────────────────────┤ │ 2. 获取 tenant_access_token： │ │ POST /auth/v3/tenant_access_token/internal │ │ Body: {app_id, app_secret} │ ├─────────────────────────────────────────────────────────┤ │ 3. 获取云文档 token： │ │ 创建时返回 或 从 URL 解析 │ │ 自动识别 doc_type: /base/→bitable, /docx/→docx... │ ├─────────────────────────────────────────────────────────┤ │ 4. 添加权限： │ │ POST /drive/v1/permissions/{token}/members │ │ Header: Authorization: Bearer {token} │ │ Body: {members: [{member_type, member_id, perm}]} │ ├─────────────────────────────────────────────────────────┤ │ 文档类型： │ │ bitable | docx | doc | sheet | folder | file | wiki │ │ 权限级别：view | edit | full_access │ └─────────────────────────────────────────────────────────┘ ```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)