openclaw-xiaoyou 1.0.0

package/src/channel.ts

@@ -0,0 +1,218 @@
+/**
+ * xiaoyou ChannelPlugin 实现
+ *
+ * 运行在 OpenClaw Gateway 进程内，通过 gateway adapter 管理
+ * 与企业服务的 WebSocket 连接生命周期。
+ *
+ * 用户通过 OpenClaw 标准 channel 配置来设置企业服务地址等参数。
+ */
+
+import type { ResolvedAccount } from "./types.js";
+import { createEnterpriseClient, type EnterpriseClient } from "./enterprise-client.js";
+
+// ─── 运行时状态 ──────────────────────────────────────
+
+/** 每个 account 一个 EnterpriseClient */
+const clients = new Map<string, EnterpriseClient>();
+
+/** OpenClaw runtime API 引用，由 index.ts register() 注入 */
+let _runtime: any = null;
+export function setRuntime(rt: any) { _runtime = rt; }
+export function getRuntime() { return _runtime; }
+
+// ─── Config Adapter ──────────────────────────────────
+
+function resolveAccount(cfg: any, accountId?: string | null): ResolvedAccount {
+  const section = cfg.channels?.["xiaoyou"];
+  if (!section) throw new Error("xiaoyou: channel config section not found");
+
+  // 多账号支持：accounts.<id> 覆盖顶层默认值
+  const acct = accountId && section.accounts?.[accountId]
+    ? { ...section, ...section.accounts[accountId] }
+    : section;
+
+  if (!acct.wsUrl) throw new Error("xiaoyou: wsUrl is required");
+
+  return {
+    accountId: accountId ?? acct.defaultAccount ?? null,
+    wsUrl: acct.wsUrl,
+    authToken: acct.authToken ?? "",
+    allowFrom: acct.allowFrom ?? [],
+    dmPolicy: acct.dmSecurity,
+    reconnectIntervalMs: acct.reconnectIntervalMs ?? 3000,
+    maxReconnectAttempts: acct.maxReconnectAttempts ?? 0,
+    heartbeatIntervalMs: acct.heartbeatIntervalMs ?? 30000,
+    heartbeatTimeoutMs: acct.heartbeatTimeoutMs ?? 10000,
+  };
+}
+
+function inspectAccount(cfg: any, _accountId?: string | null) {
+  const section = cfg.channels?.["xiaoyou"];
+  return {
+    enabled: Boolean(section?.wsUrl),
+    configured: Boolean(section?.wsUrl),
+    tokenStatus: section?.authToken ? "available" : "missing",
+  };
+}
+
+function listAccounts(cfg: any): string[] {
+  const section = cfg.channels?.["xiaoyou"];
+  if (!section?.wsUrl) return [];
+  if (section.accounts) return Object.keys(section.accounts);
+  return ["default"];
+}
+
+// ─── Channel Plugin ──────────────────────────────────
+
+export const xiayouPlugin = {
+  id: "xiaoyou" as const,
+
+  meta: {
+    id: "xiaoyou",
+    label: "Xiaoyou",
+    selectionLabel: "Xiaoyou (enterprise WebSocket)",
+    docsPath: "/channels/xiaoyou",
+    docsLabel: "xiaoyou",
+    blurb: "Bridge OpenClaw to enterprise services via persistent WebSocket.",
+    order: 50,
+  },
+
+  capabilities: {
+    chatTypes: ["direct" as const, "group" as const],
+    media: true,
+    reply: true,
+    edit: false,
+    unsend: false,
+    polls: false,
+    reactions: false,
+    threads: false,
+    nativeCommands: false,
+    blockStreaming: false,
+  },
+
+  // ── Config（必须）──────────────────────────────────
+  config: {
+    resolveAccount,
+    inspectAccount,
+    listAccounts,
+  },
+
+  // ── DM 安全策略 ────────────────────────────────────
+  security: {
+    dm: {
+      channelKey: "xiaoyou",
+      resolvePolicy: (account: ResolvedAccount) => account.dmPolicy,
+      resolveAllowFrom: (account: ResolvedAccount) => account.allowFrom,
+      defaultPolicy: "allowlist",
+    },
+  },
+
+  // ── 回复线程模式 ───────────────────────────────────
+  threading: { topLevelReplyToMode: "reply" as const },
+
+  // ── Gateway 生命周期 ───────────────────────────────
+  gateway: {
+    start: async ({ account, config, logger }: any) => {
+      const resolved: ResolvedAccount =
+        typeof account.wsUrl === "string"
+          ? account
+          : resolveAccount(config, account.accountId);
+
+      const clientKey = resolved.accountId ?? "default";
+
+      // 断开已有连接
+      const existing = clients.get(clientKey);
+      if (existing) existing.disconnect();
+
+      const client = createEnterpriseClient({
+        account: resolved,
+        logger,
+        onMessage: async (msg) => {
+          const runtime = getRuntime();
+          if (!runtime) {
+            logger.error("[xiaoyou] runtime not available");
+            return;
+          }
+          await runtime.inbound.dispatch({
+            channelId: "xiaoyou",
+            accountId: resolved.accountId ?? "default",
+            senderId: msg.senderId,
+            senderName: msg.senderName ?? msg.senderId,
+            conversationId: msg.conversationId,
+            chatType: "direct",
+            text: msg.text ?? "",
+            attachments: msg.attachments?.map((a: any) => ({
+              kind: a.kind,
+              url: a.url,
+              mimeType: a.mimeType,
+            })),
+            metadata: msg.metadata,
+          });
+        },
+      });
+
+      client.connect();
+      clients.set(clientKey, client);
+      logger.info(`[xiaoyou] gateway started (account=${clientKey})`);
+      return client;
+    },
+
+    stop: async (client: EnterpriseClient) => {
+      client.disconnect();
+      for (const [key, c] of clients.entries()) {
+        if (c === client) { clients.delete(key); break; }
+      }
+    },
+  },
+
+  // ── Outbound 出站 ──────────────────────────────────
+  outbound: {
+    send: async ({ account, to, payload }: any) => {
+      const clientKey = account.accountId ?? "default";
+      const client = clients.get(clientKey);
+      if (!client || !client.isConnected()) {
+        return { ok: false, error: "xiaoyou: not connected" };
+      }
+
+      const baseReply = {
+        type: "reply" as const,
+        conversationId: to,
+        messageId: `xiaoyou-${Date.now()}`,
+        agentId: payload.agentId,
+        timestamp: Date.now(),
+      };
+
+      if (payload.kind === "text") {
+        client.sendReply({ ...baseReply, text: payload.text });
+        return { ok: true };
+      }
+      if (payload.kind === "image" || payload.kind === "file") {
+        client.sendReply({
+          ...baseReply,
+          text: payload.caption ?? "",
+          mediaUrls: [payload.url ?? payload.filePath],
+        });
+        return { ok: true };
+      }
+      return { ok: false, error: `Unsupported payload kind: ${payload.kind}` };
+    },
+  },
+
+  // ── Status 状态检查 ────────────────────────────────
+  status: {
+    describe: async ({ account }: any) => {
+      const clientKey = account.accountId ?? "default";
+      const client = clients.get(clientKey);
+      const issues: Array<{ severity: string; message: string }> = [];
+
+      if (!account.wsUrl) issues.push({ severity: "error", message: "wsUrl not configured" });
+      if (!account.authToken) issues.push({ severity: "warning", message: "authToken not set" });
+      if (!client || !client.isConnected()) issues.push({ severity: "error", message: "WebSocket not connected" });
+
+      return {
+        summary: issues.length === 0 ? "connected" : "error",
+        issues,
+      };
+    },
+  },
+};

