karuo-ai/02_卡人（水）/水桥_平台对接/飞书管理/参考资料/飞书JSON格式全手册.md

飞书 JSON 格式全手册

基于项目 52 个 .feishu.json 实际文件 + 6 个脚本验证 + 飞书开放平台官方文档。
版本：2.1 | 更新：2026-02-22
来源：卡若AI 水桥 · 飞书管理
v2.2 新增：表格列宽 150~520px、表头/首列加粗、首尾去掉 callout、--no-callouts。v2.1：表格列宽 API、code/callout 降级

---

零、标准操作流程（SOP · 强制）

以后所有飞书相关文档，均按本手册格式写、转、传。

SOP-A：写新文档 → 上传飞书

1. 先在本地写 Markdown（推荐）
   ↓
2. 转成 .feishu.json：
   python3 脚本/md_to_feishu_json.py /path/to/文章.md
   ↓
3. 上传到飞书 Wiki：
   python3 脚本/upload_json_to_feishu_doc.py /path/to/文章.feishu.json --parent <wiki_token> --title "标题"
   ↓
4. 验证：打开飞书链接检查格式

SOP-B：Markdown 直传（不经 JSON）

python3 脚本/feishu_article_unified_publish.py --parent <token> --title "标题" --md /绝对路径/文章.md

SOP-C：批量目录上传

python3 脚本/batch_upload_json_to_feishu_wiki.py /本地目录 --wiki-parent <token>

SOP-D：飞书导出 JSON 按原格式回传

python3 脚本/upload_json_to_feishu_doc.py /path/to/导出.json

Token 出问题时

python3 脚本/feishu_token_cli.py get-access-token
python3 脚本/feishu_token_cli.py set-march-token <新token>

---

一、JSON 文件顶层结构

{
  "title": "文档标题.md",
  "source": "相对来源路径/文档标题.md",
  "children": [ 块1, 块2, ... ]
}

字段	说明
title	上传后显示的文档标题
source	本地来源路径（可选，追踪用）
children	块数组，顺序即文档顺序

写入 API 时：只传 children；块内不带 block_id（服务端生成）。

---

二、block_type 完整对照表（v2.0 · 已验证）

2.1 已验证可写入的块类型（生产代码验证）

block_type	类型	JSON 字段名	说明	验证来源
1	页面根节点	page	根节点，不通过 children 创建	导出
2	正文	text	最常用，支持富文本	脚本+导出
3	一级标题	heading1	#	md_to_feishu_json.py
4	二级标题	heading2	##	脚本+导出
5	三级标题	heading3	###	脚本+导出
6	四级标题	heading4	####，日志日期专用	脚本+导出
7	五级标题	heading5	#####	API 文档
8	六级标题	heading6	######	API 文档
9-11	七~九级标题	heading7~heading9	极少用	API 文档
14	代码块	code	支持多语言高亮	脚本+导出
17	待办	todo	可勾选任务	脚本+导出
19	高亮块/标注	callout	带颜色背景区块	脚本+导出
22	分割线	divider	水平线	脚本+导出
24	分栏	grid	多列布局容器	smart_write_wiki.py
25	分栏列	grid_column	grid 的子列	smart_write_wiki.py
30	电子表格	sheet	文档内表格，9×9 上限	md_to_feishu_json.py

2.2 图片/文件/媒体相关

block_type	类型	JSON 字段名	说明
12	文件/图片（写入）	file	先 upload_all 拿 file_token，再插入
18	画廊	gallery	多图显示，单图也可用
27	图片（导出）	image	导出时出现；写入用 12 file

2.3 复杂/高级块

block_type	类型	JSON 字段名	说明
31	表格	table	⚠️ 带 cells 接口报 9499，慎用
43	多维表格	board/bitable	须 bitable:app 权限
26	内嵌	iframe	API 不支持写入，导出可见
29	思维笔记	mindnote	API 不支持写入
34	引用容器	quote_container	引用嵌套容器
20	会话卡片	chat_card	群聊卡片

2.4 列表块（重要说明）

飞书 DocX API 定义了原生列表块类型，但当前脚本采用正文块 + 前缀符号的方式实现列表（更稳定）：

方案	block_type	实现方式	稳定性
当前方案（推荐）	2 (text)	无序用 • 前缀，有序用 1）2） 前缀	✅ 稳定
原生无序列表	12 (bullet)	"bullet": {"elements": [...]}	⚠️ 未验证
原生有序列表	13 (ordered)	"ordered": {"elements": [...]}	⚠️ 未验证

原因：bullet(12) 和 file(12) 可能存在 API 版本差异。当前生产代码中 block_type 12 = file，用于图片/文件上传，已验证稳定。列表统一用 text(2) + 前缀实现，确保兼容性。

