@shenhh/popo-oa 0.1.0

package/src/outbound.ts

@@ -0,0 +1,72 @@
+import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk";
+import { getPopoOaRuntime } from "./runtime.js";
+import { sendTextPopoOa, sendNewsPopoOa, sendImagePopoOa, sendListPopoOa, sendButtonPopoOa } from "./send.js";
+import { resolvePopoOaAccount } from "./accounts.js";
+
+export const popoOaOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunker: (text, limit) => getPopoOaRuntime()?.channel.text.chunkMarkdownText(text, limit) ?? [text],
+  chunkerMode: "markdown",
+  textChunkLimit: 2000,
+  sendText: async ({ cfg, to, text }) => {
+    const account = resolvePopoOaAccount({ cfg });
+    const result = await sendTextPopoOa({ cfg: account, to, text });
+    return { channel: "popo-oa", ...result };
+  },
+  sendMedia: async ({ cfg, to, text, mediaUrl }) => {
+    const account = resolvePopoOaAccount({ cfg });
+
+    // Send text first if provided
+    if (text?.trim()) {
+      await sendTextPopoOa({ cfg: account, to, text });
+    }
+
+    // POPO OA doesn't support direct media upload in the same way
+    // Send as link if URL provided
+    if (mediaUrl) {
+      const fallbackText = `📎 ${mediaUrl}`;
+      const result = await sendTextPopoOa({ cfg: account, to, text: fallbackText });
+      return { channel: "popo-oa", ...result };
+    }
+
+    // No media URL, just return text result
+    const result = await sendTextPopoOa({ cfg: account, to, text: text ?? "" });
+    return { channel: "popo-oa", ...result };
+  },
+  sendCard: async ({ cfg, to, card }) => {
+    const account = resolvePopoOaAccount({ cfg });
+
+    // POPO OA supports news (article) messages which are similar to cards
+    const { title, description, url, picurl } = card as {
+      title?: string;
+      description?: string;
+      url?: string;
+      picurl?: string;
+    };
+
+    if (title && url) {
+      const result = await sendNewsPopoOa({
+        cfg: account,
+        to,
+        articles: [{
+          title,
+          description: description ?? "",
+          url,
+          picurl,
+        }],
+      });
+      return { channel: "popo-oa", ...result };
+    }
+
+    // Fallback to text
+    const result = await sendTextPopoOa({
+      cfg: account,
+      to,
+      text: `${title ?? "Card"}\n${description ?? ""}\n${url ?? ""}`,
+    });
+    return { channel: "popo-oa", ...result };
+  },
+  // POPO OA doesn't support streaming cards in the same way as Native API
+  createStreamCard: undefined,
+  updateStreamCard: undefined,
+};

package/src/policy.ts

