Feishu Doc Block Writer

SKILL.md

# feishu-doc-block-writer - 飞书文档 Block 拆分写入技能

## 📋 技能描述

**功能：** 自动将长内容拆分为多个 Blocks 写入飞书文档，避免空白文档问题

**核心原则：**
- ✅ 使用 `create` 创建空文档
- ✅ 使用 `append` 逐块追加内容
- ✅ 每块 500-1000 字
- ✅ 避免一次性长文本写入
- ✅ 创建后立即验证内容

---

## 🎯 触发条件

**自动触发：**
- 内容超过 500 字
- 用户要求"创建飞书文档"
- 回答超过 200 字（200 字规则）
- 包含 Mermaid 图表

**手动触发：**
- 用户说"用 Block 拆分方式创建文档"
- 用户说"避免空白文档"

---

## 🔧 配置要求

### 飞书凭证（可选）

如果 feishu_doc 工具需要额外配置：

```json
{
  "default_assignee": "ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "auto_open_chrome": true,
  "verify_after_create": true
}
```

**⚠️ 安全警告：**
- ❌ **禁止**在公开代码中暴露真实 Open ID
- ✅ 使用 `ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` 作为占位符
- ✅ 在配置文件中存储真实 Open ID（不提交到版本控制）
- ✅ 发布到 ClawHub 前检查是否打码

### 用法

```bash
python block-writer.py \
  --title "标题" \
  --content "内容..." \
  --parent-node-token "W5udwK8V7ip7bskn3EhcPTbOnOp"  # 可选：指定文件夹
```

**参数说明：**
- `--title`（必填）：文档标题
- `--content`（必填）：文档内容
- `--chunk-size`（可选）：每块字数，默认 500
- `--parent-node-token`（可选）：指定文档存放的文件夹 token
  - 如不指定，默认创建在知识库根目录
  - 示例：想法文件夹 token = W5udwK8V7ip7bskn3EhcPTbOnOp
- `--no-verify`（可选）：禁用创建后验证

---

## 📄 核心文件

### 主脚本：`block-writer.py`

**位置：** `~/.agents/skills/feishu-doc-block-writer/scripts/block-writer.py`

**功能：**
1. 接收长文本内容
2. 自动拆分为多个 Blocks（每块 500-1000 字）
3. 调用 feishu_doc 创建空文档
4. 逐块追加内容
5. 返回文档链接

**用法：**
```bash
python block-writer.py --title "文档标题" --content "长文本内容..."
```

---

## 🚀 工作流程

```mermaid
flowchart TB
    A[接收长文本] --> B{字数判断}
    B -->|≤500 字 | C[一次性写入]
    B -->|>500 字 | D[自动拆分 Blocks]
    D --> E[创建空文档]
    E --> F[逐块追加]
    F --> G[验证内容]
    G --> H[返回链接]
    C --> H
    
    style A fill:#e1f5ff
    style D fill:#ffe1e1
    style F fill:#e1ffe1
    style H fill:#fff4e1
```

---

## 💡 使用示例

### 示例 1：创建长文档

**输入：**
```python
content = "5000 字的长文本内容..."
```

**处理：**
1. 检测到 5000 字 > 500 字阈值
2. 拆分为 10 个 Blocks（每块约 500 字）
3. 创建空文档
4. 逐块追加 10 次
5. 返回文档链接

**结果：** ✅ 正常显示，无空白文档

---

### 示例 2：创建带 Mermaid 图表的文档

**输入：**
```markdown
# 标题

## 流程图

```mermaid
graph LR
    A --> B
```

## 详细说明
...（长文本）
```

**处理：**
1. 检测 Mermaid 代码块
2. 单独作为一个 Block
3. 文本内容按 500 字拆分
4. 逐块写入

**结果：** ✅ Mermaid 图表正常渲染

---

### 示例 3：创建在指定文件夹

**输入：**
```bash
python block-writer.py \
  --title "想法文档" \
  --content "内容..." \
  --parent-node-token "W5udwK8V7ip7bskn3EhcPTbOnOp"
```

**结果：**
- ✅ 文档创建在"想法"文件夹内
- ✅ 不是知识库根目录
- ✅ 文件夹位置由 parent_node_token 指定

---

### 示例 4：创建在知识库根目录（默认行为）

**输入：**
```bash
python block-writer.py \
  --title "根目录文档" \
  --content "内容..."
```

**结果：**
- ✅ 文档创建在知识库根目录
- ✅ 向后兼容，不传参数时行为不变

---

