@core-workspace/infoflow-openclaw-plugin 2026.3.8

package/skills/infoflow-dev/references/api.md

@@ -0,0 +1,413 @@
+# 如流 (Infoflow) API 参考文档
+
+本文档是如流机器人开发的官方API参考，用于OpenClaw插件开发。
+
+**原始文档**: https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/2tsPs8CtSd/Bu7DDg4dpB/O7gUd6RJUGn7Ix
+
+## 核心概念
+
+### API 端点
+
+- **生产环境**: `http://apiin.im.baidu.com/api/v1/robot/msg/groupmsgsend`
+- **预发布环境**: `http://xplatform-preonline.dev.weiyun.baidu.com/open-plat/api/devp/v1/robot/msg/groupmsgsend`
+
+### 权限要求
+
+调用API前必须：
+1. 在企业后台开启权限【以机器人身份发送消息到群聊】
+2. 路径：企业后台 > 应用中心 > 你的机器人 > 功能 > 机器人 > 设置 > 功能 > 群聊场景 > 开放API > 设置
+
+### 限流规则
+
+- **QPS限制**: 10 QPS/机器人（默认）
+- **频率限制**: 20条消息/分钟/群
+- 超出限流会返回错误码 40046，限流5分钟
+
+## 消息格式
+
+### 基础消息结构
+
+```json
+{
+  "message": {
+    "header": {
+      "toid": 8331527,           // 群ID
+      "totype": "GROUP",          // 消息类型
+      "msgtype": "TEXT",          // 内容类型
+      "clientmsgid": 1569398477302,
+      "role": "robot"
+    },
+    "body": [
+      {
+        "type": "TEXT",
+        "content": "消息内容"
+      }
+    ]
+  }
+}
+```
+
+### Header 字段说明
+
+| 字段 | 类型 | 必须 | 说明 |
+|------|------|------|------|
+| toid | long | 是 | 目标群组ID |
+| totype | String | 是 | 目标类型，固定为 "GROUP" |
+| msgtype | String | 是 | 消息类型：TEXT/IMAGE/LINK/MD |
+| clientmsgid | long | 是 | 客户端生成的唯一标识 |
+| clienttime | long | 否 | 客户端时间戳，不传则使用服务器时间 |
+| role | String | 是 | 固定为 "robot" |
+
+## 消息类型
+
+### 1. TEXT - 文本消息
+
+```json
+{
+  "message": {
+    "header": {
+      "toid": 123456,
+      "totype": "GROUP",
+      "msgtype": "TEXT",
+      "clientmsgid": 1569398477302,
+      "role": "robot"
+    },
+    "body": [
+      {
+        "type": "TEXT",
+        "content": "这是一条文本消息"
+      }
+    ]
+  }
+}
+```
+
+**限制**:
+- 总长度 ≤ 2048字符
+- 错误码 40061: 超过2k
+
+### 2. MD - Markdown消息
+
+```json
+{
+  "message": {
+    "header": {
+      "toid": 123456,
+      "totype": "GROUP",
+      "msgtype": "MD",
+      "clientmsgid": 1569398477302,
+      "role": "robot"
+    },
+    "body": [
+      {
+        "type": "MD",
+        "content": "# 标题\n**粗体** *斜体*"
+      }
+    ]
+  }
+}
+```
+
+**支持的语法**:
+- 标题: `# 标题` (1-6级)
+- 粗体: `**文本**`
+- 斜体: `*文本*`
+- 引用: `> 引用内容`
+- 颜色: `<font color="green">文本</font>` (green/gray/red)
+- 链接: `[文本](URL)`
+- 有序列表: `1. 项目`
+- 无序列表: `- 项目`
+- 行内代码: `` `代码` ``
+
+**限制**:
+- 内容长度 ≤ 2048字符
+- 错误码 40068: 超过限制
+
+### 3. IMAGE - 图片消息
+
+```json
+{
+  "message": {
+    "header": {
+      "toid": 123456,
+      "totype": "GROUP",
+      "msgtype": "IMAGE",
+      "clientmsgid": 1569398477302,
+      "role": "robot"
+    },
+    "body": [
+      {
+        "type": "IMAGE",
+        "content": "图片URL或Base64"
+      }
+    ]
+  }
+}
+```
+
+**限制**:
+- 图片数量: 1个
+- 图片大小 ≤ 1MB
+- 错误码 40063: 图片数量超限
+- 错误码 40066: 图片大小超限
+
+### 4. LINK - 链接消息
+
+```json
+{
+  "message": {
+    "header": {
+      "toid": 123456,
+      "totype": "GROUP",
+      "msgtype": "LINK",
+      "clientmsgid": 1569398477302,
+      "role": "robot"
+    },
+    "body": [
+      {
+        "type": "LINK",
+        "url": "https://example.com",
+        "title": "链接标题",
+        "desc": "链接描述"
+      }
+    ]
+  }
+}
+```
+
+**限制**:
+- 单个链接长度 ≤ 1024字符
+- 错误码 40062: 链接长度超限
+
+## 引用回复功能
+
+支持引用回复的消息类型: TEXT、IMAGE、LINK
+
+**结构**: reply 字段与 header 和 body 同级
+
+```json
+{
+  "message": {
+    "header": { /* ... */ },
+    "body": [ /* ... */ ],
+    "reply": {
+      "messageid": "1859257727716544500",
+      "preview": "被引用的消息内容",
+      "imid": "102752365",
+      "replyType": "1"
+    }
+  }
+}
+```
+
+### Reply 字段说明
+
+| 字段 | 类型 | 必须 | 说明 |
+|------|------|------|------|
+| messageid | String | 是 | 被引用消息的ID |
+| preview | String | 否 | 被引用消息的预览文本 |
+| imid | String | 否 | 被引用消息发送者的imid（数字用户ID） |
+| replyType | String | 是 | "1"=回复模式, "2"=引用模式 |
+
+**注意事项**:
+- `messageid` 必须是字符串类型
+- `replyType` 使用驼峰命名（不是 replytype）
+- `imid` 是发送者的数字ID，可以从消息的 `fromid` 字段获取
+
+## @提及功能
+
+### @用户
+
+```json
+{
+  "message": {
+    "header": {
+      "toid": 123456,
+      "totype": "GROUP",
+      "msgtype": "TEXT",
+      "clientmsgid": 1569398477302,
+      "role": "robot"
+    },
+    "body": [
+      {
+        "type": "AT",
+        "content": "username1,username2"  // 逗号分隔
+      },
+      {
+        "type": "TEXT",
+        "content": "消息内容"
+      }
+    ]
+  }
+}
+```
+
+### @全员
+
+```json
+{
+  "body": [
+    {
+      "type": "AT",
+      "content": "all"
+    },
+    {
+      "type": "TEXT",
+      "content": "消息内容"
+    }
+  ]
+}
+```
+
+**限制**:
+- @人数 ≤ 50人
+- 错误码 40071: 超过50人
+
+## 返回结果
+
+### 成功响应
+
+```json
+{
+  "code": "ok",
+  "data": {
+    "errcode": 0,
+    "errmsg": "ok",
+    "data": {
+      "messageid": 1835260055958702611,
+      "msgseqid": 300010003,
+      "ctime": 1750240379318
+    }
+  }
+}
+```
+
+### 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| 0 | 成功 |
+| -1 | 系统错误 |
+| 40000 | 参数错误 |
+| 40035 | 群聊ID不合法 |
+| 40036 | 群聊非企业群 |
+| 40044 | 机器人未被添加到群中 |
+| 40045 | agentId不合法 |
+| 40046 | 发送消息频率超限（20条/分钟） |
+| 40047 | 文件上传失败 |
+| 40060 | body超过9k |
+| 40061 | text类型文本长度超过2k |
+| 40062 | link类型单个链接长度超过1k |
+| 40063 | image类型图片数量超过1个 |
+| 40066 | image类型图片大小超过1m |
+| 40068 | markdown内容长度超过2048字符 |
+| 40071 | at超过50人 |
+| 40200 | 机器人发送消息权限已被封禁 |
+| 40201 | 机器人接收消息权限已被封禁 |
+| 40300 | 机器人已被停用 |
+
+## 开发最佳实践
+
+### 1. 消息去重
+
+使用 `clientmsgid` 和 `clienttime` 实现消息去重：
+- `clientmsgid`: 使用时间戳或UUID
+- `clienttime`: 使用当前毫秒时间戳
+- **重要**: 不要传0，会触发排重机制
+
+### 2. 引用回复实现
+
+```typescript
+// 从接收的消息中提取关键字段
+const messageId = String(msgData.message.header.messageid);
+const senderImid = String(msgData.fromid);  // 注意：是 fromid 不是 imid
+const preview = extractPreviewText(msgData.message.body);
+
+// 构建reply对象
+const reply = {
+  messageid: messageId,     // 必须是字符串
+  preview: preview.slice(0, 100),  // 截断预览文本
+  imid: senderImid,         // 可选，但建议提供
+  replyType: "1"            // "1"=回复, "2"=引用
+};
+
+// 发送消息时包含reply
+const payload = {
+  message: {
+    header: { /* ... */ },
+    body: [ /* ... */ ],
+    reply: reply  // 与header、body同级
+  }
+};
+```
+
+### 3. 错误处理
+
+```typescript
+try {
+  const response = await sendMessage(payload);
+  const data = await response.json();
+
+  if (data.data?.errcode === 0) {
+    console.log('消息发送成功');
+  } else {
+    console.error(`发送失败: ${data.data?.errmsg} (${data.data?.errcode})`);
+  }
+} catch (error) {
+  console.error('API调用失败:', error);
+}
+```
+
+### 4. 调试技巧
+
+**添加详细日志**:
+```typescript
+console.log('[DEBUG] Request payload:', JSON.stringify(payload, null, 2));
+console.log('[DEBUG] API response:', JSON.stringify(data, null, 2));
+```
+
+**验证字段类型**:
+```typescript
+console.log('[DEBUG] messageid type:', typeof reply.messageid);  // 应该是 string
+console.log('[DEBUG] imid type:', typeof reply.imid);            // 应该是 string
+```
+
+## 常见问题排查
+
+### 问题1: 引用回复不显示
+
+**可能原因**:
+1. `messageid` 是 number 而不是 string → 转换为字符串
+2. 字段名错误（replytype vs replyType）→ 使用驼峰命名
+3. `reply` 对象未传递到API → 检查参数解构
+4. `imid` 字段缺失或错误 → 从 `msgData.fromid` 提取
+
+**解决方法**: 参考"引用回复实现"章节
+
+### 问题2: 频率限流
+
+**错误**: 40046 - 发送消息频率超限
+
+**原因**: 超过 20条/分钟/群
+
+**解决**:
+- 实现消息队列和延迟发送
+- 合并多条消息
+- 联系技术支持申请扩容
+
+### 问题3: 参数错误
+
+**错误**: 40000 - 参数错误
+
+**检查清单**:
+- [ ] header.toid 是否为有效的群ID（number类型）
+- [ ] header.msgtype 与 body[0].type 是否匹配
+- [ ] clientmsgid 是否为唯一值
+- [ ] role 是否为 "robot"
+- [ ] 内容长度是否超限
+
+## 相关链接
+
+- 企业后台: https://qy.baidu-int.com/index.html
+- API完整文档: https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/2tsPs8CtSd/Bu7DDg4dpB/O7gUd6RJUGn7Ix
+- 技术支持: 魏小伟 (weixiaowei@baidu.com)