2.5 脚本写入行为（v2.1 更新）

sanitize_blocks 清洗：写入前自动过滤：

• 空 text(2) 块
• 空 code(14) 块（elements 内容为空或空白）
• 空 callout(19) 块

code/callout 降级保底：code(14) 或 callout(19) 写入飞书 API 失败时，脚本自动将其内容降级为 text(2) 正文块写入，内容不丢失。

---

三、各 Block 类型详细 JSON 格式

3.1 正文块（block_type: 2）—— 最常用

最简版：

{"block_type": 2, "text": {"elements": [{"text_run": {"content": "这是一段正文。"}}]}}

带样式版（加粗 + 颜色）：

{
  "block_type": 2,
  "text": {
    "elements": [
      {"text_run": {"content": "[重要紧急]", "text_element_style": {"bold": true, "text_color": 5}}},
      {"text_run": {"content": " 今日必须完成的核心任务"}}
    ],
    "style": {"align": 1}
  }
}

超链接：

{
  "block_type": 2,
  "text": {
    "elements": [
      {"text_run": {"content": "项目链接：", "text_element_style": {"bold": true}}},
      {"text_run": {"content": "点击查看", "text_element_style": {"link": {"url": "https://cunkebao.feishu.cn/wiki/xxx"}}}}
    ]
  }
}

无序列表（正文块模拟，推荐）：

{"block_type": 2, "text": {"elements": [{"text_run": {"content": "• 第一项要点"}}]}}
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "• 第二项要点"}}]}}
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "  • 子项（两空格缩进）"}}]}}

有序列表（正文块模拟，推荐）：

{"block_type": 2, "text": {"elements": [{"text_run": {"content": "1）第一步：需求分析"}}]}}
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "2）第二步：方案设计"}}]}}
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "3）第三步：代码实现"}}]}}

表格（TSV 正文回退，生产常用）：

{
  "block_type": 2,
  "text": {
    "elements": [{
      "text_run": {
        "content": "产品\t价格\t分润\n:---\t:---\t:---\n书籍小程序\t9.9元起\t90%\n会员群\t365元起\t平台收入"
      }
    }]
  }
}

---

3.2 标题块（block_type: 3-11）

字段名 = heading1~heading9，结构完全相同：

{"block_type": 3, "heading1": {"elements": [{"text_run": {"content": "一级大标题"}}]}}
{"block_type": 4, "heading2": {"elements": [{"text_run": {"content": "📋 二级标题"}}]}}
{"block_type": 5, "heading3": {"elements": [{"text_run": {"content": "三级标题"}}]}}
{"block_type": 6, "heading4": {"elements": [{"text_run": {"content": "3月12日  "}}], "style": {"align": 1}}}
{"block_type": 7, "heading5": {"elements": [{"text_run": {"content": "五级标题"}}]}}
{"block_type": 8, "heading6": {"elements": [{"text_run": {"content": "六级标题"}}]}}

---

3.3 代码块（block_type: 14）

{
  "block_type": 14,
  "code": {
    "elements": [{"text_run": {"content": "SOUL派对（流量入口）\n  ↓\n触客宝自动接待\n  ↓\n存客宝AI分层"}}],
    "style": {"language": 1}
  }
}

language 枚举值（脚本实测稳定值）：

值	语言	值	语言
1	PlainText（流程图/ASCII 推荐）	2	Python
3	JavaScript / TypeScript	6	Shell / Bash
8	SQL	9	JSON
11	HTML / XML	16	Go
22	Rust	—	—

md_to_feishu_json.py 的 LANG_MAP 使用上表值，已验证可正确渲染。飞书 API 官方文档的枚举编号与实测值存在出入，以脚本 LANG_MAP 为准。

---

3.4 待办块（block_type: 17）

{"block_type": 17, "todo": {
  "elements": [{"text_run": {"content": "Soul 派对→本月突破500在线 🎬 (0%)"}}],
  "style": {"done": false, "align": 1}
}}

{"block_type": 17, "todo": {
  "elements": [{"text_run": {"content": "运营报表已写入飞书"}}],
  "style": {"done": true, "align": 1}
}}

---

3.5 高亮块/标注（block_type: 19）

// 蓝色 [执行]
{"block_type": 19, "callout": {
  "emoji_id": "sunrise", "background_color": 2, "border_color": 2,
  "elements": [{"text_run": {"content": "[执行]", "text_element_style": {"bold": true, "text_color": 7}}}]
}}

