Feishu Doc Creator With Permission

文档创建+权限管理子技能

职责

在飞书创建新文档，并智能选择 Token 模式完成权限管理，确保用户获得完全控制权。

⭐ 智能 Token 模式选择

自动判断逻辑

脚本会根据文档标题智能判断使用哪种 Token 模式：

示例

# 使用 Tenant Token（默认）
python scripts/doc_creator_with_permission.py "产品需求文档"
python scripts/doc_creator_with_permission.py "会议纪要-2026-02-10"

# 使用 User Token（检测到关键词）
python scripts/doc_creator_with_permission.py "我的个人笔记"
python scripts/doc_creator_with_permission.py "用户文件夹-测试文档"
python scripts/doc_creator_with_permission.py "放到文件夹里的文档"

# 强制使用 User Token
python scripts/doc_creator_with_permission.py "测试文档" --user-token

为什么需要智能选择？

创建文档和权限管理是强关联的操作：

Tenant Token 模式（默认）：

• 应用创建的文档，用户默认没有任何权限
• 必须添加协作者权限，用户才能编辑
• 适合自动化批量创建、团队文档

User Token 模式（关键词触发）：

• 文档直接属于用户
• 可指定文件夹位置
• 无需权限转移，用户有完全控制权
• 适合个人文档、需要指定文件夹的场景

输入

• 文档标题（必需）
• Markdown 文件路径（可选，用于确定标题）

输出

• output/doc_with_permission.json - 包含文档信息和权限状态

工作流程

Tenant Token 模式（三步）

第一步：创建文档 使用 tenant_access_token 创建新文档，应用成为创建者。

第二步：添加协作者权限 使用 tenant_access_token 添加协作者，用户获得编辑权限。

• ⚠️ 只有 tenant_token 可以添加协作者

第三步：转移所有权 ⭐ 使用 user_access_token 转移所有权，用户获得完全控制权（可编辑+可删除）。

• ⚠️ 只有 user_token 可以转移所有权
• ⚠️ 这是必要步骤，不是可选的

User Token 模式（一步）

创建文档 使用 user_access_token 创建文档，文档直接属于用户，无需权限转移。

最后一步：保存结果

保存文档信息和权限状态到 output/doc_with_permission.json。

数据格式

doc_with_permission.json 格式

{
  "document_id": "U2wNd2rMkot6fzxr67ScN7hJn7c",
  "document_url": "https://feishu.cn/docx/U2wNd2rMkot6fzxr67ScN7hJn7c",
  "title": "文档标题",
  "created_at": "2026-01-22T10:30:00",
  "token_mode": "tenant_access_token",  // 或 "user_access_token"
  "permission": {
    "collaborator_added": true,
    "owner_transferred": false,
    "user_has_full_control": true,
    "collaborator_id": "ou_xxx"
  },
  "errors": []
}

使用方式

命令行

# 默认模式（Tenant Token）
python scripts/doc_creator_with_permission.py "产品需求文档"

# User Token 模式（检测到关键词）
python scripts/doc_creator_with_permission.py "我的个人笔记"

# 强制使用 User Token
python scripts/doc_creator_with_permission.py "测试文档" --user-token

作为子技能被调用

result = call_skill("feishu-doc-creator-with-permission", {
    "title": "文档标题",
    "output_dir": "workflow/step2_create_with_permission"
})
# 返回: {"doc_info_file": "workflow/step2_create_with_permission/doc_with_permission.json"}

与其他技能的协作

• 接收来自主编排技能的标题
• 输出给 feishu-block-adder、feishu-doc-verifier、feishu-logger
• 只传递文件路径，不传递内容

注意事项

1. Token 类型必须一致：文档创建和块添加必须使用相同类型的 Token

   • ❌ 创建用 user_token，添加用 tenant_token → Forbidden
   • ✅ 创建用 tenant_token，添加用 tenant_token → 成功
   • ✅ 创建用 user_token，添加用 user_token → 成功

2. Tenant Token 创建后必须立即添加协作者

   • 否则后续的块添加会因权限不足而失败

3. User Token 需要先授权

   • 确保 feishu-token.json 文件存在且有效
   • 使用 auto_auth.py 自动完成授权（推荐）

OAuth 自动授权

运行自动化授权脚本，自动完成整个授权流程：

cd /path/to/your/project
python .claude/skills/feishu-doc-creator-with-permission/scripts/auto_auth.py

脚本会自动：

1. 启动本地服务器接收回调
2. 打开浏览器飞书授权页面
3. 自动捕获授权码
4. 获取并保存 token 到 .claude/feishu-token.json

使用方法： 运行脚本后，在浏览器中点击"同意"即可，其余全部自动完成。

正确的权限范围

drive:drive docs:doc docx:document docs:permission.member:create offline_access

注意：不要使用 drive:drive.permission，会报错 20043。