@searchfe/openclaw-baiduapp 0.1.9-beta.2 → 0.1.9

package/README.md

@@ -13,23 +13,23 @@
 | 入站文件下载与本地注入   |  ✅  |
 | 出站本地文件上传后发送   |  ✅  |
 
-> 百度 App 渠道当前使用 V2 协议：鉴权只依赖 `appKey` / `appSecret`，消息体统一使用 `msg.list` 列表格式，文件上传 STS 路径为 `/channel/file/sts`。
+> 百度文件消息当前仍挂在文本消息契约下：入站 payload 继续使用 `msgtype: "text"`，并在同层增加可选 `files` 数组；出站发送也继续走 JSON 文本消息协议，只是在顶层带 `files:[{url,fileType}]`，不会切到 `multipart/form-data` 消息发送接口。
 
 ## 当前实现行为
 
 ### 入站消息
 
-- 回调路由使用 V2 路径：`/channel/msg/callback`；轮询模式对应 `/channel/msg/poll`。
-- 入站 payload 使用 `{sessionId, msg}` 结构，其中 `msg` 为 `{list:[{type,data}]}`。
-- 纯文本与文件消息都会按 `msg.list` 逐项解析进入 Agent。
+- 纯文本消息照常进入 Agent。
+- 携带附件时，百度回调仍是 `msgtype: "text"`，附件放在同层 `files` 字段，结构为 `files:[{url,fileType}]`。
+- 当前已支持 **files-only** 和 **text+files** 两种入站形态；也就是 `text.content` 与 `files` 至少其一存在即可进入处理链。
 - 插件会下载可访问的入站文件到本机临时目录 `openclaw-baiduapp/media`，并把成功下载的本地路径注入给 Agent。
 - Agent 侧正文会保留原始文本，并在 `[local files]` 前追加 `[files]` 摘要行；其中 `[local files]` 只列出成功下载到本地的文件路径。单文件场景还会补充文件名和大小，下载失败时会追加明确的 failure placeholder，但不会伪造本地路径。
 
 ### 出站消息
 
-- 出站消息同样使用 V2 的 `msg.list` 格式发送。
+- 纯文本仍通过百度文本发送接口下发。
 - 文件出站要求传入**本地文件路径**（如 `/tmp/report.pdf` 或 `file:///tmp/report.pdf`）。
-- 插件会先基于 `appKey` / `appSecret` 生成 Bearer Token，再向 `POST {apiBase}/channel/file/sts?ak={account.appKey}&token={generatedToken}` 申请 SKS 凭证，上传到固定 BOS 端点 `https://aisearch.bj.bcebos.com` 后，再以 `msg.list` 格式发送给百度。
+- 插件会先向 `POST {apiBase}/file/sts?ak={account.appKey}&token={generatedToken}` 申请 SKS 凭证，再上传到固定 BOS 端点 `https://aisearch.bj.bcebos.com`，最后以顶层 `files:[{url,fileType}]` 的文本消息发送给百度。
 - `fileType` 优先使用显式 MIME；未指定时按本地文件扩展名推断，未知类型回退 `application/octet-stream`。
 
 ### 临时文件与清理
@@ -40,8 +40,9 @@
 
 ## 已知限制
 
+- 百度文件消息仍归属 `msgtype: "text"`，当前**没有**单独的 `msgtype: "file"` 协议分支。
 - 出站文件发送只接受本地文件路径；远程 URL 不会被当作可发送附件直接透传。
-- 发送消息接口使用 V2 JSON 协议，当前**没有** `multipart/form-data` 消息发送实现。
+- 发送消息接口仍是 JSON 请求体，当前**没有** `multipart/form-data` 消息发送实现。
 - 只有成功下载到本地的入站文件才会出现在 Agent 的 `[local files]` 文本块与 `MediaPath/MediaPaths` 上下文里；下载失败的附件会在 agent 正文里留下 failure placeholder，但不会伪造本地路径。
 - 本地 mock smoke 中，出站文件 happy/failure 闭环通过 `scripts/mock-server.ts` 的 `/simulate-file-flow` helper 验证，真实运行时代码本身由单元测试覆盖。
 
