karuo-ai/02_卡人（水）/水桥_平台对接/飞书管理/飞书JSON格式_SKILL.md

name, description, triggers, owner, group, version, updated

name	description	triggers	owner	group	version	updated
飞书JSON格式	飞书文档 JSON 格式速查、编写、上传与翻译；各 block_type 格式写法、Markdown 转换对照、表格列宽自适应、脚本 SOP 一站式参考	飞书json、飞书json格式、飞书block、飞书块格式、飞书文档格式、json上传飞书、飞书格式怎么写、block_type、飞书块类型、飞书写入格式、飞书上传json、飞书文档block、飞书高亮块、飞书代码块、飞书待办块、飞书标题块、飞书分割线、飞书callout、飞书多维表格json、飞书列表、飞书表格、飞书分栏、更新飞书JSON格式、飞书列宽、表格列宽	水桥	水	2.1	2026-02-22

飞书 JSON 格式 Skill

搞定了，清清爽爽。—— 卡人（水）

---

能做什么（Capabilities）

• 速查 block_type：根据需求快速输出对应格式的完整 JSON 块
• Markdown 翻译：把任意 Markdown 内容转成飞书 blocks 数组
• 上传文档：利用现有脚本将 JSON 或 Markdown 上传到飞书 Wiki
• 格式排版：对文档内容进行飞书风格的结构化整理
• 表格策略：根据行列数自动选择 sheet/TSV 回退方案
• API 对照：提供飞书 Docx API 路径、参数、错误排查

---

怎么用（Usage）

触发词：飞书json、飞书block、block_type、飞书格式怎么写、飞书文档格式、json上传飞书、飞书callout、飞书高亮块、飞书待办、飞书代码块、飞书多维表格、飞书列表、飞书表格、飞书分栏

---

强制操作流程（SOP · 以后所有飞书文档按此执行）

流程 A：写文档 → 转 JSON → 上传

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. 打开飞书链接验证格式

流程 B：Markdown 直传（不经 JSON）

python3 /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/水桥_平台对接/飞书管理/脚本/feishu_article_unified_publish.py \
  --parent <wiki_node_token> --title "标题" --md /绝对路径/文章.md

流程 C：批量目录上传

python3 /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/水桥_平台对接/飞书管理/脚本/batch_upload_json_to_feishu_wiki.py \
  /本地目录 --wiki-parent <token>

流程 D：飞书导出 JSON 回传

python3 /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/水桥_平台对接/飞书管理/脚本/upload_json_to_feishu_doc.py \
  /path/to/导出.json --parent <token> --title "标题"

流程 E：AI 直接生成 blocks 写入

1. 用户描述文档内容
   ↓
2. AI 按下方「格式速查卡」生成 children 数组
   ↓
3. 调用 feishu_wiki_create_doc.py 或 API 写入

---

执行步骤（Steps）

场景 A：生成飞书 JSON blocks

1. 理解用户内容需求
2. 按「格式速查卡」选择对应块类型
3. 输出完整 children 数组，可直接写入

场景 B：Markdown → 飞书 blocks

1. 解析标题层级（#→3，##→4，###→5，####→6）
2. 按「转换规则表」逐段转换
3. 输出 .feishu.json（title + source + children）

场景 C：内容涉及表格时的决策

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

---

格式速查卡（完整块类型）

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}}}], "style": {"align": 1}}}

// 超链接
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "点击查看", "text_element_style": {"link": {"url": "https://..."}}}}]}}

// 无序列表（正文块 + • 前缀，推荐）
{"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）方案设计"}}]}}

// 表格 TSV 回退（制表符分隔）
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "产品\t价格\t分润\n:---\t:---\t:---\n书籍小程序\t9.9元起\t90%"}}]}}

2. 标题（block_type: 3-11）

{"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. 高亮块 callout（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": "紧急：需立即处理"}}]}}

callout 颜色对照：1=白 2=蓝 3=绿 4=橙 5=黄 6=红 7=紫

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

4. 代码块（block_type: 14）

{"block_type": 14, "code": {
  "elements": [{"text_run": {"content": "流量入口\n  ↓\n存客宝AI分层\n  ↓\n精准变现"}}],
  "style": {"language": 1}
}}

