飞书文档权限设置技能
功能
设置飞书云文档为"获得链接的任何人可查看"，使外部用户（如鲲哥）能够访问文档。
触发场景
- 创建飞书文档后需要发送给外部用户
- 收到反馈说文档没有权限访问
- 需要批量检查/修复多个文档权限
输入参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
doc_token |
string | ✅ | 飞书文档 token（从文档链接提取） |
verify_only |
boolean | ❌ | 仅验证不修复（默认 false） |
示例：
doc_token: KTVQdB0NfohPjzxC8QOchE25nJd
verify_only: false
使用方式
方式 1：直接调用（推荐）
请设置飞书文档权限，doc_token: KTVQdB0NfohPjzxC8QOchE25nJd
方式 2：创建文档后自动调用
在创建飞书文档的 cron 任务或子代理中，完成后立即调用此技能：
1. 创建飞书文档 → 获得 doc_token
2. 写入文档内容
3. 调用 feishu-document-permission 技能设置权限
4. 验证权限生效
5. 发送邮件/消息通知
API 调用流程
步骤 1：获取 tenant_access_token
APP_ID="cli_a9217db4a3f59cb6"
APP_SECRET="G34RRAc41XOY7vb2a7NmMgwl5chruBmo"
TENANT_TOKEN=$(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\"
}" | jq -r '.tenant_access_token')
步骤 2：验证当前权限
curl -X GET "https://open.feishu.cn/open-apis/drive/v2/permissions/${DOC_TOKEN}/public?type=docx" \
-H "Authorization: Bearer $TENANT_TOKEN" | jq .
期望返回：
{
"code": 0,
"data": {
"permission_public": {
"link_share_entity": "anyone_readable",
"external_access_entity": "open"
}
}
}
步骤 3：设置权限（如需要）
curl -X PATCH "https://open.feishu.cn/open-apis/drive/v2/permissions/${DOC_TOKEN}/public?type=docx" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TENANT_TOKEN" \
-d '{
"external_access_entity": "open",
"link_share_entity": "anyone_readable"
}'
关键参数：
- type=docx — 必须指定，否则 API 不识别（v1 API 不支持 docx）
- external_access_entity: "open" — 允许分享到组织外
- link_share_entity: "anyone_readable" — 获得链接的任何人可查看
步骤 4：记录日志
echo "$(date): 文档 ${DOC_TOKEN} 权限已设置为 anyone_readable" >> memory/feishu_permission_log.md
错误 API（不要使用！）
以下 API 都返回 404 或无效参数：
- ❌ PUT /docx/v1/documents/{id}/setting
- ❌ POST /docx/v1/documents/{id}/collaborators
- ❌ GET /docx/v1/documents/{id}/share
- ❌ PATCH /docx/v1/documents/{id}
- ❌ PUT /docx/v1/documents/{id}/share/link
正确 API： PATCH /drive/v2/permissions/:token/public?type=docx
验证清单
执行完成后必须确认：
- [ ] API 返回 code: 0
- [ ] link_share_entity = "anyone_readable"
- [ ] external_access_entity = "open"
- [ ] 日志已记录到 memory/feishu_permission_log.md
- [ ] 如有外部收件人，邮件中确认"文档已设置为公开可读"
历史教训（2026-04-08 ~ 2026-04-13）
第一次犯错（2026-04-08）
- 问题： 磁带产业调研文档，鲲哥打不开
- 根因： 创建文档时只给内部用户加权限，没有设置链接分享
- 修复： 调用飞书 API 设置权限
- 教训： 飞书文档发外部人必须设置
link_share_entity: anyone_readable
第二次犯错（2026-04-12）
- 问题： HDD 产能售罄文档，鲲哥再次打不开
- 根因： 口头说"已设置"，实际未调用 API
- 教训： 不能想当然，必须调用 API 并验证
第三次犯错（2026-04-13）
- 问题： 同一文档，鲲哥第三次投诉
- 根因： 重复犯错，没有建立验证机制
- 智哥批评： "你怎么反复出这个问题"
- 修复： 创建子代理研究正确 API，找到 v2 API
- 核心教训：
1. 不能想当然 — "调用 API" ≠ "成功"
2. 必须验证 — 用 GET 请求检查返回值
3. 建立机制 — 不能只靠"记住教训"，要固化到技能中
相关文件
- 技能位置：
~/.openclaw/skills/feishu-document-permission/SKILL.md - 检查脚本：
/home/harrot/.openclaw/workspace/scripts/check-feishu-permission.sh - 权限日志：
/home/harrot/.openclaw/workspace/memory/feishu_permission_log.md - 错误记录：
/home/harrot/.openclaw/workspace/.learnings/ERRORS.md（2026-04-13 条目）
注意事项
- 必须用 v2 API —
/drive/v2/permissions/:token/public?type=docx，v1 不支持 docx - 必须验证 — 设置后用 GET 请求检查返回值，不能假设成功
- 必须记录 — doc_token 和权限状态记到日志，方便追溯
- 外部用户场景 — 只有需要发给外部用户（如鲲哥）时才设置公开权限
- 内部文档 — 如只需内部访问，不要设置公开权限
示例对话
用户： 刚创建了飞书文档，要发给鲲哥，doc_token 是 ABC123xyz
悠悠： 好的，我来设置文档权限为公开可读。
（调用 API 设置权限）
悠悠： ✅ 权限已设置成功！
- 文档链接：https://feishu.cn/docx/ABC123xyz
- 权限：获得链接的任何人可查看
- 已记录到权限日志
现在鲲哥可以打开链接查看文档了。
版本： v1.0.0（2026-04-13 创建）
作者： 悠悠
最后更新： 2026-04-13