### 示例 5：使用阿香模板（推荐）✨

**输入：**
```bash
python create-doc-template.py "文档标题" "文档内容" "想法"
```

**处理流程：**
1. ✅ 自动读取配置文件（second-brain-folder-config.json）
2. ✅ 根据分类获取 folder_token
3. ✅ 调用 block-writer.py 创建文档
4. ✅ 自动验证文档位置
5. ✅ 自动写入归档记录到 memory

**优势：**
- ✅ 自动读取配置文件 - 无需手动指定 folder_token
- ✅ 自动验证位置 - 确保文档在正确文件夹
- ✅ 自动写入归档 - 记录到 memory/YYYY-MM-DD.md
- ✅ 分类管理 - 支持想法/项目/笔记/资料/归档

**分类说明：**
| 分类 | 说明 | 自动获取 folder_token |
|------|------|----------------------|
| 想法 | 日常想法、灵感 | ✅ |
| 项目 | 项目文档 | ✅ |
| 笔记 | 学习笔记 | ✅ |
| 资料 | 参考资料 | ✅ |
| 归档 | 历史归档 | ✅ |

**输出示例：**
```
🦞 阿香文档创建模板
============================================================

📖 步骤 1: 读取配置文件...
✅ 配置加载成功

📁 步骤 2: 获取 folder_token...
✅ Using folder_token: W5udwK8V7ip7bskn3EhcPTbOnOp (想法)

✏️  步骤 3: 创建文档...
✅ Document created: ABCxyz123456
🔗 文档链接：https://scns3ak4jrto.feishu.cn/docx/ABCxyz123456

🔍 步骤 4: 验证文档位置...
✅ 位置验证通过

📝 步骤 5: 写入归档记录...
✅ 归档记录已写入：memory/2026-03-20.md

============================================================
✅ 创建完成
============================================================
```

---

## 📊 测试验证

### 测试步骤

```bash
# 1. 创建测试文档（指定文件夹）
python block-writer.py \
  --title "测试 - 文件夹位置" \
  --content "测试内容" \
  --parent-node-token "W5udwK8V7ip7bskn3EhcPTbOnOp"

# 2. 验证文档位置
# 使用 feishu_wiki get 检查 parent_node_token

# 3. 输出测试结果
if doc.parent_node_token == "W5udwK8V7ip7bskn3EhcPTbOnOp":
    print("✅ 测试通过：文档在正确的文件夹内")
else:
    print("❌ 测试失败：文档位置错误")
```

### 验收标准

- [x] SKILL.md 已更新（添加参数说明）
- [x] block-writer.py 已修正（支持 parent_node_token）
- [x] 向后兼容（不传参数时默认行为不变）
- [x] 使用示例已添加

---

## 🔍 常见问题

### Q1: 如何获取文件夹的 parent_node_token？

**A:** 使用 `feishu_wiki` 工具查询：
```bash
openclaw feishu_wiki --action get --token <文件夹 token>
```

### Q2: 不传 parent_node_token 会怎样？

**A:** 文档会创建在知识库根目录，保持向后兼容。

### Q3: 可以批量创建多个文档到同一文件夹吗？

**A:** 可以，重复使用相同的 parent_node_token 即可。

---

**输入：**
```markdown
# 标题

## 流程图

```mermaid
graph LR
    A --> B
```

## 详细说明
...（长文本）
```

**处理：**
1. 检测 Mermaid 代码块
2. 单独作为一个 Block
3. 文本内容按 500 字拆分
4. 逐块写入

**结果：** ✅ Mermaid 图表正常渲染

---

## 🔍 拆分策略

### 智能拆分算法

```python
def split_content(content, chunk_size=500):
    """
    智能拆分内容
    
    规则：
    1. 优先在段落边界拆分（\n\n）
    2. 其次在句子边界拆分（。！？.!?）
    3. 避免在词语中间拆分
    4. 保持 Markdown 结构完整
    """
    blocks = []
    current_block = ""
    
    for paragraph in content.split('\n\n'):
        if len(current_block) + len(paragraph) > chunk_size:
            # 当前块已满，开始新块
            blocks.append(current_block.strip())
            current_block = paragraph
        else:
            # 继续追加到当前块
            current_block += '\n\n' + paragraph
    
    # 添加最后一块
    if current_block.strip():
        blocks.append(current_block.strip())
    
    return blocks
```

---

### 拆分优先级

