359 lines
13 KiB
Markdown
359 lines
13 KiB
Markdown
---
|
||
name: 飞书JSON格式
|
||
description: 飞书文档 JSON 格式速查、编写、上传与翻译；各 block_type 格式写法、Markdown 转换对照、表格列宽自适应、脚本 SOP 一站式参考
|
||
triggers: 飞书json、飞书json格式、飞书block、飞书块格式、飞书文档格式、json上传飞书、飞书格式怎么写、block_type、飞书块类型、飞书写入格式、飞书上传json、飞书文档block、飞书高亮块、飞书代码块、飞书待办块、飞书标题块、飞书分割线、飞书callout、飞书多维表格json、飞书列表、飞书表格、飞书分栏、更新飞书JSON格式、飞书列宽、表格列宽
|
||
owner: 水桥
|
||
group: 水
|
||
version: "2.1"
|
||
updated: "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）
|
||
|
||
```bash
|
||
python3 /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/水桥_平台对接/飞书管理/脚本/feishu_article_unified_publish.py \
|
||
--parent <wiki_node_token> --title "标题" --md /绝对路径/文章.md
|
||
```
|
||
|
||
### 流程 C：批量目录上传
|
||
|
||
```bash
|
||
python3 /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/水桥_平台对接/飞书管理/脚本/batch_upload_json_to_feishu_wiki.py \
|
||
/本地目录 --wiki-parent <token>
|
||
```
|
||
|
||
### 流程 D：飞书导出 JSON 回传
|
||
|
||
```bash
|
||
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）
|
||
|
||
```json
|
||
// 普通正文
|
||
{"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）
|
||
|
||
```json
|
||
{"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）
|
||
|
||
```json
|
||
// 蓝色 [执行]
|
||
{"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）
|
||
|
||
```json
|
||
{"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）
|
||
|
||
```json
|
||
{"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）
|
||
|
||
```json
|
||
{"block_type": 22, "divider": {}}
|
||
```
|
||
|
||
### 7. 图片文件（block_type: 12）
|
||
|
||
```bash
|
||
# 第一步：上传拿 file_token
|
||
POST drive/v1/medias/upload_all (form-data: file_name, parent_type=docx_image, parent_node=obj_token, size, file)
|
||
```
|
||
|
||
```json
|
||
// 第二步：插入 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）
|
||
|
||
```json
|
||
// 创建两栏容器
|
||
{"block_type": 24, "grid": {"column_size": 2}}
|
||
// 子列（API 自动生成，内容插入到各列下）
|
||
{"block_type": 25, "grid_column": {"width_ratio": 50}}
|
||
```
|
||
|
||
### 9. 电子表格（block_type: 30）
|
||
|
||
```json
|
||
{"block_type": 30, "sheet": {"row_size": 5, "column_size": 4}}
|
||
```
|
||
|
||
> 最大 9×9，创建后通过 sheets API 写入单元格。
|
||
|
||
**表格列宽自动适配（强制执行，写完数据后立刻调用）**：
|
||
|
||
```bash
|
||
PUT /sheets/v2/spreadsheets/{spreadsheet_token}/dimension_range
|
||
```
|
||
|
||
```json
|
||
{
|
||
"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）
|
||
|
||
```json
|
||
{"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 参数
|
||
|
||
```json
|
||
{
|
||
"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
|