ddchat 0.2.0 → 0.3.0

package/CLAUDE.md

@@ -1,51 +1,51 @@
-# CLAUDE.md
-
-本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指导。
-
-## 项目概述
-
-DDChat 频道插件 (`@ddchat/openclaw-ddchat`) — OpenClaw AI 智能体平台的 DDChat（内部即时通讯）频道集成插件。通过 WebSocket 或 Webhook 连接，将 DDChat 的私聊和群聊消息桥接到 OpenClaw 智能体。
-
-## 技术栈
-
-- TypeScript，ES 模块 (`"type": "module"`)
-- OpenClaw monorepo 的一部分（使用 `workspace:*` 依赖）
-- OpenClaw 插件 SDK：`openclaw/plugin-sdk/core`、`openclaw/plugin-sdk/setup`、`openclaw/plugin-sdk/channel-pairing`、`openclaw/plugin-sdk/media-runtime`
-
-## 开发与测试
-
-```bash
-# 启动模拟 DDChat 服务器（WebSocket 端口 :9001，HTTP 界面端口 :9020）
-node ddchat/test/server.mjs
-
-# 将插件安装到 OpenClaw
-openclaw channels add --channel ddchat --token "appId:appSecret"
-```
-
-无独立的构建或测试脚本 — 构建由 OpenClaw 工作区统一处理。
-
-## 架构
-
-插件遵循 OpenClaw 的 `ChatChannelPlugin` 模式，包含以下核心模块：
-
-- **`index.ts`** — 插件入口，导出 extensions 和 setup entry
-- **`src/channel.ts`** — 插件定义：能力声明、配置 schema、安装流程、网关、安全策略
-- **`src/gateway.ts`** — WebSocket 生命周期：连接、认证（token 作为查询参数）、心跳 ping/pong、指数退避重连（1s→2s→5s→10s→30s）
-- **`src/inbound.ts`** — 接收消息（WebSocket 或 webhook），去重，解析媒体/文件，路由到 AI 智能体，处理流式响应
-- **`src/outbound.ts`** — 将智能体回复发送回 DDChat；按 4000 字符使用 markdown 感知方式分块；处理媒体附件（base64 或 URL）
-- **`src/types.ts`** — `DdchatResolvedAccount` 配置类型、账户解析/合并逻辑、策略类型
-- **`src/runtime.ts`** — 全局插件状态：去重存储、WebSocket 发送函数
-- **`src/dedupe.ts`** — 基于 TTL 的消息去重（默认 48 小时），带 GC 回收
-- **`src/pairing.ts`** — 用户配对审批流程，ID 标准化（去除前缀）
-- **`src/session.ts`** — 会话 key 构造，用于私聊/群聊路由
-
-**数据流：** DDChat → WebSocket/Webhook → inbound.ts（去重、解析、媒体处理）→ OpenClaw 智能体 → outbound.ts（分块、发送）→ DDChat
-
-## 关键约定
-
-- 出站消息包含 `from: "plugin"` 字段
-- 标识符：From 使用 `ddchat:${userId}`，To 使用 `user:${userId}` / `group:${groupId}`
-- 流式 ID：`ddchat-stream-${messageId}`
-- 连接模式：`websocket`（默认）| `webhook`
-- 访问策略：私聊使用 `open | pairing | allowlist`（默认：pairing）；群聊使用 `open | allowlist | disabled`（默认：allowlist）
-- 流式模式：`chunk` | `token`
+# CLAUDE.md
+
+本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指导。
+
+## 项目概述
+
+DDChat 频道插件 (`@ddchat/openclaw-ddchat`) — OpenClaw AI 智能体平台的 DDChat（内部即时通讯）频道集成插件。通过 WebSocket 或 Webhook 连接，将 DDChat 的私聊和群聊消息桥接到 OpenClaw 智能体。
+
+## 技术栈
+
+- TypeScript，ES 模块 (`"type": "module"`)
+- OpenClaw monorepo 的一部分（使用 `workspace:*` 依赖）
+- OpenClaw 插件 SDK：`openclaw/plugin-sdk/core`、`openclaw/plugin-sdk/setup`、`openclaw/plugin-sdk/channel-pairing`、`openclaw/plugin-sdk/media-runtime`
+
+## 开发与测试
+
+```bash
+# 启动模拟 DDChat 服务器（WebSocket 端口 :9001，HTTP 界面端口 :9020）
+node ddchat/test/server.mjs
+
+# 将插件安装到 OpenClaw
+openclaw channels add --channel ddchat --token "appId:appSecret"
+```
+
+无独立的构建或测试脚本 — 构建由 OpenClaw 工作区统一处理。
+
+## 架构
+
+插件遵循 OpenClaw 的 `ChatChannelPlugin` 模式，包含以下核心模块：
+
+- **`index.ts`** — 插件入口，导出 extensions 和 setup entry
+- **`src/channel.ts`** — 插件定义：能力声明、配置 schema、安装流程、网关、安全策略
+- **`src/gateway.ts`** — WebSocket 生命周期：连接、认证（token 作为查询参数）、心跳 ping/pong、指数退避重连（1s→2s→5s→10s→30s）
+- **`src/inbound.ts`** — 接收消息（WebSocket 或 webhook），去重，解析媒体/文件，路由到 AI 智能体，处理流式响应
+- **`src/outbound.ts`** — 将智能体回复发送回 DDChat；按 4000 字符使用 markdown 感知方式分块；处理媒体附件（base64 或 URL）
+- **`src/types.ts`** — `DdchatResolvedAccount` 配置类型、账户解析/合并逻辑、策略类型
+- **`src/runtime.ts`** — 全局插件状态：去重存储、WebSocket 发送函数
+- **`src/dedupe.ts`** — 基于 TTL 的消息去重（默认 48 小时），带 GC 回收
+- **`src/pairing.ts`** — 用户配对审批流程，ID 标准化（去除前缀）
+- **`src/session.ts`** — 会话 key 构造，用于私聊/群聊路由
+
+**数据流：** DDChat → WebSocket/Webhook → inbound.ts（去重、解析、媒体处理）→ OpenClaw 智能体 → outbound.ts（分块、发送）→ DDChat
+
+## 关键约定
+
+- 出站消息包含 `from: "plugin"` 字段
+- 标识符：From 使用 `ddchat:${userId}`，To 使用 `user:${userId}` / `group:${groupId}`
+- 流式 ID：`ddchat-stream-${messageId}`
+- 连接模式：`websocket`（默认）| `webhook`
+- 访问策略：私聊使用 `open | pairing | allowlist`（默认：pairing）；群聊使用 `open | allowlist | disabled`（默认：allowlist）
+- 流式模式：`chunk` | `token`