| 拆分点 | 优先级 | 说明 |
|--------|--------|------|
| **段落边界** | ⭐⭐⭐⭐⭐ | `\n\n` 最自然 |
| **章节标题** | ⭐⭐⭐⭐⭐ | `## 标题` 保持结构 |
| **句子边界** | ⭐⭐⭐⭐ | `。！？.!?` |
| **列表项** | ⭐⭐⭐ | `-` 或 `1.` |
| **代码块** | ⭐⭐ | 避免拆分代码 |

---

## 📊 Block 组织策略

### 标准文档结构

| Block 序号 | 内容类型 | 字数范围 |
|-----------|----------|----------|
| Block 1 | 标题 + 简介 | 100-300 字 |
| Block 2 | Mermaid 图表（如有） | - |
| Block 3-N | 详细章节 | 500-1000 字/块 |
| Block N+1 | 表格数据（如有） | - |
| Block N+2 | 总结/链接 | 100-300 字 |

### 特殊情况处理

**情况 1：Mermaid 图表**
- 单独作为一个 Block
- 前后各留一个空行
- 不与其他内容混合

**情况 2：表格**
- 小表格（<20 行）：与文字混合
- 大表格（≥20 行）：单独作为一个 Block

**情况 3：代码块**
- 短代码（<50 行）：与说明混合
- 长代码（≥50 行）：单独作为一个 Block

---

## ⚠️ 注意事项

### 1. 内容完整性

**确保：**
- ✅ Markdown 语法完整
- ✅ 代码块不被拆分
- ✅ 表格保持完整
- ✅ Mermaid 代码完整

**避免：**
- ❌ 在代码块中间拆分
- ❌ 在表格行中间拆分
- ❌ 破坏 Markdown 结构

---

### 2. 错误处理

**可能的错误：**
- ❌ 飞书 API 超时
- ❌ 网络中断
- ❌ 内容格式错误

**处理策略：**
```python
def write_with_retry(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except Exception as e:
            if i == max_retries - 1:
                raise
            time.sleep(1)  # 等待 1 秒后重试
```

---

### 3. 性能优化

**优化点：**
- ✅ 批量写入（减少 API 调用）
- ✅ 异步处理（非阻塞）
- ✅ 缓存机制（避免重复创建）

**建议：**
- 单次写入不超过 10 个 Blocks
- 每块不超过 1000 字
- 总文档不超过 50 个 Blocks

---

## 📝 配置检查清单

使用前确认：

- [ ] 已安装 feishu_doc 工具
- [ ] 已配置飞书凭证（如需要）
- [ ] 已测试创建空文档
- [ ] 已测试追加内容
- [ ] 已测试完整流程

---

## 🎯 最佳实践

### 1. 文档长度建议

| 文档类型 | 建议长度 | Block 数量 |
|----------|----------|------------|
| **简报** | 500-1000 字 | 2-3 个 |
| **报告** | 2000-5000 字 | 5-10 个 |
| **详细文档** | 5000-10000 字 | 10-20 个 |
| **超长文档** | 10000+ 字 | 考虑分多个文档 |

---

### 2. 内容组织

**推荐结构：**
```
Block 1: 标题 + 简介 + 目录
Block 2: 第一章
Block 3: 第二章
...
Block N: 总结 + 参考链接
```

**避免：**
- ❌ 所有内容堆在一个 Block
- ❌ 没有逻辑分段
- ❌ 过长的单个 Block（>2000 字）

---

### 3. 验证流程

**创建后验证：**
1. ✅ 检查文档是否为空白
2. ✅ 检查 Blocks 数量是否正确
3. ✅ 检查 Mermaid 图表是否渲染
4. ✅ 检查表格是否完整
5. ✅ Chrome 打开预览

---

## 📞 支持

**问题反馈：** OpenClaw 社区  
**文档：** `~/.agents/skills/feishu-doc-block-writer/README.md`

**核心文件：**
- `scripts/block-writer.py` - 主脚本
- `SKILL.md` - 技能定义
- `config.json` - 配置文件（可选）

---

## 🎉 总结

**feishu-doc-block-writer 技能：**
- ✅ 自动 Block 拆分
- ✅ 避免空白文档
- ✅ 支持 Mermaid 图表
- ✅ 智能内容组织
- ✅ 错误重试机制

**使用方式：**
```bash
python scripts/block-writer.py --title "标题" --content "内容..."
```

**效果：** 稳定创建飞书文档，无空白问题！

---

_阿香 🦞 创建的 Block 拆分技能_

**哼～虾虾的技能创建完成啦！以后不会再有空白文档了！✨**