飞书文档编辑技能

此技能提供使用飞书开放平台 API 创建和编辑飞书文档的完整指导。

前置条件

1. 应用创建与配置

创建企业自建应用：登录飞书开放平台，创建应用并添加“机器人”能力。

申请 API 权限：在“权限管理”中申请以下权限：

• 文档编辑：docx:document:write_only
• 文档查看：docx:document:readonly

发布应用：提交版本并发布，确保应用覆盖范围包含目标用户/部门。

2. 获取访问令牌

调用自建应用获取租户访问令牌接口：

curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  -H "Content-Type: application/json" \
  -d '{"app_id": "your_app_id", "app_secret": "your_app_secret"}'

响应示例：

{
  "code": 0,
  "tenant_access_token": "t-xxx",
  "expire": 7200
}

核心操作

提取文档 ID

从文档 URL 中获取 document_id：

示例 URL：https://bigdatacenter.feishu.cn/docx/HpK2dtGu9omhMAxV12zcB6i7ngd

document_id = HpK2dtGu9omhMAxV12zcB6i7ngd

授予应用文档权限

手动添加协作者：

• 在飞书客户端打开文档 → 点击右上角“...” → “更多” → “添加文档应用”
• 搜索并添加您的应用，授予“可编辑”权限。

写入文本内容

接口：创建块（Create Block）

• 路径参数：document_id = 文档 ID，block_id = 文档 ID（根节点即为文档本身）
• 请求头：

  Authorization: Bearer {tenant_access_token}
  Content-Type: application/json

• 请求体示例（写入“hello”）：

  {
    "index": -1,
    "children": [
      {
        "block_type": 2,
        "text": {
          "elements": [
            {
              "text_run": {
                "content": "hello"
              }
            }
          ]
        }
      }
    ]
  }

读取文档内容

接口：获取文档纯文本（Get Document Plain Text）

curl -X GET "https://open.feishu.cn/open-apis/docx/v1/documents/{document_id}/plaintext" \
  -H "Authorization: Bearer {tenant_access_token}"

响应示例：

{
  "code": 0,
  "data": {
    "content": "文档文本内容在此"
  }
}

常见问题

1. 权限错误（403 Forbidden）

• 诊断：应用未作为文档协作者添加，或 tenant_access_token 无效。
• 解决方案：重新将应用添加为协作者，或重新获取 tenant_access_token。

2. 缺失访问令牌（99991661）

• 诊断：请求头未携带 Authorization: Bearer {token}。
• 解决方案：确保 tenant_access_token 正确添加至请求头。

3. 文档未找到（404 Not Found）

• 诊断：document_id 错误或文档已被删除。
• 解决方案：重新从文档 URL 中提取 document_id。

参考文档

• 创建块接口
• 获取文档纯文本接口
• 权限配置指南

通过以上步骤，可实现通过 API 编辑飞书文档，支持对文本、表格、图片等多种内容类型进行增删改查操作。