ddchat 0.1.0 → 0.2.0

package/CLAUDE.md

@@ -0,0 +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`

package/OPTIMIZATION.md

@@ -0,0 +1,105 @@
+# 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` 中未使用的配置字段。

package/README.md

@@ -1,14 +1,14 @@
-# 本地安装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 "安装包路径"
+```
+
+# 默认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.1.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.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"
+    }
+  }
+}

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);

package/src/channel.ts

@@ -1,101 +1,101 @@
-import { createChatChannelPlugin, type OpenClawConfig } from "openclaw/plugin-sdk/core";
-import { patchScopedAccountConfig, prepareScopedSetupConfig } from "openclaw/plugin-sdk/setup";
-import { DDCHAT_CHANNEL_ID } from "./constants.js";
-import { ddchatGateway } from "./gateway.js";
-import { ddchatOutbound } from "./outbound.js";
-import { ddchatPairing } from "./pairing.js";
-import { listDdchatAccountIds, resolveDdchatAccount, type DdchatResolvedAccount } from "./types.js";
-
-function inspectDdchatAccount(cfg: OpenClawConfig, accountId?: string | null) {
-  const account = resolveDdchatAccount(cfg, accountId);
-  return {
-    enabled: account.enabled,
-    configured: account.configured,
-    tokenStatus: account.token ? "available" : "missing",
-    connectionMode: account.connectionMode,
-    dmPolicy: account.dmPolicy,
-    groupPolicy: account.groupPolicy,
-    streaming: account.streaming,
-    streamingMode: account.streamingMode,
-  };
-}
-
-export const ddchatPlugin = createChatChannelPlugin<DdchatResolvedAccount>({
-  base: {
-    id: DDCHAT_CHANNEL_ID,
-    meta: {
-      id: DDCHAT_CHANNEL_ID,
-      label: "DDChat",
-      selectionLabel: "DDChat (IM)",
-      blurb: "DDChat internal IM integration.",
-      order: 90,
-    },
-    capabilities: {
-      chatTypes: ["direct", "channel"],
-      media: true,
-      threads: false,
-      polls: false,
-    },
-    config: {
-      listAccountIds: (cfg) => listDdchatAccountIds(cfg),
-      resolveAccount: (cfg, accountId) => resolveDdchatAccount(cfg, accountId),
-      inspectAccount: inspectDdchatAccount,
-      isEnabled: (account) => account.enabled,
-      isConfigured: (account) => account.configured,
-    },
-    setup: {
-      resolveAccountId: ({ accountId }) => accountId ?? "default",
-      applyAccountName: ({ cfg, accountId, name }) =>
-        prepareScopedSetupConfig({
-          cfg,
-          channelKey: DDCHAT_CHANNEL_ID,
-          accountId,
-          name,
-          alwaysUseAccounts: true,
-        }),
-      validateInput: ({ input }) => {
-        const token = typeof input.token === "string" ? input.token.trim() : "";
-        return token ? null : "ddchat requires --token";
-      },
-      applyAccountConfig: ({ cfg, accountId, input }) => {
-        const token = typeof input.token === "string" ? input.token.trim() : "";
-        const next = prepareScopedSetupConfig({
-          cfg,
-          channelKey: DDCHAT_CHANNEL_ID,
-          accountId,
-          name: input.name,
-          alwaysUseAccounts: true,
-        });
-        const patch: Record<string, unknown> = {};
-        if (token) {
-          patch.token = token;
-        }
-        return patchScopedAccountConfig({
-          cfg: next,
-          channelKey: DDCHAT_CHANNEL_ID,
-          accountId,
-          patch,
-          accountPatch: patch,
-          ensureChannelEnabled: true,
-          ensureAccountEnabled: true,
-          scopeDefaultToAccounts: true,
-        });
-      },
-    },
-    gateway: ddchatGateway,
-  },
-  pairing: ddchatPairing,
-  security: {
-    dm: {
-      channelKey: DDCHAT_CHANNEL_ID,
-      resolvePolicy: (account) => account.dmPolicy,
-      resolveAllowFrom: (account) => account.allowFrom,
-      defaultPolicy: "pairing",
-      normalizeEntry: (raw) => raw.replace(/^ddchat:/i, "").trim(),
-    },
-  },
-  outbound: ddchatOutbound,
-  threading: {
-    topLevelReplyToMode: "off",
-  },
-});
+import { createChatChannelPlugin, type OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { patchScopedAccountConfig, prepareScopedSetupConfig } from "openclaw/plugin-sdk/setup";
+import { DDCHAT_CHANNEL_ID } from "./constants.js";
+import { ddchatGateway } from "./gateway.js";
+import { ddchatOutbound } from "./outbound.js";
+import { ddchatPairing } from "./pairing.js";
+import { listDdchatAccountIds, resolveDdchatAccount, type DdchatResolvedAccount } from "./types.js";
+
+function inspectDdchatAccount(cfg: OpenClawConfig, accountId?: string | null) {
+  const account = resolveDdchatAccount(cfg, accountId);
+  return {
+    enabled: account.enabled,
+    configured: account.configured,
+    tokenStatus: account.token ? "available" : "missing",
+    connectionMode: account.connectionMode,
+    dmPolicy: account.dmPolicy,
+    groupPolicy: account.groupPolicy,
+    streaming: account.streaming,
+    streamingMode: account.streamingMode,
+  };
+}
+
+export const ddchatPlugin = createChatChannelPlugin<DdchatResolvedAccount>({
+  base: {
+    id: DDCHAT_CHANNEL_ID,
+    meta: {
+      id: DDCHAT_CHANNEL_ID,
+      label: "DDChat",
+      selectionLabel: "DDChat (IM)",
+      blurb: "DDChat internal IM integration.",
+      order: 90,
+    },
+    capabilities: {
+      chatTypes: ["direct", "channel"],
+      media: true,
+      threads: false,
+      polls: false,
+    },
+    config: {
+      listAccountIds: (cfg) => listDdchatAccountIds(cfg),
+      resolveAccount: (cfg, accountId) => resolveDdchatAccount(cfg, accountId),
+      inspectAccount: inspectDdchatAccount,
+      isEnabled: (account) => account.enabled,
+      isConfigured: (account) => account.configured,
+    },
+    setup: {
+      resolveAccountId: ({ accountId }) => accountId ?? "default",
+      applyAccountName: ({ cfg, accountId, name }) =>
+        prepareScopedSetupConfig({
+          cfg,
+          channelKey: DDCHAT_CHANNEL_ID,
+          accountId,
+          name,
+          alwaysUseAccounts: true,
+        }),
+      validateInput: ({ input }) => {
+        const token = typeof input.token === "string" ? input.token.trim() : "";
+        return token ? null : "ddchat requires --token";
+      },
+      applyAccountConfig: ({ cfg, accountId, input }) => {
+        const token = typeof input.token === "string" ? input.token.trim() : "";
+        const next = prepareScopedSetupConfig({
+          cfg,
+          channelKey: DDCHAT_CHANNEL_ID,
+          accountId,
+          name: input.name,
+          alwaysUseAccounts: true,
+        });
+        const patch: Record<string, unknown> = {};
+        if (token) {
+          patch.token = token;
+        }
+        return patchScopedAccountConfig({
+          cfg: next,
+          channelKey: DDCHAT_CHANNEL_ID,
+          accountId,
+          patch,
+          accountPatch: patch,
+          ensureChannelEnabled: true,
+          ensureAccountEnabled: true,
+          scopeDefaultToAccounts: true,
+        });
+      },
+    },
+    gateway: ddchatGateway,
+  },
+  pairing: ddchatPairing,
+  security: {
+    dm: {
+      channelKey: DDCHAT_CHANNEL_ID,
+      resolvePolicy: (account) => account.dmPolicy,
+      resolveAllowFrom: (account) => account.allowFrom,
+      defaultPolicy: "pairing",
+      normalizeEntry: (raw) => raw.replace(/^ddchat:/i, "").trim(),
+    },
+  },
+  outbound: ddchatOutbound,
+  threading: {
+    topLevelReplyToMode: "off",
+  },
+});

package/src/constants.ts

@@ -1,5 +1,5 @@
-export const DDCHAT_CHANNEL_ID = "ddchat";
-export const DDCHAT_DEFAULT_ACCOUNT_ID = "default";
-
-/** Default WebSocket endpoint when `channels.ddchat.wsUrl` / per-account `wsUrl` is unset (`token` query appended at connect). */
-export const DDCHAT_PLUGIN_WS_BASE_URL = "wss://chat.ddjf.info/socket/ai/plugin";
+export const DDCHAT_CHANNEL_ID = "ddchat";
+export const DDCHAT_DEFAULT_ACCOUNT_ID = "default";
+
+/** Default WebSocket endpoint when `channels.ddchat.wsUrl` / per-account `wsUrl` is unset (`token` query appended at connect). */
+export const DDCHAT_PLUGIN_WS_BASE_URL = "wss://chat.ddjf.info/socket/ai/plugin";

package/src/dedupe.ts

@@ -1,31 +1,31 @@
-const DEFAULT_TTL_MS = 48 * 60 * 60 * 1000;
-
-export class DdchatDedupeStore {
-  private readonly seen = new Map<string, number>();
-  private readonly ttlMs: number;
-
-  constructor(ttlMs = DEFAULT_TTL_MS) {
-    this.ttlMs = ttlMs;
-  }
-
-  isDuplicate(accountId: string, messageId: string): boolean {
-    this.gc();
-    const key = `${accountId}:${messageId}`;
-    const now = Date.now();
-    const expiresAt = this.seen.get(key);
-    if (expiresAt && expiresAt > now) {
-      return true;
-    }
-    this.seen.set(key, now + this.ttlMs);
-    return false;
-  }
-
-  private gc(): void {
-    const now = Date.now();
-    for (const [key, expiresAt] of this.seen.entries()) {
-      if (expiresAt <= now) {
-        this.seen.delete(key);
-      }
-    }
-  }
-}
+const DEFAULT_TTL_MS = 48 * 60 * 60 * 1000;
+
+export class DdchatDedupeStore {
+  private readonly seen = new Map<string, number>();
+  private readonly ttlMs: number;
+
+  constructor(ttlMs = DEFAULT_TTL_MS) {
+    this.ttlMs = ttlMs;
+  }
+
+  isDuplicate(accountId: string, messageId: string): boolean {
+    this.gc();
+    const key = `${accountId}:${messageId}`;
+    const now = Date.now();
+    const expiresAt = this.seen.get(key);
+    if (expiresAt && expiresAt > now) {
+      return true;
+    }
+    this.seen.set(key, now + this.ttlMs);
+    return false;
+  }
+
+  private gc(): void {
+    const now = Date.now();
+    for (const [key, expiresAt] of this.seen.entries()) {
+      if (expiresAt <= now) {
+        this.seen.delete(key);
+      }
+    }
+  }
+}