feishu-doc-orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书文档创建主编排技能

Feishu Document Creation Orchestration Skill

快速开始

Quick Start

命令行使用

Command Line Usage

bash

undefined

bash

undefined

创建文档

Create document

python scripts/orchestrator.py input.md "文档标题"

python scripts/orchestrator.py input.md "Document Title"

使用默认标题（文件名）

Use default title (filename)

python scripts/orchestrator.py input.md

undefined

python scripts/orchestrator.py input.md

undefined

作为技能使用

Usage as a Skill

请帮我将 docs/example.md 转换为飞书文档

Please help me convert docs/example.md to a Feishu document

工作流程（五步编排）

Workflow (5-Step Orchestration)

这个技能编排 5 个子技能协作完成文档创建：

This skill orchestrates 5 sub-skills to collaborate on document creation:

第一步：Markdown 解析

Step 1: Markdown Parsing

调用

feishu-md-parser

子技能

输入：Markdown 文件路径
输出：
```
workflow/step1_parse/blocks.json
```
说明：将 Markdown 解析为飞书块格式

Call the

feishu-md-parser

sub-skill

Input: Markdown file path
Output:
```
workflow/step1_parse/blocks.json
```
Description: Parse Markdown into Feishu block format

第二步：文档创建+权限管理 ⭐ 原子操作

Step 2: Document Creation + Permission Management ⭐ Atomic Operation

调用

feishu-doc-creator-with-permission

子技能

输入：文档标题

输出：

workflow/step2_create_with_permission/doc_with_permission.json

说明：创建文档并自动完成权限分配（添加协作者+转移所有权）
⚠️ 重要：文档创建和权限管理合并，确保每次创建都正确分配权限

Call the

feishu-doc-creator-with-permission

sub-skill

Input: Document title

Output:

workflow/step2_create_with_permission/doc_with_permission.json

Description: Create a document and automatically complete permission assignment (add collaborators + transfer ownership)
⚠️ Important: Document creation and permission management are combined to ensure correct permission assignment for each creation

第三步：块添加

Step 3: Block Addition

调用

feishu-block-adder

子技能

输入：

step1_parse/blocks.json

step2_create_with_permission/doc_with_permission.json

输出：

workflow/step3_add_blocks/add_result.json

说明：分批添加内容块到文档

Call the

feishu-block-adder

sub-skill

Input:

step1_parse/blocks.json

step2_create_with_permission/doc_with_permission.json

Output:

workflow/step3_add_blocks/add_result.json

Description: Add content blocks to the document in batches

第四步：文档验证

Step 4: Document Verification

调用

feishu-doc-verifier

子技能

输入：

step2_create_with_permission/doc_with_permission.json

输出：

workflow/step4_verify/verify_result.json

说明：使用 Playwright 验证文档可访问

Call the

feishu-doc-verifier

sub-skill

Input:

step2_create_with_permission/doc_with_permission.json

Output:

workflow/step4_verify/verify_result.json

Description: Use Playwright to verify document accessibility

第五步：日志记录

Step 5: Logging

调用

feishu-logger

子技能

输入：所有步骤的结果文件
输出：
```
CREATED_DOCS.md
```
+
```
created_docs.json
```
说明：汇总记录到日志文件

Call the

feishu-logger

sub-skill

Input: Result files from all steps
Output:
```
CREATED_DOCS.md
```
+
```
created_docs.json
```
Description: Summarize and record to log files

数据流（文件传递）

Data Flow (File Transfer)

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

input.md
    ↓
[feishu-md-parser]
    ↓ workflow/step1_parse/blocks.json
[feishu-doc-creator-with-permission] ⭐ Creation + Permission Atomic Operation
    ↓ 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

关键设计原则

Key Design Principles

1. 只传文件路径，不传内容

1. Only pass file paths, not content

子技能之间只传递文件路径，不传递实际内容，节省 Token。

Sub-skills only pass file paths instead of actual content to save Tokens.

2. 中间结果保存为文件

2. Save intermediate results as files

每一步的结果都保存到

workflow/

目录，可追溯、可断点续传。

Results of each step are saved to the

workflow/

directory, enabling traceability and resumable execution.

3. 自然语言编排

3. Natural language orchestration

主技能用自然语言描述流程，子技能各自独立可测试。

The main skill describes the process in natural language, and each sub-skill is independent and testable.

4. 单一职责

4. Single Responsibility

每个子技能只做一件事：

```
feishu-md-parser
```
：只解析 Markdown
```
feishu-doc-creator-with-permission
```
：创建文档并分配权限（原子操作）⭐
```
feishu-block-adder
```
：只添加块
```
feishu-doc-verifier
```
：只验证文档
```
feishu-logger
```
：只记录日志

Each sub-skill only does one thing:

```
feishu-md-parser
```
: Only parses Markdown
```
feishu-doc-creator-with-permission
```
: Creates documents and assigns permissions (atomic operation) ⭐
```
feishu-block-adder
```
: Only adds blocks
```
feishu-doc-verifier
```
: Only verifies documents
```
feishu-logger
```
: Only records logs