package/src/enterprise-client.ts

@@ -0,0 +1,190 @@
+/**
+ * 企业服务 WebSocket 客户端
+ *
+ * 由 gateway adapter 的 start() 创建，运行在 OpenClaw Gateway 进程内。
+ * 负责：连接企业 WebSocket Server、认证、心跳、自动重连、收发消息。
+ */
+
+import WebSocket from "ws";
+import type {
+  ResolvedAccount,
+  Frame,
+  InboundMessage,
+  OutboundReply,
+  PongFrame,
+} from "./types.js";
+
+export type Logger = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+  debug?: (msg: string) => void;
+};
+
+export type EnterpriseClientOptions = {
+  account: ResolvedAccount;
+  logger: Logger;
+  onMessage: (msg: InboundMessage) => Promise<void>;
+};
+
+export type EnterpriseClient = {
+  connect: () => void;
+  disconnect: () => void;
+  sendReply: (reply: OutboundReply) => boolean;
+  isConnected: () => boolean;
+};
+
+export function createEnterpriseClient(opts: EnterpriseClientOptions): EnterpriseClient {
+  const { account, logger, onMessage } = opts;
+
+  let ws: WebSocket | null = null;
+  let authenticated = false;
+  let reconnectAttempts = 0;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  let heartbeatTimeoutTimer: ReturnType<typeof setTimeout> | null = null;
+  let heartbeatSeq = 0;
+  let intentionalClose = false;
+
+  // ─── 心跳 ──────────────────────────────────────────
+
+  function startHeartbeat() {
+    stopHeartbeat();
+    heartbeatTimer = setInterval(() => {
+      if (!ws || ws.readyState !== WebSocket.OPEN) return;
+      heartbeatSeq++;
+      ws.send(JSON.stringify({ type: "ping", seq: heartbeatSeq, ts: Date.now() }));
+
+      heartbeatTimeoutTimer = setTimeout(() => {
+        logger.warn(`[xiaoyou] heartbeat timeout (seq=${heartbeatSeq}), reconnecting`);
+        ws?.close(4002, "heartbeat timeout");
+      }, account.heartbeatTimeoutMs);
+    }, account.heartbeatIntervalMs);
+  }
+
+  function stopHeartbeat() {
+    if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+    if (heartbeatTimeoutTimer) { clearTimeout(heartbeatTimeoutTimer); heartbeatTimeoutTimer = null; }
+  }
+
+  function handlePong(_pong: PongFrame) {
+    if (heartbeatTimeoutTimer) { clearTimeout(heartbeatTimeoutTimer); heartbeatTimeoutTimer = null; }
+  }
+
+  // ─── 认证 ──────────────────────────────────────────
+
+  function sendAuth() {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify({
+      type: "auth",
+      token: account.authToken,
+      clientId: `openclaw-xiaoyou-${account.accountId ?? "default"}`,
+      clientVersion: "1.0.0",
+    }));
+    logger.info("[xiaoyou] auth sent, waiting for auth_result...");
+  }
+
+  // ─── 帧处理 ────────────────────────────────────────
+
+  function handleFrame(raw: string) {
+    let frame: Frame;
+    try { frame = JSON.parse(raw); } catch {
+      logger.warn(`[xiaoyou] invalid JSON: ${raw.slice(0, 200)}`);
+      return;
+    }
+
+    switch (frame.type) {
+      case "auth_result":
+        if (frame.ok) {
+          authenticated = true;
+          reconnectAttempts = 0;
+          logger.info(`[xiaoyou] authenticated (sessionId=${frame.sessionId ?? "n/a"})`);
+          startHeartbeat();
+        } else {
+          logger.error(`[xiaoyou] auth failed: ${frame.error ?? "unknown"}`);
+          ws?.close(4001, "auth failed");
+        }
+        break;
+
+      case "pong":
+        handlePong(frame);
+        break;
+
+      case "message":
+        if (!authenticated) { logger.warn("[xiaoyou] message before auth, ignoring"); return; }
+        onMessage(frame).catch((err) => {
+          logger.error(`[xiaoyou] inbound dispatch error: ${err}`);
+        });
+        break;
+
+      default:
+        logger.warn?.(`[xiaoyou] unknown frame type: ${(frame as any).type}`);
+    }
+  }
+
+  // ─── 重连 ──────────────────────────────────────────
+
+  function scheduleReconnect() {
+    if (intentionalClose) return;
+    if (account.maxReconnectAttempts > 0 && reconnectAttempts >= account.maxReconnectAttempts) {
+      logger.error(`[xiaoyou] max reconnect attempts (${account.maxReconnectAttempts}) reached`);
+      return;
+    }
+    const delay = Math.min(account.reconnectIntervalMs * Math.pow(2, reconnectAttempts), 60_000);
+    reconnectAttempts++;
+    logger.info(`[xiaoyou] reconnecting in ${delay}ms (attempt ${reconnectAttempts})`);
+    reconnectTimer = setTimeout(() => connectInternal(), delay);
+  }
+
+  // ─── 连接 ──────────────────────────────────────────
+
+  function connectInternal() {
+    if (ws && ws.readyState === WebSocket.OPEN) return;
+    logger.info(`[xiaoyou] connecting to ${account.wsUrl}`);
+    authenticated = false;
+
+    ws = new WebSocket(account.wsUrl, {
+      headers: { Authorization: `Bearer ${account.authToken}` },
+      handshakeTimeout: 10_000,
+    });
+
+    ws.on("open", () => { logger.info("[xiaoyou] connected"); sendAuth(); });
+    ws.on("message", (data) => handleFrame(data.toString()));
+    ws.on("close", (code, reason) => {
+      logger.info(`[xiaoyou] closed (code=${code}, reason=${reason.toString()})`);
+      stopHeartbeat(); authenticated = false; scheduleReconnect();
+    });
+    ws.on("error", (err) => { logger.error(`[xiaoyou] error: ${err.message}`); });
+  }
+
+  // ─── 公开 API ──────────────────────────────────────
+
+  function connect() {
+    intentionalClose = false;
+    reconnectAttempts = 0;
+    connectInternal();
+  }
+
+  function disconnect() {
+    intentionalClose = true;
+    stopHeartbeat();
+    if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+    if (ws) { ws.close(1000, "plugin shutdown"); ws = null; }
+    authenticated = false;
+  }
+
+  function sendReply(reply: OutboundReply): boolean {
+    if (!ws || ws.readyState !== WebSocket.OPEN || !authenticated) {
+      logger.warn("[xiaoyou] cannot send: not connected");
+      return false;
+    }
+    ws.send(JSON.stringify(reply));
+    return true;
+  }
+
+  function isConnected(): boolean {
+    return ws !== null && ws.readyState === WebSocket.OPEN && authenticated;
+  }
+
+  return { connect, disconnect, sendReply, isConnected };
+}