package/OPTIMIZATION.md

@@ -1,105 +1,129 @@
-# DDChat 插件代码优化建议
-
-## 1. 去重 GC 性能问题
-
-**文件：** `src/dedupe.ts:23-29`
-
-`gc()` 在每次 `isDuplicate()` 调用时都全量遍历整个 Map。高频消息场景下性能会线性退化。
-
-**建议：** 改为按频率限流 GC（如每 N 次调用或每 M 秒执行一次），或改用双桶/时间轮策略。
-
----
-
-## 2. 全局单例状态不支持多账户并发（功能缺陷）
-
-**文件：** `src/runtime.ts`
-
-`wsSend` 和 `wsConnected` 是全局唯一的，但插件支持多账户。如果两个账户同时启动 WebSocket，后启动的会覆盖前一个的 `wsSend`，导致第一个账户的出站消息实际发到第二个连接上。
-
-**建议：** 将 `wsSend` 改为 `Map<accountId, sendFn>` 结构，出站时按 `accountId` 查找对应的发送函数。
-
----
-
-## 3. messageId 使用 Date.now() 存在碰撞风险
-
-**文件：** `src/outbound.ts:33,55`
-
-`ddchat-text-${Date.now()}` 在高并发下可能产生重复 ID。
-
-**建议：** 加入自增计数器或使用 `crypto.randomUUID()`。
-
----
-
-## 4. Webhook 模式下的轮询等待（资源浪费）
-
-**文件：** `src/gateway.ts:29-36`
-
-Webhook 模式用 `setInterval` 每秒轮询 `abortSignal.aborted`，浪费资源。
-
-**建议：** 改为直接监听 `abortSignal` 的 `abort` 事件：
-
-```ts
-await new Promise<void>(resolve => {
-  ctx.abortSignal.addEventListener("abort", () => resolve(), { once: true });
-});
-```
-
----
-
-## 5. resolveMediaMaxBytes 重复定义
-
-**文件：** `src/inbound.ts:68-76` 和 `src/outbound.ts:6-12`
-
-`inbound.ts` 的 `resolveMediaFetchMaxBytes` 和 `outbound.ts` 的 `resolveMediaMaxBytes` 逻辑完全相同。
-
-**建议：** 提取到 `types.ts` 或新建一个共享工具函数。
-
----
-
-## 6. WebSocket 构造器类型处理冗余
-
-**文件：** `src/gateway.ts:122-135`
-
-通过 `globalThis as unknown` 手动声明 WebSocket 类型，既冗长又不安全。
-
-**建议：** 使用 TypeScript 内置的 `WebSocket` 类型（TS 4.4+ 全局可用），或在文件顶部用 `/// <reference lib="dom" />` 引入，去掉手动类型断言。
-
----
-
-## 7. gateway.ts 中 ctx 类型未复用
-
-**文件：** `src/gateway.ts:102-117`
-
-`runWsSession` 的 `ctx` 参数手写了大量类型结构，���这些应该可以从 SDK 中导入。
-
-**建议：** 从 `openclaw/plugin-sdk/core` 导入网关上下文类型，避免与 SDK 类型不同步。
-
----
-
-## 8. 流式响应在 WebSocket 断开时静默丢失
-
-**文件：** `src/inbound.ts:320-334`
-
-`emitStream` 中调用 `getDdchatState().wsSend?.(...)` 使用了可选链，连接断开时流式数据无声丢失，客户端无法感知。
-
-**建议：** 至少记录一条日志，或在 `wsSend` 返回 `false` 时尝试缓冲/通知调用方。
-
----
-
-## 9. buildDdchatSessionKey 未被使用
-
-**文件：** `src/session.ts`
-
-整个 `session.ts` 导出了 `buildDdchatSessionKey` 函数，但在项目中没有任何地方引用它（路由使用的是 SDK 的 `resolveAgentRoute`）。
-
-**建议：** 确认是否为遗留代码，如果不需要则移除。
-
----
-
-## 10. Webhook 路径配置未生效
-
-**文件：** `src/inbound.ts:212` 和 `src/types.ts:108-111`
-
-`types.ts` 中解析了 `webhookPath` 和 `webhookPort` 配置，但 `registerDdchatWebhook` 硬编码了 `/ddchat/webhook` 路径，并未使用账户配置中的值。
-
-**建议：** 使用 `account.webhookPath` 注册路由，或移除 `types.ts` 中未使用的配置字段。
+# DDChat 插件优化记录
+
+本文按实施优先级记录当前代码中的优化项。状态说明：`已完成` 表示本轮已落地；`待后续` 表示仍建议单独评估或实施。
+
+## P0：正确性与安全边界
+
+### 1. 多账户 WebSocket 运行态为全局单例（已完成）
+
+**文件：** `src/runtime.ts`、`src/gateway.ts`、`src/outbound.ts`、`src/inbound.ts`
+
+当前 `wsSend` 和 `wsConnected` 是全局唯一状态，但插件支持多账户。多个账户同时连接 WebSocket 时，后启动账户会覆盖前一个账户的发送函数，导致出站消息和流式消息可能发到错误连接。
+
+**建议：** 将 WebSocket 运行态改为按 `accountId` 存储，例如 `Map<accountId, { connected, send }>`；出站文本、媒体、流式 chunk、入站 reply delivery 都按账户取对应发送函数。停止某个账户时只清理该账户状态。
+
+### 2. WebSocket 入站失败缺少 nack（已完成）
+
+**文件：** `src/gateway.ts`
+
+WebSocket `message` handler 处理失败时目前只记录日志，不向 DDChat 端返回失败确认。调用方无法区分“仍在处理”“已失败”“消息被丢弃”。
+
+**建议：** 在处理异常时，如果连接仍打开，发送 `ack` 且 `ok:false`，包含 `from:"plugin"`、`accountId`、`messageId`（如可解析）和简短错误信息。
+
+### 3. 入站未拒绝禁用账户（已完成）
+
+**文件：** `src/inbound.ts`
+
+入站处理解析账户后没有检查 `account.enabled`。禁用账户仍可能通过 webhook 或已有 WebSocket 路径进入后续路由。
+
+**建议：** 在 dedupe 前检查 `account.enabled`，禁用账户直接拒绝，避免消息被记录为已处理。
+
+### 4. Webhook 请求体无最大读取限制（已完成）
+
+**文件：** `src/inbound.ts`
+
+`readRawBodyFromStream` 会将整个请求体读入内存，没有上限。异常大请求可能造成内存压力。
+
+**建议：** 增加 webhook body 最大字节数，读取 stream 时累计字节数并在超限时中止处理。
+
+### 5. Base64 媒体解码前未做大小预检（已完成）
+
+**文件：** `src/inbound.ts`
+
+入站 base64 媒体会先 `Buffer.from(base64, "base64")` 完整解码，再交给 `saveMediaBuffer` 校验大小。超大 base64 会先消耗内存。
+
+**建议：** 解码前根据 base64 长度预估 decoded size，超过 `mediaMaxMb` 时直接拒绝该媒体，保留保存阶段的二次校验。
+
+## P1：可靠性和可观测性
+
+### 6. 去重 GC 每次全量扫描（已完成）
+
+**文件：** `src/dedupe.ts`
+
+`isDuplicate()` 每次调用都会遍历整个 Map 清理过期项。高频消息场景下会线性退化。
+
+**建议：** 按时间间隔或调用次数触发 GC，例如每 60 秒或每 1000 次检查清理一次，同时保持过期 key 被覆盖的现有语义。
+
+### 7. messageId 使用 Date.now() 存在碰撞风险（已完成）
+
+**文件：** `src/outbound.ts`、`src/inbound.ts`
+
+`ddchat-text-${Date.now()}`、`ddchat-media-${Date.now()}`、`ddchat-out-${Date.now()}` 在同毫秒并发下可能重复。
+
+**建议：** 使用 `crypto.randomUUID()` 或时间戳 + 进程内自增计数器生成后缀，保留现有前缀。
+
+### 8. 出站日志过多且可能泄露内容（已完成）
+
+**文件：** `src/outbound.ts`
+
+当前出站路径使用 `console.log/error` 打印连接状态、完整 payload、媒体路径和加载细节。完整 payload 可能包含用户消息、媒体 URL、本地路径或大体积字段。
+
+**建议：** 移除调试日志，或只保留不含正文/base64/token 的简短错误信息；避免打印完整 payload、text、mediaBase64。
+
+### 9. 流式/非流式发送失败反馈不足（已完成）
+
+**文件：** `src/inbound.ts`
+
+流式发送使用可选链，WebSocket 断开时会静默丢失；非流式 reply delivery 计算了 `sent` 但没有使用结果。
+
+**建议：** 按账户发送并检查返回值；失败时至少记录简短日志，避免静默丢失。
+
+## P2：配置一致性和维护性
+
+### 10. Webhook 模式使用轮询等待停止（已完成）
+
+**文件：** `src/gateway.ts`
+
+Webhook 模式通过 `setInterval` 每秒检查 `abortSignal.aborted`。
+
+**建议：** 改为监听 `abortSignal` 的 `abort` 事件，避免无意义轮询并提升停止响应速度。
+
+### 11. webhookPath 配置未生效（已完成）
+
+**文件：** `src/inbound.ts`、`src/types.ts`
+
+`types.ts` 解析了 `webhookPath`，但注册 HTTP 路由时硬编码 `/ddchat/webhook`。用户配置自定义路径不会生效。
+
+**建议：** 注册默认路径，并从当前配置收集账户级 `webhookPath` 去重注册；非法路径回退默认路径。若某路径唯一映射到一个账户，可作为该 route 的 fallback account。
+
+### 12. webhookPort 配置未被使用（待后续）
+
+**文件：** `src/types.ts`
+
+`webhookPort` 被解析但当前插件入口只注册 SDK HTTP route，并未自行监听端口。
+
+**建议：** 如果 SDK route 不支持插件自管端口，应移除或标记为暂不支持，避免误导配置使用者。
+
+### 13. mediaMaxMb 解析逻辑重复（已完成）
+
+**文件：** `src/inbound.ts`、`src/outbound.ts`
+
+入站和出站分别实现了相同的 `agents.defaults.mediaMaxMb` 解析逻辑。
+
+**建议：** 提取共享 helper，例如 `resolveDdchatMediaMaxBytes(cfg)`，统一供入站、出站、大小预检使用。
+
+### 14. gateway 上下文和 WebSocket 类型可进一步收敛（待后续）
+
+**文件：** `src/gateway.ts`
+
+`runWsSession` 手写了较多 ctx 类型并使用了类型断言。长期看容易和 SDK 类型不同步。
+
+**建议：** 若 SDK 暴露对应 gateway context 类型，则复用；否则保留本地最小类型，不为类型美化引入行为风险。
+
+### 15. session.ts 当前未被引用（待后续）
+
+**文件：** `src/session.ts`
+
+当前会话路由使用 SDK 的 `resolveAgentRoute`，`buildDdchatSessionKey` 未被项目引用。
+
+**建议：** 确认是否属于外部可用 API；如果不是，后续可单独移除，避免误导维护者。

