172 lines
3.5 KiB
Markdown
172 lines
3.5 KiB
Markdown
# 飞书文档创建失败经验总结
|
|
|
|
> **创建日期**: 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 秒)
|
|
|
|
---
|
|
|
|
*本文档由欢欢助理整理，避免重复踩坑。*
|