@yanhaidao/wecom 2.3.4 → 2.3.10

package/src/target.ts

@@ -20,6 +20,12 @@ export interface WecomTarget {
     chatid?: string;
 }
 
+export interface ScopedWecomTarget {
+    accountId?: string;
+    target: WecomTarget;
+    rawTarget: string;
+}
+
 /**
  * Parses a raw target string into a WeComTarget object.
  * 解析原始目标字符串为 WeComTarget 对象。
@@ -78,3 +84,25 @@ export function resolveWecomTarget(raw: string | undefined): WecomTarget | undef
     // Default to User (默认为用户)
     return { touser: clean };
 }
+
+export function resolveScopedWecomTarget(raw: string | undefined, defaultAccountId?: string): ScopedWecomTarget | undefined {
+    if (!raw?.trim()) return undefined;
+
+    const trimmed = raw.trim();
+    const agentScoped = trimmed.match(/^wecom-agent:([^:]+):(.+)$/i);
+    if (agentScoped) {
+        const accountId = agentScoped[1]?.trim() || defaultAccountId;
+        const rawTarget = agentScoped[2]?.trim() || "";
+        const target = resolveWecomTarget(rawTarget);
+        return target ? { accountId, target, rawTarget } : undefined;
+    }
+
+    const target = resolveWecomTarget(trimmed);
+    return target
+        ? {
+            accountId: defaultAccountId,
+            target,
+            rawTarget: trimmed,
+        }
+        : undefined;
+}

package/src/transport/agent-api/client.ts

@@ -0,0 +1,44 @@
+import type { ResolvedAgentAccount } from "../../types/index.js";
+import {
+  downloadMedia as downloadLegacyMedia,
+  getAccessToken as getLegacyAccessToken,
+  sendMedia as sendLegacyMedia,
+  sendText as sendLegacyText,
+} from "./core.js";
+
+export async function getAgentApiAccessToken(agent: ResolvedAgentAccount): Promise<string> {
+  return getLegacyAccessToken(agent);
+}
+
+export async function sendAgentApiText(params: {
+  agent: ResolvedAgentAccount;
+  toUser?: string;
+  toParty?: string;
+  toTag?: string;
+  chatId?: string;
+  text: string;
+}): Promise<void> {
+  await sendLegacyText(params);
+}
+
+export async function sendAgentApiMedia(params: {
+  agent: ResolvedAgentAccount;
+  toUser?: string;
+  toParty?: string;
+  toTag?: string;
+  chatId?: string;
+  mediaId: string;
+  mediaType: "image" | "voice" | "video" | "file";
+  title?: string;
+  description?: string;
+}): Promise<void> {
+  await sendLegacyMedia(params);
+}
+
+export async function downloadAgentApiMedia(params: {
+  agent: ResolvedAgentAccount;
+  mediaId: string;
+  maxBytes?: number;
+}): Promise<{ buffer: Buffer; contentType: string; filename?: string }> {
+  return downloadLegacyMedia(params);
+}

package/src/transport/agent-api/core.ts

@@ -0,0 +1,367 @@
+import crypto from "node:crypto";
+
+import { resolveWecomEgressProxyUrlFromNetwork } from "../../config/index.js";
+import { readResponseBodyAsBuffer, wecomFetch } from "../../http.js";
+import { API_ENDPOINTS, LIMITS } from "../../types/constants.js";
+import type { ResolvedAgentAccount } from "../../types/index.js";
+
+type TokenCache = {
+  token: string;
+  expiresAt: number;
+  refreshPromise: Promise<string> | null;
+};
+
+const tokenCaches = new Map<string, TokenCache>();
+
+function truncateForLog(raw: string, maxChars = 180): string {
+  const compact = raw.replace(/\s+/g, " ").trim();
+  if (compact.length <= maxChars) return compact;
+  return `${compact.slice(0, maxChars)}...(truncated)`;
+}
+
+function normalizeUploadFilename(filename: string): string {
+  const trimmed = filename.trim();
+  if (!trimmed) return "file.bin";
+  const ext = trimmed.includes(".") ? `.${trimmed.split(".").pop()!.toLowerCase()}` : "";
+  const base = ext ? trimmed.slice(0, -ext.length) : trimmed;
+  const sanitizedBase = base
+    .replace(/[^\x20-\x7e]/g, "_")
+    .replace(/["\\/;=]/g, "_")
+    .replace(/\s+/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  const safeBase = sanitizedBase || "file";
+  const safeExt = ext.replace(/[^a-z0-9.]/g, "");
+  return `${safeBase}${safeExt || ".bin"}`;
+}
+
+function guessUploadContentType(filename: string): string {
+  const ext = filename.split(".").pop()?.toLowerCase() || "";
+  const contentTypeMap: Record<string, string> = {
+    jpg: "image/jpg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    bmp: "image/bmp",
+    amr: "voice/amr",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    m4a: "audio/mp4",
+    ogg: "audio/ogg",
+    mp4: "video/mp4",
+    mov: "video/quicktime",
+    txt: "text/plain",
+    md: "text/markdown",
+    csv: "text/csv",
+    tsv: "text/tab-separated-values",
+    json: "application/json",
+    xml: "application/xml",
+    yaml: "application/yaml",
+    yml: "application/yaml",
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    rtf: "application/rtf",
+    odt: "application/vnd.oasis.opendocument.text",
+    zip: "application/zip",
+    rar: "application/vnd.rar",
+    "7z": "application/x-7z-compressed",
+    gz: "application/gzip",
+    tgz: "application/gzip",
+    tar: "application/x-tar",
+  };
+  return contentTypeMap[ext] || "application/octet-stream";
+}
+
+function requireAgentId(agent: ResolvedAgentAccount): number {
+  if (typeof agent.agentId === "number" && Number.isFinite(agent.agentId)) return agent.agentId;
+  throw new Error(`wecom agent account=${agent.accountId} missing agentId; sending via cgi-bin/message/send requires agentId`);
+}
+
+export async function getAccessToken(agent: ResolvedAgentAccount): Promise<string> {
+  const cacheKey = `${agent.corpId}:${String(agent.agentId ?? "na")}`;
+  let cache = tokenCaches.get(cacheKey);
+
+  if (!cache) {
+    cache = { token: "", expiresAt: 0, refreshPromise: null };
+    tokenCaches.set(cacheKey, cache);
+  }
+
+  const now = Date.now();
+  if (cache.token && cache.expiresAt > now + LIMITS.TOKEN_REFRESH_BUFFER_MS) {
+    return cache.token;
+  }
+
+  if (cache.refreshPromise) {
+    return cache.refreshPromise;
+  }
+
+  cache.refreshPromise = (async () => {
+    try {
+      const url = `${API_ENDPOINTS.GET_TOKEN}?corpid=${encodeURIComponent(agent.corpId)}&corpsecret=${encodeURIComponent(agent.corpSecret)}`;
+      const res = await wecomFetch(url, undefined, {
+        proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network),
+        timeoutMs: LIMITS.REQUEST_TIMEOUT_MS,
+      });
+      const json = (await res.json()) as { access_token?: string; expires_in?: number; errcode?: number; errmsg?: string };
+
+      if (!json?.access_token) {
+        throw new Error(`gettoken failed: ${json?.errcode} ${json?.errmsg}`);
+      }
+
+      cache!.token = json.access_token;
+      cache!.expiresAt = Date.now() + (json.expires_in ?? 7200) * 1000;
+      return cache!.token;
+    } finally {
+      cache!.refreshPromise = null;
+    }
+  })();
+
+  return cache.refreshPromise;
+}
+
+export async function sendText(params: {
+  agent: ResolvedAgentAccount;
+  toUser?: string;
+  toParty?: string;
+  toTag?: string;
+  chatId?: string;
+  text: string;
+}): Promise<void> {
+  const { agent, toUser, toParty, toTag, chatId, text } = params;
+  console.log(
+    `[wecom-agent-api] sendText request account=${agent.accountId} agentId=${String(agent.agentId ?? "N/A")} ` +
+      `toUser=${toUser ?? ""} toParty=${toParty ?? ""} toTag=${toTag ?? ""} chatId=${chatId ?? ""} ` +
+      `textLen=${text.length} textPreview=${JSON.stringify(truncateForLog(text))}`,
+  );
+  const token = await getAccessToken(agent);
+
+  const useChat = Boolean(chatId);
+  const url = useChat
+    ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+    : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+
+  const body = useChat
+    ? { chatid: chatId, msgtype: "text", text: { content: text } }
+    : {
+        touser: toUser,
+        toparty: toParty,
+        totag: toTag,
+        msgtype: "text",
+        agentid: requireAgentId(agent),
+        text: { content: text },
+      };
+
+  const res = await wecomFetch(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    },
+    { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+  );
+  const json = (await res.json()) as {
+    errcode?: number;
+    errmsg?: string;
+    invaliduser?: string;
+    invalidparty?: string;
+    invalidtag?: string;
+  };
+
+  console.log(
+    `[wecom-agent-api] sendText response account=${agent.accountId} agentId=${String(agent.agentId ?? "N/A")} ` +
+      `toUser=${toUser ?? ""} toParty=${toParty ?? ""} toTag=${toTag ?? ""} chatId=${chatId ?? ""} ` +
+      `errcode=${String(json?.errcode ?? "N/A")} errmsg=${json?.errmsg ?? ""} ` +
+      `invaliduser=${json?.invaliduser ?? ""} invalidparty=${json?.invalidparty ?? ""} invalidtag=${json?.invalidtag ?? ""}`,
+  );
+
+  if (json?.errcode !== 0) {
+    throw new Error(`send failed: ${json?.errcode} ${json?.errmsg}`);
+  }
+
+  if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+    const details = [
+      json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+      json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+      json.invalidtag ? `invalidtag=${json.invalidtag}` : "",
+    ]
+      .filter(Boolean)
+      .join(", ");
+    throw new Error(`send partial failure: ${details}`);
+  }
+}
+
+export async function uploadMedia(params: {
+  agent: ResolvedAgentAccount;
+  type: "image" | "voice" | "video" | "file";
+  buffer: Buffer;
+  filename: string;
+}): Promise<string> {
+  const { agent, type, buffer, filename } = params;
+  const safeFilename = normalizeUploadFilename(filename);
+  const token = await getAccessToken(agent);
+  const proxyUrl = resolveWecomEgressProxyUrlFromNetwork(agent.network);
+  const url = `${API_ENDPOINTS.UPLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&type=${encodeURIComponent(type)}&debug=1`;
+
+  console.log(`[wecom-upload] Uploading media: type=${type}, filename=${safeFilename}, size=${buffer.length} bytes`);
+
+  const uploadOnce = async (fileContentType: string) => {
+    const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
+    const header = Buffer.from(
+      `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="media"; filename="${safeFilename}"; filelength=${buffer.length}\r\n` +
+        `Content-Type: ${fileContentType}\r\n\r\n`,
+    );
+    const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+    const body = Buffer.concat([header, buffer, footer]);
+
+    console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
+
+    const res = await wecomFetch(
+      url,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": `multipart/form-data; boundary=${boundary}`,
+          "Content-Length": String(body.length),
+        },
+        body,
+      },
+      { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+    );
+    const json = (await res.json()) as { media_id?: string; errcode?: number; errmsg?: string };
+    console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+    return json;
+  };
+
+  const preferredContentType = guessUploadContentType(safeFilename);
+  let json = await uploadOnce(preferredContentType);
+
+  if (!json?.media_id && preferredContentType !== "application/octet-stream") {
+    console.warn(
+      `[wecom-upload] Upload failed with ${preferredContentType}, retrying as application/octet-stream: ${json?.errcode} ${json?.errmsg}`,
+    );
+    json = await uploadOnce("application/octet-stream");
+  }
+
+  if (!json?.media_id) {
+    throw new Error(`upload failed: ${json?.errcode} ${json?.errmsg}`);
+  }
+  return json.media_id;
+}
+
+export async function sendMedia(params: {
+  agent: ResolvedAgentAccount;
+  toUser?: string;
+  toParty?: string;
+  toTag?: string;
+  chatId?: string;
+  mediaId: string;
+  mediaType: "image" | "voice" | "video" | "file";
+  title?: string;
+  description?: string;
+}): Promise<void> {
+  const { agent, toUser, toParty, toTag, chatId, mediaId, mediaType, title, description } = params;
+  const token = await getAccessToken(agent);
+
+  const useChat = Boolean(chatId);
+  const url = useChat
+    ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+    : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+
+  const mediaPayload = mediaType === "video" ? { media_id: mediaId, title: title ?? "Video", description: description ?? "" } : { media_id: mediaId };
+  const body = useChat
+    ? { chatid: chatId, msgtype: mediaType, [mediaType]: mediaPayload }
+    : {
+        touser: toUser,
+        toparty: toParty,
+        totag: toTag,
+        msgtype: mediaType,
+        agentid: requireAgentId(agent),
+        [mediaType]: mediaPayload,
+      };
+
+  const res = await wecomFetch(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    },
+    { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+  );
+  const json = (await res.json()) as {
+    errcode?: number;
+    errmsg?: string;
+    invaliduser?: string;
+    invalidparty?: string;
+    invalidtag?: string;
+  };
+
+  if (json?.errcode !== 0) {
+    throw new Error(`send ${mediaType} failed: ${json?.errcode} ${json?.errmsg}`);
+  }
+
+  if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+    const details = [
+      json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+      json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+      json.invalidtag ? `invalidtag=${json.invalidtag}` : "",
+    ]
+      .filter(Boolean)
+      .join(", ");
+    throw new Error(`send ${mediaType} partial failure: ${details}`);
+  }
+}
+
+export async function downloadMedia(params: {
+  agent: ResolvedAgentAccount;
+  mediaId: string;
+  maxBytes?: number;
+}): Promise<{ buffer: Buffer; contentType: string; filename?: string }> {
+  const { agent, mediaId } = params;
+  const token = await getAccessToken(agent);
+  const url = `${API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
+
+  const res = await wecomFetch(url, undefined, {
+    proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network),
+    timeoutMs: LIMITS.REQUEST_TIMEOUT_MS,
+  });
+
+  if (!res.ok) {
+    throw new Error(`download failed: ${res.status}`);
+  }
+
+  const contentType = res.headers.get("content-type") || "application/octet-stream";
+  const disposition = res.headers.get("content-disposition") || "";
+  const filename = (() => {
+    const mStar = disposition.match(/filename\*\s*=\s*([^;]+)/i);
+    if (mStar) {
+      const raw = mStar[1]!.trim().replace(/^"(.*)"$/, "$1");
+      const parts = raw.split("''");
+      const encoded = parts.length === 2 ? parts[1]! : raw;
+      try {
+        return decodeURIComponent(encoded);
+      } catch {
+        return encoded;
+      }
+    }
+    const m = disposition.match(/filename\s*=\s*([^;]+)/i);
+    if (!m) return undefined;
+    return m[1]!.trim().replace(/^"(.*)"$/, "$1") || undefined;
+  })();
+
+  if (contentType.includes("application/json")) {
+    const json = (await res.json()) as { errcode?: number; errmsg?: string };
+    throw new Error(`download failed: ${json?.errcode} ${json?.errmsg}`);
+  }
+
+  const buffer = await readResponseBodyAsBuffer(res, params.maxBytes);
+  return { buffer, contentType, filename };
+}

package/src/transport/agent-api/delivery.ts

@@ -0,0 +1,41 @@
+import type { ResolvedAgentAccount } from "../../types/index.js";
+import type { WecomTarget } from "../../target.js";
+import { sendAgentApiMediaReply, sendAgentApiTextReply } from "./reply.js";
+import { uploadAgentApiMedia } from "./media-upload.js";
+
+export async function deliverAgentApiText(params: {
+  agent: ResolvedAgentAccount;
+  target: WecomTarget;
+  text: string;
+}): Promise<void> {
+  await sendAgentApiTextReply(params);
+}
+
+export async function deliverAgentApiMedia(params: {
+  agent: ResolvedAgentAccount;
+  target: WecomTarget;
+  buffer: Buffer;
+  filename: string;
+  contentType: string;
+  text?: string;
+}): Promise<void> {
+  let mediaType: "image" | "voice" | "video" | "file" = "file";
+  if (params.contentType.startsWith("image/")) mediaType = "image";
+  else if (params.contentType.startsWith("audio/")) mediaType = "voice";
+  else if (params.contentType.startsWith("video/")) mediaType = "video";
+
+  const mediaId = await uploadAgentApiMedia({
+    agent: params.agent,
+    type: mediaType,
+    buffer: params.buffer,
+    filename: params.filename,
+  });
+  await sendAgentApiMediaReply({
+    agent: params.agent,
+    target: params.target,
+    mediaId,
+    mediaType,
+    title: mediaType === "video" ? params.text?.trim().slice(0, 64) : undefined,
+    description: mediaType === "video" ? params.text?.trim().slice(0, 512) : undefined,
+  });
+}

package/src/transport/agent-api/media-upload.ts

@@ -0,0 +1,11 @@
+import type { ResolvedAgentAccount } from "../../types/index.js";
+import { uploadMedia as uploadLegacyMedia } from "./core.js";
+
+export async function uploadAgentApiMedia(params: {
+  agent: ResolvedAgentAccount;
+  type: "image" | "voice" | "video" | "file";
+  buffer: Buffer;
+  filename: string;
+}): Promise<string> {
+  return uploadLegacyMedia(params);
+}

package/src/transport/agent-api/reply.ts

@@ -0,0 +1,39 @@
+import type { ResolvedAgentAccount } from "../../types/index.js";
+import type { WecomTarget } from "../../target.js";
+import { sendAgentApiMedia, sendAgentApiText } from "./client.js";
+
+export async function sendAgentApiTextReply(params: {
+  agent: ResolvedAgentAccount;
+  target: WecomTarget;
+  text: string;
+}): Promise<void> {
+  await sendAgentApiText({
+    agent: params.agent,
+    toUser: params.target.touser,
+    toParty: params.target.toparty,
+    toTag: params.target.totag,
+    chatId: params.target.chatid,
+    text: params.text,
+  });
+}
+
+export async function sendAgentApiMediaReply(params: {
+  agent: ResolvedAgentAccount;
+  target: WecomTarget;
+  mediaId: string;
+  mediaType: "image" | "voice" | "video" | "file";
+  title?: string;
+  description?: string;
+}): Promise<void> {
+  await sendAgentApiMedia({
+    agent: params.agent,
+    toUser: params.target.touser,
+    toParty: params.target.toparty,
+    toTag: params.target.totag,
+    chatId: params.target.chatid,
+    mediaId: params.mediaId,
+    mediaType: params.mediaType,
+    title: params.title,
+    description: params.description,
+  });
+}

package/src/transport/agent-callback/http-handler.ts

@@ -0,0 +1,47 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+import type { WecomRuntimeEnv } from "../../types/runtime-context.js";
+import type { ResolvedAgentAccount } from "../../types/index.js";
+import type { WecomAccountRuntime } from "../../app/account-runtime.js";
+import { resolveAgentCallbackPaths } from "./inbound.js";
+import { createAgentCallbackSessionSnapshot } from "./session.js";
+import { registerAgentWebhookTarget } from "../http/registry.js";
+
+export function startAgentCallbackTransport(params: {
+  account: ResolvedAgentAccount;
+  cfg: OpenClawConfig;
+  runtime: WecomAccountRuntime;
+  runtimeEnv: WecomRuntimeEnv;
+}): { paths: string[]; stop: () => void } {
+  const paths = resolveAgentCallbackPaths(params.account.accountId);
+  params.runtime.updateTransportSession(
+    createAgentCallbackSessionSnapshot({
+      accountId: params.account.accountId,
+      running: true,
+    }),
+  );
+  const unregisters = paths.map((path) =>
+    registerAgentWebhookTarget({
+      agent: params.account,
+      config: params.cfg,
+      runtimeEnv: params.runtimeEnv,
+      touchTransportSession: (patch) => params.runtime.touchTransportSession("agent-callback", patch),
+      auditSink: (event) => params.runtime.recordOperationalIssue(event),
+      path,
+    }),
+  );
+  return {
+    paths,
+    stop: () => {
+      for (const unregister of unregisters) {
+        unregister();
+      }
+      params.runtime.updateTransportSession(
+        createAgentCallbackSessionSnapshot({
+          accountId: params.account.accountId,
+          running: false,
+        }),
+      );
+    },
+  };
+}

package/src/transport/agent-callback/inbound.ts

@@ -0,0 +1,5 @@
+import { resolveDerivedPathSummary } from "../../config/index.js";
+
+export function resolveAgentCallbackPaths(accountId: string): string[] {
+  return resolveDerivedPathSummary(accountId).agentCallback;
+}

package/src/transport/agent-callback/reply.ts

@@ -0,0 +1,13 @@
+import type { ReplyContext } from "../../types/index.js";
+
+export function createAgentCallbackReplyContext(params: {
+  accountId: string;
+  raw: ReplyContext["raw"];
+}): ReplyContext {
+  return {
+    transport: "agent-callback",
+    accountId: params.accountId,
+    passiveWindowMs: 5_000,
+    raw: params.raw,
+  };
+}