@@ -65,12 +66,16 @@ openclaw plugins install @searchfe/openclaw-baiduapp
 
 - **App Key**：应用标识
 - **App Secret**：应用密钥
+- **Token**：消息校验 Token
+- **EncodingAESKey**：消息加密密钥（43 位字符）
 
 ## 步骤三：配置 OpenClaw
 
 ### 使用命令行配置
 
 ```bash
+openclaw config set channels.openclaw-baiduapp.token your-token
+openclaw config set channels.openclaw-baiduapp.encodingAESKey your-43-char-encoding-aes-key
 openclaw config set channels.openclaw-baiduapp.appKey your-app-key
 openclaw config set channels.openclaw-baiduapp.appSecret your-app-secret
 ```
@@ -83,6 +88,8 @@ openclaw config set channels.openclaw-baiduapp.appSecret your-app-secret
 {
     "channels": {
         "openclaw-baiduapp": {
+            "token": "your-token",
+            "encodingAESKey": "your-43-char-encoding-aes-key",
             "appKey": "your-app-key",
             "appSecret": "your-app-secret"
         }
@@ -92,21 +99,25 @@ openclaw config set channels.openclaw-baiduapp.appSecret your-app-secret
 
 ### 配置说明
 
-| 字段          | 必填 | 说明                                 |
-| :------------ | :--: | :----------------------------------- |
-| `enabled`     |  ✅  | 是否启用该渠道                       |
-| `webhookPath` |  ✅  | 回调路径，需与百度平台配置一致       |
-| `appKey`      |  ✅  | 应用 App Key（回调鉴权与主动发送必需） |
-| `appSecret`   |  ✅  | 应用 App Secret（回调鉴权与主动发送必需） |
+| 字段             | 必填 | 说明                            |
+| :--------------- | :--: | :------------------------------ |
+| `enabled`        |  ✅  | 是否启用该渠道                  |
+| `webhookPath`    |  ✅  | 回调路径，需与百度平台配置一致  |
+| `token`          |  ✅  | 消息校验 Token                  |
+| `encodingAESKey` |  ✅  | 消息加密密钥（43 位）           |
+| `appKey`         |  ✅  | 应用 App Key（主动发送必需）    |
+| `appSecret`      |  ✅  | 应用 App Secret（主动发送必需） |
 
 ### 环境变量支持
 
 默认账户的凭证也可以通过环境变量设置：
 
-| 环境变量            | 对应配置   |
-| :------------------ | :--------- |
-| `BAIDU_APP_KEY`     | `appKey`   |
-| `BAIDU_APP_SECRET`  | `appSecret` |
+| 环境变量                     | 对应配置         |
+| :--------------------------- | :--------------- |
+| `BAIDU_APP_TOKEN`            | `token`          |
+| `BAIDU_APP_ENCODING_AES_KEY` | `encodingAESKey` |
+| `BAIDU_APP_KEY`              | `appKey`         |
+| `BAIDU_APP_SECRET`           | `appSecret`      |
 
 ## 步骤四：重启 Gateway
 
@@ -117,7 +128,7 @@ openclaw gateway restart
 ## 步骤五：验证配置
 
 1. 在百度平台配置 Webhook 回调地址，指向你的 OpenClaw Gateway
-2. 平台验证通过后，先发送一条测试文本消息，再发送一条带附件的 V2 `msg.list` 消息
+2. 平台验证通过后，先发送一条测试文本消息，再发送一条带 `files` 的文本消息
 3. 查看 OpenClaw 日志，确认 webhook 接收生效；如果是文件消息，还要确认插件完成本地下载并把 `[local files]` / `MediaPaths` 注入给 Agent
 
 ## 常见问题
@@ -126,7 +137,7 @@ openclaw gateway restart
 
 1. 检查 OpenClaw 是否已启动并监听正确端口
 2. 确认 `webhookPath` 与平台 URL 路径一致
-3. 确认 `appKey` 和 `appSecret` 与平台配置完全一致
+3. 确认 `token` 和 `encodingAESKey` 与平台配置完全一致
 4. 确认服务器公网可访问
 
 ### Q: 消息接收成功但发送失败？