SOLO 3.0 打通飞书开放平台 API：从零到自动写文档的完整踩坑实录
SOLO 能不能直接操作飞书文档？这个问题看起来简单，但真正做起来远比想象中复杂。本文记录了从零打通飞书开放平台 API 的完整过程——试了浏览器自动化、MCP、直接 API 调用，踩了一堆坑，最终才跑通。
先说结论：跑通了。 SOLO 现在可以通过飞书开放平台 API，自动创建文档、写入结构化内容、修改已有文档、管理权限。但这个过程一点都不轻松。
一、尝试过的方案
方案 1：浏览器自动化 
最先想到的方案——用浏览器工具直接操作飞书网页。结果飞书用的是自定义 ProseMirror 富文本编辑器，所有可编辑区域对自动化工具完全不可见。点击、双击、Tab 导航、坐标点击，全部无效。放弃。
方案 2：飞书 MCP 飞书官方有 MCP 服务，但需要内测资格，个人配置页面显示"抱歉，您无权访问此页面"。本地 MCP 包（@larksuiteoapi/lark-mcp）装了，但云端 SOLO 无法加载本地 MCP 配置。放弃。
方案 3：飞书开放平台 API 
既然现成的路都走不通，那就自己写代码，直接调 API。
二、API 对接踩坑实录
坑 1：权限开通 ≠ 权限生效 开通 API 权限后调用接口，返回错误码 99991672，提示"应用尚未开通所需权限"。反复检查，权限明明已经开了。最后发现：开通权限后必须创建应用版本并发布，权限才会真正生效。 这个步骤没有任何明显提示，极其容易遗漏。
坑 2：Wiki API 返回 404 解析飞书知识库链接时，用 POST 调用 wiki/v2/spaces/get_node 接口，一直返回 404。翻遍文档才发现：这个接口必须用 GET 方法，wiki_token 作为 query 参数传递。 飞书文档里大部分接口是 POST，唯独这个是 GET。
坑 3：更新块的参数名 尝试修改已有文档的块内容，用 {"text": {...}} 格式，报 1770001 invalid param。换成 {"update_data": {"text": {...}}}，还是报错。最后在官方文档的角落里找到：正确字段名是 update_text_elements。 这个名字完全不直觉。
坑 4：Content-Type 必须带 charset 写入中文内容时，部分中文字符乱码。排查发现：请求头的 Content-Type 必须是 application/json; charset=utf-8，不能只写 application/json。
坑 5：应用编辑别人的文档被拒 所有 API 都调通了，但更新已有文档的块时返回 1770032 forbidden。应用有 wiki:node:read 权限能读，但就是不能写。原因：应用必须被添加为文档协作者才能编辑。 而飞书知识库文档的"添加文档应用"入口藏得很深，有些版本甚至没有这个入口。
坑 6：link_share_entity 的类型 设置链接分享权限时，按直觉传了一个 JSON 对象 {"type": "docx", "token": "xxx"}，报参数错误。实际：这个字段是字符串类型，值应该是 "tenant_editable" 或 "anyone_readable"。
坑 7：API 限流 连续快速写入几十个块时，部分请求返回空响应。需要加入延迟和重试机制。
三、最终方案
经过反复尝试，最终确定的稳定方案：
创建新文档（推荐）： 应用通过 API 自建文档 → 自动拥有完整编辑权限 → 通过 Block API 写入内容 → 设置分享权限 → 添加协作者。全程无人工干预。
修改已有文档： Wiki Token 解析获取 document_id → 读取块列表定位目标块 → 使用 update_text_elements 更新内容。前提是应用已被添加为协作者。
四、需要开通的权限（6 项）
wiki:wiki · wiki:wiki:readonly · wiki:node:read · docx:document · docx:document:create · drive:drive
开通路径：飞书开放平台 → 应用管理 → 权限管理 → 搜索开通 → 创建版本并发布（关键！）
五、核心代码
Python
import requests, json, time
APP_ID = '你的App ID'
APP_SECRET = '你的App Secret'
BASE = 'https://open.feishu.cn'
# 1. 获取 Token
token = requests.post(
f'{BASE}/open-apis/auth/v3/tenant_access_token/internal',
json={'app_id': APP_ID, 'app_secret': APP_SECRET}
).json()['tenant_access_token']
# 2. 创建文档（应用自建，自动拥有编辑权限）
doc_id = requests.post(
f'{BASE}/open-apis/docx/v1/documents',
headers={'Authorization': f'Bearer {token}',
'Content-Type': 'application/json; charset=utf-8'},
json={'title': 'AI 自动生成的文档'}
).json()['data']['document']['document_id']
# 3. 写入内容块
def add_block(block_type, elements):
type_key = {2:'text',3:'heading1',4:'heading2',
12:'bullet',13:'ordered'}[block_type]
time.sleep(0.15) # 防限流
requests.post(
f'{BASE}/open-apis/docx/v1/documents/{doc_id}/blocks/{doc_id}/children',
headers={'Authorization': f'Bearer {token}',
'Content-Type': 'application/json; charset=utf-8'},
json={'children': [{'block_type': block_type,
type_key: {'elements': elements}}]})
add_block(3, [{'text_run': {'content': '一级标题'}}])
add_block(2, [{'text_run': {'content': '正文内容'}}])
add_block(12, [{'text_run': {'content': '列表项'}}])
# 4. 设置权限 + 添加协作者
requests.patch(
f'{BASE}/open-apis/drive/v2/permissions/{doc_id}/public?type=docx',
headers={'Authorization': f'Bearer {token}',
'Content-Type': 'application/json; charset=utf-8'},
json={'external_access': False,
'link_share_entity': 'tenant_editable'})
requests.post(
f'{BASE}/open-apis/drive/v1/permissions/{doc_id}/members?type=docx',
headers={'Authorization': f'Bearer {token}',
'Content-Type': 'application/json; charset=utf-8'},
json={'need_notification': False, 'member_type': 'openid',
'member_id': '用户的openid', 'perm': 'full_access'})
print(f'完成! https://xxx.feishu.cn/docx/{doc_id}')
六、总结
浏览器自动化不行，MCP 不行，最后回到最原始的方式——直接调 API，一行一行代码写出来的。飞书的 API 文档不算差，但很多细节藏在角落里，参数命名也不太直觉，只能靠实际调用 + 报错信息一点点摸索。
整个过程踩了 7 个以上的坑，每个坑都花了大量时间排查。但最终跑通的那一刻，看到 AI 生成的文档直接出现在飞书里，还是很有成就感的。
如果你也在做类似的事情，希望这篇踩坑实录能帮你少走弯路。欢迎交流！
效果：
具体操作流程（新solo自己生成）：https://ecnwhsquon5z.feishu.cn/docx/YQGVdkULSoyTOox4Vzlc9WJknWf?from=from_copylink