package/src/onboarding.ts

@@ -0,0 +1,76 @@
+/**
+ * Onboarding Adapter —— openclaw channels add 交互式向导
+ *
+ * 当用户执行 `openclaw channels add --channel xiaoyou` 时，
+ * 此向导会引导用户填写必要配置项，并写入 OpenClaw 配置文件。
+ */
+
+export const onboardingAdapter = {
+  steps: [
+    {
+      key: "wsUrl",
+      label: "Enterprise WebSocket URL",
+      prompt: "企业服务 WebSocket 地址 (如 wss://im.corp.example.com/ws):",
+      required: true,
+      validate: (value: string) => {
+        if (!value.startsWith("ws://") && !value.startsWith("wss://")) {
+          return "地址必须以 ws:// 或 wss:// 开头";
+        }
+        return true;
+      },
+    },
+    {
+      key: "authToken",
+      label: "Auth Token",
+      prompt: "企业服务认证 Token:",
+      required: true,
+      sensitive: true,
+    },
+    {
+      key: "dmSecurity",
+      label: "DM Security Policy",
+      prompt: "DM 安全策略 (open / allowlist):",
+      required: false,
+      default: "open",
+    },
+    {
+      key: "allowFrom",
+      label: "Allow List",
+      prompt: "白名单用户 ID (逗号分隔，留空表示不限制):",
+      required: false,
+      transform: (value: string) =>
+        value ? value.split(",").map((s) => s.trim()).filter(Boolean) : [],
+    },
+    {
+      key: "reconnectIntervalMs",
+      label: "Reconnect Interval",
+      prompt: "重连基础间隔 (毫秒):",
+      required: false,
+      default: "3000",
+      transform: (value: string) => parseInt(value, 10) || 3000,
+    },
+    {
+      key: "heartbeatIntervalMs",
+      label: "Heartbeat Interval",
+      prompt: "心跳间隔 (毫秒):",
+      required: false,
+      default: "30000",
+      transform: (value: string) => parseInt(value, 10) || 30000,
+    },
+  ],
+
+  /** 将向导收集的值组装为 channel 配置 */
+  buildConfig(values: Record<string, any>) {
+    return {
+      enabled: true,
+      wsUrl: values.wsUrl,
+      authToken: values.authToken,
+      dmSecurity: values.dmSecurity || "open",
+      allowFrom: values.allowFrom || [],
+      reconnectIntervalMs: values.reconnectIntervalMs || 3000,
+      maxReconnectAttempts: 0,
+      heartbeatIntervalMs: values.heartbeatIntervalMs || 30000,
+      heartbeatTimeoutMs: 10000,
+    };
+  },
+};

