@wwlocal/aibot-plugin-node 20260409.20.0

package/dist/esm/types/src/dm-policy.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DM（私聊）访问控制模块
+ *
+ * 仅保留 open/allowlist/disabled 三种策略，不包含 OpenClaw 的 pairing 机制
+ */
+import type { RuntimeLogger, ResolvedAccount } from "./interface.js";
+import type { WSClient, WsFrame } from "@wecom/aibot-node-sdk";
+export interface DmPolicyCheckResult {
+    /** 是否允许继续处理消息 */
+    allowed: boolean;
+}
+/**
+ * 检查 DM Policy 访问控制
+ *
+ * 策略说明：
+ * - open: 允许所有人私聊
+ * - allowlist: 仅允许白名单中的用户私聊
+ * - disabled: 禁用所有私聊
+ */
+export declare function checkDmPolicy(params: {
+    senderId: string;
+    isGroup: boolean;
+    account: ResolvedAccount;
+    wsClient: WSClient;
+    frame: WsFrame;
+    runtime: RuntimeLogger;
+}): Promise<DmPolicyCheckResult>;

package/dist/esm/types/src/group-policy.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 群组访问控制模块
+ *
+ * 负责群组策略检查（groupPolicy、群组白名单、群内发送者白名单）
+ * 使用独立配置类型，不依赖 OpenClaw
+ */
+import type { RuntimeLogger, ResolvedAccount } from "./interface.js";
+export interface GroupPolicyCheckResult {
+    /** 是否允许继续处理消息 */
+    allowed: boolean;
+}
+/**
+ * 检查群组策略访问控制
+ *
+ * 两层检查：
+ * 1. 群组白名单（groupAllowFrom）
+ * 2. 每群发送者白名单（groups[chatId].allowFrom）
+ */
+export declare function checkGroupPolicy(params: {
+    chatId: string;
+    senderId: string;
+    account: ResolvedAccount;
+    runtime: RuntimeLogger;
+}): GroupPolicyCheckResult;
+/**
+ * 检查发送者是否在允许列表中（通用）
+ */
+export declare function isSenderAllowed(senderId: string, allowFrom: string[]): boolean;

package/dist/esm/types/src/interface.d.ts

