@rowger_go/chatu 0.1.3

package/dist/sdk/types/channel.js

@@ -0,0 +1,36 @@
+"use strict";
+/******************************************************************
+ * Channel SDK - Channel Types
+ *
+ * OpenClaw Channel SDK 的核心类型定义
+ *
+ * @see https://github.com/chatu-ai/openclaw-web-hub-channel
+ ******************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TargetType = exports.MessageType = void 0;
+/**
+ * 消息类型 [Channel SDK 标准]
+ */
+var MessageType;
+(function (MessageType) {
+    MessageType["TEXT"] = "text";
+    MessageType["IMAGE"] = "image";
+    MessageType["VIDEO"] = "video";
+    MessageType["AUDIO"] = "audio";
+    MessageType["FILE"] = "file";
+    MessageType["LOCATION"] = "location";
+    /** Plugin-Channel Realtime: operation/command type */
+    MessageType["ACTION"] = "action";
+    /** Plugin-Channel Realtime: unrecognised type, frontend renders placeholder */
+    MessageType["UNKNOWN"] = "unknown";
+})(MessageType || (exports.MessageType = MessageType = {}));
+/**
+ * 目标类型 [Channel SDK 标准]
+ */
+var TargetType;
+(function (TargetType) {
+    TargetType["USER"] = "user";
+    TargetType["GROUP"] = "group";
+    TargetType["CHANNEL"] = "channel";
+})(TargetType || (exports.TargetType = TargetType = {}));
+//# sourceMappingURL=channel.js.map

package/dist/sdk/types/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../../src/sdk/types/channel.ts"],"names":[],"mappings":";AAAA;;;;;;oEAMoE;;;AAWpE;;GAEG;AACH,IAAY,WAWX;AAXD,WAAY,WAAW;IACrB,4BAAa,CAAA;IACb,8BAAe,CAAA;IACf,8BAAe,CAAA;IACf,8BAAe,CAAA;IACf,4BAAa,CAAA;IACb,oCAAqB,CAAA;IACrB,sDAAsD;IACtD,gCAAiB,CAAA;IACjB,+EAA+E;IAC/E,kCAAmB,CAAA;AACrB,CAAC,EAXW,WAAW,2BAAX,WAAW,QAWtB;AAED;;GAEG;AACH,IAAY,UAIX;AAJD,WAAY,UAAU;IACpB,2BAAa,CAAA;IACb,6BAAe,CAAA;IACf,iCAAmB,CAAA;AACrB,CAAC,EAJW,UAAU,0BAAV,UAAU,QAIrB"}

package/docs/channel/01-overview.md

@@ -0,0 +1,117 @@
+# Chatu Channel Plugin - 架构概述
+
+> **下一节**：[02-configuration.md](02-configuration.md)
+
+---
+
+## 1. 什么是 Chatu 插件？
+
+Chatu 是一个 OpenClaw 频道插件，让 OpenClaw AI 能与任意基于 HTTP/WebSocket 的 **WebHub 后端服务**通信。典型场景是将网站聊天窗口接入 OpenClaw AI。
+
+### 角色说明
+
+| 角色 | 说明 |
+|------|------|
+| **Browser / 前端** | 用户所在的网页，发送消息的源 |
+| **WebHub 后端服务** | 中间层，管理频道和消息队列，需要开发者实现 |
+| **Chatu 插件** | OpenClaw 内运行，连接 WebHub 后端服务 |
+| **OpenClaw AI** | 处理消息、生成回复 |
+
+---
+
+## 2. 系统架构
+
+```
+Browser (用户)
+    │  POST /api/webhub/channels/:id/messages
+    ▼
+WebHub 后端服务
+    │  WebSocket ws://...  /api/channel/ws
+    │  (或 HTTP 轮询 fallback)
+    ▼
+Chatu 插件 (本插件)
+    │  调用 OpenClaw AI 流水线
+    ▼
+OpenClaw AI
+    │  POST /api/channel/messages  (AI 回复)
+    ▼
+WebHub 后端服务
+    │  WebSocket push
+    ▼
+Browser (用户收到 AI 回复)
+```
+
+---
+
+## 3. 消息流向
+
+### 3.1 入站（用户 → AI）
+
+1. 浏览器发消息到 WebHub 后端
+2. WebHub 后端通过 WebSocket 推送消息到 Chatu 插件
+3. 插件解析消息，调用 OpenClaw AI 流水线
+4. AI 生成回复，插件通过 `POST /api/channel/messages` 回传给 WebHub
+5. WebHub 通过 WebSocket 将 AI 回复推送给浏览器
+
+### 3.2 出站（AI → 用户）
+
+AI 回复通过以下 HTTP 请求发送：
+
+```http
+POST {apiUrl}/api/channel/messages
+X-Channel-Token: {accessToken}
+X-Channel-ID: {channelId}
+Content-Type: application/json
+
+{
+  "messageId": "msg_1234567_abc",
+  "target": { "type": "user", "id": "user-123" },
+  "content": { "text": "AI 回复内容", "format": "plain" },
+  "timestamp": 1708139100000,
+  "role": "ai"
+}
+```
+
+---
+
+## 4. 连接机制
+
+### 4.1 主连接：WebSocket
+
+插件优先使用 WebSocket 实时连接：
+
+- 连接地址：`{apiUrl}/api/channel/ws`（自动将 http 转为 ws）
+- 认证：请求头携带 `accessToken` 和 `channelId`
+- 断线自动重连（指数退避，最大 30 秒）
+- 重连后自动重发断线期间缓存的未送达回复
+
+### 4.2 兜底：HTTP 轮询（已废弃）
+
+早期版本使用 HTTP 轮询（`GET /api/channel/messages/pending`，每 2 秒），当前版本已切换为 WebSocket，轮询逻辑保留仅供参考。
+
+---
+
+## 5. 生命周期
+
+插件通过 OpenClaw 的 Gateway 生命周期管理连接：
+
+1. **启动**：通过 `quick-register`（环境变量方式）或手动配置获取凭证，然后调用 `POST /api/channel/connect` 通知后端
+2. **运行**：维持 WebSocket 长连接，持续接收消息并派发给 AI
+3. **停止**：调用 `POST /api/channel/disconnect` 通知后端，断开 WebSocket
+
+---
+
+## 6. 快速注册（环境变量方式）
+
+如果设置了以下环境变量，插件启动时会自动向 WebHub 后端注册：
+
+| 环境变量 | 说明 |
+|----------|------|
+| `CHATU_KEY` | 注册密钥 |
+| `CHATU_URL` 或 `CHATU_API_URL` | WebHub 后端地址 |
+
+自动注册调用：`POST {apiUrl}/api/channel/quick-register`，获取 `channelId` 和 `accessToken` 后写入配置。
+
+---
+
+*最后更新: 2026-02-25*

