@zhin.js/adapter-weixin-ilink 3.0.2 → 4.0.0

package/src/index.ts

@@ -1,55 +1,26 @@
-/**
- * 微信 iLink（ClawBot）适配器入口
- */
-import path from "node:path";
-import { usePlugin, type Plugin } from "zhin.js";
-import type { Router } from "@zhin.js/host-router";
-import { PageManager } from "@zhin.js/host-api";
-import { WeixinIlinkAdapter } from "./adapter.js";
-import { registerRoutes } from "./routes.js";
+export {
+  formatInboundContent,
+  formatOutboundSegments,
+  inboundMessageId,
+  resolveWeixinIlinkConfig,
+  segmentLocalPath,
+  sleep,
+  type ResolvedWeixinIlinkConfig,
+  type WeixinIlinkAdapterConfig,
+  type WeixinIlinkEndpointConfig,
+  type WeixinInboundMediaPaths,
+  type WeixinMessageWithMedia,
+  type WeixinWireSegment,
+} from './protocol.js';
 
-declare module "zhin.js" {
-  namespace Plugin {
-    interface Contexts {
-      web: PageManager;
-      router: Router;
-    }
-  }
-  interface Adapters {
-    "weixin-ilink": WeixinIlinkAdapter;
-  }
-}
+export type { WeixinMessage, MessageItem } from './ilink-types.js';
+export type { WeixinIlinkCredentials } from './credentials.js';
 
-export * from "./types.js";
-export { WeixinIlinkEndpoint } from "./endpoint.js";
-export { WeixinIlinkAdapter } from "./adapter.js";
-export { registerLoginAssistRoutes } from "./login-assist-routes.js";
-
-const plugin = usePlugin();
-const { provide, useContext, root } = plugin;
-
-provide({
-  name: "weixin-ilink",
-  description: "WeChat personal account via Tencent iLink Endpoint API (ClawBot)",
-  mounted: async (p: Plugin) => {
-    const adapter = new WeixinIlinkAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: WeixinIlinkAdapter) => {
-    await adapter.stop();
-  },
-} as any);
-
-useContext("web", (pageManager) => {
-  pageManager.addEntry({
-    id: "weixin-ilink",
-    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-    production: path.resolve(import.meta.dirname, "../dist/index.js"),
-    meta: { name: "微信 iLink" },
-  });
-});
-
-useContext("router", "weixin-ilink", async (router: Router, adapter: WeixinIlinkAdapter) => {
-  registerRoutes(router, adapter, root);
-});
+export {
+  WeixinIlinkEndpoint,
+  type WeixinIlinkEndpointOptions,
+  type WeixinIlinkGetUpdates,
+  type WeixinIlinkNotifyStart,
+  type WeixinIlinkNotifyStop,
+  type WeixinIlinkSendText,
+} from './endpoint.js';

package/src/login.ts

@@ -1,15 +1,18 @@
-import type { Plugin } from "zhin.js";
-import { apiGetFetch, apiPostFetch } from "./ilink-api.js";
-import { buildBaseInfo, DEFAULT_API_BASE_URL } from "./ilink-meta.js";
-import { logger } from "./ilink-logger.js";
+/**
+ * Resolve iLink bot credentials (env / config / sidecar file / QR login).
+ * No legacy Plugin / loginAssist dependency — QR URL is logged for manual scan.
+ */
+import { apiGetFetch, apiPostFetch } from './ilink-api.js';
+import { buildBaseInfo, DEFAULT_API_BASE_URL } from './ilink-meta.js';
+import { logger } from './ilink-logger.js';
 import {
   loadCredentials,
   saveCredentials,
   type WeixinIlinkCredentials,
-} from "./credentials.js";
-import type { WeixinIlinkEndpointConfig } from "./types.js";
+} from './credentials.js';
+import type { ResolvedWeixinIlinkConfig } from './protocol.js';
 
-const DEFAULT_ILINK_BOT_TYPE = "3";
+const DEFAULT_ILINK_BOT_TYPE = '3';
 const QR_LONG_POLL_TIMEOUT_MS = 35_000;
 const LOGIN_TIMEOUT_MS = 480_000;
 