package/README.md

@@ -1,14 +1,22 @@
-# 本地安装ddchat插件
-```shell
-openclaw plugins install "安装包路径"
-```
-
-# 默认default账号
-```shell
-openclaw channels add --channel ddchat --token "appId:appSecret"
-```
-
-# 多个账号时指定账户名 避免覆盖
-```shell
-openclaw channels add --channel ddchat --account xxx --token "appId:appSecret"
-```
+# 本地安装ddchat插件
+```shell
+openclaw plugins install "安装包路径"
+```
+
+# 仓库管理ddchat插件
+```shell
+openclaw plugins install ddchat # 安装插件
+openclaw plugins update ddchat # 更新插件
+openclaw plugins uninstall ddchat # 卸载插件
+```
+
+
+# 默认default账号
+```shell
+openclaw channels add --channel ddchat --token "appId:appSecret"
+```
+
+# 多个账号时指定账户名 避免覆盖
+```shell
+openclaw channels add --channel ddchat --account xxx --token "appId:appSecret"
+```

package/index.ts

@@ -1,13 +1,13 @@
-import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
-import { ddchatPlugin } from "./src/channel.js";
-import { registerDdchatWebhook } from "./src/inbound.js";
-
-export { ddchatPlugin } from "./src/channel.js";
-
-export default defineChannelPluginEntry({
-  id: "ddchat",
-  name: "DDChat",
-  description: "DDChat channel plugin",
-  plugin: ddchatPlugin,
-  registerFull: registerDdchatWebhook,
-});
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { ddchatPlugin } from "./src/channel.js";
+import { registerDdchatWebhook } from "./src/inbound.js";
+
+export { ddchatPlugin } from "./src/channel.js";
+
+export default defineChannelPluginEntry({
+  id: "ddchat",
+  name: "DDChat",
+  description: "DDChat channel plugin",
+  plugin: ddchatPlugin,
+  registerFull: registerDdchatWebhook,
+});