// 橙色 [警告]
{"block_type": 19, "callout": {
  "emoji_id": "warning", "background_color": 4, "border_color": 4,
  "elements": [{"text_run": {"content": "注意：Token 2小时过期"}}]
}}

// 绿色 [完成]
{"block_type": 19, "callout": {
  "emoji_id": "white_check_mark", "background_color": 3, "border_color": 3,
  "elements": [{"text_run": {"content": "已完成：运营报表写入成功"}}]
}}

// 红色 [紧急]
{"block_type": 19, "callout": {
  "emoji_id": "fire", "background_color": 6, "border_color": 6,
  "elements": [{"text_run": {"content": "紧急：服务器宕机需立即处理"}}]
}}

background_color / border_color 枚举：

值	颜色	常用场景
1	白色/无	普通引用
2	蓝色	[执行]、信息提示
3	绿色	[完成]、成功
4	橙色	[警告]、注意
5	黄色	重点提醒
6	红色	[紧急]、错误
7	紫色	思考、创意

常用 emoji_id：sunrise🌅、warning⚠️、white_check_mark✅、bulb💡、fire🔥、star⭐、quote引用、rocket🚀、dart🎯、memo📝

---

3.6 分割线（block_type: 22）

{"block_type": 22, "divider": {}}

---

3.7 图片/文件块（block_type: 12，写入专用）

{"block_type": 12, "file": {
  "file_token": "上传后返回的 file_token",
  "view_type": "inline",
  "file_name": "进度图表.png"
}}

两步走：① POST drive/v1/medias/upload_all（form-data: file_name, parent_type=docx_image, parent_node=obj_token, size, file=binary）→ 拿 file_token ② 插入此块

view_type 枚举：preview（预览）、card（卡片）、inline（行内）

---

3.8 画廊块（block_type: 18）

{"block_type": 18, "gallery": {
  "image_list": [
    {"file_token": "xxx_file_token_1"},
    {"file_token": "xxx_file_token_2"}
  ],
  "gallery_style": {"align": "center"}
}}

一行最多 6 张图。align: center（默认）、left、right

---

3.9 分栏布局（block_type: 24 + 25）

分栏容器 grid：

{"block_type": 24, "grid": {"column_size": 2}}

分栏列 grid_column（须作为 grid 的子块插入）：

{"block_type": 25, "grid_column": {"width_ratio": 50}}

完整用法（两栏布局）：

1. 先创建 grid 块 → 拿到 grid_block_id
2. API 自动生成 column_size 个 grid_column 子块
3. 在每个 grid_column 下插入内容块

# 创建分栏（脚本 smart_write_wiki.py 中的实际写法）
grid_block = {"block_type": 24, "grid": {"column_size": 2}}
# 插入后拿到 grid_id，再查询其子块拿到两个 column_id
# 然后在 column_id 下分别插入左右内容

---

3.10 电子表格（block_type: 30）

{"block_type": 30, "sheet": {"row_size": 5, "column_size": 4}}

创建空表格，最大 9×9。创建后通过电子表格 API 写入单元格内容。
限制：不能在创建时直接带内容。

写入单元格：

PUT /sheets/v2/spreadsheets/{spreadsheet_token}/values
Body: {"valueRange": {"range": "sheet1!A1:D5", "values": [[...], ...]}}

列宽自动适配（v2.1 新增，强制在写完数据后执行）：

PUT /sheets/v2/spreadsheets/{spreadsheet_token}/dimension_range
Body:
{
  "dimension": {
    "sheetId": "<sheet_id>",
    "majorDimension": "COLUMNS",
    "startIndex": 0,
    "endIndex": 1
  },
  "dimensionProperties": {"pixelSize": 200}
}

• 对每一列循环调用，pixelSize 按内容自动计算：中文 ≈ 20px/字、ASCII ≈ 9px/字 + 24px 内边距。
• 最小 80px，最大 400px。
• v2.2：列宽 min 150px、max 520px；表头行+首列自动加粗（PUT .../styles appendStyle）；sanitize 去掉首尾 callout。
• feishu_publish_blocks_with_images.py 中 _auto_resize_sheet_columns + _apply_sheet_bold_style 已封装；md_to_feishu_json --no-callouts 将 > 转正文。

Markdown 表格分割行兼容（v2.1 修复）：

支持 2+ 破折号的分割行，不再要求最少 3 个：

|:--|:---| ✅ 有效（2 个破折号）
|:---|:---| ✅ 有效（3 个破折号）

---

3.11 表格块（block_type: 31，⚠️ 限制）

// 创建空表格（可行）
{"block_type": 31, "table": {"property": {"row_size": 3, "column_size": 4}}}