@@ -20,14 +23,14 @@ interface QRCodeResponse {
 
 interface StatusResponse {
   status:
-    | "wait"
-    | "scaned"
-    | "confirmed"
-    | "expired"
-    | "scaned_but_redirect"
-    | "need_verifycode"
-    | "verify_code_blocked"
-    | "binded_redirect";
+    | 'wait'
+    | 'scaned'
+    | 'confirmed'
+    | 'expired'
+    | 'scaned_but_redirect'
+    | 'need_verifycode'
+    | 'verify_code_blocked'
+    | 'binded_redirect';
   bot_token?: string;
   ilink_endpoint_id?: string;
   baseurl?: string;
@@ -44,7 +47,7 @@ async function fetchQRCode(apiBaseUrl: string, botType: string): Promise<QRCodeR
     baseUrl: apiBaseUrl,
     endpoint: `ilink/bot/get_bot_qrcode?bot_type=${encodeURIComponent(botType)}`,
     body: JSON.stringify({ local_token_list: getLocalBotTokenList(), base_info: buildBaseInfo() }),
-    label: "fetchQRCode",
+    label: 'fetchQRCode',
   });
   return JSON.parse(rawText) as QRCodeResponse;
 }
@@ -59,21 +62,20 @@ async function pollQRStatus(
       baseUrl: apiBaseUrl,
       endpoint,
       timeoutMs: QR_LONG_POLL_TIMEOUT_MS,
-      label: "pollQRStatus",
+      label: 'pollQRStatus',
     });
     return JSON.parse(rawText) as StatusResponse;
   } catch (err) {
-    if (err instanceof Error && err.name === "AbortError") {
-      return { status: "wait" };
+    if (err instanceof Error && err.name === 'AbortError') {
+      return { status: 'wait' };
     }
     logger.warn(`pollQRStatus error: ${String(err)}`);
-    return { status: "wait" };
+    return { status: 'wait' };
   }
 }
 
 export async function resolveCredentials(
-  plugin: Plugin,
-  config: WeixinIlinkEndpointConfig,
+  config: ResolvedWeixinIlinkConfig,
 ): Promise<WeixinIlinkCredentials> {
   const envToken = process.env.WEIXIN_ILINK_TOKEN?.trim() || config.botToken?.trim();
   if (envToken) {
@@ -94,73 +96,55 @@ export async function resolveCredentials(
     };
   }
 
-  return loginWithQr(plugin, config);
+  return loginWithQr(config);
 }
 
 export async function loginWithQr(
-  plugin: Plugin,
-  config: WeixinIlinkEndpointConfig,
+  config: ResolvedWeixinIlinkConfig,
 ): Promise<WeixinIlinkCredentials> {
   const apiBaseUrl = config.baseUrl ?? DEFAULT_API_BASE_URL;
   const qr = await fetchQRCode(apiBaseUrl, DEFAULT_ILINK_BOT_TYPE);
   const qrcodeUrl = qr.qrcode_img_content || qr.qrcode;
 
-  const loginAssist = plugin.inject("loginAssist");
-  if (!loginAssist) {
-    throw new Error("loginAssist 服务不可用，请确保已加载 zhin 核心服务");
-  }
-  void loginAssist.waitForInput("weixin-ilink", config.name, "qrcode", {
-    message: "请用微信扫描 ClawBot 二维码完成登录",
-    image: qrcodeUrl.startsWith("data:") ? qrcodeUrl : undefined,
-    url: qrcodeUrl.startsWith("http") ? qrcodeUrl : undefined,
-    qrcode: qr.qrcode,
-  });
-  const assistTask = loginAssist
-    .listPending()
-    .find((t) => t.adapter === "weixin-ilink" && t.endpointId === config.name);
+  logger.info(
+    `weixin-ilink QR login for ${config.name}: scan with WeChat ClawBot entry — ${qrcodeUrl.slice(0, 120)}${qrcodeUrl.length > 120 ? '…' : ''}`,
+  );
 
   const deadline = Date.now() + LOGIN_TIMEOUT_MS;
   let currentBaseUrl = apiBaseUrl;
 
-  try {
-    while (Date.now() < deadline) {
-      const status = await pollQRStatus(currentBaseUrl, qr.qrcode);
+  while (Date.now() < deadline) {
+    const status = await pollQRStatus(currentBaseUrl, qr.qrcode);
 
-      if (status.status === "scaned_but_redirect" && status.redirect_host) {
-        currentBaseUrl = status.redirect_host.startsWith("http")
-          ? status.redirect_host
-          : `https://${status.redirect_host}`;
-      }
+    if (status.status === 'scaned_but_redirect' && status.redirect_host) {
+      currentBaseUrl = status.redirect_host.startsWith('http')
+        ? status.redirect_host
+        : `https://${status.redirect_host}`;
+    }
 
-      if (status.status === "confirmed" || status.status === "binded_redirect") {
-        if (!status.bot_token && status.status !== "binded_redirect") {
-          throw new Error("扫码成功但未返回 bot_token");
-        }
-        const creds: WeixinIlinkCredentials = {
-          botToken: status.bot_token ?? loadCredentials(config.name)?.botToken ?? "",
-          ilinkUserId: status.ilink_user_id,
-          ilinkBotId: status.ilink_endpoint_id,
-          baseUrl: status.baseurl ?? currentBaseUrl,
-        };
-        if (!creds.botToken) {
-          throw new Error("binded_redirect 但本地无有效 bot_token");
-        }
-        saveCredentials(config.name, creds);
-        if (assistTask) loginAssist.submit(assistTask.id, "confirmed");
-        return creds;
+    if (status.status === 'confirmed' || status.status === 'binded_redirect') {
+      if (!status.bot_token && status.status !== 'binded_redirect') {
+        throw new Error('扫码成功但未返回 bot_token');
       }
-
-      if (status.status === "expired") {
-        if (assistTask) loginAssist.cancel(assistTask.id, "expired");
-        throw new Error("二维码已过期，请重启 bot 重新登录");
+      const creds: WeixinIlinkCredentials = {
+        botToken: status.bot_token ?? loadCredentials(config.name)?.botToken ?? '',
+        ilinkUserId: status.ilink_user_id,
+        ilinkBotId: status.ilink_endpoint_id,
+        baseUrl: status.baseurl ?? currentBaseUrl,
+      };
+      if (!creds.botToken) {
+        throw new Error('binded_redirect 但本地无有效 bot_token');
       }
+      saveCredentials(config.name, creds);
+      return creds;
+    }
 
-      await new Promise((r) => setTimeout(r, 500));
+    if (status.status === 'expired') {
+      throw new Error('二维码已过期，请重启 bot 重新登录');
     }
-    if (assistTask) loginAssist.cancel(assistTask.id, "timeout");
-    throw new Error("微信扫码登录超时");
-  } catch (err) {
-    if (assistTask) loginAssist.cancel(assistTask.id, String(err));
-    throw err;
+
+    await new Promise((r) => setTimeout(r, 500));
   }
+
+  throw new Error('微信扫码登录超时');
 }

package/src/outbound-media.ts

@@ -1,92 +1,98 @@
 /**
  * 微信 iLink 出站媒体：base64 / 远程 URL 须落盘后再走 CDN 上传。
  */
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import type { MessageSegment, SendContent } from "zhin.js";
-import { downloadRemoteImageToTemp } from "./upload.js";
-import { getExtensionFromMime } from "./mime.js";
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { downloadRemoteImageToTemp } from './upload.js';
+import { getExtensionFromMime } from './mime.js';
+import type { WeixinWireSegment } from './protocol.js';
 
-const MEDIA_TYPES = new Set(["image", "video", "file", "record", "audio"]);
+const MEDIA_TYPES = new Set(['image', 'video', 'file', 'record', 'audio']);
+
+export type OutboundWireContent = string | WeixinWireSegment | ReadonlyArray<string | WeixinWireSegment>;
 
 function isRemoteUrl(value: string): boolean {
   return /^https?:\/\//i.test(value);
 }
 
 function isInlineMediaRef(value: string): boolean {
-  return value.startsWith("base64://") || /^data:[^/]+\/[^;]+;base64,/i.test(value);
+  return value.startsWith('base64://') || /^data:[^/]+\/[^;]+;base64,/i.test(value);
 }
 
 function normalizeLocalPath(value: string): string {
-  return value.replace(/^file:\/\//, "");
+  return value.replace(/^file:\/\//, '');
 }
 
-export function segmentMediaRef(seg: MessageSegment): string | undefined {
-  const data = seg.data as Record<string, unknown>;
-  const candidates = [data.file, data.path, data.url].filter((v): v is string => typeof v === "string" && Boolean(v));
+export function segmentMediaRef(seg: WeixinWireSegment): string | undefined {
+  const data = seg.data as Record<string, unknown> | undefined;
+  if (!data) return undefined;
+  const candidates = [data.file, data.path, data.url].filter(
+    (v): v is string => typeof v === 'string' && Boolean(v),
+  );
   return candidates[0];
 }
 
 function extractBase64Buffer(data: Record<string, unknown>): Buffer | undefined {
-  const url = typeof data.url === "string" ? data.url : undefined;
-  const file = typeof data.file === "string" ? data.file : undefined;
-  const base64 = typeof data.base64 === "string" ? data.base64 : undefined;
+  const url = typeof data.url === 'string' ? data.url : undefined;
+  const file = typeof data.file === 'string' ? data.file : undefined;
+  const base64 = typeof data.base64 === 'string' ? data.base64 : undefined;
 
-  if (url?.startsWith("base64://")) {
-    return Buffer.from(url.slice(9), "base64");
+  if (url?.startsWith('base64://')) {
+    return Buffer.from(url.slice(9), 'base64');
   }
   if (url && /^data:[^/]+\/[^;]+;base64,/i.test(url)) {
-    return Buffer.from(url.replace(/^data:[^/]+\/[^;]+;base64,/, ""), "base64");
+    return Buffer.from(url.replace(/^data:[^/]+\/[^;]+;base64,/, ''), 'base64');
   }
-  if (file?.startsWith("base64://")) {
-    return Buffer.from(file.slice(9), "base64");
+  if (file?.startsWith('base64://')) {
+    return Buffer.from(file.slice(9), 'base64');
   }
   if (base64) {
-    const raw = base64.startsWith("base64://") ? base64.slice(9) : base64;
-    return Buffer.from(raw, "base64");
+    const raw = base64.startsWith('base64://') ? base64.slice(9) : base64;
+    return Buffer.from(raw, 'base64');
   }
   return undefined;
 }
 
-function resolveExt(seg: MessageSegment, mime?: string): string {
-  const data = seg.data as Record<string, unknown>;
-  const name = typeof data.name === "string" ? data.name : undefined;
+function resolveExt(seg: WeixinWireSegment, mime?: string): string {
+  const data = (seg.data ?? {}) as Record<string, unknown>;
+  const name = typeof data.name === 'string' ? data.name : undefined;
   if (name) {
     const ext = path.extname(name);
     if (ext) return ext;
   }
-  const mimeHint = mime ?? (typeof data.mime === "string" ? data.mime : typeof data.mimeType === "string" ? data.mimeType : undefined);
+  const mimeHint = mime
+    ?? (typeof data.mime === 'string' ? data.mime : typeof data.mimeType === 'string' ? data.mimeType : undefined);
   if (mimeHint) {
-    return getExtensionFromMime(mimeHint) ?? ".bin";
+    return getExtensionFromMime(mimeHint) ?? '.bin';
   }
-  if (seg.type === "image") return ".png";
-  if (seg.type === "video") return ".mp4";
-  if (seg.type === "record" || seg.type === "audio") return ".mp3";
-  return ".bin";
+  if (seg.type === 'image') return '.png';
+  if (seg.type === 'video') return '.mp4';
+  if (seg.type === 'record' || seg.type === 'audio') return '.mp3';
+  return '.bin';
 }
 
-function withLocalFile(seg: MessageSegment, filePath: string): MessageSegment {
-  const data = { ...seg.data, file: filePath } as Record<string, unknown>;
+function withLocalFile(seg: WeixinWireSegment, filePath: string): WeixinWireSegment {
+  const data = { ...(seg.data ?? {}), file: filePath } as Record<string, unknown>;
   delete data.base64;
-  return { type: seg.type, data } as MessageSegment;
+  return { type: seg.type, data };
 }
 
-function writeOutboundBuffer(buffer: Buffer, outboundDir: string, seg: MessageSegment): string {
+function writeOutboundBuffer(buffer: Buffer, outboundDir: string, seg: WeixinWireSegment): string {
   fs.mkdirSync(outboundDir, { recursive: true });
   const ext = resolveExt(seg);
   const filePath = path.join(
     outboundDir,
-    `out-${seg.type}-${Date.now()}-${crypto.randomBytes(4).toString("hex")}${ext}`,
+    `out-${seg.type}-${Date.now()}-${crypto.randomBytes(4).toString('hex')}${ext}`,
   );
   fs.writeFileSync(filePath, buffer);
   return filePath;
 }
 
 async function materializeSegment(
-  seg: MessageSegment,
+  seg: WeixinWireSegment,
   outboundDir: string,
-): Promise<MessageSegment> {
+): Promise<WeixinWireSegment> {
   if (!MEDIA_TYPES.has(seg.type)) return seg;
 
   const ref = segmentMediaRef(seg);
@@ -101,7 +107,7 @@ async function materializeSegment(
     }
   }
 
-  const buffer = extractBase64Buffer(seg.data as Record<string, unknown>);
+  const buffer = extractBase64Buffer((seg.data ?? {}) as Record<string, unknown>);
   if (buffer) {
     return withLocalFile(seg, writeOutboundBuffer(buffer, outboundDir, seg));
   }
@@ -109,30 +115,30 @@ async function materializeSegment(
   return seg;
 }
 
-function asSegments(content: SendContent): MessageSegment[] {
-  if (typeof content === "string") {
-    return [{ type: "text", data: { text: content } }];
+function asSegments(content: OutboundWireContent): WeixinWireSegment[] {
+  if (typeof content === 'string') {
+    return [{ type: 'text', data: { text: content } }];
   }
   if (!Array.isArray(content)) {
-    return typeof content === "object" && content !== null && "type" in content
-      ? [content as MessageSegment]
+    return typeof content === 'object' && content !== null && 'type' in content
+      ? [content]
       : [];
   }
   return content.flatMap((item) => {
-    if (typeof item === "string") return [{ type: "text", data: { text: item } } as MessageSegment];
-    return typeof item === "object" && item !== null && "type" in item ? [item as MessageSegment] : [];
+    if (typeof item === 'string') return [{ type: 'text', data: { text: item } }];
+    return typeof item === 'object' && item !== null && 'type' in item ? [item] : [];
   });
 }
 
 /** 将 base64 / 远程图落盘，供 sendWeixinMediaFile 上传 */
 export async function materializeOutboundMedia(
-  content: SendContent,
+  content: OutboundWireContent,
   outboundDir: string,
-): Promise<SendContent> {
+): Promise<OutboundWireContent> {
   const segments = asSegments(content);
   const out = await Promise.all(segments.map((seg) => materializeSegment(seg, outboundDir)));
-  if (typeof content === "string") {
-    return out[0]?.type === "text" ? (out[0].data as { text: string }).text : content;
+  if (typeof content === 'string') {
+    return out[0]?.type === 'text' ? String((out[0].data as { text?: string })?.text ?? content) : content;
   }
   if (!Array.isArray(content)) {
     return out[0] ?? content;

package/src/protocol.ts

@@ -0,0 +1,172 @@
+/**
+ * Weixin iLink protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+
+import { pickCredential } from '@zhin.js/adapter';
+import { bodyFromItemList, isMediaItem } from './weixin-inbound.js';
+import { DEFAULT_API_BASE_URL, DEFAULT_CDN_BASE_URL } from './ilink-meta.js';
+import type { WeixinMessage } from './ilink-types.js';
+
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface WeixinIlinkAdapterConfig {
+  readonly name?: string;
+  readonly botAgent?: string;
+  readonly baseUrl?: string;
+  readonly cdnBaseUrl?: string;
+  readonly longPollTimeoutMs?: number;
+  readonly botToken?: string;
+  /** Transitional: legacy root `endpoints[]` with `context: weixin-ilink`. */
+  readonly endpoints?: ReadonlyArray<Partial<ResolvedWeixinIlinkConfig> & {
+    readonly context?: string;
+  }>;
+}
+
+export interface ResolvedWeixinIlinkConfig {
+  readonly context: 'weixin-ilink';
+  readonly name: string;
+  readonly botAgent?: string;
+  readonly baseUrl: string;
+  readonly cdnBaseUrl: string;
+  readonly longPollTimeoutMs: number;
+  readonly botToken?: string;
+}
+
+export type WeixinIlinkEndpointConfig = ResolvedWeixinIlinkConfig;
+
+export interface WeixinWireSegment {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface WeixinInboundMediaPaths {
+  readonly decryptedPicPath?: string;
+  readonly decryptedVideoPath?: string;
+  readonly decryptedFilePath?: string;
+  readonly decryptedVoicePath?: string;
+}
+
+export type WeixinMessageWithMedia = WeixinMessage & {
+  readonly _media?: WeixinInboundMediaPaths;
+};
+
+const DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000;
+
+export function resolveWeixinIlinkConfig(
+  config: WeixinIlinkAdapterConfig = {},
+): ResolvedWeixinIlinkConfig {
+  const entry = config.endpoints?.find((item) => item.context === 'weixin-ilink');
+  const name = (typeof config.name === 'string' && config.name)
+    || (typeof entry?.name === 'string' && entry.name)
+    || process.env.WEIXIN_ILINK_BOT_NAME
+    || 'weixin-ilink-bot';
+  const botToken = pickCredential(
+    typeof config.botToken === 'string' ? config.botToken.trim() : config.botToken,
+    typeof entry?.botToken === 'string' ? entry.botToken.trim() : entry?.botToken,
+    process.env.WEIXIN_ILINK_TOKEN?.trim(),
+  );
+  // No throw here: missing botToken is resolved later by resolveCredentials()
+  // (sidecar credentials file / QR login) during endpoint.start().
+  return {
+    context: 'weixin-ilink',
+    name,
+    botAgent: config.botAgent ?? entry?.botAgent,
+    baseUrl: config.baseUrl ?? entry?.baseUrl ?? DEFAULT_API_BASE_URL,
+    cdnBaseUrl: config.cdnBaseUrl ?? entry?.cdnBaseUrl ?? DEFAULT_CDN_BASE_URL,
+    longPollTimeoutMs: config.longPollTimeoutMs
+      ?? entry?.longPollTimeoutMs
+      ?? DEFAULT_LONG_POLL_TIMEOUT_MS,
+    botToken,
+  };
+}
+
+/** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
+export function formatInboundContent(msg: WeixinMessageWithMedia): string {
+  const parts: string[] = [];
+  const text = bodyFromItemList(msg.item_list);
+  if (text) parts.push(text);
+
+  const media = msg._media;
+  if (media?.decryptedPicPath) {
+    parts.push(`[image: ${media.decryptedPicPath}]`);
+  } else if (media?.decryptedVideoPath) {
+    parts.push(`[video: ${media.decryptedVideoPath}]`);
+  } else if (media?.decryptedFilePath) {
+    parts.push(`[file: ${media.decryptedFilePath}]`);
+  } else if (media?.decryptedVoicePath) {
+    parts.push(`[record: ${media.decryptedVoicePath}]`);
+  } else if (!text && msg.item_list?.some((item) => isMediaItem(item))) {
+    parts.push('[媒体消息]');
+  }
+
+  return parts.join('\n').trim() || '';
+}
+
+export function inboundMessageId(msg: WeixinMessage): string {
+  return String(msg.message_id ?? msg.client_id ?? msg.seq ?? Date.now());
+}
+
+/**
+ * Wire-encode an already-rendered outbound payload into Weixin wire segments.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundSegments(payload: unknown): WeixinWireSegment[] {
+  if (typeof payload === 'string') {
+    return [{ type: 'text', data: { text: payload } }];
+  }
+
+  const items: Array<string | WeixinWireSegment> = Array.isArray(payload)
+    ? payload as Array<string | WeixinWireSegment>
+    : payload && typeof payload === 'object' && 'type' in (payload as object)
+      ? [payload as WeixinWireSegment]
+      : [];
+
+  if (items.length === 0) {
+    const text = payload == null
+      ? ''
+      : typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : String(payload);
+    return [{ type: 'text', data: { text } }];
+  }
+
+  const segs: WeixinWireSegment[] = [];
+  for (const item of items) {
+    if (typeof item === 'string') {
+      segs.push({ type: 'text', data: { text: item } });
+      continue;
+    }
+    segs.push({ type: item.type, data: item.data ?? {} });
+  }
+  return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
+}
+
+export function segmentLocalPath(seg: WeixinWireSegment): string | undefined {
+  const data = seg.data ?? {};
+  const candidates = [data.file, data.path, data.url].filter(
+    (value): value is string => typeof value === 'string' && Boolean(value),
+  );
+  const ref = candidates[0];
+  if (!ref || ref.startsWith('base64://') || /^data:/.test(ref) || /^https?:\/\//i.test(ref)) {
+    return undefined;
+  }
+  return ref.replace(/^file:\/\//, '');
+}
+
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}

package/src/types.ts

@@ -1,16 +1,7 @@
-export interface WeixinIlinkEndpointConfig {
-  context: "weixin-ilink";
-  name: string;
-  /** 观测用 bot_agent，默认 Zhin.js/<version> */
-  botAgent?: string;
-  /** iLink API 根地址，默认 https://ilinkai.weixin.qq.com */
-  baseUrl?: string;
-  /** CDN 根地址 */
-  cdnBaseUrl?: string;
-  /** 长轮询超时（ms），默认 35000 */
-  longPollTimeoutMs?: number;
-  /** 直接配置 token（优先于侧车凭证文件） */
-  botToken?: string;
-}
+export type {
+  WeixinIlinkEndpointConfig,
+  WeixinIlinkAdapterConfig,
+  ResolvedWeixinIlinkConfig,
+} from './protocol.js';
 
-export type { WeixinMessage, MessageItem } from "./ilink-types.js";
+export type { WeixinMessage, MessageItem } from './ilink-types.js';