@shenhh/popo-oa 0.1.0

package/index.ts

@@ -0,0 +1,36 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { popoOaPlugin } from "./src/channel.js";
+import { setPopoOaRuntime } from "./src/runtime.js";
+
+export { monitorPopoOaProvider } from "./src/monitor.js";
+export {
+  sendMessagePopoOa,
+  sendTextPopoOa,
+  sendImagePopoOa,
+  sendNewsPopoOa,
+  sendListPopoOa,
+  sendButtonPopoOa,
+} from "./src/send.js";
+export { probePopoOa } from "./src/probe.js";
+export { popoOaPlugin } from "./src/channel.js";
+export { verifySignature, generateSignature } from "./src/crypto.js";
+export type {
+  PopoOaConfig,
+  PopoOaXmlMessage,
+  PopoOaSendMessage,
+  ResolvedPopoOaAccount,
+} from "./src/types.js";
+
+const plugin = {
+  id: "popo-oa",
+  name: "POPO 服务号",
+  description: "POPO Official Account (服务号) channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setPopoOaRuntime(api.runtime);
+    api.registerChannel({ plugin: popoOaPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "popo-oa",
+  "channels": ["popo-oa"],
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@shenhh/popo-oa",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenClaw POPO Official Account (服务号) channel plugin",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json"
+  ],
+  "author": {
+    "name": "Hengheng Shen",
+    "email": "1048157315@qq.com"
+  },
+  "publishConfig": {
+    "cache": "~/.npm",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m1heng/clawdbot-popo-oa.git"
+  },
+  "keywords": [
+    "openclaw",
+    "popo",
+    "netease",
+    "chatbot",
+    "ai",
+    "claude",
+    "official-account",
+    "服务号"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "popo-oa",
+      "label": "POPO 服务号",
+      "selectionLabel": "POPO 服务号 (网易)",
+      "docsPath": "/channels/popo-oa",
+      "docsLabel": "popo-oa",
+      "blurb": "POPO Official Account messaging via Open API.",
+      "aliases": [],
+      "order": 82
+    },
+    "install": {
+      "npmSpec": "@shenhh/clawdbot-popo-oa",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "openclaw": "2026.1.29",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,53 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type { PopoOaConfig, ResolvedPopoOaAccount } from "./types.js";
+
+export function resolvePopoOaCredentials(cfg?: PopoOaConfig): {
+  appId: string;
+  appSecret: string;
+  token: string;
+  server: string;
+  webhookPath: string;
+} | null {
+  const appId = cfg?.appId?.trim();
+  const appSecret = cfg?.appSecret?.trim();
+  const token = cfg?.token?.trim();
+  if (!appId || !appSecret || !token) return null;
+  return {
+    appId,
+    appSecret,
+    token,
+    server: cfg?.server ?? "https://open.popo.netease.com",
+    webhookPath: cfg?.webhookPath ?? "/popo-oa/events",
+  };
+}
+
+export function resolvePopoOaAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedPopoOaAccount {
+  const popoCfg = params.cfg.channels?.["popo-oa"] as PopoOaConfig | undefined;
+  const creds = resolvePopoOaCredentials(popoCfg);
+
+  if (!creds || !popoCfg) {
+    throw new Error("POPO OA not configured");
+  }
+
+  return {
+    id: creds.appId,
+    appId: creds.appId,
+    appSecret: creds.appSecret,
+    token: creds.token,
+    server: creds.server,
+    webhookPath: creds.webhookPath,
+    cfg: popoCfg,
+  };
+}
+
+export function listPopoOaAccountIds(_cfg: ClawdbotConfig): string[] {
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultPopoOaAccountId(_cfg: ClawdbotConfig): string {
+  return DEFAULT_ACCOUNT_ID;
+}

package/src/auth.ts

@@ -0,0 +1,104 @@
+import type { CachedAccessToken, AccessTokenResponse } from "./types.js";
+
+// In-memory token cache: appId -> cached token
+const tokenCache = new Map<string, CachedAccessToken>();
+
+/**
+ * Get access token for POPO OA API.
+ * Uses cached token if available and not expired.
+ */
+export async function getAccessToken({
+  appId,
+  appSecret,
+  server,
+}: {
+  appId: string;
+  appSecret: string;
+  server: string;
+}): Promise<string> {
+  const cached = tokenCache.get(appId);
+
+  // Return cached token if still valid (with 5 min buffer)
+  if (cached && cached.expiresAt > Date.now() + 5 * 60 * 1000) {
+    return cached.token;
+  }
+
+  // Fetch new token
+  const token = await fetchAccessToken({ appId, appSecret, server });
+
+  // Cache the token
+  tokenCache.set(appId, {
+    token: token.accessToken,
+    expiresAt: Date.now() + token.expiresIn * 1000,
+  });
+
+  return token.accessToken;
+}
+
+/**
+ * Fetch new access token from POPO OA API.
+ */
+async function fetchAccessToken({
+  appId,
+  appSecret,
+  server,
+}: {
+  appId: string;
+  appSecret: string;
+  server: string;
+}): Promise<AccessTokenResponse> {
+  const url = new URL("/open/api/v1/token", server);
+
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      appId,
+      appSecret,
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(
+      `Failed to get access token: ${response.status} ${response.statusText} - ${text}`
+    );
+  }
+
+  const data = (await response.json()) as {
+    code: number;
+    message?: string;
+    data?: {
+      accessToken: string;
+      expiresIn: number;
+    };
+  };
+
+  if (data.code !== 0) {
+    throw new Error(
+      `POPO OA API error: ${data.code} - ${data.message || "Unknown error"}`
+    );
+  }
+
+  return {
+    accessToken: data.data?.accessToken ?? "",
+    expiresIn: data.data?.expiresIn ?? 7200,
+  };
+}
+
+/**
+ * Clear cached token for an appId.
+ * Useful when token is known to be invalid.
+ */
+export function clearAccessToken(appId: string): void {
+  tokenCache.delete(appId);
+}
+
+/**
+ * Clear all cached tokens.
+ */
+export function clearAllAccessTokens(): void {
+  tokenCache.clear();
+}

package/src/bot.ts

@@ -0,0 +1,285 @@
+import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk";
+import {
+  recordPendingHistoryEntryIfEnabled,
+  clearHistoryEntriesIfEnabled,
+  DEFAULT_DM_HISTORY_LIMIT,
+  type HistoryEntry,
+} from "openclaw/plugin-sdk";
+import type { PopoOaConfig, PopoOaXmlMessage } from "./types.js";
+import { getPopoOaRuntime } from "./runtime.js";
+import { isUserAllowed, getDmSystemPrompt, isDmEnabled } from "./policy.js";
+import { createPopoOaReplyDispatcher } from "./reply-dispatcher.js";
+
+export interface PopoOaMessageEvent {
+  xml: PopoOaXmlMessage;
+  rawBody: string;
+}
+
+/**
+ * Parse XML message from POPO OA webhook.
+ */
+export function parsePopoOaXmlMessage(xml: string): PopoOaXmlMessage {
+  // Simple XML parsing using regex (for basic structure)
+  // In production, consider using a proper XML parser like fast-xml-parser
+  const extract = (tag: string): string | undefined => {
+    const match = xml.match(new RegExp(`<${tag}><!\\[CDATA\\[(.*?)\\]\\]></${tag}>`));
+    return match?.[1];
+  };
+
+  const extractRaw = (tag: string): string | undefined => {
+    const match = xml.match(new RegExp(`<${tag}>(.*?)</${tag}>`));
+    return match?.[1];
+  };
+
+  const msgType = (extract("MsgType") || "text") as PopoOaXmlMessage["MsgType"];
+
+  return {
+    ToUserName: extract("ToUserName") || "",
+    FromUserName: extract("FromUserName") || "",
+    CreateTime: extractRaw("CreateTime") || String(Date.now()),
+    MsgType: msgType,
+    MsgId: extractRaw("MsgId"),
+    Content: extract("Content"),
+    PicUrl: extract("PicUrl"),
+    MediaId: extract("MediaId"),
+    Event: extract("Event") as PopoOaXmlMessage["Event"],
+    EventKey: extract("EventKey"),
+  };
+}
+
+/**
+ * Build passive reply XML for webhook response.
+ * This allows immediate reply without making a separate API call.
+ */
+export function buildPassiveReply(params: {
+  toUser: string;
+  fromUser: string;
+  content: string;
+}): string {
+  const { toUser, fromUser, content } = params;
+  const timestamp = Math.floor(Date.now() / 1000);
+
+  return `<xml>
+  <ToUserName><![CDATA[${toUser}]]></ToUserName>
+  <FromUserName><![CDATA[${fromUser}]]></FromUserName>
+  <CreateTime>${timestamp}</CreateTime>
+  <MsgType><![CDATA[text]]></MsgType>
+  <Content><![CDATA[${content}]]></Content>
+</xml>`;
+}
+
+/**
+ * Parse POPO OA message event into normalized format.
+ */
+export function parsePopoOaMessageEvent(event: PopoOaMessageEvent): {
+  openid: string;
+  serviceAccountId: string;
+  messageId?: string;
+  content: string;
+  msgType: string;
+  isEvent: boolean;
+  eventType?: string;
+  eventKey?: string;
+  timestamp: number;
+} {
+  const { xml } = event;
+  const isEvent = xml.MsgType === "event";
+
+  return {
+    openid: xml.FromUserName,
+    serviceAccountId: xml.ToUserName,
+    messageId: xml.MsgId,
+    content: xml.Content || "",
+    msgType: xml.MsgType,
+    isEvent,
+    eventType: xml.Event,
+    eventKey: xml.EventKey,
+    timestamp: parseInt(xml.CreateTime, 10) || Date.now(),
+  };
+}
+
+/**
+ * Handle incoming POPO OA message.
+ */
+export async function handlePopoOaMessage(params: {
+  cfg: ClawdbotConfig;
+  event: PopoOaMessageEvent;
+  runtime?: RuntimeEnv;
+  approvedUsers: Set<string>;
+  chatHistories?: Map<string, HistoryEntry[]>;
+}): Promise<string | null> {
+  const { cfg, event, runtime, approvedUsers, chatHistories } = params;
+  const popoCfg = cfg.channels?.["popo-oa"] as PopoOaConfig | undefined;
+  const log = runtime?.log ?? console.log;
+  const error = runtime?.error ?? console.error;
+
+  if (!popoCfg) {
+    error("popo-oa: configuration not found");
+    return null;
+  }
+
+  const ctx = parsePopoOaMessageEvent(event);
+  const openid = ctx.openid;
+
+  // Skip event messages (subscribe/unsubscribe etc)
+  if (ctx.isEvent) {
+    log(`popo-oa: received event ${ctx.eventType} from ${openid}`);
+    // Handle subscribe event - auto-approve user
+    if (ctx.eventType === "subscribe") {
+      approvedUsers.add(openid);
+      log(`popo-oa: auto-approved user ${openid} on subscribe`);
+    }
+    return null;
+  }
+
+  // Skip non-text messages for now
+  if (ctx.msgType !== "text") {
+    log(`popo-oa: skipping non-text message type ${ctx.msgType}`);
+    return null;
+  }
+
+  log(`popo-oa: received message from ${openid}: ${ctx.content.slice(0, 50)}`);
+
+  // Check if user is allowed
+  if (!isUserAllowed({ cfg: popoCfg, openid, approvedUsers })) {
+    log(`popo-oa: user ${openid} not allowed (policy=${popoCfg.dmPolicy})`);
+    return "您还没有被授权使用此服务号。请联系管理员添加您的账号。";
+  }
+
+  // Check if DM is enabled for this user
+  if (!isDmEnabled({ cfg: popoCfg, openid })) {
+    log(`popo-oa: DM disabled for ${openid}`);
+    return null;
+  }
+
+  try {
+    const core = getPopoOaRuntime();
+    if (!core) {
+      throw new Error("POPO OA runtime not initialized");
+    }
+
+    const historyLimit = Math.max(
+      0,
+      popoCfg.dmHistoryLimit ?? popoCfg.historyLimit ?? DEFAULT_DM_HISTORY_LIMIT
+    );
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "popo-oa",
+      peer: {
+        kind: "dm",
+        id: openid,
+      },
+    });
+
+    const preview = ctx.content.replace(/\s+/g, " ").slice(0, 160);
+    core.system.enqueueSystemEvent(`POPO 服务号消息 from ${openid}: ${preview}`, {
+      sessionKey: route.sessionKey,
+      contextKey: `popo-oa:message:${openid}:${ctx.messageId || Date.now()}`,
+    });
+
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+
+    // Build message body with system prompt if configured
+    let messageBody = ctx.content;
+    const systemPrompt = getDmSystemPrompt({ cfg: popoCfg, openid });
+    if (systemPrompt) {
+      messageBody = `${systemPrompt}\n\n---\n\n${messageBody}`;
+    }
+
+    const body = core.channel.reply.formatAgentEnvelope({
+      channel: "POPO 服务号",
+      from: openid,
+      timestamp: new Date(ctx.timestamp),
+      envelope: envelopeOptions,
+      body: messageBody,
+    });
+
+    let combinedBody = body;
+    const historyKey = openid;
+
+    if (historyKey && chatHistories) {
+      combinedBody = core.channel.reply.buildPendingHistoryContextFromMap({
+        historyMap: chatHistories,
+        historyKey,
+        limit: historyLimit,
+        currentMessage: combinedBody,
+        formatEntry: (entry) =>
+          core.channel.reply.formatAgentEnvelope({
+            channel: "POPO 服务号",
+            from: entry.sender,
+            timestamp: entry.timestamp,
+            body: entry.body,
+            envelope: envelopeOptions,
+          }),
+      });
+    }
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: combinedBody,
+      RawBody: ctx.content,
+      CommandBody: ctx.content,
+      From: `popo-oa:${openid}`,
+      To: `user:${openid}`,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: "direct",
+      SenderName: openid,
+      SenderId: openid,
+      Provider: "popo-oa" as const,
+      Surface: "popo-oa" as const,
+      MessageSid: ctx.messageId || String(Date.now()),
+      Timestamp: ctx.timestamp,
+      WasMentioned: false,
+      CommandAuthorized: true,
+      OriginatingChannel: "popo-oa" as const,
+      OriginatingTo: `user:${openid}`,
+    });
+
+    const { dispatcher, replyOptions, markDispatchIdle } = createPopoOaReplyDispatcher({
+      cfg,
+      agentId: route.agentId,
+      runtime: runtime as RuntimeEnv,
+      openid,
+    });
+
+    log(`popo-oa: dispatching to agent (session=${route.sessionKey})`);
+
+    const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
+      ctx: ctxPayload,
+      cfg,
+      dispatcher,
+      replyOptions,
+    });
+
+    markDispatchIdle();
+
+    // Record history entry
+    if (chatHistories && historyKey) {
+      recordPendingHistoryEntryIfEnabled({
+        historyMap: chatHistories,
+        historyKey,
+        entry: {
+          sender: openid,
+          body: ctx.content,
+          timestamp: new Date(ctx.timestamp),
+        },
+        limit: historyLimit,
+      });
+
+      clearHistoryEntriesIfEnabled({
+        historyMap: chatHistories,
+        historyKey,
+        limit: historyLimit,
+      });
+    }
+
+    log(`popo-oa: dispatch complete (queuedFinal=${queuedFinal}, replies=${counts.final})`);
+
+    // Return null - replies will be sent via outbound adapter
+    return null;
+  } catch (err) {
+    error(`popo-oa: failed to dispatch message: ${String(err)}`);
+    return "抱歉，处理消息时出现了错误。请稍后重试。";
+  }
+}