openclaw-agentforum 0.1.0

package/src/gateway.ts

@@ -0,0 +1,379 @@
+/**
+ * AgentForum WebSocket Gateway
+ *
+ * 核心职责:
+ * 1. 建立并维护与 AgentForum 的 WebSocket 连接
+ * 2. 响应服务端 ping，保持心跳
+ * 3. 接收 message.new 事件，构建 OpenClaw envelope 并分发给 AI 处理
+ * 4. 将 AI 的回复通过 REST API 发回 AgentForum
+ * 5. 断线自动重连（指数退避，初始 1s，最大 30s）
+ *
+ * 相比 QQBot 插件，AgentForum Gateway 简单很多:
+ * - 只有一种消息事件 (message.new)，不需要 op code 解析
+ * - 发送消息走 REST API，不需要通过 WS 发送
+ * - 认证只需 apiKey query param，无 OAuth 流程
+ */
+
+import WebSocket from "ws";
+import { getAgentForumRuntime } from "./runtime.js";
+import { sendText } from "./outbound.js";
+import type {
+  GatewayContext,
+  AgentForumWSEvent,
+  MessageNewPayload,
+} from "./types.js";
+
+/** 重连延迟序列（毫秒），超出数组长度后使用最后一个值 */
+const RECONNECT_DELAYS = [1000, 2000, 5000, 10000, 30000];
+
+/** 最大重连尝试次数 */
+const MAX_RECONNECT_ATTEMPTS = 100;
+
+/**
+ * 启动 AgentForum WebSocket Gateway
+ * 建立 WS 连接，监听消息事件，处理心跳和重连。
+ * 返回的 Promise 在 abortSignal 触发时 resolve。
+ *
+ * @param ctx - Gateway 上下文，包含账户信息、中断信号、日志等
+ * @returns Promise，在连接被中断时 resolve
+ */
+export async function startGateway(ctx: GatewayContext): Promise<void> {
+  const { account, abortSignal, cfg, log, onReady, onError } = ctx;
+
+  let ws: WebSocket | null = null;
+  let reconnectAttempts = 0;
+  let isAborted = false;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * 清理当前 WebSocket 连接
+   */
+  const cleanup = (): void => {
+    if (
+      ws &&
+      (ws.readyState === WebSocket.OPEN ||
+        ws.readyState === WebSocket.CONNECTING)
+    ) {
+      ws.close();
+    }
+    ws = null;
+  };
+
+  // 监听中断信号，优雅关闭连接
+  abortSignal.addEventListener("abort", () => {
+    isAborted = true;
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    cleanup();
+    log?.info("[af] Gateway aborted");
+  });
+
+  /**
+   * 调度重连，使用指数退避策略
+   */
+  const scheduleReconnect = (): void => {
+    if (isAborted || reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+      if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+        log?.error(
+          `[af] 达到最大重连次数 (${MAX_RECONNECT_ATTEMPTS})，停止重连`
+        );
+        onError?.(new Error("Max reconnect attempts exceeded"));
+      }
+      return;
+    }
+
+    const delay =
+      RECONNECT_DELAYS[
+        Math.min(reconnectAttempts, RECONNECT_DELAYS.length - 1)
+      ];
+    reconnectAttempts++;
+    log?.info(`[af] 将在 ${delay}ms 后重连 (第 ${reconnectAttempts} 次)`);
+    reconnectTimer = setTimeout(connect, delay);
+  };
+
+  /**
+   * 判断消息是否需要触发 AI 回复
+   * 只有当消息 @mention 了本 Agent 或 reply 目标是本 Agent 时才触发
+   *
+   * @param message - 消息对象
+   * @returns 是否应触发回复
+   */
+  const shouldRespond = (message: MessageNewPayload["message"]): boolean => {
+    // 被 reply 指向时触发
+    if (message.reply_target_agent_id === account.agentId) return true;
+
+    // 被 @mention 时触发
+    if (message.mentions?.some((m) => m.agentId === account.agentId)) return true;
+
+    return false;
+  };
+
+  /**
+   * 从消息中提取线性讨论上下文（如果本 agent 是预期发言者）
+   * 返回 discussionSessionId 和应回复的消息 ID
+   *
+   * @param message - 消息对象
+   * @returns 讨论上下文，或 null（非讨论消息 / 非本 agent 发言）
+   */
+  const extractDiscussionContext = (message: MessageNewPayload["message"]): {
+    discussionSessionId: string;
+    replyToMessageId: string;
+  } | null => {
+    const discussion = message.discussion;
+    if (!discussion || discussion.status !== "active") return null;
+    if (discussion.expectedSpeakerId !== account.agentId) return null;
+
+    return {
+      discussionSessionId: discussion.id,
+      // 回复当前消息（它就是讨论中的最新消息 = lastMessageId）
+      replyToMessageId: message.id,
+    };
+  };
+
+  /**
+   * 处理收到的 message.new 事件
+   * 所有消息都会进入上下文，但只有被 @mention 或 reply 时才触发 AI 回复
+   *
+   * @param payload - message.new 事件的 payload
+   */
+  const handleMessageNew = async (payload: MessageNewPayload): Promise<void> => {
+    const { message, sender } = payload;
+
+    // 过滤自己发出的消息，避免无限循环
+    if (sender.id === account.agentId) return;
+
+    const userContent = message.content?.trim();
+    if (!userContent) return;
+
+    log?.info(`[af] 收到 [${sender.name}]: ${userContent.slice(0, 80)}`);
+
+    // 提取线性讨论上下文（如果有）
+    const discussionCtx = extractDiscussionContext(message);
+
+    // 只有被 @mention 或 reply 时才触发 AI 回复
+    if (!shouldRespond(message)) {
+      log?.debug?.(`[af] 消息未 @mention 或 reply 本 Agent，跳过回复`);
+      return;
+    }
+
+    if (discussionCtx) {
+      log?.info(`[af] 被触发回复 (线性讨论 session=${discussionCtx.discussionSessionId})`);
+    } else {
+      log?.info(`[af] 被触发回复 (mention/reply)`);
+    }
+
+    try {
+      const runtime = getAgentForumRuntime();
+      log?.info(`[af] runtime 获取成功`);
+
+      // 从事件 payload 中获取 channelId，不依赖配置中的固定频道
+      const channelId = payload.channelId || message.channel_id || account.channelId || "";
+      const fromAddress = `agentforum:${account.accountId}:channel:${channelId}`;
+      const toAddress = `agentforum:${account.accountId}:channel:${channelId}`;
+
+      log?.info(`[af] channelId=${channelId}, from=${fromAddress}`);
+
+      // 解析 Agent 路由（获取 sessionKey 等）
+      let route;
+      try {
+        route = runtime.channel.routing.resolveAgentRoute({
+          cfg,
+          channel: "agentforum",
+          accountId: account.accountId,
+          // 用 channelId 作为 peer ID，使每个频道拥有独立 session
+          // kind: "group" 让框架按群组粒度隔离会话
+          peer: { kind: "group", id: channelId },
+        });
+        log?.info(`[af] route 解析成功: sessionKey=${route.sessionKey}, accountId=${route.accountId}`);
+      } catch (routeErr) {
+        log?.error(`[af] resolveAgentRoute 失败: ${String(routeErr)}`);
+        throw routeErr;
+      }
+
+      // 获取 envelope 格式化选项
+      let envelopeOptions;
+      try {
+        envelopeOptions = runtime.channel.reply.resolveEnvelopeFormatOptions(cfg);
+        log?.info(`[af] envelopeOptions 获取成功`);
+      } catch (envErr) {
+        log?.error(`[af] resolveEnvelopeFormatOptions 失败: ${String(envErr)}`);
+        throw envErr;
+      }
+
+      // 格式化入站消息的展示内容（Web UI 用）
+      let body: string;
+      try {
+        body = runtime.channel.reply.formatInboundEnvelope({
+          channel: "agentforum",
+          from: sender.name,
+          timestamp: Date.now(),
+          body: userContent,
+          chatType: "group",
+          sender: { id: sender.id, name: sender.name },
+          envelope: envelopeOptions,
+        });
+        log?.info(`[af] formatInboundEnvelope 成功: ${body.slice(0, 80)}`);
+      } catch (fmtErr) {
+        log?.error(`[af] formatInboundEnvelope 失败: ${String(fmtErr)}`);
+        throw fmtErr;
+      }
+
+      // AI 实际看到的消息内容
+      const agentBody = `[AgentForum] 来自 ${sender.name}: ${userContent}`;
+
+      // 构建最终的入站上下文
+      let ctxPayload;
+      try {
+        ctxPayload = runtime.channel.reply.finalizeInboundContext({
+          Body: body,
+          BodyForAgent: agentBody,
+          RawBody: userContent,
+          CommandBody: userContent,
+          From: fromAddress,
+          To: toAddress,
+          SessionKey: route.sessionKey,
+          AccountId: route.accountId,
+          ChatType: "group",
+          SenderId: sender.id,
+          SenderName: sender.name,
+          Provider: "agentforum",
+          Surface: "agentforum",
+          MessageSid: message.id,
+          Timestamp: Date.now(),
+          OriginatingChannel: "agentforum",
+        });
+        log?.info(`[af] finalizeInboundContext 成功`);
+      } catch (ctxErr) {
+        log?.error(`[af] finalizeInboundContext 失败: ${String(ctxErr)}`);
+        throw ctxErr;
+      }
+
+      // 分发给 OpenClaw AI 处理，并通过 deliver 回调发送回复
+      log?.info(`[af] 开始 dispatchReply...`);
+      await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx: ctxPayload,
+        cfg,
+        dispatcherOptions: {
+          deliver: async (
+            deliverPayload: {
+              text?: string;
+              mediaUrl?: string;
+              mediaUrls?: string[];
+            },
+            info: { kind: string }
+          ) => {
+            log?.info(`[af] deliver 回调触发, kind=${info.kind}, hasText=${Boolean(deliverPayload.text)}`);
+            // 处理 AI 的最终文本回复（kind 可能是 "block" 或 "final"），忽略 tool 类型
+            if (info.kind !== "tool" && deliverPayload.text) {
+              // 讨论模式下回复到讨论的最新消息并传递 sessionId；普通模式回复原始消息
+              const replyToId = discussionCtx?.replyToMessageId ?? message.id;
+              const sessionId = discussionCtx?.discussionSessionId;
+              log?.info(
+                `[af] 回复到频道 ${channelId}: ${deliverPayload.text.slice(0, 50)}...${sessionId ? ` (discussion=${sessionId})` : ""}`
+              );
+              const result = await sendText(
+                account.forumUrl,
+                channelId,
+                deliverPayload.text,
+                account.apiKey,
+                replyToId,
+                sessionId
+              );
+              if (result.error) {
+                log?.error(`[af] 发送失败: ${result.error}`);
+              } else {
+                log?.info(`[af] 发送成功: messageId=${result.id}`);
+              }
+            }
+          },
+          onError: (err: unknown) => {
+            log?.error(`[af] dispatcherOptions.onError: ${String(err)}`);
+          },
+        },
+        // 禁用流式块合并：收集完所有块后一次性 deliver
+        // AgentForum 走 REST API 发消息，没有流式推送能力
+        replyOptions: { disableBlockStreaming: true },
+      });
+      log?.info(`[af] dispatchReply 完成`);
+    } catch (err) {
+      log?.error(`[af] 处理消息失败: ${String(err)}`);
+      // 打印完整堆栈
+      if (err instanceof Error && err.stack) {
+        log?.error(`[af] 堆栈: ${err.stack}`);
+      }
+    }
+  };
+
+  /**
+   * 建立 WebSocket 连接
+   */
+  const connect = async (): Promise<void> => {
+    if (isAborted) return;
+
+    try {
+      cleanup();
+
+      const wsUrl = account.forumUrl.replace(/^http/, "ws");
+      log?.info(`[af] 连接到 ${wsUrl}/ws`);
+
+      ws = new WebSocket(`${wsUrl}/ws?apiKey=${account.apiKey}`);
+
+      ws.on("open", () => {
+        log?.info("[af] WebSocket 已连接");
+        reconnectAttempts = 0;
+        onReady?.({});
+      });
+
+      ws.on("message", async (raw: WebSocket.RawData) => {
+        try {
+          const event = JSON.parse(raw.toString()) as AgentForumWSEvent;
+
+          // 响应服务端心跳
+          if (event.type === "ping") {
+            ws?.send(
+              JSON.stringify({
+                type: "pong",
+                payload: {},
+                timestamp: new Date().toISOString(),
+              })
+            );
+            return;
+          }
+
+          // 处理新消息事件
+          if (event.type === "message.new") {
+            await handleMessageNew(event.payload as unknown as MessageNewPayload);
+            return;
+          }
+
+          // 其他事件类型可按需扩展
+          log?.debug?.(`[af] 收到事件: ${event.type}`);
+        } catch (parseErr) {
+          log?.error(`[af] 解析 WS 消息失败: ${String(parseErr)}`);
+        }
+      });
+
+      ws.on("close", (code: number, reason: Buffer) => {
+        log?.info(`[af] 连接关闭: code=${code} reason=${reason.toString()}`);
+        cleanup();
+        if (!isAborted) scheduleReconnect();
+      });
+
+      ws.on("error", (err: Error) => {
+        log?.error(`[af] WebSocket 错误: ${err.message}`);
+        onError?.(err);
+      });
+    } catch (err) {
+      log?.error(`[af] 连接失败: ${String(err)}`);
+      cleanup();
+      if (!isAborted) scheduleReconnect();
+    }
+  };
+
+  // 发起首次连接
+  await connect();
+
+  // 保持 gateway 运行直到 abortSignal 触发
+  return new Promise<void>((resolve) => {
+    abortSignal.addEventListener("abort", () => resolve());
+  });
+}

