lark-wiki-writer

将 Markdown 格式内容解析并写入飞书知识库，支持标题、多级列表、富文本、代码块和本地图片自动上传插入。

飞书知识库文档写入器 - 支持 Markdown 解析、富文本、标题识别。

快速开始

步骤 1：创建飞书应用

1. 访问 飞书开放平台
2. 点击"创建企业自建应用"
3. 填写应用名称和描述
4. 记录 App ID 和 App Secret

步骤 2：配置应用权限

在应用管理页面，添加以下权限：

• ✅ 知识库 → 查看、编辑和管理知识空间
• ✅ 文档 → 查看、编辑和管理文档

步骤 3：获取知识库 Space ID

1. 打开飞书知识库
2. 在浏览器地址栏找到 Space ID（长数字串）
3. 例如：https://xxx.larksuite.com/wiki/space/7603663680785370844
   • Space ID 就是 7603663680785370844

步骤 4：获取父节点 Token（可选）

如果要在特定目录下创建文档：

1. 打开目标目录
2. 在地址栏找到 node_token
3. 例如：https://xxx.larksuite.com/wiki/JieGwPB0MiKhPbkkq9cltbPIgid
   • 父节点 token 就是 JieGwPB0MiKhPbkkq9cltbPIgid

步骤 5：配置环境变量

export LARK_APP_ID="cli_xxxxxxxxxx"
export LARK_APP_SECRET="xxxxxxxxxxxxxx"
export LARK_SPACE_ID="7603663680785370844"
export LARK_WIKI_DOMAIN="your-domain.larksuite.com"  # 可选
export LARK_PARENT_NODE="JieGwPB0MiKhPbkkq9cltbPIgid"  # 可选

或者创建配置文件 config.json：

{
  "app_id": "cli_xxxxxxxxxx",
  "app_secret": "xxxxxxxxxxxxxx",
  "space_id": "7603663680785370844",
  "wiki_domain": "your-domain.larksuite.com"
}

步骤 6：验证配置

python3 lark_wiki_writer.py validate \
  --app-id YOUR_APP_ID \
  --app-secret YOUR_APP_SECRET \
  --space-id YOUR_SPACE_ID

输出示例：

📊 配置验证结果

APP_ID: ✅
APP_SECRET: ✅
Space ID: ✅
Token 获取: ✅
知识库访问: ✅

---

核心功能

1. 标题识别

根据 # 数量自动识别标题级别：

Markdown	飞书 Block
# 标题	heading1
## 二级标题	heading2
### 三级标题	heading3
...	...
###### 六级标题	heading6

2. 富文本支持

Markdown	效果
**加粗**	加粗
*斜体*	斜体
***加粗斜体***	加粗斜体
~~删除线~~	删除线
`行内代码`	行内代码
[链接](url)	链接

3. 列表支持

- 无序列表项 1
- 无序列表项 2

1. 有序列表项 1
2. 有序列表项 2

4. 代码块

```python
def hello():
    print("Hello World")
```

支持的语言：python, javascript, typescript, go, rust, java, c, cpp, shell, bash, sql, html, css, json, yaml, xml, markdown

5. 分隔线

---

或

***

---

使用方法

方式 1：命令行参数

# 创建文档
python3 lark_wiki_writer.py create "文档标题" "# 内容" \
  --app-id YOUR_APP_ID \
  --app-secret YOUR_APP_SECRET \
  --space-id YOUR_SPACE_ID \
  --parent YOUR_PARENT_NODE

# 从文件写入
python3 lark_wiki_writer.py write_file "文档标题" /path/to/file.md \
  --app-id YOUR_APP_ID \
  --app-secret YOUR_APP_SECRET \
  --space-id YOUR_SPACE_ID

方式 2：环境变量

# 设置环境变量
export LARK_APP_ID="cli_xxx"
export LARK_APP_SECRET="xxx"
export LARK_SPACE_ID="xxx"
export LARK_PARENT_NODE="xxx"

# 使用
python3 lark_wiki_writer.py create "文档标题" "# 内容"
python3 lark_wiki_writer.py write_file "文档标题" report.md

方式 3：Python API

from lark_wiki_writer import LarkWikiWriter

# 初始化
writer = LarkWikiWriter(
    app_id="cli_xxx",
    app_secret="xxx",
    space_id="xxx",
    wiki_domain="your-domain.larksuite.com"
)

