ai_member_xiaobian/memory/2025-05-11.md

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

问题场景

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

失败模式

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

正确做法（已验证有效）

分段写入本地文件 → 用 @file 引用写入飞书：

# 步骤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 @相对路径，这是最稳定的路径。