lark-wiki-writer
by @griffithkk3-del
将 Markdown 格式内容解析并写入飞书知识库，支持标题、多级列表、富文本、代码块和本地图片自动上传插入。
clawhub install lark-wiki-writer📖 About This Skill
Lark Wiki Writer
飞书知识库文档写入器 - 支持 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 | 效果 |
|----------|------|
| 加粗 | 加粗 |
| *斜体* | *斜体* |
| *加粗斜体* | *加粗斜体* |
| ~~删除线~~ | ~~删除线~~ |
| ` 行内代码 | 行内代码 |
| 链接 | 链接 |
3. 列表支持
- 无序列表项 1
无序列表项 2 1. 有序列表项 1
2. 有序列表项 2
4. 代码块
支持的语言：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：创建简单文档
python3 lark_wiki_writer.py create "测试文档" "# Hello World这是一个测试文档。
功能
支持 Markdown
支持富文本
支持代码块" \
--app-id cli_xxx \
--app-secret xxx \
--space-id xxx
示例 2：从 Markdown 文件创建
创建文件
：# 研究报告摘要
这是一份关于 Polymarket 的研究报告。
主要发现
1. 市场规模持续增长
2. 用户活跃度提升
3. 技术架构稳定
数据分析
python
import pandas as pddata = pd.read_csv("data.csv")
print(data.head())
结论
Polymarket 是一个值得关注的预测市场平台。
*报告完成于 2026-03-11*
写入飞书：
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.comQ: 父节点 token 是必需的吗？
A: 不是必需的，但建议提供。如果不提供，需要设置
Q: 支持哪些 Markdown 语法？
A: 支持标题、加粗、斜体、删除线、行内代码、链接、列表、代码块、分隔线。
Q: 可以更新已有文档吗？
A: 当前版本只支持创建新文档，不支持更新已有文档。
许可证
MIT License
贡献
欢迎提交 Issue 和 Pull Request！
更新日志
v1.0.0 (2026-03-11)
📋 Tips & Best Practices
Q: 如何获取飞书域名？
A: 在浏览器中打开飞书知识库，地址栏中的域名就是你的飞书域名。例如：
https://omq113gwol.sg.larksuite.com/ → 域名是 omq113gwol.sg.larksuite.comQ: 父节点 token 是必需的吗？
A: 不是必需的，但建议提供。如果不提供，需要设置 LARK_PARENT_NODE 环境变量。
Q: 支持哪些 Markdown 语法？
A: 支持标题、加粗、斜体、删除线、行内代码、链接、列表、代码块、分隔线。
Q: 可以更新已有文档吗？
A: 当前版本只支持创建新文档，不支持更新已有文档。