# 创建并写入
doc = writer.create_and_write(
    title="我的文档",
    content="""
# 主标题

## 二级标题

这是**加粗**和*斜体*内容。

### 列表
- 项目1
- 项目2

### 代码
```python
print("Hello")

""", parent_node_token="YOUR_PARENT_NODE" )

print(f"文档链接: {doc['url']}")

---

## 完整示例

### 示例 1：创建简单文档

```bash
python3 lark_wiki_writer.py create "测试文档" "# Hello World

这是一个测试文档。

## 功能
- 支持 Markdown
- 支持富文本
- 支持代码块" \
  --app-id cli_xxx \
  --app-secret xxx \
  --space-id xxx

示例 2：从 Markdown 文件创建

创建文件 report.md：

# 研究报告

## 摘要

这是一份关于 **Polymarket** 的研究报告。

## 主要发现

1. 市场规模持续增长
2. 用户活跃度提升
3. 技术架构稳定

## 数据分析

```python
import pandas as pd

data = pd.read_csv("data.csv")
print(data.head())

结论

Polymarket 是一个值得关注的预测市场平台。

---

报告完成于 2026-03-11

写入飞书：

```bash
python3 lark_wiki_writer.py write_file "Polymarket 研究报告" report.md \
  --app-id cli_xxx \
  --app-secret xxx \
  --space-id xxx \
  --parent JieGwPB0MiKhPbkkq9cltbPIgid

---

故障排查

问题 1：APP_ID 或 APP_SECRET 错误

错误信息：

❌ 配置错误: APP_ID 或 APP_SECRET 错误，请检查配置

解决方法：

1. 检查 App ID 和 App Secret 是否正确
2. 确认应用状态是否正常
3. 重新获取凭证

问题 2：应用权限不足

错误信息：

❌ 配置错误: 应用权限不足，请在飞书开放平台添加知识库权限

解决方法：

1. 进入飞书开放平台
2. 选择你的应用
3. 添加"知识库"和"文档"权限
4. 重新获取 access_token

问题 3：找不到知识库

错误信息：

❌ 知识库访问: ❌ space not found

解决方法：

1. 检查 Space ID 是否正确
2. 确认应用有访问该知识库的权限
3. 确认知识库未被删除

问题 4：缺少配置

错误信息：

❌ 配置错误: 缺少 LARK_APP_ID，请通过参数或环境变量提供

解决方法：

• 通过 --app-id 参数提供
• 或设置 LARK_APP_ID 环境变量

---

技术细节

API 端点

功能	端点
获取 token	POST /open-apis/auth/v3/tenant_access_token/internal
创建文档	POST /open-apis/wiki/v2/spaces/{space_id}/nodes
获取 blocks	GET /open-apis/docx/v1/documents/{obj_token}/blocks
写入 blocks	POST /open-apis/docx/v1/documents/{obj_token}/blocks/{block_id}/children

Block Type 对照

Block Type	说明
2	段落文本
3-11	heading1-heading9
12	无序列表
13	有序列表
14	代码块
22	分隔线

写入策略

1. 将 Markdown 解析为 block 结构
2. 批量写入（每批 10 个 blocks）
3. 块之间间隔 300ms 避免 API 限制

---

注意事项

1. ⚠️ Token 有效期：access_token 有效期 2 小时，过期需重新获取
2. ⚠️ API 限速：建议每秒不超过 10 次请求
3. ⚠️ 内容长度：单个 block 内容不要超过 5000 字符
4. ⚠️ 图片功能：当前版本图片功能为占位符，实际上传功能待完善

---

常见问题

Q: 如何获取飞书域名？

A: 在浏览器中打开飞书知识库，地址栏中的域名就是你的飞书域名。例如：

• https://omq113gwol.sg.larksuite.com/ → 域名是 omq113gwol.sg.larksuite.com

Q: 父节点 token 是必需的吗？

A: 不是必需的，但建议提供。如果不提供，需要设置 LARK_PARENT_NODE 环境变量。

Q: 支持哪些 Markdown 语法？

A: 支持标题、加粗、斜体、删除线、行内代码、链接、列表、代码块、分隔线。

Q: 可以更新已有文档吗？

A: 当前版本只支持创建新文档，不支持更新已有文档。

---

许可证

MIT License

---

贡献

欢迎提交 Issue 和 Pull Request！

---

更新日志

v1.0.0 (2026-03-11)

• ✅ 支持 Markdown 解析
• ✅ 支持富文本格式
• ✅ 支持标题识别
• ✅ 支持列表和代码块
• ✅ 添加配置验证命令
• ✅ 改进错误提示