package/src/types.ts

@@ -0,0 +1,86 @@
+/**
+ * xiaoyou 类型定义
+ *
+ * 企业服务端 ↔ xiaoyou 插件之间的 WebSocket 协议帧
+ */
+
+// ─── 解析后的账号配置 ────────────────────────────────────
+
+export type ResolvedAccount = {
+  accountId: string | null;
+  /** 企业 WebSocket 服务地址，如 wss://im.corp.example.com/ws */
+  wsUrl: string;
+  /** 连接企业服务的认证 token */
+  authToken: string;
+  /** DM 白名单 */
+  allowFrom: string[];
+  /** DM 安全策略 */
+  dmPolicy: string | undefined;
+  /** 重连基础间隔（毫秒） */
+  reconnectIntervalMs: number;
+  /** 最大重连次数，0 = 无限 */
+  maxReconnectAttempts: number;
+  /** 心跳间隔（毫秒） */
+  heartbeatIntervalMs: number;
+  /** 心跳超时（毫秒） */
+  heartbeatTimeoutMs: number;
+};
+
+// ─── 入站消息（企业服务 → 插件）─────────────────────────
+
+export type InboundMessage = {
+  type: "message";
+  conversationId: string;
+  senderId: string;
+  senderName?: string;
+  text?: string;
+  attachments?: Attachment[];
+  metadata?: Record<string, unknown>;
+};
+
+export type Attachment = {
+  kind: "image" | "file" | "audio" | "video";
+  url: string;
+  mimeType?: string;
+  fileName?: string;
+};
+
+// ─── 出站回复（插件 → 企业服务）─────────────────────────
+
+export type OutboundReply = {
+  type: "reply";
+  conversationId: string;
+  messageId: string;
+  text: string;
+  mediaUrls?: string[];
+  agentId?: string;
+  timestamp: number;
+};
+
+// ─── 控制帧 ─────────────────────────────────────────────
+
+export type AuthFrame = {
+  type: "auth";
+  token: string;
+  clientId: string;
+  clientVersion: string;
+};
+
+export type AuthResultFrame = {
+  type: "auth_result";
+  ok: boolean;
+  error?: string;
+  sessionId?: string;
+};
+
+export type PingFrame = { type: "ping"; seq: number; ts: number };
+export type PongFrame = { type: "pong"; seq: number; ts: number };
+
+/** 所有帧类型的联合 */
+export type Frame =
+  | InboundMessage
+  | OutboundReply
+  | AuthFrame
+  | AuthResultFrame
+  | PingFrame
+  | PongFrame;

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["*.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}