package/docs/channel/02-configuration.md

@@ -0,0 +1,138 @@
+# Chatu Channel Plugin - 配置说明
+
+> **上一节**：[01-overview.md](01-overview.md)  
+> **下一节**：[03-capabilities.md](03-capabilities.md)
+
+---
+
+## 1. 配置项完整列表
+
+| 配置项 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `enabled` | boolean | 否 | `true` | 是否启用此频道 |
+| `apiUrl` | string | **是** | — | WebHub 后端服务的 HTTP 地址 |
+| `channelId` | string | **是** | — | 频道 ID（从 WebHub 后端管理页获取，如 `wh_ch_xxxxx`） |
+| `secret` | string | 二选一 | — | 频道密钥（`wh_secret_xxx`），用于初次注册 |
+| `accessToken` | string | 二选一 | — | 访问凭证（`wh_xxxxxxx`），注册后自动写入或手动填写 |
+| `timeout` | number | 否 | `30000` | HTTP/WS 请求超时时间（毫秒） |
+
+> **说明**：`secret` 和 `accessToken` 二选一。建议通过 WebHub 管理界面获取 `accessToken` 后直接配置，`secret` 仅在需要通过 API 注册时使用。
+
+---
+
+## 2. CLI 快速配置
+
+```bash
+# 设置 WebHub 后端地址
+openclaw config set channels.chatu.apiUrl "https://your-webhub.example.com"
+
+# 设置频道 ID
+openclaw config set channels.chatu.channelId "wh_ch_xxxxxx"
+
+# 设置访问凭证（推荐）
+openclaw config set channels.chatu.accessToken "wh_xxxxxxxxxxxxxxxx"
+
+# 或者设置密钥（用于自动注册）
+openclaw config set channels.chatu.secret "wh_secret_xxxxxxxxxx"
+
+# 重启网关使配置生效
+openclaw gateway restart
+```
+
+---
+
+## 3. 配置文件示例
+
+编辑 `~/.openclaw/openclaw.json`：
+
+### 3.1 单账户配置（推荐）
+
+```json
+{
+  "channels": {
+    "chatu": {
+      "enabled": true,
+      "apiUrl": "https://your-webhub.example.com",
+      "channelId": "wh_ch_xxxxxx",
+      "accessToken": "wh_xxxxxxxxxxxxxxxx",
+      "timeout": 30000
+    }
+  }
+}
+```
+
+### 3.2 多账户配置
+
+当需要同时连接多个 WebHub 服务时：
+
+```json
+{
+  "channels": {
+    "chatu": {
+      "accounts": {
+        "site-a": {
+          "accountId": "site-a",
+          "apiUrl": "https://webhub-a.example.com",
+          "channelId": "wh_ch_aaaaaa",
+          "accessToken": "wh_aaaaaaaaaaaaaaa"
+        },
+        "site-b": {
+          "accountId": "site-b",
+          "apiUrl": "https://webhub-b.example.com",
+          "channelId": "wh_ch_bbbbbb",
+          "accessToken": "wh_bbbbbbbbbbbbbbb"
+        }
+      }
+    }
+  }
+}
+```
+
+配置优先级：账户级 > 频道级（`channels.chatu.*`）> 插件级（`plugins.entries.chatu.config.*`）
+
+---
+
+## 4. 环境变量（快速注册）
+
+如果需要在部署时自动完成频道注册，可以使用环境变量：
+
+| 变量名 | 说明 |
+|--------|------|
+| `CHATU_KEY` | 注册密钥（由 WebHub 后端提供） |
+| `CHATU_URL` | WebHub 后端地址（与 `apiUrl` 等效） |
+| `CHATU_API_URL` | 同上，备用名 |
+| `CHATU_CACHE_MAX` | 本地缓存队列最大容量（默认 1000） |
+| `CHATU_CACHE_FILE` | 缓存文件路径前缀（用于持久化未送达消息） |
+
+当 `CHATU_KEY` 和 `CHATU_URL` 都设置时，插件启动时自动调用 `POST /api/channel/quick-register` 获取 `channelId` 和 `accessToken`，无需手动配置。
+
+```bash
+export CHATU_KEY="your-registration-key"
+export CHATU_URL="https://your-webhub.example.com"
+openclaw gateway restart
+```
+
+---
+
+## 5. 验证配置
+
+```bash
+# 查看当前 chatu 配置
+openclaw config get channels.chatu
+
+# 查看插件加载状态
+openclaw plugins list | grep chatu
+
+# 检查连接状态
+openclaw health
+```
+
+期望输出（插件已正确加载）：
+
+```
+│ Chatu │ chatu │ loaded │ .../dist/index.js │ 0.1.0 │
+```
+
+---
+
+*最后更新: 2026-02-25*