@@ -0,0 +1,332 @@
+/**
+ * 企业微信私有部署 AI 机器人插件类型定义
+ */
+import { WeComCommand } from "./const.js";
+/**
+ * 运行时日志接口
+ * 用于统一日志输出，替代 OpenClaw 的 RuntimeEnv
+ */
+export interface RuntimeLogger {
+    log?: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+}
+/** 智能体端点配置 */
+export interface AgentEndpoint {
+    /** 端点名称（用于路由选择） */
+    name: string;
+    /** 适配器类型：openai / deepseek / anthropic / dify / webhook（默认 openai） */
+    provider?: string;
+    /** API URL (如 https://api.openai.com/v1/chat/completions) */
+    url: string;
+    /** API Key */
+    apiKey?: string;
+    /** 模型名称 */
+    model?: string;
+    /** 自定义请求头 */
+    headers?: Record<string, string>;
+    /** 是否启用流式 (默认 true) */
+    stream?: boolean;
+    /** 系统提示词 */
+    systemPrompt?: string;
+    /** 请求超时 (毫秒，默认 300000) */
+    timeoutMs?: number;
+    /** 多轮对话最大保留轮数（0 = 禁用对话记忆，默认 20） */
+    maxHistoryRounds?: number;
+    /** 适配器专属扩展配置 */
+    providerOptions?: Record<string, unknown>;
+}
+/** 企微账号配置 */
+export interface AccountConfig {
+    /** 账号 ID（用于内部标识，默认为 botId） */
+    accountId?: string;
+    /** 账号名称（可选，用于日志显示） */
+    name?: string;
+    /** 是否启用（默认 true） */
+    enabled?: boolean;
+    /** WebSocket 连接地址 */
+    websocketUrl: string;
+    /** 机器人 ID */
+    botId: string;
+    /** 机器人密钥 */
+    secret: string;
+    /** CA 证书文件路径（PEM 格式，用于私有化部署自签名证书） */
+    caCert?: string;
+    /** 是否在智能体响应前发送"思考中"消息（默认 true） */
+    sendThinkingMessage?: boolean;
+    /** 私聊策略：open=全部允许, allowlist=白名单, disabled=禁用 */
+    dmPolicy?: "open" | "allowlist" | "disabled";
+    /** 私聊白名单（userid 列表，dmPolicy=allowlist 时生效） */
+    allowFrom?: string[];
+    /** 群组策略：open=全部允许, allowlist=白名单, disabled=禁用 */
+    groupPolicy?: "open" | "allowlist" | "disabled";
+    /** 群组白名单（chatid 列表，groupPolicy=allowlist 时生效） */
+    groupAllowFrom?: string[];
+    /** 每群发送者白名单 */
+    groups?: Record<string, {
+        allowFrom?: string[];
+    }>;
+    /** 允许读取本地媒体文件的根目录列表 */
+    mediaLocalRoots?: string[];
+    /** 指定使用的智能体端点名称（默认使用第一个） */
+    agentName?: string;
+}
+/** 插件配置 */
+export interface PluginConfig {
+    /** HTTP 服务端口 (默认 3000) */
+    port?: number;
+    /** 数据存储目录（媒体文件等，默认 ./data） */
+    dataDir?: string;
+    /** 智能体端点列表 */
+    agents: AgentEndpoint[];
+    /** 企微账号列表 */
+    accounts: AccountConfig[];
+}
+/**
+ * Monitor 配置选项
+ */
+export interface MonitorOptions {
+    /** 企微账号配置（已解析） */
+    account: ResolvedAccount;
+    /** 插件配置 */
+    config: PluginConfig;
+    /** 运行时日志 */
+    runtime: RuntimeLogger;
+    /** 中止信号 */
+    abortSignal?: AbortSignal;
+    /** 状态更新回调 */
+    setStatus?: (next: Record<string, unknown>) => void;
+}
+/** 已解析的账号配置（带默认值和智能体端点引用） */
+export interface ResolvedAccount extends Required<Pick<AccountConfig, "accountId" | "websocketUrl" | "botId" | "secret">> {
+    name: string;
+    enabled: boolean;
+    caCert?: string;
+    sendThinkingMessage: boolean;
+    dmPolicy: "open" | "allowlist" | "disabled";
+    allowFrom: string[];
+    groupPolicy: "open" | "allowlist" | "disabled";
+    groupAllowFrom: string[];
+    groups: Record<string, {
+        allowFrom?: string[];
+    }>;
+    mediaLocalRoots: string[];
+    /** 解析后的智能体端点 */
+    agent: AgentEndpoint;
+}
+/**
+ * 消息状态
+ */
+export interface MessageState {
+    accumulatedText: string;
+    /** 流式回复的 streamId */
+    streamId?: string;
+    /** 是否已成功发送过媒体文件 */
+    hasMedia?: boolean;
+    /** 是否有媒体发送失败 */
+    hasMediaFailed?: boolean;
+    /** 媒体发送失败时的纯文本错误摘要 */
+    mediaErrorSummary?: string;
+    /** deliver 回调是否被调用过 */
+    deliverCalled?: boolean;
+    /** 流式回复是否已过期（errcode 846608） */
+    streamExpired?: boolean;
+    /** 是否已成功发送过模板卡片 */
+    hasTemplateCard?: boolean;
+}
+/** 从文本中提取的模板卡片 */
+export interface ExtractedTemplateCard {
+    /** 原始 JSON 对象（已验证 card_type 合法） */
+    cardJson: Record<string, unknown>;
+    /** card_type 值 */
+    cardType: string;
+}
+/** extractTemplateCards 返回值 */
+export interface TemplateCardExtractionResult {
+    /** 提取到的合法模板卡片列表 */
+    cards: ExtractedTemplateCard[];
+    /** 移除卡片代码块后的剩余文本 */
+    remainingText: string;
+}
+/**
+ * WebSocket 请求消息基础格式
+ */
+export interface WeComRequest {
+    cmd: string;
+    headers: {
+        req_id: string;
+    };
+    body: any;
+}
+/**
+ * WebSocket 响应消息格式
+ */
+export interface WeComResponse {
+    headers: {
+        req_id: string;
+    };
+    errcode: number;
+    errmsg: string;
+}
+/**
+ * 企业微信私有部署认证请求
+ */
+export interface WeComSubscribeRequest extends WeComRequest {
+    cmd: WeComCommand.SUBSCRIBE;
+    body: {
+        secret: string;
+        bot_id: string;
+    };
+}
+/**
+ * 企业微信私有部署推送消息格式
+ */
+export interface WeComCallbackMessage {
+    cmd: WeComCommand.AIBOT_CALLBACK | "aibot_event_callback";
+    headers: {
+        req_id: string;
+    };
+    body: {
+        msgid: string;
+        aibotid: string;
+        chatid?: string;
+        chattype: "single" | "group";
+        from: {
+            userid: string;
+        };
+        response_url: string;
+        msgtype: "text" | "image" | "voice" | "video" | "file" | "stream" | "mixed" | "event";
+        text?: {
+            content: string;
+        };
+        image?: {
+            url?: string;
+            base64?: string;
+            md5?: string;
+        };
+        mixed?: {
+            msg_item: Array<{
+                msgtype: "text" | "image";
+                text?: {
+                    content: string;
+                };
+                image?: {
+                    url?: string;
+                    base64?: string;
+                    md5?: string;
+                };
+            }>;
+        };
+        quote?: {
+            msgtype: string;
+            text?: {
+                content: string;
+            };
+            image?: {
+                url?: string;
+                aeskey?: string;
+            };
+            file?: {
+                url?: string;
+                aeskey?: string;
+            };
+        };
+        stream?: {
+            id: string;
+        };
+        event?: {
+            eventtype: string;
+            template_card_event?: {
+                card_type?: string;
+                event_key?: string;
+                task_id?: string;
+                selected_items?: {
+                    selected_item?: Array<{
+                        question_key?: string;
+                        option_ids?: {
+                            option_id?: string[];
+                        };
+                    }>;
+                };
+            };
+        };
+    };
+}
+/**
+ * 企业微信私有部署响应消息格式
+ */
+export interface WeComResponseMessage extends WeComRequest {
+    cmd: WeComCommand.AIBOT_RESPONSE;
+    body: {
+        msgtype: "stream" | "text" | "markdown";
+        stream?: {
+            id: string;
+            finish: boolean;
+            content: string;
+            msg_item?: Array<{
+                msgtype: "image" | "file";
+                image?: {
+                    base64: string;
+                    md5: string;
+                };
+            }>;
+            feedback?: {
+                id: string;
+            };
+        };
+        text?: {
+            content: string;
+        };
+        markdown?: {
+            content: string;
+        };
+    };
+}
+/** deliver 回调参数 */
+export interface DeliverPayload {
+    text?: string;
+    mediaUrl?: string;
+    mediaUrls?: string[];
+}
+/** deliver 回调信息 */
+export interface DeliverInfo {
+    kind: "block" | "final";
+}
+/** 智能体转发选项 */
+export interface ForwardOptions {
+    /** 消息文本 */
+    text: string;
+    /** 媒体文件路径列表 */
+    mediaPaths?: Array<{
+        path: string;
+        contentType?: string;
+    }>;
+    /** 引用内容 */
+    quoteContent?: string;
+    /** 智能体端点配置 */
+    agent: AgentEndpoint;
+    /** deliver 回调 */
+    deliver: (payload: DeliverPayload, info: DeliverInfo) => Promise<void>;
+    /** 回复开始回调 */
+    onReplyStart?: () => Promise<void>;
+    /** 错误回调 */
+    onError?: (err: Error, info: {
+        kind: string;
+    }) => void;
+    /** 中止信号 */
+    abortSignal?: AbortSignal;
+    /** 运行时日志 */
+    runtime?: RuntimeLogger;
+    /** 扩展上下文（适配器可按需使用，如 Dify 的会话管理） */
+    context?: {
+        /** 账号 ID（用于会话隔离，防止多账号历史串联） */
+        accountId?: string;
+        /** 企微用户 ID */
+        userId?: string;
+        /** 企微聊天 ID */
+        chatId?: string;
+        /** 聊天类型 */
+        chatType?: "single" | "group";
+        /** 其他自定义字段 */
+        [key: string]: unknown;
+    };
+}

