@sumeai/sumeclaw 1.1.19 → 1.1.20

package/HARNESS_EXPERIENCE.md

@@ -0,0 +1,457 @@
+# sumeclaw Harness 调试经验
+
+本文记录友虾名片通过 `sumeclaw` 插件对接 OpenClaw 的调试经验，用于后续开发类似 Channel / Harness 集成时避坑。
+
+## 一句话结论
+
+Channel 插件不是简单 WebSocket 转发，而是三套状态机的对接：
+
+- 友虾后端的智能体、名片、客户、会话状态
+- sumeclaw 插件的连接、请求、回包状态
+- OpenClaw Agent runtime 的消息分发、回复、流式输出状态
+
+任何一层边界不清，都会表现成连接成功但无法对话、能对话但超时、能流式但截断、非流式只返回第一句等问题。
+
+## 最终职责划分
+
+推荐采用以下架构边界：
+
+```text
+友虾后端：上下文编排层
+sumeclaw 插件：通道适配层
+OpenClaw：推理执行层
+```
+
+友虾后端负责：
+
+- 识别用户、智能体、名片、客户和会话
+- 生成 `requestId` 与稳定的 `sessionKey`
+- 组装 `route / card / customer / conversation / policy / context_pack`
+- 处理普通模式和海报模式的不同返回方式
+
+sumeclaw 插件负责：
+
+- 维护到友虾后端的 WebSocket 连接
+- 接收 `hooks_agent`
+- 将消息投递到 OpenClaw runtime
+- 将 OpenClaw 回复转换为 `agent_reply / agent_delta / agent_done`
+
+OpenClaw 负责：
+
+- 根据插件注入的上下文执行 Agent
+- 生成回复
+- 通过 Channel delivery 回调输出文本块
+
+## 协议生命周期
+
+以后设计类似集成时，应先明确完整生命周期：
+
+```text
+connect
+  -> register_info
+  -> heartbeat
+  -> backend sends hooks_agent
+  -> plugin dispatches to OpenClaw runtime
+  -> OpenClaw delivers one or more reply blocks
+  -> plugin returns agent_delta or buffered agent_reply
+  -> plugin sends explicit done for streaming
+  -> backend matches requestId
+  -> backend persists and returns result
+```
+
+不要只验证 WebSocket 是否连接成功。连接成功只能证明通道可用，不能证明 Agent 能收到消息、能生成回复、能完整回传。
+
+## requestId 与 sessionKey
+
+必须分清两个字段的职责。
+
+```text
+requestId  = 单次请求匹配
+sessionKey = 长期对话上下文隔离
+```
+
+`requestId` 用于：
+
+- 后端 pending future / stream queue 匹配
+- 插件回包关联
+- 并发请求不串包
+
+`sessionKey` 用于：
+
+- OpenClaw 会话记忆隔离
+- 名片与客户的长期会话上下文
+- 多名片、多客户场景下防止串上下文
+
+推荐格式：
+
+```text
+sumeclaw:conversation:{conversation_id}
+```
+
+不要使用粗粒度默认值，例如：
+
+```text
+http_user
+agent:{agent_id}:user:http_user
+```
+
+这些值在多名片、多客户、多智能体场景下很容易导致上下文串线。
+
+## Runtime 能力探测
+
+不要假设 OpenClaw runtime 一定暴露某个 API。
+
+本次早期误判了 `runtime.channel.turn.run` 可用，实际 OpenClaw 2026.4.21 没有该入口，导致插件收到消息后无法分发。
+
+正确做法是在插件启动或异常时打印能力矩阵：
+
+```text
+apiKeys
+runtimeKeys
+runtime.channel keys
+reply dispatcher availability
+direct-dm helper availability
+```
+
+本次最终走通的入口是：
+
+```text
+dispatchInboundDirectDmWithRuntime
+```
+
+以后接入新版 OpenClaw 时，应先确认可用 runtime 分发路径，再实现业务协议。
+
+## 插件管理命令不能启动业务连接
+
+执行类似命令时：
+
+```bash
+openclaw plugins update sumeclaw
+```
+
+OpenClaw 也可能加载插件并调用 `register()`。如果此时插件启动业务 WebSocket，会出现临时进程连上后台，然后马上断开，甚至替换真实连接。
+
+典型现象：
+
+```text
+connected
+disconnected
+replaced by a newer OpenClaw plugin connection
+```
+
+处理原则：
+
+- 识别插件安装、更新、管理命令
+- 管理命令中跳过业务 WebSocket 连接
+- 正常 gateway 进程中才启动连接
+
+## 连接必须幂等
+
+OpenClaw 可能多次 register / reload 插件。
+
+插件连接逻辑必须保证：
+
+- 同一 account 已有 `OPEN` 或 `CONNECTING` 连接时复用
+- 新连接替换旧连接时，旧连接不再自动重连
+- 后端注销旧连接时不要误删新连接
+
+后端连接池应按 `agent_config_id` 管理当前 WebSocket，并在注销时校验对象身份：
+
+```text
+只有当前连接对象才能注销当前连接
+旧连接断开时忽略旧连接注销
+```
+
+## 非流式也可能多块 deliver
+
+这是最容易忽视的坑。
+
+即使友虾名片处于普通非流式模式，OpenClaw 也可能多次触发 delivery：
+
+```text
+第一句
+第二段
+第三段
+...
+```
+
+如果插件收到第一块就发送 `agent_reply`，后端非流式 `send()` 会立即完成任务，用户只能看到第一句。
+
+正确协议：
+
+```text
+非流式：
+OpenClaw deliver 多块文本
+插件全部缓冲
+OpenClaw dispatch 完成
+插件发送一次完整 agent_reply
+```
+
+关键日志应表现为：
+
+```text
+outbound reply buffered
+OpenClaw Direct DM dispatched
+agent_reply sent textLength=完整长度
+```
+
+## 流式必须显式 done
+
+不要用静默窗口猜测流式结束。
+
+本次尝试过 12 秒、15 秒、45 秒静默窗口，但 OpenClaw 中间可能长时间进行检索、工具调用或模型思考。任何固定时间窗口都有误判风险。
+
+正确协议：
+
+```text
+agent_delta
+agent_delta
+agent_delta
+agent_done
+```
+
+后端只有收到 `agent_done` 才能：
+
+- 向 SSE 输出 `done`
+- 清理 stream queue
+- 完成请求状态
+
+不要因为收到某个 final/future 就提前清理流队列，否则会出现：
+
+```text
+OpenClaw 增量无匹配流队列
+```
+
+## 流式队列要按顺序消费
+
+流式请求中，`agent_delta` 和 `agent_done` 必须按队列顺序处理。
+
+注意不要让 pending future 抢跑队列，否则可能出现：
+
+```text
+future 先完成
+stream queue 被清理
+后续 delta 到达时找不到队列
+```
+
+推荐做法：
+
+- `agent_delta` 进入 stream queue
+- `agent_done` 也进入同一个 stream queue
+- stream generator 按队列顺序 yield
+- 非流式 future 只用于普通 `agent_reply`
+
+## SSE 不等于真实流式
+
+前端可以模拟打字机效果，但这不代表服务端真实流式。
+
+判断真实流式要看后端是否持续输出：
+
+```text
+agent_delta received
+OpenClaw 流式输出 delta
+chat_stream event=content
+```
+
+如果只在最后一次性输出一大段，前端再拆字显示，那只是前端模拟。
+
+## 多租户设计原则
+
+一个 OpenClaw 可以连接多个友虾智能体；一个友虾智能体可以绑定多个名片；每个名片又服务多个客户。
+
+因此 payload 不能只传 `message`。
+
+推荐 payload 分层：
+
+```json
+{
+  "requestId": "req_xxx",
+  "message": "用户输入",
+  "agentId": "main",
+  "sessionKey": "sumeclaw:conversation:xxx",
+  "stream": true,
+  "route": {},
+  "card": {},
+  "customer": {},
+  "conversation": {},
+  "policy": {},
+  "context_pack": {}
+}
+```
+
+各层职责：
+
+- `route`：发给哪个 OpenClaw、哪个智能体、哪个名片、哪个客户会话
+- `card`：名片身份、角色定位、语气、人设、约束
+- `customer`：客户画像、风险偏好、关系阶段、已知需求
+- `conversation`：历史摘要、当前场景、语言、时区
+- `policy`：合规等级、敏感领域、免责声明、最大长度
+- `context_pack`：后端压缩后的 OpenClaw 可用上下文
+
+插件不应直接理解友虾业务数据库。友虾后端负责生成 `context_pack`，插件只负责透传。
+
+## 推荐调试顺序
+
+后续做类似集成时，建议按以下顺序推进：
+
+1. WebSocket 连接成功
+2. `heartbeat / heartbeat_ack` 正常
+3. `register_info` 上报 agentId 和插件版本
+4. 后端发送 `hooks_agent`，插件确认收到
+5. 插件打印 runtime 能力矩阵
+6. 插件用可用 runtime 入口分发到 OpenClaw
+7. 非流式缓冲多块 deliver，最终返回一次 `agent_reply`
+8. 流式逐块返回 `agent_delta`
+9. 流式结束返回明确 `agent_done`
+10. 后端按 `requestId` 匹配 pending future / stream queue
+11. 普通名片轮询结果成功
+12. 海报名片 SSE 流式成功
+13. 多客户、多名片、多智能体并发验证
+
+## 必须保留的诊断日志
+
+插件侧建议保留：
+
+```text
+register called
+connected
+heartbeat_ack
+hooks_agent received
+runtime keys / channel keys
+OpenClaw Direct DM dispatched
+outbound reply buffered
+agent_reply sent
+agent_delta sent
+agent_done sent
+```
+
+后端侧建议保留：
+
+```text
+send_to_openclaw request_id
+stream_to_openclaw request_id
+agent_reply received
+agent_delta received
+agent_done received
+stream queue matched
+stream queue done
+chat_task completed
+```
+
+这些日志要包含：
+
+- `agent_config_id`
+- `request_id`
+- `session_id`
+- `card_id`
+- `conversation_id`
+- `text_len`
+
+不要只打印“成功”或“失败”，否则定位不了串包、截断和超时。
+
+## 常见故障模式
+
+### 连接成功但不能对话
+
+可能原因：
+
+- runtime 分发入口不存在
+- 插件只连上 WebSocket，没有把消息投递给 OpenClaw
+- `hooks_agent` 类型未处理
+
+排查：
+
+- 看插件是否打印 `hooks_agent`
+- 看是否打印 runtime 能力矩阵
+- 看是否打印 `OpenClaw Direct DM dispatched`
+
+### 后端超时
+
+可能原因：
+
+- 插件没有回传 `requestId`
+- 后端 pending key 和插件回包 key 不一致
+- 插件 dispatch 卡住
+- 插件连接被管理命令替换
+
+排查：
+
+- 对比后端发送和插件回包的 `requestId`
+- 看是否有 `replaced by newer connection`
+
+### 流式只输出第一段
+
+可能原因：
+
+- 后端提前发 `done`
+- 插件用定时器猜 final
+- future 抢跑 stream queue
+
+修复：
+
+- 使用显式 `agent_done`
+- 按 stream queue 顺序消费
+
+### 非流式只输出第一句
+
+可能原因：
+
+- OpenClaw 多块 deliver
+- 插件第一块就发 `agent_reply`
+
+修复：
+
+- 非流式也缓冲 deliver
+- dispatch 完成后一次性发完整 `agent_reply`
+
+## 最小正确协议
+
+非流式：
+
+```text
+backend -> hooks_agent(stream=false)
+plugin -> OpenClaw
+OpenClaw -> deliver block 1
+plugin -> buffer
+OpenClaw -> deliver block 2
+plugin -> buffer
+OpenClaw dispatch completed
+plugin -> agent_reply(full_text)
+backend -> complete task
+```
+
+流式：
+
+```text
+backend -> hooks_agent(stream=true)
+plugin -> OpenClaw
+OpenClaw -> deliver block 1
+plugin -> agent_delta(block 1)
+OpenClaw -> deliver block 2
+plugin -> agent_delta(block 2)
+OpenClaw dispatch completed
+plugin -> agent_done(full_text)
+backend -> SSE done
+```
+
+## 后续演进建议
+
+下一阶段应把上下文构建收敛到统一模块，例如：
+
+```text
+OpenClawRequestContextBuilder
+```
+
+它负责生成：
+
+- route
+- card
+- customer
+- conversation
+- policy
+- context_pack
+- requestId
+- sessionKey
+
+不要在 `chat.py`、API handler、插件代码里分散拼上下文。上下文编排应该是后端的显式能力，插件只做稳定的通道适配。
+