package/docs/channel/03-capabilities.md

@@ -0,0 +1,86 @@
+# Chatu Channel Plugin - 功能支持矩阵
+
+> **上一节**：[02-configuration.md](02-configuration.md)  
+> **下一节**：[04-api-reference.md](04-api-reference.md)
+
+---
+
+## 1. 核心能力
+
+| 能力 | 支持状态 | 说明 |
+|------|----------|------|
+| 私聊（Direct Message） | ✅ 支持 | 与单个用户对话 |
+| 群聊（Group） | ✅ 支持 | 多人会话 |
+| 回复 | ✅ 支持 | 回复指定消息，携带 `replyTo` |
+| 消息编辑 | ✅ 支持 | 编辑已发送的消息 |
+| 消息撤回 | ✅ 支持 | 删除已发送的消息 |
+| 表情反应 | ✅ 支持 | Emoji 反应（需后端实现） |
+| 媒体附件 | ✅ 支持 | 图片、文件等（通过 URL 引用） |
+| 消息线程 | ✅ 支持 | 将回复关联到原消息 |
+| 流式输出 | ✅ 支持 | 分块推送 AI 回复（通过 `/stream/chunk` 端点） |
+| 投票 | ❌ 不支持 | — |
+
+---
+
+## 2. 消息内容
+
+| 内容类型 | 支持状态 | 说明 |
+|----------|----------|------|
+| 纯文本 | ✅ 支持 | `content.format = "plain"` |
+| 媒体 URL | ✅ 支持 | 图片、文件以 URL 引用，`media[].url` |
+| 回复引用 | ✅ 支持 | `replyTo.id` 携带被回复的消息 ID |
+
+---
+
+## 3. 会话管理
+
+| 功能 | 支持状态 | 说明 |
+|------|----------|------|
+| 会话重置 | ✅ 支持 | 通过 WebHub 后端下发 `reset` 命令清空对话历史 |
+| 会话切换 | ✅ 支持 | 通过 `switch` 命令切换到指定历史会话 |
+| Slash 命令 | ✅ 支持 | 以 `/` 开头的消息自动授权为命令 |
+
+---
+
+## 4. 跨频道中继
+
+| 功能 | 支持状态 | 说明 |
+|------|----------|------|
+| 跨频道消息同步 | ✅ 支持 | 将其他 OpenClaw 频道（如 WhatsApp、TUI）的消息同步显示到 WebHub 前端 |
+
+通过 `POST /api/channel/cross-channel-messages` 实现，消息携带原始频道标识和方向（入站/出站）。
+
+---
+
+## 5. 连接可靠性
+
+| 特性 | 说明 |
+|------|------|
+| 自动重连 | WebSocket 断线后指数退避重连（2s → 4s → 8s → … 上限 30s） |
+| 失败重发 | 断线期间的未送达 AI 回复缓存在内存（可配置持久化到文件），重连后自动重发 |
+| 消息去重 | 内存维护已处理消息 ID 集合，防止 same-ms 消息重复处理（容量 500） |
+| 心跳探测 | 定期 `GET {apiUrl}/health` 检查后端可达性 |
+
+---
+
+## 6. 声明的能力（代码）
+
+以下是插件向 OpenClaw 注册的 `capabilities` 声明（来自 `src/index.ts`）：
+
+```typescript
+capabilities: {
+  chatTypes: ['direct', 'group'],
+  reply: true,
+  edit: true,
+  unsend: true,
+  reactions: true,
+  polls: false,
+  media: true,
+  threads: true,
+  blockStreaming: false,
+}
+```
+
+---
+
+*最后更新: 2026-02-25*