package/dist/esm/types/src/media-handler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 入站媒体（图片/文件）下载和保存模块
+ *
+ * 负责下载、检测格式、保存媒体到本地文件系统
+ * 替代 OpenClaw 的 core.channel.media.saveMediaBuffer 和 fetchRemoteMedia
+ */
+import type { WSClient } from "@wecom/aibot-node-sdk";
+import type { RuntimeLogger, ResolvedAccount, PluginConfig } from "./interface.js";
+/**
+ * 下载并保存所有图片到本地
+ */
+export declare function downloadAndSaveImages(params: {
+    imageUrls: string[];
+    imageAesKeys?: Map<string, string>;
+    account: ResolvedAccount;
+    config: PluginConfig;
+    runtime: RuntimeLogger;
+    wsClient: WSClient;
+}): Promise<Array<{
+    path: string;
+    contentType?: string;
+}>>;
+/**
+ * 下载并保存所有文件到本地
+ */
+export declare function downloadAndSaveFiles(params: {
+    fileUrls: string[];
+    fileAesKeys?: Map<string, string>;
+    account: ResolvedAccount;
+    config: PluginConfig;
+    runtime: RuntimeLogger;
+    wsClient: WSClient;
+}): Promise<Array<{
+    path: string;
+    contentType?: string;
+}>>;

