@rowger_go/chatu 0.1.3

package/docs/channel/04-api-reference.md

@@ -0,0 +1,394 @@
+# Chatu Channel Plugin - API 接口参考
+
+> **上一节**：[03-capabilities.md](03-capabilities.md)  
+> **下一节**：[05-message-protocol.md](05-message-protocol.md)
+
+本文档描述 Chatu 插件**调用 WebHub 后端**的所有 HTTP/WebSocket 接口。WebHub 后端开发者需要实现这些接口。
+
+---
+
+## 认证方式（通用规则）
+
+大多数接口通过以下请求头认证：
+
+```http
+X-Channel-Token: {accessToken}
+X-Channel-ID: {channelId}
+```
+
+部分接口使用：
+
+```http
+x-access-token: {accessToken}
+```
+
+或：
+
+```http
+Authorization: Bearer {accessToken}
+```
+
+具体认证头见各接口说明。
+
+---
+
+## 1. 健康检查
+
+### `GET /health`
+
+检查后端服务是否可达（心跳探测使用）。
+
+**请求头**：无
+
+**响应示例**：
+```json
+{ "status": "ok", "timestamp": "2026-02-25T10:00:00.000Z" }
+```
+
+---
+
+## 2. 注册 / 连接管理
+
+### `POST /api/channel/quick-register`
+
+环境变量方式自动注册，获取频道凭证。
+
+**请求头**：无
+
+**请求体**：
+```json
+{
+  "key": "your-registration-key",
+  "url": "https://your-webhub.example.com"
+}
+```
+
+**响应**：
+```json
+{
+  "data": {
+    "channelId": "wh_ch_xxxxxx",
+    "accessToken": "wh_xxxxxxxxxxxxxxxx"
+  }
+}
+```
+
+---
+
+### `POST /api/channel/connect`
+
+插件启动时通知后端建立连接。
+
+**请求头**：
+```http
+x-access-token: {accessToken}
+```
+
+**请求体**：
+```json
+{
+  "channelId": "wh_ch_xxxxxx",
+  "pluginVersion": "0.1.0",
+  "workingDir": "/home/user"
+}
+```
+
+---
+
+### `POST /api/channel/disconnect`
+
+插件停止时通知后端断开连接。
+
+**请求头**：
+```http
+x-access-token: {accessToken}
+```
+
+**请求体**：
+```json
+{
+  "channelId": "wh_ch_xxxxxx"
+}
+```
+
+---
+
+## 3. 实时连接（WebSocket）
+
+### `GET /api/channel/ws` ← WebSocket 升级
+
+插件主连接方式，通过 WebSocket 实时接收用户消息。
+
+**协议**：`ws://` 或 `wss://`（由 `apiUrl` 的 http/https 自动转换）
+
+**认证**：连接时携带 `accessToken` 和 `channelId`（具体参数由后端实现决定）
+
+**后端推送消息格式**：见 [05-message-protocol.md](05-message-protocol.md)
+
+---
+
+## 4. 消息收发
+
+### `POST /api/channel/messages`
+
+插件向后端发送 AI 回复。
+
+**请求头**：
+```http
+Content-Type: application/json
+X-Channel-Token: {accessToken}
+X-Channel-ID: {channelId}
+```
+
+**请求体**：见 [05-message-protocol.md#出站消息格式](05-message-protocol.md#2-出站消息格式ai--webhub-后端)
+
+**响应**：
+```json
+{
+  "success": true,
+  "messageId": "msg_1234567_abc",
+  "id": "internal-db-id",
+  "deliveredAt": "2026-02-25T10:00:00.000Z"
+}
+```
+
+---
+
+### `POST /api/channel/messages/:messageId/ack`
+
+确认消息已被插件处理（HTTP 轮询模式使用）。
+
+**请求头**：
+```http
+Content-Type: application/json
+X-Channel-Token: {accessToken}
+```
+
+---
+
+## 5. 流式输出
+
+### `POST /api/channel/stream/chunk`
+
+发送流式 AI 回复的单个分块。
+
+**请求头**：
+```http
+Content-Type: application/json
+Authorization: Bearer {accessToken}
+```
+
+**请求体**：
+```json
+{
+  "messageId": "msg_1234567_abc",
+  "seq": 1,
+  "delta": "Hello, "
+}
+```
+
+---
+
+### `POST /api/channel/stream/done`
+
+通知后端流式回复已完成。
+
+**请求头**：
+```http
+Content-Type: application/json
+Authorization: Bearer {accessToken}
+```
+
+**请求体**：
+```json
+{
+  "messageId": "msg_1234567_abc",
+  "totalSeq": 5
+}
+```
+
+---
+
+## 6. 状态查询
+
+### `GET /api/channel/status`
+
+查询频道在后端的状态。
+
+**请求头**：
+```http
+x-access-token: {accessToken}
+X-Channel-ID: {channelId}
+```
+
+**响应**：
+```json
+{
+  "data": {
+    "status": "active"
+  }
+}
+```
+
+---
+
+## 7. 输入中状态
+
+### `POST /api/channel/typing`
+
+通知后端 AI 正在处理（显示"正在输入"提示）。
+
+**请求头**：
+```http
+Content-Type: application/json
+X-Channel-Token: {accessToken}
+```
+
+**请求体**：
+```json
+{
+  "channelId": "wh_ch_xxxxxx"
+}
+```
+
+---
+
+## 8. 会话命令
+
+### `GET /api/channel/commands`
+
+轮询获取后端下发的会话管理命令（在 HTTP 轮询模式末尾调用）。
+
+**请求头**：
+```http
+X-Channel-Token: {accessToken}
+X-Channel-ID: {channelId}
+```
+
+**查询参数**：`channelId={channelId}`
+
+**响应**：
+```json
+{
+  "data": {
+    "commands": [
+      {
+        "id": "cmd_001",
+        "commandType": "reset",
+        "senderId": "user-123",
+        "payload": null
+      },
+      {
+        "id": "cmd_002",
+        "commandType": "switch",
+        "senderId": "user-456",
+        "payload": {
+          "targetSessionKey": "session_key_abc",
+          "reason": "restore"
+        }
+      }
+    ]
+  }
+}
+```
+
+命令类型：
+
+| 类型 | 说明 |
+|------|------|
+| `reset` | 清空该用户的 OpenClaw 会话历史（删除 transcript 文件） |
+| `switch` | 将用户切换到指定历史会话 |
+
+---
+
+### `POST /api/channel/commands/:commandId/ack`
+
+确认命令执行结果。
+
+**请求头**：
+```http
+Content-Type: application/json
+X-Channel-Token: {accessToken}
+```
+
+**请求体**：
+```json
+{
+  "success": true,
+  "error": null,
+  "channelId": "wh_ch_xxxxxx"
+}
+```
+
+---
+
+## 9. 跨频道中继
+
+### `POST /api/channel/cross-channel-messages`
+
+将来自其他 OpenClaw 频道的消息同步到 WebHub 前端显示。
+
+**请求头**：
+```http
+Content-Type: application/json
+X-Access-Token: {accessToken}
+```
+
+**请求体**：
+```json
+{
+  "sourceChannel": "whatsapp",
+  "direction": "inbound",
+  "sender": {
+    "id": "user-123",
+    "name": "张三"
+  },
+  "content": "消息内容",
+  "sessionKey": "session_key_xxx",
+  "dedupId": "openclaw-msg-id"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `sourceChannel` | string | 来源频道 ID（如 `whatsapp`、`tui`） |
+| `direction` | `"inbound"` \| `"outbound"` | `inbound` = AI 回复，`outbound` = 用户消息 |
+| `sender.id` | string | 发送者 ID（可选） |
+| `sender.name` | string | 发送者显示名 |
+| `content` | string | 消息文本 |
+| `sessionKey` | string | 来源频道的会话 Key |
+| `dedupId` | string | OpenClaw 内部消息 ID（去重用，可选） |
+
+---
+
+## 10. HTTP 轮询（已废弃，仅参考）
+
+### `GET /api/channel/messages/pending`
+
+获取待处理的用户消息列表。当前版本使用 WebSocket 代替，此接口仅供参考。
+
+**请求头**：
+```http
+X-Channel-Token: {accessToken}
+X-Channel-ID: {accountId}
+```
+
+**查询参数**：`channelId={channelId}&after={isoTimestamp}`
+
+**响应**：
+```json
+{
+  "data": [
+    {
+      "id": "msg_001",
+      "content": "用户消息内容",
+      "sender": { "id": "user-123", "name": "张三" },
+      "createdAt": "2026-02-25T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+*最后更新: 2026-02-25*

package/docs/channel/05-message-protocol.md

@@ -0,0 +1,194 @@
+# Chatu Channel Plugin - 消息协议规范
+
+> **上一节**：[04-api-reference.md](04-api-reference.md)  
+> **下一节**：[06-security.md](06-security.md)
+
+本文档描述 Chatu 插件与 WebHub 后端之间交换的消息格式。
+
+---
+
+## 1. 入站消息格式（WebHub 后端 → 插件）
+
+通过 WebSocket 推送给插件的消息格式：
+
+```typescript
+interface InboundMessage {
+  /** 消息唯一 ID */
+  id: string;
+
+  /** 消息文本内容 */
+  content: {
+    text: string;
+    format?: string;
+  };
+
+  /** 发送者信息 */
+  sender: {
+    id: string;
+    displayName?: string;
+  };
+
+  /** 消息时间戳（毫秒） */
+  timestamp: number;
+
+  /** 消息角色（可选，'agent' 表示来自人工操作员） */
+  role?: 'agent' | string;
+
+  /** 媒体附件（可选） */
+  media?: Array<{
+    type: string;
+    url: string;
+  }>;
+}
+```
+
+### 示例
+
+```json
+{
+  "id": "msg-abc123",
+  "content": {
+    "text": "你好，我有一个问题"
+  },
+  "sender": {
+    "id": "user-456",
+    "displayName": "张三"
+  },
+  "timestamp": 1708139100000
+}
+```
+
+### `role: 'agent'` 的处理
+
+当 `role` 为 `"agent"` 时，消息来源为 WebHub 前端的人工操作员，插件会以 sender ID `webhub-agent` 派发到 OpenClaw AI。普通用户消息 `role` 字段为空。
+
+---
+
+## 2. 出站消息格式（AI → WebHub 后端）
+
+插件调用 `POST /api/channel/messages` 发送 AI 回复：
+
+```typescript
+interface OutboundMessage {
+  /** 插件生成的消息 ID（格式：msg_{timestamp}_{random}） */
+  messageId: string;
+
+  /** 目标接收者 */
+  target: {
+    type: 'user';
+    id: string;  // 用户 ID（与入站 sender.id 对应）
+  };
+
+  /** 消息内容 */
+  content: {
+    text: string;
+    format: 'plain';  // 当前固定为 plain
+  };
+
+  /** 消息时间戳（毫秒） */
+  timestamp: number;
+
+  /** 消息角色（固定为 'ai'） */
+  role: 'ai';
+
+  /** 回复引用（可选） */
+  replyTo?: {
+    id: string;  // 被回复的消息 ID
+  };
+
+  /** 媒体附件（可选） */
+  media?: Array<{
+    type: string;  // 如 'image', 'file'
+    url: string;
+  }>;
+
+  /** 消息类型（可选，由后端扩展使用） */
+  messageType?: string;
+
+  /** 元数据（可选，用于去重等） */
+  metadata?: {
+    dedupId?: string;   // OpenClaw 内部消息 ID，用于跨频道去重
+    [key: string]: unknown;
+  };
+}
+```
+
+### 示例
+
+```json
+{
+  "messageId": "msg_1708139100000_a3f7b",
+  "target": {
+    "type": "user",
+    "id": "user-456"
+  },
+  "content": {
+    "text": "您好！我来为您解答。",
+    "format": "plain"
+  },
+  "timestamp": 1708139102000,
+  "role": "ai",
+  "replyTo": {
+    "id": "msg-abc123"
+  }
+}
+```
+
+---
+
+## 3. 流式消息格式
+
+当 AI 以流式方式生成回复时，插件通过以下两个端点分块发送：
+
+### 3.1 单个分块（`POST /api/channel/stream/chunk`）
+
+```json
+{
+  "messageId": "msg_1708139100000_a3f7b",
+  "seq": 1,
+  "delta": "您好！"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `messageId` | 本次流式回复的消息 ID（全程保持不变） |
+| `seq` | 分块序号，从 1 开始递增 |
+| `delta` | 本次分块的文本增量 |
+
+### 3.2 流式完成（`POST /api/channel/stream/done`）
+
+```json
+{
+  "messageId": "msg_1708139100000_a3f7b",
+  "totalSeq": 5
+}
+```
+
+---
+
+## 4. 会话 Key 推导规则
+
+OpenClaw 通过以下规则将 `senderId` 映射到唯一会话 Key，相同 `senderId` + `accountId` + `channelId` 始终映射到同一会话：
+
+```
+sessionKey = resolveAgentRoute({
+  channel: 'chatu',
+  accountId: accountId,
+  peer: { kind: 'direct', id: senderId }
+})
+```
+
+这意味着：
+- 同一用户（`senderId` 相同）在同一账户下始终共享同一 AI 会话
+- 重置会话就是删除该 `sessionKey` 对应的 transcript 文件
+
+---
+
+## 5. Slash 命令授权规则
+
+消息文本以 `/` 开头时，OpenClaw 会将其标记为授权命令（`CommandAuthorized: true`），允许执行 agent slash-commands。普通消息不授权命令执行。
+
+---
+
+*最后更新: 2026-02-25*

package/docs/channel/06-security.md

@@ -0,0 +1,83 @@
+# Chatu Channel Plugin - 安全说明
+
+> **上一节**：[05-message-protocol.md](05-message-protocol.md)  
+> **返回**：[README.md](README.md)
+
+---
+
+## 1. 认证机制
+
+Chatu 插件使用基于 Token 的简单认证，无签名验证要求。
+
+### 1.1 主要认证方式
+
+大多数 API 请求使用以下请求头：
+
+```http
+X-Channel-Token: {accessToken}
+X-Channel-ID: {channelId}
+```
+
+### 1.2 连接时认证
+
+连接通知和断开通知使用：
+
+```http
+x-access-token: {accessToken}
+```
+
+### 1.3 流式接口认证
+
+流式输出相关接口使用标准 Bearer 令牌：
+
+```http
+Authorization: Bearer {accessToken}
+```
+
+### 1.4 跨频道中继认证
+
+```http
+X-Access-Token: {accessToken}
+```
+
+---
+
+## 2. Token 获取方式
+
+| 方式 | 说明 |
+|------|------|
+| **手动配置** | 从 WebHub 管理界面获取 `accessToken` 后直接写入 OpenClaw 配置 |
+| **环境变量注册** | 设置 `CHATU_KEY` + `CHATU_URL`，插件启动时自动调用 `/api/channel/quick-register` 获取 |
+| **密钥注册** | 配置 `secret`（`wh_secret_xxx`），用于自动注册 |
+
+---
+
+## 3. 安全最佳实践
+
+### 3.1 Token 保护
+
+- 不要将 `accessToken` 或 `secret` 提交到版本控制
+- 使用环境变量方式（`CHATU_KEY`）代替硬编码凭证
+- 定期轮换 Access Token
+
+### 3.2 网络安全
+
+- **生产环境务必使用 HTTPS/WSS**，避免 Token 在传输层泄露
+- `apiUrl` 使用 `https://` 时，WebSocket 自动升级为 `wss://`
+
+### 3.3 SSRF 防护
+
+由于 `apiUrl` 来自用户配置，WebHub 后端应验证 OpenClaw 侧的请求来源合法性。OpenClaw 平台本身也内置了 SSRF 防护机制。
+
+---
+
+## 4. 配置文件安全
+
+OpenClaw 配置存储在 `~/.openclaw/openclaw.json`，包含 `accessToken` 等敏感字段。建议：
+
+- 确保该文件权限为 `600`（仅所有者可读）
+- 不要将 `~/.openclaw/` 目录内容共享或纳入版本控制
+
+---
+
+*最后更新: 2026-02-25*

package/docs/channel/README.md

@@ -0,0 +1,30 @@
+# Chatu Channel Plugin - 文档目录
+
+本目录包含 OpenClaw Chatu 频道插件的技术文档。Chatu 通过 WebSocket（主）和 HTTP 轮询（兜底）与任意 WebHub 后端服务通信。
+
+---
+
+## 目录结构
+
+| 文档 | 内容 |
+|------|------|
+| [01-overview.md](01-overview.md) | 架构概述、消息流向、工作原理 |
+| [02-configuration.md](02-configuration.md) | 配置项说明、多账户配置、环境变量 |
+| [03-capabilities.md](03-capabilities.md) | 插件支持的功能矩阵 |
+| [04-api-reference.md](04-api-reference.md) | 插件调用的 WebHub API 端点 |
+| [05-message-protocol.md](05-message-protocol.md) | 入站/出站消息格式规范 |
+| [06-security.md](06-security.md) | 认证方式与安全说明 |
+
+---
+
+## 快速导航
+
+- **新接入 WebHub 后端？** → [01-overview.md](01-overview.md)
+- **配置插件？** → [02-configuration.md](02-configuration.md)
+- **实现 WebHub 后端服务？** → [04-api-reference.md](04-api-reference.md) 和 [05-message-protocol.md](05-message-protocol.md)
+- **了解支持的消息类型？** → [03-capabilities.md](03-capabilities.md)
+- **Auth/Token 问题？** → [06-security.md](06-security.md)
+
+---
+
+*最后更新: 2026-02-25*

package/docs/sdk/README.md

@@ -0,0 +1,13 @@
+# OpenClaw Channel Plugin SDK - 变更说明
+
+本目录记录 OpenClaw Channel Plugin SDK 各版本间的 API 变更，供插件维护者参考。
+
+## 版本变更记录
+
+| 文件 | 内容 |
+|------|------|
+| [v2026.1.29-v2026.2.19.md](v2026.1.29-v2026.2.19.md) | SDK `v2026.1.29` → `v2026.2.19` 变更报告 |
+
+---
+
+*最后更新: 2026-02-25*