181 lines
4.3 KiB
Markdown
181 lines
4.3 KiB
Markdown
# 🎉 Telegram sendPhoto 功能实现完成！
|
||
|
||
## ✅ 完成的工作
|
||
|
||
### 修改的文件
|
||
|
||
1. **extensions/telegram/src/channel-actions.ts**
|
||
- 添加 `sendPhoto` 到 `TELEGRAM_MESSAGE_ACTION_MAP`
|
||
- 添加注释说明 sendPhoto 始终可用（与 sendMessage 共享基础设施）
|
||
|
||
2. **extensions/telegram/src/action-runtime.ts**
|
||
- 添加 `sendPhotoTelegram` 到 `telegramActionRuntime` 导出
|
||
- 添加 `sendPhoto: "sendPhoto"` 到动作别名映射
|
||
- 实现 `sendPhoto` 动作处理器：
|
||
- 读取 `photoUrl`/`mediaUrl`/`photo` 参数
|
||
- 读取可选的 `caption` 参数
|
||
- 支持 threading (`replyToMessageId`, `messageThreadId`)
|
||
- 支持 `silent` 选项
|
||
- 返回 messageId 和 chatId
|
||
|
||
3. **extensions/telegram/src/send.ts**
|
||
- 实现 `sendPhotoTelegram` 函数：
|
||
- 从 URL 加载图片
|
||
- 处理 caption（支持 HTML 渲染）
|
||
- 处理超长 caption（自动分割为 follow-up 消息）
|
||
- 支持 thread 参数
|
||
- 支持 silent 选项
|
||
- 记录发送活动和缓存
|
||
|
||
---
|
||
|
||
## 📋 使用示例
|
||
|
||
### Agent 工具调用
|
||
|
||
```json
|
||
{
|
||
"action": "sendPhoto",
|
||
"channel": "telegram",
|
||
"to": "123456789",
|
||
"photoUrl": "https://example.com/image.png",
|
||
"caption": "这是分析的图片：",
|
||
"silent": false
|
||
}
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `to` | ✅ | Telegram 聊天 ID |
|
||
| `photoUrl` | ✅ | 图片 URL（也支持 `mediaUrl` 或 `photo`） |
|
||
| `caption` | ❌ | 图片说明文字（支持 Markdown） |
|
||
| `replyToMessageId` | ❌ | 回复的消息 ID |
|
||
| `messageThreadId` | ❌ | 论坛主题 ID |
|
||
| `silent` | ❌ | 静默发送（无通知） |
|
||
|
||
---
|
||
|
||
## 🔧 技术实现
|
||
|
||
### 核心功能
|
||
|
||
1. **图片加载**
|
||
- 使用 `loadWebMedia` 从 URL 加载图片
|
||
- 支持本地文件路径（通过 `mediaLocalRoots`）
|
||
- 遵守 `mediaMaxMb` 配置限制
|
||
|
||
2. **Caption 处理**
|
||
- 使用 `splitTelegramCaption` 分割超长 caption
|
||
- HTML 渲染支持 Markdown 格式
|
||
- 超长部分自动发送为 follow-up 消息
|
||
|
||
3. **Thread 支持**
|
||
- 支持论坛主题（`messageThreadId`）
|
||
- 支持回复链（`replyToMessageId`）
|
||
- 自动处理 thread-not-found 错误
|
||
|
||
4. **错误处理**
|
||
- Chat not found 错误包装
|
||
- Thread fallback 机制
|
||
- 重试机制（通过 `createTelegramNonIdempotentRequestWithDiag`）
|
||
|
||
---
|
||
|
||
## 📊 代码统计
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| 新增代码行数 | ~163 行 |
|
||
| 修改文件数 | 3 个 |
|
||
| 新增函数 | 1 个 (`sendPhotoTelegram`) |
|
||
| 新增动作 | 1 个 (`sendPhoto`) |
|
||
|
||
---
|
||
|
||
## 🧪 测试建议
|
||
|
||
### 基本测试
|
||
```bash
|
||
# 发送带 caption 的图片
|
||
{
|
||
"action": "sendPhoto",
|
||
"to": "<chat_id>",
|
||
"photoUrl": "https://picsum.photos/800/600",
|
||
"caption": "测试图片"
|
||
}
|
||
```
|
||
|
||
### Thread 测试
|
||
```bash
|
||
# 在论坛主题中发送
|
||
{
|
||
"action": "sendPhoto",
|
||
"to": "<group_id>",
|
||
"photoUrl": "https://example.com/image.png",
|
||
"messageThreadId": 12345
|
||
}
|
||
```
|
||
|
||
### Silent 测试
|
||
```bash
|
||
# 静默发送
|
||
{
|
||
"action": "sendPhoto",
|
||
"to": "<chat_id>",
|
||
"photoUrl": "https://example.com/image.png",
|
||
"silent": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 相关链接
|
||
|
||
- **Issue**: https://github.com/openclaw/openclaw/issues/49729
|
||
- **PR**: https://github.com/openclaw/openclaw/pull/new/feat/telegram-sendphoto-support
|
||
- **Telegram API**: https://core.telegram.org/bots/api#sendphoto
|
||
|
||
---
|
||
|
||
## 📝 提交信息
|
||
|
||
```
|
||
feat(telegram): add sendPhoto action support
|
||
|
||
- Add sendPhoto action to channel-actions.ts mapping
|
||
- Implement sendPhotoTelegram function in send.ts
|
||
- Add sendPhoto handler in action-runtime.ts
|
||
- Support photo URL, caption, threading, and silent options
|
||
- Follows Telegram Bot API sendPhoto endpoint
|
||
|
||
Resolves: #49729
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 下一步
|
||
|
||
1. **创建 PR** - 访问下面的链接
|
||
2. **等待审查** - 维护者会审查代码
|
||
3. **回复反馈** - 如有需要，及时修改
|
||
4. **合并** - 等待 PR 被合并
|
||
|
||
---
|
||
|
||
## ✨ 功能亮点
|
||
|
||
- ✅ **完整实现** - 从 API 到 UI 的完整支持
|
||
- ✅ **参数灵活** - 支持多种参数名称（photoUrl/mediaUrl/photo）
|
||
- ✅ **Caption 智能处理** - 自动分割超长文本
|
||
- ✅ **Thread 支持** - 完整的 threading 支持
|
||
- ✅ **错误处理** - 健壮的错误处理和重试机制
|
||
- ✅ **活动记录** - 记录发送活动用于监控
|
||
|
||
---
|
||
|
||
*实现时间：2026-03-18*
|
||
*实现者：ahern88*
|
||
*解决 Issue: #49729*
|