// 带 cells 创建（⚠️ 返回 9499 报错）
{"block_type": 31, "table": {"property": {"row_size": 3, "column_size": 4}, "cells": [...]}}

表格处理策略（决策树）：

Markdown 表格
├── 行列 ≤ 9×9 → 优先用 sheet(30) 创建空表格 + 写入单元格
├── 行列 > 9×9 → 用 text(2) TSV 回退
└── sheet 失败 → 用 text(2) TSV 回退（保底方案）

TSV 回退格式（稳定，推荐兜底）：

{"block_type": 2, "text": {
  "elements": [{"text_run": {
    "content": "文档名称\t路径\t核心内容\t状态\n:---\t:---\t:---\t:---\n品牌定位画布\t金/品牌定位.md\t一句话定位\t✅ 完成\n人物画像\t金/人物画像.md\tABCD用户画像\t✅ 完成"
  }}]
}}

---

3.12 多维表格（block_type: 43）

// 导出格式
{"block_type": 43, "board": {"token": "bascnXXXXXXXX"}}

// 写入格式（嵌入文档内）
{"block_type": 43, "bitable": {"token": "bascnXXXXXXXX"}}

⚠️ 须开通 bitable:app 用户身份权限。独立多维表格链接为 https://cunkebao.feishu.cn/base/{app_token}。

---

四、text_element_style 样式完整参数

{
  "text_element_style": {
    "bold": true,
    "italic": true,
    "strikethrough": true,
    "underline": true,
    "inline_code": true,
    "text_color": 5,
    "background_color": 2,
    "link": {"url": "https://..."}
  }
}

text_color 枚举：

值	颜色	场景
1	黑色（默认）	正文
2	深灰	次要信息
3	深橙
4	橙色	不重要紧急
5	红色	重要紧急标注
6	玫红
7	紫色	执行标注
8	浅蓝
9	深蓝
10	绿色	重要不紧急标注

---

五、style 对齐参数

"style": {"align": 1}

值	对齐方式
1	左对齐（默认）
2	居中
3	右对齐

适用于：text.style、heading*.style、todo.style

---

六、Markdown → 飞书 Block 转换规则（完整版）

Markdown 写法	飞书 block_type	字段名	备注
# 标题	3	heading1
## 标题	4	heading2
### 标题	5	heading3
#### 标题	6	heading4
##### 标题	7	heading5
###### 标题	8	heading6
普通段落	2	text
**加粗**	2	text + bold=true	elements 拆分
*斜体*	2	text + italic=true
~~删除线~~	2	text + strikethrough=true
`行内代码`	2	text + inline_code=true
[链接](url)	2	text + link.url
> 引用	19	callout（蓝色）
---	22	divider
```代码```	14	code	language 自动识别
	12	file（先 upload_all）	失败保底为文字
- 无序列表	2	text（• 前缀）	正文块模拟
1. 有序列表	2	text（1） 前缀）	正文块模拟
- [ ] 未完成	17	todo + done=false
- [x] 已完成	17	todo + done=true
Markdown 表格	30 或 2	sheet 或 TSV 回退	≤9×9 用 sheet

---

七、日志 TNTWF 格式对应 Block 结构

[
  {"block_type": 6, "heading4": {"elements": [{"text_run": {"content": "3月12日  "}}], "style": {"align": 1}}},
  {"block_type": 19, "callout": {"emoji_id": "sunrise", "background_color": 2, "border_color": 2,
    "elements": [{"text_run": {"content": "[执行]", "text_element_style": {"bold": true, "text_color": 7}}}]}},
  {"block_type": 2, "text": {
    "elements": [{"text_run": {"content": "[重要紧急]", "text_element_style": {"bold": true, "text_color": 5}}}],
    "style": {"align": 1}}},
  {"block_type": 17, "todo": {
    "elements": [{"text_run": {"content": "Soul 派对→本月突破500在线 🎬 (0%)"}}],
    "style": {"done": false, "align": 1}}},
  {"block_type": 2, "text": {
    "elements": [{"text_run": {"content": "[重要不紧急]", "text_element_style": {"bold": true, "text_color": 10}}}],
    "style": {"align": 1}}},
  {"block_type": 22, "divider": {}}
]

---

八、完整文档示例