package/src/onboarding.ts

@@ -0,0 +1,274 @@
+/**
+ * AgentForum CLI Onboarding Adapter
+ *
+ * 对齐 openclaw-qqbot/src/onboarding.ts，
+ * 实现 ChannelOnboardingAdapter 接口，供 `openclaw onboard` 命令使用。
+ * 交互式引导用户完成 AgentForum 账户配置。
+ */
+
+import type {
+  ChannelOnboardingAdapter,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk";
+import {
+  DEFAULT_ACCOUNT_ID,
+  listAgentForumAccountIds,
+  resolveAgentForumAccount,
+  isAgentForumAccountConfigured,
+} from "./config.js";
+
+/** 环境变量名，用于非交互式场景下自动读取凭证 */
+const ENV_API_KEY = "AGENTFORUM_API_KEY";
+const ENV_AGENT_ID = "AGENTFORUM_AGENT_ID";
+const ENV_FORUM_URL = "AGENTFORUM_URL";
+
+/** Prompter 类型（由 OpenClaw 框架注入的交互原语） */
+interface Prompter {
+  note: (message: string, title?: string) => Promise<void>;
+  confirm: (opts: { message: string; initialValue?: boolean }) => Promise<boolean>;
+  text: (opts: {
+    message: string;
+    placeholder?: string;
+    initialValue?: string;
+    validate?: (value: string) => string | undefined;
+  }) => Promise<string>;
+  select: <T>(opts: {
+    message: string;
+    options: Array<{ value: T; label: string }>;
+    initialValue?: T;
+  }) => Promise<T>;
+}
+
+/**
+ * 解析默认账户 ID
+ */
+function resolveDefaultAccountId(cfg: OpenClawConfig): string {
+  const ids = listAgentForumAccountIds(cfg);
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+/**
+ * AgentForum Onboarding Adapter
+ */
+export const agentforumOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel: "agentforum" as any,
+
+  /**
+   * 获取当前通道的配置状态
+   */
+  getStatus: async (ctx) => {
+    const cfg = ctx.cfg as OpenClawConfig;
+    const configured = listAgentForumAccountIds(cfg).some((accountId) => {
+      const account = resolveAgentForumAccount(cfg, accountId);
+      return isAgentForumAccountConfigured(account);
+    });
+
+    return {
+      channel: "agentforum" as any,
+      configured,
+      statusLines: [
+        `AgentForum: ${configured ? "已配置" : "需要 API Key 和 Agent ID"}`,
+      ],
+      selectionHint: configured
+        ? "已配置"
+        : "连接 AgentForum 多 Agent 协作平台",
+      quickstartScore: configured ? 1 : 30,
+    };
+  },
+
+  /**
+   * 交互式配置向导
+   */
+  configure: async (ctx) => {
+    const cfg = ctx.cfg as OpenClawConfig;
+    const prompter = ctx.prompter as Prompter;
+    const accountOverrides = ctx.accountOverrides as Record<string, string> | undefined;
+    const shouldPromptAccountIds = ctx.shouldPromptAccountIds;
+
+    const agentforumOverride = accountOverrides?.agentforum?.trim();
+    const defaultAccountId = resolveDefaultAccountId(cfg);
+    let accountId = agentforumOverride ?? defaultAccountId;
+
+    // 多账户选择
+    if (shouldPromptAccountIds && !agentforumOverride) {
+      const existingIds = listAgentForumAccountIds(cfg);
+      if (existingIds.length > 1) {
+        accountId = await prompter.select({
+          message: "选择 AgentForum 账户",
+          options: existingIds.map((id) => ({
+            value: id,
+            label: id === DEFAULT_ACCOUNT_ID ? "默认账户" : id,
+          })),
+          initialValue: accountId,
+        });
+      }
+    }
+
+    let next: OpenClawConfig = cfg;
+    const resolvedAccount = resolveAgentForumAccount(next, accountId);
+    const accountConfigured = isAgentForumAccountConfigured(resolvedAccount);
+    const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+    const envApiKey = typeof process !== "undefined" ? process.env?.[ENV_API_KEY]?.trim() : undefined;
+    const envAgentId = typeof process !== "undefined" ? process.env?.[ENV_AGENT_ID]?.trim() : undefined;
+    const envForumUrl = typeof process !== "undefined" ? process.env?.[ENV_FORUM_URL]?.trim() : undefined;
+    const canUseEnv = allowEnv && Boolean(envApiKey && envAgentId);
+    const hasConfigCredentials = Boolean(resolvedAccount.apiKey && resolvedAccount.agentId);
+
+    let apiKey: string | null = null;
+    let agentId: string | null = null;
+    let forumUrl: string | null = null;
+
+    // 显示帮助
+    if (!accountConfigured) {
+      await prompter.note(
+        [
+          "AgentForum 连接配置",
+          "",
+          "你需要提供：",
+          "  - API Key (af_xxx 格式，注册 Agent 时返回)",
+          "  - Agent ID (UUID，注册 Agent 时返回)",
+          "  - 服务器地址 (默认 http://localhost:3000)",
+          "",
+          "Channel ID 可选 — 不指定则监听所有已加入频道",
+          "Agent 通过 @mention 或 reply 被触发回复",
+          "",
+          "也可以设置环境变量 AGENTFORUM_API_KEY 和 AGENTFORUM_AGENT_ID",
+        ].join("\n"),
+        "AgentForum 配置",
+      );
+    }
+
+    // 检测环境变量
+    if (canUseEnv && !hasConfigCredentials) {
+      const keepEnv = await prompter.confirm({
+        message: `检测到环境变量 ${ENV_API_KEY} 和 ${ENV_AGENT_ID}，是否使用？`,
+        initialValue: true,
+      });
+      if (keepEnv) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            agentforum: {
+              ...(next.channels?.agentforum as Record<string, unknown> || {}),
+              enabled: true,
+              apiKey: envApiKey,
+              agentId: envAgentId,
+              ...(envForumUrl ? { forumUrl: envForumUrl } : {}),
+            },
+          },
+        };
+        return { success: true, cfg: next as any, accountId };
+      }
+    }
+
+    // 已有配置
+    if (hasConfigCredentials) {
+      const keep = await prompter.confirm({
+        message: `AgentForum 已配置 (agent: ${resolvedAccount.agentId})，是否保留当前配置？`,
+        initialValue: true,
+      });
+      if (keep) {
+        return { success: true, cfg: next as any, accountId };
+      }
+    }
+
+    // 手动输入
+    forumUrl = String(
+      await prompter.text({
+        message: "AgentForum 服务器地址",
+        placeholder: "http://localhost:3000",
+        initialValue: resolvedAccount.forumUrl || "http://localhost:3000",
+      }),
+    ).trim();
+
+    apiKey = String(
+      await prompter.text({
+        message: "API Key (af_xxx 格式)",
+        placeholder: "af_...",
+        initialValue: resolvedAccount.apiKey || undefined,
+        validate: (value: string) => {
+          if (!value?.trim()) return "API Key 不能为空";
+          if (!value.startsWith("af_")) return "API Key 必须以 af_ 开头";
+          return undefined;
+        },
+      }),
+    ).trim();
+
+    agentId = String(
+      await prompter.text({
+        message: "Agent ID (UUID)",
+        placeholder: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+        initialValue: resolvedAccount.agentId || undefined,
+        validate: (value: string) => {
+          if (!value?.trim()) return "Agent ID 不能为空";
+          return undefined;
+        },
+      }),
+    ).trim();
+
+    // 写入配置
+    if (apiKey && agentId) {
+      const existingSection = (next.channels?.agentforum as Record<string, unknown>) || {};
+
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            agentforum: {
+              ...existingSection,
+              enabled: true,
+              apiKey,
+              agentId,
+              forumUrl,
+            },
+          },
+        };
+      } else {
+        const existingAccounts = (existingSection.accounts as Record<string, unknown>) || {};
+        const existingAccount = (existingAccounts[accountId] as Record<string, unknown>) || {};
+
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            agentforum: {
+              ...existingSection,
+              enabled: true,
+              accounts: {
+                ...existingAccounts,
+                [accountId]: {
+                  ...existingAccount,
+                  enabled: true,
+                  apiKey,
+                  agentId,
+                  forumUrl,
+                },
+              },
+            },
+          },
+        };
+      }
+    }
+
+    return { success: true, cfg: next as any, accountId };
+  },
+
+  /**
+   * 禁用 AgentForum 通道
+   */
+  disable: (cfg: unknown) => {
+    const config = cfg as OpenClawConfig;
+    return {
+      ...config,
+      channels: {
+        ...config.channels,
+        agentforum: {
+          ...(config.channels?.agentforum as Record<string, unknown> || {}),
+          enabled: false,
+        },
+      },
+    } as any;
+  },
+};