# 飞书 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 出问题时

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

---

## 一、JSON 文件顶层结构

```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）—— 最常用

**最简版**：
```json
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "这是一段正文。"}}]}}
```

**带样式版（加粗 + 颜色）**：
```json
{
  "block_type": 2,
  "text": {
    "elements": [
      {"text_run": {"content": "[重要紧急]", "text_element_style": {"bold": true, "text_color": 5}}},
      {"text_run": {"content": " 今日必须完成的核心任务"}}
    ],
    "style": {"align": 1}
  }
}
```

**超链接**：
```json
{
  "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"}}}}
    ]
  }
}
```

**无序列表（正文块模拟，推荐）**：
```json
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "• 第一项要点"}}]}}
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "• 第二项要点"}}]}}
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "  • 子项（两空格缩进）"}}]}}
```

**有序列表（正文块模拟，推荐）**：
```json
{"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 正文回退，生产常用）**：
```json
{
  "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`，结构完全相同：

```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.3 代码块（block_type: 14）

```json
{
  "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）

```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}
}}
```

---

### 3.5 高亮块/标注（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": "紧急：服务器宕机需立即处理"}}]
}}
```

**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）

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

---

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

```json
{"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）

```json
{"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**：
```json
{"block_type": 24, "grid": {"column_size": 2}}
```

**分栏列 grid_column**（须作为 grid 的子块插入）：
```json
{"block_type": 25, "grid_column": {"width_ratio": 50}}
```

**完整用法（两栏布局）**：
```
1. 先创建 grid 块 → 拿到 grid_block_id
2. API 自动生成 column_size 个 grid_column 子块
3. 在每个 grid_column 下插入内容块
```

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

---

### 3.10 电子表格（block_type: 30）

```json
{"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，⚠️ 限制）

```json
// 创建空表格（可行）
{"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 回退格式（稳定，推荐兜底）**：
```json
{"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）

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

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

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

---

## 四、text_element_style 样式完整参数

```json
{
  "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 对齐参数

```json
"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 结构

```json
[
  {"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": {}}
]
```

---

## 八、完整文档示例

```json
{
  "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` |

**追加子块请求体**：
```json
{"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 降级。