package/openclaw.plugin.json

@@ -24,5 +24,63 @@
       }
     },
     "required": []
+  },
+
+  "channelConfigs": {
+    "sumeclaw": {
+      "label": "友虾名片",
+      "description": "通过 WebSocket 连接友虾名片平台，接收客户消息并调用 AI 名片回复",
+      "schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "token": {
+            "type": "string",
+            "description": "从友虾平台获取的连接令牌"
+          },
+          "wsUrl": {
+            "type": "string",
+            "description": "友虾名片平台 WebSocket 地址，默认为 wss://api.gixin.cc"
+          },
+          "allowFrom": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "允许接收消息的用户 ID 白名单，空表示不限制"
+          },
+          "dmSecurity": {
+            "type": "string",
+            "description": "私聊安全策略，例如 open / closed / allowlist"
+          }
+        },
+        "required": ["token"]
+      },
+      "uiHints": {
+        "token": {
+          "label": "连接令牌",
+          "placeholder": "从友虾小程序获取的 token",
+          "sensitive": true,
+          "help": "用于鉴权 WebSocket 连接，请妥善保管"
+        },
+        "wsUrl": {
+          "label": "WebSocket 地址",
+          "placeholder": "wss://api.gixin.cc",
+          "advanced": true
+        },
+        "allowFrom": {
+          "label": "允许的用户",
+          "placeholder": "用户 ID，多个用英文逗号分隔",
+          "help": "为空表示允许所有用户；填写后仅白名单内用户可触发对话"
+        },
+        "dmSecurity": {
+          "label": "私聊安全策略",
+          "placeholder": "open / closed / allowlist",
+          "advanced": true
+        }
+      },
+      "commands": {
+        "nativeCommandsAutoEnabled": true,
+        "nativeSkillsAutoEnabled": true
+      }
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sumeai/sumeclaw",
-  "version": "1.1.19",
+  "version": "1.1.20",
   "description": "友虾名片 OpenClaw Channel 插件 — 将 OpenClaw 连接到友虾名片平台，通过 AI 名片为客户提供服务",
   "type": "commonjs",
   "main": "dist/index.js",