每日备份 2026-03-27

2026-03-27 23:38:45 +08:00
parent 4f11cd7b03
commit d09281e48c
827 changed files with 6991 additions and 148648 deletions
@@ -0,0 +1,171 @@
+# 飞书文档创建失败经验总结
+
+> **创建日期**: 2026-03-18  
+> **问题类型**: API 调用失败 / 工具超时  
+> **来源**: 欢欢助理与欢哥的对话记录
+
+---
+
+## 📋 问题描述
+
+**任务**: 创建飞书云文档"欢欢助理运行环境配置"  
+**期望**: 使用 `feishu-create-doc` 技能创建到个人知识库  
+**结果**: 多次尝试均超时失败
+
+---
+
+## 🔍 尝试方案
+
+### 方案 1: 使用子代理调用技能
+```
+sessions_spawn → subagent → feishu-create-doc
+```
+**结果**: ❌ 超时 (60 秒)
+
+**可能原因**:
+- 子代理初始化耗时过长
+- 技能加载慢
+- 飞书 API 响应慢
+
+---
+
+### 方案 2: 使用 ACP 运行时
+```
+sessions_spawn --runtime=acp --agentId=@larksuite/openclaw-lark
+```
+**结果**: ❌ 错误 "ACP runtime backend is not configured"
+
+**原因**: ACP 运行时后端未配置
+
+---
+
+### 方案 3: 使用 openclaw CLI
+```bash
+openclaw feishu_doc create --title "xxx" --wiki-space "my_library"
+```
+**结果**: ❌ 错误 "unknown command 'feishu_doc'"
+
+**原因**: CLI 不支持该命令
+
+---
+
+### 方案 4: 直接调用 Gateway API
+```python
+# 尝试通过 Python 调用
+payload = {
+    'tool': 'feishu_create_doc',
+    'params': {...}
+}
+```
+**结果**: ⏳ 未完全尝试
+
+---
+
+## ✅ 可行方案
+
+### 方案 A: 手动创建（推荐）
+1. 打开飞书 → 知识库 → 个人知识库
+2. 新建文档
+3. 粘贴 Markdown 内容
+4. 设置标题
+
+**优点**: 100% 可靠，即时可见  
+**缺点**: 需要人工介入
+
+---
+
+### 方案 B: 使用飞书导入功能
+1. 准备 Markdown 文件
+2. 飞书文档 → 导入 → 选择文件
+3. 选择目标位置
+
+**优点**: 保留格式  
+**缺点**: 需要手动操作
+
+---
+
+### 方案 C: 使用 feishu_chat 工具（待验证）
+```
+通过 message 工具发送文档内容到飞书
+```
+
+---
+
+## 📝 经验教训
+
+### 1. 子代理超时问题
+**问题**: 子代理调用技能容易超时  
+**教训**: 
+- 简单任务尽量在主会话完成
+- 子代理适合长时间任务
+- 超时时间设置至少 120 秒
+
+---
+
+### 2. ACP 运行时配置
+**问题**: 默认未配置 ACP 运行时  
+**教训**:
+- 使用前先检查配置
+- `agents_list` 只返回 subagent 允许列表
+- ACP 需要额外配置 `acp.defaultAgent`
+
+---
+
+### 3. CLI 命令限制
+**问题**: 不是所有工具都有 CLI 命令  
+**教训**:
+- CLI 命令有限，主要工具需通过 Gateway API
+- 先用 `openclaw --help` 查看可用命令
+- 不确定时先测试
+
+---
+
+### 4. 飞书 API 权限
+**问题**: 可能需要额外权限  
+**教训**:
+- 检查飞书应用权限配置
+- 确认 OAuth token 有效
+- 知识库写入需要相应 scope
+
+---
+
+## 🛠️ 解决方案建议
+
+### 短期方案
+1. **手动创建**文档，后续自动化
+2. 准备 Markdown 模板，减少重复工作
+
+### 中期方案
+1. 配置 ACP 运行时
+2. 测试 Gateway API 直接调用
+
+### 长期方案
+1. 创建 `feishu-doc-creator` 技能
+2. 集成到工作流自动化
+
+---
+
+## 📞 相关资源
+
+| 资源 | 链接/位置 |
+|------|-----------|
+| 飞书文档 API | https://open.feishu.cn/document/ukTMukTMukTM/uEDO4QjLxgDM14SM2gTN/ |
+| OpenClaw 飞书插件 | `~/.openclaw/extensions/openclaw-lark/` |
+| feishu-create-doc 技能 | `~/.openclaw/extensions/openclaw-lark/skills/feishu-create-doc/SKILL.md` |
+
+---
+
+## ✅ 检查清单
+
+创建飞书文档前检查：
+
+- [ ] 飞书插件已启用
+- [ ] OAuth token 有效
+- [ ] 知识库权限已授权
+- [ ] Markdown 内容格式正确
+- [ ] 目标位置 (wiki_space/folder_token) 正确
+- [ ] 超时时间设置充足 (≥120 秒)
+
+---
+
+*本文档由欢欢助理整理，避免重复踩坑。*