===========================================
SKILL-FEISHU-DOC-001 - 飞书文档生成（V1.0）
分章节写入，避免空白文档
===========================================

【这个 Skill 是干啥的】
生成长文档到飞书，分章节写入，避免空白文档问题

【什么时候用】
- 用户要求生成飞书文档
- 文档内容较长（>200 blocks）
- 需要稳定生成（无空白）

【6 步标准化流程】

🆕 第 0 步：维护版头信息（版本/时间/内容/人）
  - 版本号：V{主版本}.{次版本}.{修订号}
  - 更改时间：YYYY-MM-DD HH:mm
  - 更改内容：简要说明
  - 更改人：阿福

第 1 步：提取 AI 生成的结论文字
  - 从 AI 分析结果中提取内容
  - 解析章节结构
  - 预估总 block 数

第 2 步：创建空白飞书文档
  - 动作：feishu_doc -action create
  - 参数：title（内容留空）
  - 返回：document_id, url

第 3 步：分章节写入内容
  - 第 1 章：write（≤200 blocks）
  - 后续章：append
  - 记录每个 block_id

第 4 步：处理 400 错误（分块写入）
  - 长文档分块（30-50 blocks/块）
  - 第 1 块：write
  - 后续块：append

第 5 步：单独发送文档链接
  - 不要附在回复里
  - 单独发送消息
  - 方便以后查找

【write vs append 选择】

| 场景 | 动作 | 说明 |
|------|------|------|
| 首次写入 | write | 写入第 1 个章节 |
| 增量更新 | append | 追加后续章节 |
| 完全重写 | write | 覆盖整个文档（谨慎） |
| 单个 block | update_block | 更新指定 block |

【版头格式】

# 文档标题

> **版本：** V{主版本}.{次版本}.{修订号}  
> **创建时间：** YYYY-MM-DD HH:mm  
> **最后更新：** YYYY-MM-DD HH:mm（更新说明）  
> **维护方式：** 三线同步（飞书 + MD + TXT）

示例：
# AI 专业术语知识库

> **版本：** V2.0  
> **创建时间：** 2026-03-08 00:25  
> **最后更新：** 2026-03-08 00:32（标准化流程测试）  
> **维护方式：** 三线同步（飞书 + MD + TXT）

【严重警告】

❌ write 会覆盖整个文档！
- 原文档 500 blocks → write 后只剩 1 block
- 增量更新必须用 append
- 只在首次写入或完全重写时用 write

【空白文档问题】

问题：长文件一次性写入 → 返回空白文档

原因：
- create -content "长内容" 不支持
- 单次写入超过限制（约 200 blocks）

解决方案：
1. create 创建空白文档（不写入内容）
2. write 写入第 1 章（≤200 blocks）
3. append 追加后续章节
4. 长文档分块（30-50 blocks/块）

【分块策略】

| 文档长度 | 分块数 | 每块大小 |
|----------|--------|----------|
| <200 blocks | 1 块 | 一次性写入 |
| 200-500 blocks | 2-3 块 | 100-150 blocks/块 |
| >500 blocks | 5-10 块 | 30-50 blocks/块 |

【成功案例】

AI 术语知识库（2026-03-08 00:25）：
- 标题：AI 专业术语知识库 V2.0
- Token: KVgQdxnlVoiPbexfKR3cnEIWnId
- 内容：26 个术语，6 大分类
- 执行：create → write → append → 发送链接
- 结果：文档正常显示，无空白

【错误案例】

错误 1：create 时写入长内容
❌ feishu_doc -action create -content "长内容"
✅ feishu_doc -action create（留空）

错误 2：误用 write 模式
❌ 增量更新用 write → 覆盖整个文档
✅ 增量更新用 append

错误 3：不分块写入长文档
❌ 一次性写入 500 blocks → 400 错误
✅ 分块写入（30-50 blocks/块）

错误 4：文档链接附在回复里
❌ 附在回复底部 → 用户搜不到
✅ 单独发送消息 → 方便查找

【检查清单】

执行前：
  - [ ] 维护版头信息（版本/时间/内容/人）
  - [ ] 提取结论文字（Markdown）
  - [ ] 解析章节结构
  - [ ] 预估总 block 数
  - [ ] 决定分块策略

执行中：
  - [ ] create 创建空白文档
  - [ ] 第 1 章用 write（≤200 blocks）
  - [ ] 后续章节用 append
  - [ ] 长文档分块（30-50 blocks/块）
  - [ ] 记录每个 block_id

执行后：
  - [ ] 文档内容完整显示
  - [ ] 无空白文档问题
  - [ ] 单独发送文档链接
  - [ ] 链接可正常访问

【核心口诀】

创建要空白
写入分章节
长文要分块
链接单独发

【文件位置】

MD 模块：skills/feishu-document-generation/SKILL.md
TXT 说明：skills/feishu-document-generation/SKILL.txt

【关联 Skill】

前置：AI 分析生成结论文字
后置：message 工具发送文档链接
复用：ATOM-FEISHU-028（写入飞书文档）

【用户约定】

- 文档生成后单独发送链接
- 不要附在回复里
- 方便以后通过对话记录查找

===========================================
创建时间：2026-03-08 00:30
版本：V1.0
===========================================