package/openclaw.plugin.json

@@ -1,15 +1,15 @@
-{
-  "id": "ddchat",
-  "kind": "channel",
-  "channels": ["ddchat"],
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {
-      "channels": {
-        "type": "object",
-        "additionalProperties": true
-      }
-    }
-  }
-}
+{
+  "id": "ddchat",
+  "kind": "channel",
+  "channels": ["ddchat"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "channels": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/package.json

@@ -1,36 +1,36 @@
-{
-  "name": "ddchat",
-  "version": "0.2.0",
-  "description": "DDChat channel plugin for OpenClaw",
-  "type": "module",
-  "devDependencies": {
-    "openclaw": "workspace:*"
-  },
-  "peerDependencies": {
-    "openclaw": ">=2026.2.0"
-  },
-  "peerDependenciesMeta": {
-    "openclaw": {
-      "optional": true
-    }
-  },
-  "openclaw": {
-    "extensions": [
-      "./index.ts"
-    ],
-    "setupEntry": "./setup-entry.ts",
-    "channel": {
-      "id": "ddchat",
-      "label": "DDChat",
-      "selectionLabel": "DDChat (IM)",
-      "detailLabel": "DDChat IM",
-      "blurb": "DDChat internal IM integration.",
-      "order": 90
-    },
-    "install": {
-      "npmSpec": "ddchat",
-      "localPath": "ddchat",
-      "defaultChoice": "local"
-    }
-  }
-}
+{
+  "name": "ddchat",
+  "version": "0.3.0",
+  "description": "DDChat channel plugin for OpenClaw",
+  "type": "module",
+  "devDependencies": {
+    "openclaw": "^2026.2.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.2.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "ddchat",
+      "label": "DDChat",
+      "selectionLabel": "DDChat (IM)",
+      "detailLabel": "DDChat IM",
+      "blurb": "DDChat internal IM integration.",
+      "order": 90
+    },
+    "install": {
+      "npmSpec": "ddchat",
+      "localPath": "ddchat",
+      "defaultChoice": "local"
+    }
+  }
+}

package/setup-entry.ts

@@ -1,4 +1,4 @@
-import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
-import { ddchatPlugin } from "./src/channel.js";
-
-export default defineSetupPluginEntry(ddchatPlugin);
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
+import { ddchatPlugin } from "./src/channel.js";
+
+export default defineSetupPluginEntry(ddchatPlugin);