打通AI自动阅读垂直平台文档的关键步骤
背景与动机
通用型 AI（如 GPT-4、Claude）在通用编程语言（Python、JavaScript 等）上已非常强大，但在特定平台的产品能力开发上仍显薄弱。
典型场景：
纷享销客的 Groovy 脚本
销售易的 NEXUI 框架
各类低代码/无代码平台的专有语法
核心痛点：这些平台的文档通常需要登录才能访问，通用 AI 无法直接读取，且文档结构复杂、概念繁多。
技术挑战
1. 文档获取层
问题 现状 解决方案
登录壁垒 文档需登录，无公开 API 使用 DrissionPage 模拟浏览器操作，绕过登录限制
导航复杂 面包屑层级深（H1→H2→H3…） 解析 ul/li 结构，提取层级关系
格式混乱 原始 HTML 或纯文本效果差 飞书提供 Markdown/HTML 转文档块 接口
2. 飞书文档接入层
原以为找到飞书转换接口是终点，实则是复杂流程的起点。
标准七步流程
graph TD
A[1. 创建 docx 文档] --> B[2. Markdown/HTML 转文档块]
B --> C[3. 批量插入嵌套块]
C --> D{4. 处理表格?}
D -->|是| E[去除 merge_info 字段]
D -->|否| F[5. 下载网络图片到本地]
E --> F
F --> G[6. 以 Image BlockID 为父节点上传素材]
G --> H[7. 调用更新块接口
replace_image 操作绑定素材]
H --> I[文档完美呈现]
关键陷阱：表格处理
飞书文档块的 merge_info 为只读属性，若直接传入会导致报错。需在插入前预先剔除该字段。
图片处理链路
网络图片无法直接使用，必须：
下载本地化 → 2. 创建素材 → 3. 绑定替换
飞书文档核心概念映射
文档体系架构
层级 概念 标识符 说明
存储层 云空间 - 容器：应用云空间（tenant_access_token）/ 个人云空间（user_access_token）
资源层 云文档 document_id 统称：文档、表格、多维表格、知识库
结构层 块（Block） block_id 最小单元，类型包括：文本、标题、列表、表格、图片等
媒体层 素材 file_token 图片、视频、文件等资源
关键标识符对照
字段 用途 示例场景
document_id 文档唯一标识 创建/更新文档时指定目标
block_id 块唯一标识 插入子块、更新内容、绑定图片
block_type 块类型枚举 2=文本, 3-11=标题1-9, 12=无序列表, 14=图片
parent_id 父块 ID 构建层级结构（大纲）
space_id 知识空间 ID 知识库管理
node_token 知识库节点标识 知识库内定位文档
obj_token 实际文档标识 节点对应的底层文档
obj_type 文档类型 docx, sheet, bitable
块类型速查（常用）
类型 枚举值 说明
页面块 1 根块，block_id = document_id
文本 2 普通段落
标题 1-9 3-11 层级标题
无序列表 12 Bullet
有序列表 13 Ordered
图片 14 Image，需配合素材上传
表格 18 Table，注意 merge_info 处理
代码块 22 Code
待办事项 23 Todo
实现难点总结
链路冗长：7 步流程，每步都有前置依赖
概念密集：云文档/云空间/块/素材/知识库等多套体系交织
参数复杂：每个接口涉及大量业务参数，需理解底层模型
边界处理：表格 merge_info、图片替换等隐式约束
状态管理：BlockID、素材 Token 等需在多步骤间传递
价值展望
一旦打通此流程，即可实现：
“AI 自动阅读垂直平台文档 → 结构化理解 → 生成可交互知识库”
让 AI 真正掌握纷享、销售易、钉钉宜搭等专有平台的产品能力，补齐通用 AI 在垂直领域的短板。