{
  "title": "商业模式总览.md",
  "source": "材料/商业模式总览.md",
  "children": [
    {"block_type": 4, "heading2": {"elements": [{"text_run": {"content": "一、项目背景"}}]}},
    {"block_type": 5, "heading3": {"elements": [{"text_run": {"content": "市场痛点"}}]}},
    {"block_type": 2, "text": {"elements": [{"text_run": {
      "content": "痛点\t描述\n:---\t:---\n资源分散\t80%创业者缺乏有效渠道\n匹配低效\t有效链接率<5%"}}]}},
    {"block_type": 22, "divider": {}},
    {"block_type": 4, "heading2": {"elements": [{"text_run": {"content": "二、商业模式"}}]}},
    {"block_type": 14, "code": {"elements": [{"text_run": {
      "content": "SOUL派对（流量入口）\n  ↓\n触客宝自动接待\n  ↓\n存客宝AI分层（ABCD）\n  ↓\n精准变现"}}],
      "style": {"language": 1}}},
    {"block_type": 19, "callout": {"emoji_id": "bulb", "background_color": 2, "border_color": 2,
      "elements": [{"text_run": {"content": "核心模式：云阿米巴——不占股、分现钱、稳流量"}}]}},
    {"block_type": 2, "text": {"elements": [{"text_run": {"content": "• 产品一：书籍小程序 9.9元起"}}]}},
    {"block_type": 2, "text": {"elements": [{"text_run": {"content": "• 产品二：会员群 365元起"}}]}},
    {"block_type": 17, "todo": {"elements": [{"text_run": {"content": "完成产品矩阵报价表"}}],
      "style": {"done": false, "align": 1}}}
  ]
}

---

九、API 接口速查

用途	方法	路径
获取 Wiki 节点	GET	wiki/v2/spaces/get_node?token={wiki_token}
获取文档块列表	GET	docx/v1/documents/{doc_id}/blocks
追加子块（写入）	POST	docx/v1/documents/{doc_id}/blocks/{block_id}/children
批量删除块	POST	docx/v1/documents/{doc_id}/blocks/batch_delete
创建 Wiki 子节点	POST	wiki/v2/spaces/{space_id}/nodes
上传图片/文件	POST	drive/v1/medias/upload_all
创建多维表格	POST	bitable/v1/apps
写入电子表格单元格	PUT	sheets/v2/spreadsheets/{token}/values
设置列宽	PUT	sheets/v2/spreadsheets/{token}/dimension_range

追加子块请求体：

{"children": [块1, 块2, ...], "index": 0}

index: 0 = 最前；不传 = 末尾。单次 ≤ 50 块，超出分批。

---

十、脚本速查

脚本	用途	命令
md_to_feishu_json.py	Markdown → .feishu.json	python3 脚本/md_to_feishu_json.py /path/xxx.md
upload_json_to_feishu_doc.py	JSON 按格式上传	python3 脚本/upload_json_to_feishu_doc.py /path/xxx.json
batch_upload_json_to_feishu_wiki.py	批量目录上传	python3 脚本/batch_upload_json_to_feishu_wiki.py /目录 --wiki-parent <token>
feishu_article_unified_publish.py	Markdown 直传	python3 脚本/feishu_article_unified_publish.py --parent <t> --title "标题" --md /路径.md
feishu_wiki_create_doc.py	创建 Wiki 子文档	python3 脚本/feishu_wiki_create_doc.py --parent <t> --title "标题"
smart_write_wiki.py	智能写入（含分栏）	脚本内调用

---

十一、错误排查

问题	原因	解决
9499 Invalid parameter: cells	table(31) 带 cells 不支持	改用 TSV 正文(2) 或 sheet(30)
1770001 invalid param	字段名/格式错误	确认字段名正确；图片先上传再用 token
1770013	file_token 关联错误	upload_all 时 parent_node 用正确 obj_token
token 过期	access_token 有效期 2 小时	python3 脚本/feishu_token_cli.py get-access-token
多维表格权限不足	未开通 bitable:app	python3 脚本/feishu_force_reauth.py
块数 > 50 写入失败	单次限制 50 块	分批写入，每批 ≤ 50
sheet 超 9×9 报错	电子表格创建上限	改用 TSV 正文(2) 回退
写入串月	wiki_token 路由错误	写前校验文档标题含目标月份
表格列太窄挤压	默认列宽约 72px	v2.2：min 150px max 520px；_auto_resize_sheet_columns 自动调用
表格未识别（显示 ｜文字｜）	分割行破折号不足 3 个（:--）	脚本 v2.1 已修复，现接受 2+ 破折号
code(14)/callout(19) 写入失败	API 1770001	脚本自动降级为 text(2) 正文块，内容保留

---

版本：2.1 | 整理：卡若AI 水桥 | 更新：2026-02-22
数据来源：52 个 .feishu.json + 6 个脚本 + 飞书开放平台 API 文档
v2.2 变更：表格列宽 150~520px；表头+首列加粗（PUT styles）；首尾 callout 去除；--no-callouts。v2.1：列宽 API、code/callout 降级。