package/dist/esm/types/src/media-loader.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 出站媒体文件加载器
+ *
+ * 内联 openclaw-compat.ts 的 fallback 实现：
+ * - loadOutboundMediaFromUrl（支持远程 URL 和本地文件）
+ * - detectMime（buffer 嗅探 + 扩展名映射）
+ * - assertLocalMediaAllowed（安全白名单检查）
+ *
+ * 不再有 OpenClaw SDK 探测逻辑，直接使用独立实现。
+ */
+/** 媒体加载结果 */
+export type WebMediaResult = {
+    buffer: Buffer;
+    contentType?: string;
+    kind?: string;
+    fileName?: string;
+};
+export type OutboundMediaLoadOptions = {
+    maxBytes?: number;
+    mediaLocalRoots?: readonly string[];
+};
+export type DetectMimeOptions = {
+    buffer?: Buffer;
+    headerMime?: string | null;
+    filePath?: string;
+};
+/**
+ * 检测 MIME 类型
+ *
+ * 支持两种调用签名：
+ * - detectMime(buffer)           → 仅 buffer 嗅探
+ * - detectMime({ buffer, headerMime, filePath }) → 完整参数
+ */
+export declare function detectMime(bufferOrOpts: Buffer | DetectMimeOptions): Promise<string | undefined>;
+/**
+ * 校验本地媒体文件路径是否在允许的根目录列表内
+ */
+export declare function assertLocalMediaAllowed(mediaPath: string, localRoots: readonly string[] | undefined): Promise<void>;
+/**
+ * 从 URL 或本地路径加载媒体文件
+ *
+ * 支持：
+ * - 远程 URL (http:// / https://)
+ * - 本地文件路径 (file:// 或绝对路径)
+ * - ~ 路径展开
+ */
+export declare function loadOutboundMediaFromUrl(mediaUrl: string, options?: OutboundMediaLoadOptions): Promise<WebMediaResult>;

