| name | feishu-doc-orchestrator |
| description | 飞书文档创建主编排技能 - 将 Markdown 文件转换为飞书文档，编排多个子技能协作完成，使用文件传递数据以节省 Token。 |
飞书文档创建主编排技能
快速开始
命令行使用
python scripts/orchestrator.py input.md "文档标题"
python scripts/orchestrator.py input.md
作为技能使用
请帮我将 docs/example.md 转换为飞书文档
工作流程（五步编排）
这个技能编排 5 个子技能协作完成文档创建：
第一步：Markdown 解析
调用 feishu-md-parser 子技能
- 输入：Markdown 文件路径
- 输出：
workflow/step1_parse/blocks.json
- 说明：将 Markdown 解析为飞书块格式
第二步：文档创建+权限管理 ⭐ 原子操作
调用 feishu-doc-creator-with-permission 子技能
- 输入：文档标题
- 输出：
workflow/step2_create_with_permission/doc_with_permission.json
- 说明：创建文档并自动完成权限分配（添加协作者+转移所有权）
- ⚠️ 重要：文档创建和权限管理合并，确保每次创建都正确分配权限
第三步：块添加
调用 feishu-block-adder 子技能
- 输入：
step1_parse/blocks.json + step2_create_with_permission/doc_with_permission.json
- 输出：
workflow/step3_add_blocks/add_result.json
- 说明：分批添加内容块到文档
第四步：文档验证
调用 feishu-doc-verifier 子技能
- 输入：
step2_create_with_permission/doc_with_permission.json
- 输出：
workflow/step4_verify/verify_result.json
- 说明：使用 Playwright 验证文档可访问
第五步：日志记录
调用 feishu-logger 子技能
- 输入：所有步骤的结果文件
- 输出：
CREATED_DOCS.md + created_docs.json
- 说明：汇总记录到日志文件
数据流（文件传递）
input.md
↓
[feishu-md-parser]
↓ workflow/step1_parse/blocks.json
[feishu-doc-creator-with-permission] ⭐ 创建+权限原子操作
↓ workflow/step2_create_with_permission/doc_with_permission.json
├─→ [feishu-block-adder] → workflow/step3_add_blocks/add_result.json
└─→ [feishu-doc-verifier] → workflow/step4_verify/verify_result.json
[feishu-logger]
↓
CREATED_DOCS.md + created_docs.json
关键设计原则
1. 只传文件路径，不传内容
子技能之间只传递文件路径，不传递实际内容，节省 Token。
2. 中间结果保存为文件
每一步的结果都保存到 workflow/ 目录，可追溯、可断点续传。
3. 自然语言编排
主技能用自然语言描述流程，子技能各自独立可测试。
4. 单一职责
每个子技能只做一件事：
feishu-md-parser：只解析 Markdownfeishu-doc-creator-with-permission：创建文档并分配权限（原子操作）⭐feishu-block-adder：只添加块feishu-doc-verifier：只验证文档feishu-logger：只记录日志
工作流目录结构
workflow/
├── step1_parse/
│ ├── blocks.json # 解析后的块数据
│ └── metadata.json # 解析元数据
├── step2_create_with_permission/
│ └── doc_with_permission.json # 文档信息+权限状态 ⭐
├── step3_add_blocks/
│ └── add_result.json # 块添加结果
└── step4_verify/
└── verify_result.json # 验证结果
输出结果
成功完成后，你会得到：
- 文档 URL：可直接访问的飞书文档链接
- CREATED_DOCS.md：Markdown 格式的创建日志
- created_docs.json：JSON 格式的创建日志
- workflow/：完整的中间结果，可追溯每一步
配置要求
需要配置 .claude/feishu-config.env：
FEISHU_APP_ID = "cli_xxx"
FEISHU_APP_SECRET = "xxxxxxxx"
FEISHU_API_DOMAIN = "https://open.feishu.cn"
FEISHU_AUTO_COLLABORATOR_ID = "ou_xxx"
使用示例
示例1：基本使用
请帮我将 .claude/skills/feishu-doc-creator/test_doc.md 转换为飞书文档
示例2：指定标题
请将 docs/report.md 转为飞书文档，标题设为"周报-2026-01-22"
示例3：断点续传
如果某一步失败，可以手动修改中间结果后继续：
# 第2步创建+权限失败，手动重新执行
python .claude/skills/feishu-doc-creator-with-permission/scripts/doc_creator_with_permission.py "文档标题" workflow/step2_create_with_permission
常见问题
Q1: 某一步失败了怎么办？
A: 查看 workflow/stepX_*/ 目录下的 JSON 文件，可以手动修复后继续下一步。
Q2: 如何只执行某一步？
A: 直接调用对应的子技能脚本，传入正确的文件路径。
Q3: Token 节省效果如何？
A: 文件传递方式比内容传递节省约 60-80% 的 Token。
⚠️ 重要调试说明
Callout 块颜色问题
如果创建的 callout（高亮块）没有颜色和边框：
原因：Callout 块的颜色字段必须直接放在 callout 对象下，不能嵌套在 style 中。
验证方法：检查 API 返回的 callout 对象是否包含颜色字段：
returned_callout = result["data"]["children"][0].get("callout", {})
解决方案：已在 feishu-md-parser 和 feishu-block-adder 中修复。
详细排查：见 TROUBLESHOOTING.md（问题 1）
测试脚本：test_callout_only.py - 单独测试 callout 格式
