飞书文档权限自动添加

SKILL.md

---
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 解析：token=doxcnxxx, 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] 解析文档信息...
      → token=bascnxxx, 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                    │
└─────────────────────────────────────────────────────────┘
```