package/dist/esm/types/src/media-storage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 本地文件媒体存储模块
+ *
+ * 替代 OpenClaw 的 core.channel.media.saveMediaBuffer
+ * 将媒体文件存储到本地文件系统，按日期/方向/类型组织目录
+ */
+export interface SaveMediaResult {
+    /** 存储的文件路径 */
+    path: string;
+    /** 检测到的内容类型 */
+    contentType: string;
+    /** 文件名 */
+    fileName: string;
+}
+/**
+ * 将媒体文件保存到本地文件系统
+ *
+ * 存储路径: {dataDir}/media/{direction}/{YYYY-MM-DD}/{filename}
+ *
+ * @param buffer - 文件数据
+ * @param contentType - 内容类型（如 image/jpeg）
+ * @param direction - 方向：inbound（入站）或 outbound（出站）
+ * @param maxBytes - 最大字节数限制
+ * @param originalFilename - 原始文件名（可选）
+ * @param dataDir - 数据目录路径
+ * @returns 保存结果
+ */
+export declare function saveMediaBuffer(buffer: Buffer, contentType: string, direction: "inbound" | "outbound", maxBytes: number, originalFilename: string | undefined, dataDir: string): Promise<SaveMediaResult>;
+/**
+ * 从本地路径加载媒体文件
+ *
+ * @param filePath - 文件路径
+ * @returns 文件 buffer
+ */
+export declare function loadLocalMedia(filePath: string): Buffer;

package/dist/esm/types/src/media-uploader.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 出站媒体上传工具模块
+ *
+ * 负责：
+ * - 从 mediaUrl 加载文件 buffer（远程 URL 或本地路径均支持）
+ * - 检测 MIME 类型并映射为企微媒体类型
+ * - 文件大小检查与降级策略
+ * - 分片上传 + 发送
+ */
+import type { WeComMediaType, WSClient, WsFrameHeaders } from "@wecom/aibot-node-sdk";
+/** 媒体文件解析结果 */
+export interface ResolvedMedia {
+    buffer: Buffer;
+    contentType: string;
+    fileName: string;
+}
+/** 文件大小检查结果 */
+export interface FileSizeCheckResult {
+    finalType: WeComMediaType;
+    shouldReject: boolean;
+    rejectReason?: string;
+    downgraded: boolean;
+    downgradeNote?: string;
+}
+export declare function detectWeComMediaType(mimeType: string): WeComMediaType;
+export declare function resolveMediaFile(mediaUrl: string, mediaLocalRoots?: readonly string[]): Promise<ResolvedMedia>;
+export declare function applyFileSizeLimits(fileSize: number, detectedType: WeComMediaType, contentType?: string): FileSizeCheckResult;
+export interface UploadAndSendMediaOptions {
+    wsClient: WSClient;
+    mediaUrl: string;
+    chatId: string;
+    mediaLocalRoots?: readonly string[];
+    log?: (...args: any[]) => void;
+    errorLog?: (...args: any[]) => void;
+}
+export interface UploadAndSendMediaResult {
+    ok: boolean;
+    messageId?: string;
+    finalType?: WeComMediaType;
+    rejected?: boolean;
+    rejectReason?: string;
+    downgraded?: boolean;
+    downgradeNote?: string;
+    error?: string;
+}
+/**
+ * 公共媒体上传+发送流程
+ *
+ * resolveMediaFile → detectType → sizeCheck → uploadMedia → sendMediaMessage
+ */
+export declare function uploadAndSendMedia(options: UploadAndSendMediaOptions): Promise<UploadAndSendMediaResult>;
+export interface UploadAndReplyMediaOptions {
+    wsClient: WSClient;
+    mediaUrl: string;
+    frame: WsFrameHeaders;
+    mediaLocalRoots?: readonly string[];
+    log?: (...args: any[]) => void;
+    errorLog?: (...args: any[]) => void;
+}
+/**
+ * 被动回复媒体上传+发送流程
+ *
+ * resolveMediaFile → detectType → sizeCheck → uploadMedia → replyMedia
+ */
+export declare function uploadAndReplyMedia(options: UploadAndReplyMediaOptions): Promise<UploadAndSendMediaResult>;

