飞书知识库API必须使用tenant_access_token而非user_access_token，有效期2小时需缓存刷新；document.get返回嵌套blocks结构，需递归提取text_run.content；新建文档需先docx.create再document.batch_update，注意HTTP头、JSON格式及文档ID格式。
飞书知识库 API 需要先拿到 tenant_access_token，不是用个人 token
调用飞书知识库（如读取文档、创建文档）必须使用企业级凭证，user_access_token 权限不够，会直接返回 {"code":99991665,"msg":"invalid tenant_access_token"}。这个 token 有效期 2 小时，必须自己缓存并刷新。
- 先用
app_id和app_secret调https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal/换取tenant_access_token - PHP 中建议用
file_get_contents()或cURL发 POST 请求，注意设置Content-Type: application/json - 别把
tenant_access_token写死在代码里，每次请求前检查是否过期，过期就重取；可存在 Redis 或文件中，带时间戳判断
读取知识库文档内容得用 document.get，但返回的是富文本结构，不是纯文本
飞书文档 API 的 document.get 接口（https://open.feishu.cn/open-apis/docx/v1/documents/{document_id}/content）返回的是嵌套的 blocks 数组，每个 block 是段落、标题、表格等结构单元，不是直接给你 HTML 或 Markdown 字符串。
- 想提取纯文本，得递归遍历
blocks，读取每个text_elements里的text_run.content - 如果文档含图片、@人、超链接，对应字段是
image、mention、link，不处理会丢内容或解析失败 - PHP 示例片段：
$content = json_decode($response_body, true); $text = ''; foreach ($content['data']['content']['blocks'] as $block) { if (isset($block['paragraph']['elements'])) { foreach ($block['paragraph']['elements'] as $el) { if (isset($el['text_run']['content'])) { $text .= $el['text_run']['content']; } } } }
写入文档要用 docx.create + document.batch_update 两步，不能直接“保存”
飞书不提供“上传一个 Markdown 文件就生成文档”的接口。新建文档得先调 docx.create 创建空文档，再用 document.batch_update 插入 blocks —— 这意味着你得把 PHP 里的字符串转成飞书认可的 block 格式。
-
docx.create返回document_id和url，后续所有操作都靠这个 ID - 插入内容时，
batch_update的 body 是数组，每个 item 是{ "insert_block": { "block": { ... } } }，block 类型必须是paragraph、heading1等合法值，错一个字段整个请求 400 - 中文换行要注意：飞书用
{"text_run": {"content": "\n"}}表示换行，不是\n字符本身；直接拼字符串会断行失败 - 权限问题：目标知识库必须已对当前应用授权“编辑文档”，否则
batch_update返回code: 99991678
PHP 处理飞书 API 容易忽略的三个细节
很多 PHP 项目卡在看似简单的地方，其实和飞书协议细节强相关：
立即学习“PHP免费学习笔记（深入）”；
- HTTP Header 必须带
Authorization: Bearer ttt_xxx（ttt_前缀不能少），漏了就401 unauthorized - 所有 POST 请求体必须是 JSON 字符串，且
Content-Type设为application/json；用http_build_query()发送会 400 - 飞书文档 ID 形如
doxcnxxxxxxxxxxxxxxxxxxxxxxxx，开头是doxcn，不是doc也不是xxxxxx，传错 ID 会返回code: 99991663（文档不存在）
飞书知识库 API 不是“填个 token 就能跑”，每一步都卡在 token 类型、block 结构、HTTP 头细节上——这些地方出错，错误信息几乎一样，得靠日志比对请求路径、header、body 才能定位。