language（脚本实测值，与 md_to_feishu_json.py LANG_MAP 对应）：

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

5. 待办（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}}}

6. 分割线（block_type: 22）

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

7. 图片文件（block_type: 12）

# 第一步：上传拿 file_token
POST drive/v1/medias/upload_all  (form-data: file_name, parent_type=docx_image, parent_node=obj_token, size, file)

// 第二步：插入 file 块
{"block_type": 12, "file": {"file_token": "xxx", "view_type": "inline", "file_name": "chart.png"}}

// 或画廊块（多图）
{"block_type": 18, "gallery": {"image_list": [{"file_token": "xxx"}], "gallery_style": {"align": "center"}}}

8. 分栏（block_type: 24 + 25）

// 创建两栏容器
{"block_type": 24, "grid": {"column_size": 2}}
// 子列（API 自动生成，内容插入到各列下）
{"block_type": 25, "grid_column": {"width_ratio": 50}}

9. 电子表格（block_type: 30）

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

最大 9×9，创建后通过 sheets API 写入单元格。

表格列宽自动适配（强制执行，写完数据后立刻调用）：

PUT /sheets/v2/spreadsheets/{spreadsheet_token}/dimension_range

{
  "dimension": {
    "sheetId": "<sheet_id>",
    "majorDimension": "COLUMNS",
    "startIndex": 0,
    "endIndex": 1
  },
  "dimensionProperties": {"pixelSize": 200}
}

• 中文字符 ≈ 20px/字，ASCII ≈ 9px/字，加 24px 内边距；最小 80px，最大 400px。
• 脚本 feishu_publish_blocks_with_images.py 的 _auto_resize_sheet_columns() 自动完成此步骤，无需手动调用。

10. 多维表格（block_type: 43）

{"block_type": 43, "bitable": {"token": "bascnXXX"}}

须 bitable:app 权限

---

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

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

---

text_element_style 参数

{
  "bold": true, "italic": true, "strikethrough": true, "underline": true, "inline_code": true,
  "text_color": 5,         // 1黑 2深灰 3深橙 4橙 5红 6玫红 7紫 8浅蓝 9深蓝 10绿
  "background_color": 2,
  "link": {"url": "https://..."}
}

---

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
上传图片/文件	POST	drive/v1/medias/upload_all
创建 Wiki 子节点	POST	wiki/v2/spaces/{space_id}/nodes
创建多维表格	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 块

---

错误排查

错误码	原因	解决
9499	table(31) 带 cells 不支持	TSV 正文(2) 或 sheet(30)
1770001	字段名/格式错误	确认字段名；图片先上传再插入
1770013	file_token 关联错误	parent_node 用正确的 obj_token
token 过期	2小时有效期	python3 脚本/feishu_token_cli.py get-access-token
多维表格权限不足	未开通 bitable:app	python3 脚本/feishu_force_reauth.py
块数 > 50	单次写入上限	分批，每批 ≤ 50
sheet >9×9	电子表格上限	改用 TSV 正文(2) 回退
表格列挤压	sheet 默认列宽约 72px	_auto_resize_sheet_columns() 写完后自动调用 PUT dimension_range
code/callout 写入失败	1770001	脚本自动降级为 text(2) 正文块，内容不丢失

---

相关文件（Files）

• 全量手册：参考资料/飞书JSON格式全手册.md（v2.0，含完整枚举+SOP+决策树）
• API 对照：参考资料/飞书日志JSON格式与API对照.md
• 图片 API：参考资料/飞书docx插入图片_API说明.md
• 转换脚本：脚本/md_to_feishu_json.py
• 上传脚本：脚本/upload_json_to_feishu_doc.py
• 批量上传：脚本/batch_upload_json_to_feishu_wiki.py
• 统一发布：脚本/feishu_article_unified_publish.py
• 项目样本：/Users/karuo/Documents/1、金：项目/3、自营项目/soul创业实验/飞书格式/（52 个文件）

---

依赖（Dependencies）

• 前置技能：W07 飞书管理（Token 授权、写入日志）
• 外部工具：python3、飞书开放平台 access_token