package/dist/esm/types/src/message-parser.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 企业微信私有部署消息内容解析模块
+ *
+ * 负责从 WsFrame 中提取文本、图片、引用等内容
+ */
+export interface MessageBody {
+    msgid: string;
+    aibotid?: string;
+    chatid?: string;
+    chattype: "single" | "group";
+    from: {
+        corpid?: string;
+        userid: string;
+    };
+    response_url?: string;
+    msgtype: string;
+    text?: {
+        content: string;
+    };
+    image?: {
+        url?: string;
+        aeskey?: string;
+    };
+    voice?: {
+        content?: string;
+    };
+    mixed?: {
+        msg_item: Array<{
+            msgtype: "text" | "image";
+            text?: {
+                content: string;
+            };
+            image?: {
+                url?: string;
+                aeskey?: string;
+            };
+        }>;
+    };
+    file?: {
+        url?: string;
+        aeskey?: string;
+    };
+    quote?: {
+        msgtype: string;
+        text?: {
+            content: string;
+        };
+        voice?: {
+            content: string;
+        };
+        image?: {
+            url?: string;
+            aeskey?: string;
+        };
+        file?: {
+            url?: string;
+            aeskey?: string;
+        };
+    };
+    event?: {
+        eventtype?: string;
+        template_card_event?: {
+            card_type?: string;
+            event_key?: string;
+            task_id?: string;
+            selected_items?: {
+                selected_item?: Array<{
+                    question_key?: string;
+                    option_ids?: {
+                        option_id?: string[];
+                    };
+                }>;
+            };
+        };
+    };
+}
+export interface ParsedMessageContent {
+    textParts: string[];
+    imageUrls: string[];
+    imageAesKeys: Map<string, string>;
+    fileUrls: string[];
+    fileAesKeys: Map<string, string>;
+    quoteContent: string | undefined;
+}
+/**
+ * 解析消息内容（支持单条消息、图文混排、事件回调和引用消息）
+ * @returns 提取的文本数组、图片URL数组和引用消息内容
+ */
+export declare function parseMessageContent(body: MessageBody): ParsedMessageContent;

package/dist/esm/types/src/message-sender.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 企业微信私有部署消息发送模块
+ *
+ * 负责通过 WSClient 发送回复消息，包含超时保护
+ */
+import type { RuntimeLogger } from "./interface.js";
+import { type WSClient, type WsFrame } from "@wecom/aibot-node-sdk";
+/** 流式回复超时错误码（>6分钟未更新，服务端拒绝继续流式更新） */
+export declare const STREAM_EXPIRED_ERRCODE = 846608;
+/**
+ * 流式回复过期错误
+ * 当服务端返回 errcode=846608 时抛出，表示流式消息已超过6分钟无法更新，
+ * 调用方需降级为主动发送（sendMessage）方式回复。
+ */
+export declare class StreamExpiredError extends Error {
+    readonly errcode = 846608;
+    constructor(message?: string);
+}
+/**
+ * 发送企业微信回复消息
+ * 供 monitor 内部和出站消息使用
+ *
+ * @returns messageId (streamId)
+ */
+export declare function sendWeComReply(params: {
+    wsClient: WSClient;
+    frame: WsFrame;
+    text?: string;
+    runtime: RuntimeLogger;
+    /** 是否为流式回复的最终消息，默认为 true */
+    finish?: boolean;
+    /** 指定 streamId，用于流式回复时保持相同的 streamId */
+    streamId?: string;
+}): Promise<string>;