工作流目录结构

Workflow Directory Structure

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      # 验证结果

workflow/
├── step1_parse/
│   ├── blocks.json       # Parsed block data
│   └── metadata.json     # Parsing metadata
├── step2_create_with_permission/
│   └── doc_with_permission.json  # Document info + permission status ⭐
├── step3_add_blocks/
│   └── add_result.json   # Block addition result
└── step4_verify/
    └── verify_result.json      # Verification result

输出结果

Output Results

成功完成后，你会得到：

文档 URL：可直接访问的飞书文档链接
CREATED_DOCS.md：Markdown 格式的创建日志
created_docs.json：JSON 格式的创建日志
workflow/：完整的中间结果，可追溯每一步

After successful completion, you will get:

Document URL: Directly accessible Feishu document link
CREATED_DOCS.md: Creation log in Markdown format
created_docs.json: Creation log in JSON format
workflow/: Complete intermediate results, allowing traceability of each step

配置要求

Configuration Requirements

需要配置

.claude/feishu-config.env

：

ini

FEISHU_APP_ID = "cli_xxx"
FEISHU_APP_SECRET = "xxxxxxxx"
FEISHU_API_DOMAIN = "https://open.feishu.cn"
FEISHU_AUTO_COLLABORATOR_ID = "ou_xxx"

Need to configure

.claude/feishu-config.env

ini

FEISHU_APP_ID = "cli_xxx"
FEISHU_APP_SECRET = "xxxxxxxx"
FEISHU_API_DOMAIN = "https://open.feishu.cn"
FEISHU_AUTO_COLLABORATOR_ID = "ou_xxx"

使用示例

Usage Examples

示例1：基本使用

Example 1: Basic Usage

请帮我将 .claude/skills/feishu-doc-creator/test_doc.md 转换为飞书文档

Please help me convert .claude/skills/feishu-doc-creator/test_doc.md to a Feishu document

示例2：指定标题

Example 2: Specify Title

请将 docs/report.md 转为飞书文档，标题设为"周报-2026-01-22"

Please convert docs/report.md to a Feishu document with the title "Weekly Report - 2026-01-22"

示例3：断点续传

Example 3: Resumable Workflow

如果某一步失败，可以手动修改中间结果后继续：

undefined

If a step fails, you can manually modify the intermediate results and continue:

undefined

第2步创建+权限失败，手动重新执行

Step 2 creation + permission failed, manually re-execute

python .claude/skills/feishu-doc-creator-with-permission/scripts/doc_creator_with_permission.py "文档标题" workflow/step2_create_with_permission

undefined

python .claude/skills/feishu-doc-creator-with-permission/scripts/doc_creator_with_permission.py "Document Title" workflow/step2_create_with_permission

undefined

常见问题

Frequently Asked Questions

Q1: 某一步失败了怎么办？

Q1: What to do if a step fails?

A: 查看

workflow/stepX_*/

目录下的 JSON 文件，可以手动修复后继续下一步。

A: Check the JSON files in the

workflow/stepX_*/

directory, you can manually fix them and proceed to the next step.

Q2: 如何只执行某一步？

Q2: How to execute only a specific step?

A: 直接调用对应的子技能脚本，传入正确的文件路径。

A: Directly call the corresponding sub-skill script and pass the correct file path.

Q3: Token 节省效果如何？

Q3: How effective is Token saving?

A: 文件传递方式比内容传递节省约 60-80% 的 Token。

A: The file transfer method saves approximately 60-80% of Tokens compared to content transfer.

⚠️ 重要调试说明

⚠️ Important Debugging Notes

Callout 块颜色问题

Callout Block Color Issue

如果创建的 callout（高亮块）没有颜色和边框：

原因：Callout 块的颜色字段必须直接放在

callout

对象下，不能嵌套在

style

中。

验证方法：检查 API 返回的 callout 对象是否包含颜色字段：

python

undefined

If the created callout (highlight block) has no color or border:

Cause: The color field of the callout block must be placed directly under the

callout

object, not nested in

style

Verification Method: Check if the callout object returned by the API contains the color field:

python

undefined

如果只有 emoji_id 而没有 background_color，说明格式错误

If only emoji_id exists without background_color, the format is incorrect

returned_callout = result["data"]["children"][0].get("callout", {})


**解决方案**：已在 `feishu-md-parser` 和 `feishu-block-adder` 中修复。

**详细排查**：见 `TROUBLESHOOTING.md`（问题 1）

**测试脚本**：`test_callout_only.py` - 单独测试 callout 格式

returned_callout = result["data"]["children"][0].get("callout", {})


**Solution**: Already fixed in `feishu-md-parser` and `feishu-block-adder`.

**Detailed Troubleshooting**: See `TROUBLESHOOTING.md` (Issue 1)

**Test Script**: `test_callout_only.py` - Test callout format independently