@@ -0,0 +1,60 @@
+import type { PopoOaConfig } from "./config-schema.js";
+
+/**
+ * Check if a user is allowed to interact with the bot.
+ */
+export function isUserAllowed({
+  cfg,
+  openid,
+  approvedUsers,
+}: {
+  cfg: PopoOaConfig;
+  openid: string;
+  approvedUsers: Set<string>;
+}): boolean {
+  const policy = cfg.dmPolicy ?? "pairing";
+
+  switch (policy) {
+    case "open":
+      return true;
+    case "pairing":
+      return approvedUsers.has(openid);
+    case "allowlist": {
+      const allowList = cfg.allowFrom ?? [];
+      return allowList.includes(openid);
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * Get system prompt for a specific user DM.
+ */
+export function getDmSystemPrompt({
+  cfg,
+  openid,
+}: {
+  cfg: PopoOaConfig;
+  openid: string;
+}): string | undefined {
+  const dmConfig = cfg.dms?.[openid];
+  return dmConfig?.systemPrompt ?? cfg.systemPrompt;
+}
+
+/**
+ * Check if DM is enabled for a specific user.
+ */
+export function isDmEnabled({
+  cfg,
+  openid,
+}: {
+  cfg: PopoOaConfig;
+  openid: string;
+}): boolean {
+  const dmConfig = cfg.dms?.[openid];
+  if (dmConfig?.enabled !== undefined) {
+    return dmConfig.enabled;
+  }
+  return cfg.enabled !== false;
+}

package/src/probe.ts

@@ -0,0 +1,44 @@
+import type { PopoOaConfig } from "./types.js";
+import { getAccessToken, clearAccessToken } from "./auth.js";
+
+export interface ProbeResult {
+  ok: boolean;
+  appId?: string;
+  error?: string;
+}
+
+/**
+ * Probe POPO OA configuration by attempting to get an access token.
+ */
+export async function probePopoOa(cfg?: PopoOaConfig): Promise<ProbeResult> {
+  if (!cfg) {
+    return { ok: false, error: "Configuration not found" };
+  }
+
+  const appId = cfg.appId?.trim();
+  const appSecret = cfg.appSecret?.trim();
+
+  if (!appId || !appSecret) {
+    return { ok: false, error: "Missing appId or appSecret" };
+  }
+
+  try {
+    // Clear any cached token to force a fresh request
+    clearAccessToken(appId);
+
+    // Try to get an access token
+    await getAccessToken({
+      appId,
+      appSecret,
+      server: cfg.server ?? "https://open.popo.netease.com",
+    });
+
+    return { ok: true, appId };
+  } catch (err) {
+    return {
+      ok: false,
+      appId,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/reply-dispatcher.ts

@@ -0,0 +1,130 @@
+import {
+  createReplyPrefixContext,
+  createTypingCallbacks,
+  logTypingFailure,
+  type ClawdbotConfig,
+  type RuntimeEnv,
+  type ReplyPayload,
+} from "openclaw/plugin-sdk";
+import { getPopoOaRuntime } from "./runtime.js";
+import { sendTextPopoOa } from "./send.js";
+import type { PopoOaConfig } from "./types.js";
+import { resolvePopoOaAccount } from "./accounts.js";
+
+export type CreatePopoOaReplyDispatcherParams = {
+  cfg: ClawdbotConfig;
+  agentId: string;
+  runtime: RuntimeEnv;
+  openid: string;
+};
+
+export function createPopoOaReplyDispatcher(params: CreatePopoOaReplyDispatcherParams) {
+  const core = getPopoOaRuntime();
+  const { cfg, agentId, openid } = params;
+
+  const prefixContext = createReplyPrefixContext({
+    cfg,
+    agentId,
+  });
+
+  // Track whether any tool results have been sent
+  let hasToolResults = false;
+  let toolResultCount = 0;
+
+  // POPO OA doesn't have a native typing indicator API
+  const typingCallbacks = createTypingCallbacks({
+    start: async () => {
+      // No-op for POPO OA
+    },
+    stop: async () => {
+      // No-op for POPO OA
+    },
+    onStartError: (err) => {
+      logTypingFailure({
+        log: (message) => params.runtime.log?.(message),
+        channel: "popo-oa",
+        action: "start",
+        error: err,
+      });
+    },
+    onStopError: (err) => {
+      logTypingFailure({
+        log: (message) => params.runtime.log?.(message),
+        channel: "popo-oa",
+        action: "stop",
+        error: err,
+      });
+    },
+  });
+
+  const textChunkLimit = core.channel.text.resolveTextChunkLimit({
+    cfg,
+    channel: "popo-oa",
+    defaultLimit: 2000,
+  });
+  const chunkMode = core.channel.text.resolveChunkMode(cfg, "popo-oa");
+
+  const popoCfg = cfg.channels?.["popo-oa"] as PopoOaConfig | undefined;
+
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    core.channel.reply.createReplyDispatcherWithTyping({
+      responsePrefix: prefixContext.responsePrefix,
+      responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
+      humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, agentId),
+      onReplyStart: typingCallbacks.onReplyStart,
+      deliver: async (payload: ReplyPayload) => {
+        params.runtime.log?.(`popo-oa deliver called: text=${payload.text?.slice(0, 100)}`);
+        const text = payload.text ?? "";
+
+        // Build tool execution indicator if tools were used
+        let fullText = text;
+        if (hasToolResults) {
+          const toolIndicator = toolResultCount === 1
+            ? "🛠️ **使用了 1 个工具**\n\n"
+            : `🛠️ **使用了 ${toolResultCount} 个工具**\n\n`;
+          fullText = toolIndicator + text;
+          // Reset after including in message
+          hasToolResults = false;
+          toolResultCount = 0;
+        }
+
+        if (!fullText.trim()) {
+          params.runtime.log?.(`popo-oa deliver: empty text, skipping`);
+          return;
+        }
+
+        const chunks = core.channel.text.chunkTextWithMode(fullText, textChunkLimit, chunkMode);
+        params.runtime.log?.(`popo-oa deliver: sending ${chunks.length} chunks to ${openid}`);
+
+        const account = resolvePopoOaAccount({ cfg });
+
+        for (const chunk of chunks) {
+          await sendTextPopoOa({
+            cfg: account,
+            to: openid,
+            text: chunk,
+          });
+        }
+      },
+      onError: (err, info) => {
+        params.runtime.error?.(`popo-oa ${info.kind} reply failed: ${String(err)}`);
+        typingCallbacks.onIdle?.();
+      },
+      onIdle: typingCallbacks.onIdle,
+    });
+
+  return {
+    dispatcher,
+    replyOptions: {
+      ...replyOptions,
+      onModelSelected: prefixContext.onModelSelected,
+      // Track tool results as they are executed
+      onToolResult: (_payload: { text?: string; mediaUrls?: string[] }) => {
+        hasToolResults = true;
+        toolResultCount++;
+        params.runtime.log?.(`popo-oa: tracked tool result #${toolResultCount}`);
+      },
+    },
+    markDispatchIdle,
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,27 @@
+import type { RuntimeApi } from "openclaw/plugin-sdk";
+
+let runtime: RuntimeApi | undefined;
+
+/**
+ * Set the runtime API for POPO OA plugin.
+ */
+export function setPopoOaRuntime(api: RuntimeApi): void {
+  runtime = api;
+}
+
+/**
+ * Get the runtime API.
+ */
+export function getPopoOaRuntime(): RuntimeApi | undefined {
+  return runtime;
+}
+
+/**
+ * Require runtime API (throws if not set).
+ */
+export function requirePopoOaRuntime(): RuntimeApi {
+  if (!runtime) {
+    throw new Error("POPO OA runtime not initialized");
+  }
+  return runtime;
+}

package/src/send.ts

@@ -0,0 +1,129 @@
+import type { ResolvedPopoOaAccount, PopoOaSendMessage, SendMessageResponse } from "./types.js";
+import { createPopoOaClient } from "./client.js";
+import { resolvePopoOaAccount } from "./accounts.js";
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+
+/**
+ * Send a message to a user via POPO OA.
+ */
+export async function sendMessagePopoOa({
+  cfg,
+  to,
+  message,
+}: {
+  cfg: ResolvedPopoOaAccount;
+  to: string;
+  message: PopoOaSendMessage;
+}): Promise<SendMessageResponse> {
+  const client = createPopoOaClient(cfg);
+  return client.sendMessage(message);
+}
+
+/**
+ * Send a text message to a user.
+ */
+export async function sendTextPopoOa({
+  cfg,
+  to,
+  text,
+}: {
+  cfg: ResolvedPopoOaAccount;
+  to: string;
+  text: string;
+}): Promise<SendMessageResponse> {
+  const client = createPopoOaClient(cfg);
+  return client.sendText(to, text);
+}
+
+/**
+ * Send an image message to a user.
+ */
+export async function sendImagePopoOa({
+  cfg,
+  to,
+  mediaId,
+}: {
+  cfg: ResolvedPopoOaAccount;
+  to: string;
+  mediaId: string;
+}): Promise<SendMessageResponse> {
+  const client = createPopoOaClient(cfg);
+  return client.sendImage(to, mediaId);
+}
+
+/**
+ * Send a news (article) message to a user.
+ */
+export async function sendNewsPopoOa({
+  cfg,
+  to,
+  articles,
+}: {
+  cfg: ResolvedPopoOaAccount;
+  to: string;
+  articles: Array<{
+    title: string;
+    description: string;
+    url: string;
+    picurl?: string;
+  }>;
+}): Promise<SendMessageResponse> {
+  const client = createPopoOaClient(cfg);
+  return client.sendNews(to, articles);
+}
+
+/**
+ * Send a list/select message to a user.
+ */
+export async function sendListPopoOa({
+  cfg,
+  to,
+  header,
+  items,
+}: {
+  cfg: ResolvedPopoOaAccount;
+  to: string;
+  header: string;
+  items: Array<{
+    title: string;
+    description?: string;
+    url?: string;
+  }>;
+}): Promise<SendMessageResponse> {
+  const client = createPopoOaClient(cfg);
+  return client.sendList(to, header, items);
+}
+
+/**
+ * Send a button message to a user.
+ */
+export async function sendButtonPopoOa({
+  cfg,
+  to,
+  content,
+  buttons,
+}: {
+  cfg: ResolvedPopoOaAccount;
+  to: string;
+  content: string;
+  buttons: Array<{ key: string; value: string }>;
+}): Promise<SendMessageResponse> {
+  const client = createPopoOaClient(cfg);
+  return client.sendButton(to, content, buttons);
+}
+
+/**
+ * Send message using config (for internal use).
+ */
+export async function sendPopoOaMessageFromConfig({
+  config,
+  to,
+  message,
+}: {
+  config: ClawdbotConfig;
+  to: string;
+  message: PopoOaSendMessage;
+}): Promise<SendMessageResponse> {
+  const account = resolvePopoOaAccount({ cfg: config });
+  return sendMessagePopoOa({ cfg: account, to, message });
+}

package/src/targets.ts

@@ -0,0 +1,25 @@
+/**
+ * Normalize POPO OA target.
+ * POPO OA uses OpenID as user identifier.
+ */
+export function normalizePopoOaTarget(target: string): string {
+  // Remove any prefix if present
+  return target.replace(/^(popo-oa|user):/i, "");
+}
+
+/**
+ * Check if a string looks like a POPO OA OpenID.
+ * OpenIDs are typically UUID-like strings.
+ */
+export function looksLikePopoOaId(id: string): boolean {
+  // OpenID is typically a UUID or similar format
+  // Basic check: non-empty string without @ symbol (not an email)
+  return id.length > 0 && !id.includes("@");
+}
+
+/**
+ * Format target for POPO OA.
+ */
+export function formatPopoOaTarget(openid: string): string {
+  return `popo-oa:${openid}`;
+}

package/src/types.ts

@@ -0,0 +1,158 @@
+import type { PopoOaConfig as ImportedPopoOaConfig } from "./config-schema.js";
+
+// Re-export for use in other modules
+export type PopoOaConfig = ImportedPopoOaConfig;
+
+/**
+ * Resolved POPO OA account configuration
+ */
+export interface ResolvedPopoOaAccount {
+  id: string; // appId
+  appId: string;
+  appSecret: string;
+  token: string;
+  server: string;
+  webhookPath: string;
+  cfg: PopoOaConfig;
+}
+
+/**
+ * Access token response from POPO OA API
+ */
+export interface AccessTokenResponse {
+  accessToken: string;
+  expiresIn: number; // seconds
+}
+
+/**
+ * Cached access token with expiration
+ */
+export interface CachedAccessToken {
+  token: string;
+  expiresAt: number; // timestamp in ms
+}
+
+/**
+ * XML message received from POPO OA webhook
+ */
+export interface PopoOaXmlMessage {
+  ToUserName: string; // 服务号 ID
+  FromUserName: string; // 用户 OpenID
+  CreateTime: string;
+  MsgType: "text" | "image" | "voice" | "video" | "location" | "link" | "event";
+  MsgId?: string;
+  // Text message
+  Content?: string;
+  // Image message
+  PicUrl?: string;
+  MediaId?: string;
+  // Event
+  Event?:
+    | "subscribe"
+    | "unsubscribe"
+    | "CLICK"
+    | "VIEW"
+    | "BUTTON_CLICK"
+    | "TEMPLATE_CLICK";
+  EventKey?: string;
+}
+
+/**
+ * Text message to send
+ */
+export interface PopoOaTextMessage {
+  openid: string;
+  type: "text";
+  body: {
+    content: string;
+  };
+}
+
+/**
+ * Image message to send
+ */
+export interface PopoOaImageMessage {
+  openid: string;
+  type: "image";
+  body: {
+    mediaId: string;
+  };
+}
+
+/**
+ * News (article) message to send
+ */
+export interface PopoOaNewsMessage {
+  openid: string;
+  type: "news";
+  body: {
+    articles: Array<{
+      title: string;
+      description: string;
+      url: string;
+      picurl?: string;
+    }>;
+  };
+}
+
+/**
+ * List/select message to send
+ */
+export interface PopoOaListMessage {
+  openid: string;
+  type: "list";
+  body: {
+    header: string;
+    items: Array<{
+      title: string;
+      description?: string;
+      url?: string;
+    }>;
+  };
+}
+
+/**
+ * Button message to send
+ */
+export interface PopoOaButtonMessage {
+  openid: string;
+  type: "button";
+  body: {
+    content: string;
+    buttons: Array<{
+      key: string;
+      value: string;
+    }>;
+  };
+}
+
+/**
+ * Union type for all sendable messages
+ */
+export type PopoOaSendMessage =
+  | PopoOaTextMessage
+  | PopoOaImageMessage
+  | PopoOaNewsMessage
+  | PopoOaListMessage
+  | PopoOaButtonMessage;
+
+/**
+ * Send message response
+ */
+export interface SendMessageResponse {
+  code: number;
+  message?: string;
+  data?: {
+    msgId?: string;
+  };
+}
+
+/**
+ * Webhook verification params
+ */
+export interface WebhookVerifyParams {
+  signature: string;
+  timestamp: string;
+  nonce: string;
+  echostr: string;
+}