## 飞书文档写入经验总结 [胡笳复盘触发]

### 问题场景
需要将大量 Markdown 内容（多个表格，数十行）写入飞书知识库文档。

### 失败模式
1. **`write` 工具 + 大段 content** — 当内容量很大时，content 参数可能传空导致校验失败 `content: must have required properties content`
2. **`exec` 工具直接内联大段内容** — 同样可能因内容过长导致 command 参数传空
3. **在同一失败模式上反复重试** — 浪费了大量时间，没有及时切换方案

### 正确做法（已验证有效）
**分段写入本地文件 → 用 @file 引用写入飞书：**

```bash
# 步骤1：用 heredoc 写入本地文件（内容过长时可分多次 cat >> 追加）
cat > tmp/content.md << 'EOF'
（markdown内容）
EOF

# 如果内容很长，分多次追加
cat >> tmp/content.md << 'EOF'
（更多内容）
EOF

# 步骤2：用 lark-cli 从文件读取写入飞书
# 覆盖写入（清空后重写）：
cd /root/.openclaw/workspace-xiaobian && \
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaoyan \
lark-cli docs +update --api-version v2 --doc "<obj_token>" \
  --command overwrite --doc-format markdown --content @tmp/content.md --as bot

# 追加写入（不删除已有内容）：
cd /root/.openclaw/workspace-xiaobian && \
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaoyan \
lark-cli docs +update --api-version v2 --doc "<obj_token>" \
  --command append --doc-format markdown --content @tmp/content.md --as bot
```

### 关键注意事项
1. **`--content @file` 必须用相对路径**，不能用绝对路径，需要先 `cd` 到工作区目录
2. **overwrite 会清空文档**，追加内容用 **append**
3. **wiki 链接的 token ≠ doc token**，需要先 `wiki spaces get_node` 获取 `obj_token` 再操作
4. **遇到工具调用反复失败时，立即切换方案**，不要在同一思路上打转

### 核心教训
大段内容写入飞书文档 = **exec heredoc 写本地文件** + **lark-cli --content @相对路径**，这是最稳定的路径。