hyacinth-ai 0.9.6

package/dist/channels/plugins/clawbot/clawbot-client.d.ts

@@ -0,0 +1,180 @@
+export interface QRCodeResult {
+    qrcode: string;
+    qrcode_img_content: string;
+}
+export type QRCodeStatus = 'wait' | 'scaned' | 'confirmed' | 'expired' | 'scaned_but_redirect' | 'need_verifycode' | 'binded_redirect';
+export interface QRCodeStatusResult {
+    status: QRCodeStatus;
+    /** 确认后的 bot_token（仅 confirmed 时有值） */
+    bot_token?: string;
+    /** bot 用户 ID，格式 xxx@im.bot */
+    ilink_bot_id?: string;
+    /** 微信用户 ID，格式 xxx@im.wechat */
+    ilink_user_id?: string;
+    /** API 根域名 */
+    baseurl?: string;
+}
+export type MessageItemType = 1 | 2 | 3 | 4 | 5;
+export type MessageType = 1 | 2;
+export type MessageState = 0 | 1 | 2;
+export interface TextItem {
+    type: 1;
+    text_item: {
+        text: string;
+    };
+}
+export interface ImageItem {
+    type: 2;
+    image_item: {
+        /** CDN 下载/上传 URL 或 base64 data URL */
+        url?: string;
+        /** 图片宽度 */
+        width?: number;
+        /** 图片高度 */
+        height?: number;
+    };
+}
+export interface VoiceItem {
+    type: 3;
+    voice_item: Record<string, unknown>;
+}
+export interface FileItem {
+    type: 4;
+    file_item: Record<string, unknown>;
+}
+export interface VideoItem {
+    type: 5;
+    video_item: Record<string, unknown>;
+}
+export type MessageItem = TextItem | ImageItem | VoiceItem | FileItem | VideoItem;
+/** 入站消息（来自 getUpdates） */
+export interface ClawbotIncomingMessage {
+    from_user_id: string;
+    to_user_id: string;
+    message_type: MessageType;
+    message_state: MessageState;
+    context_token: string;
+    item_list: MessageItem[];
+}
+/** 出站消息（传给 sendMessage） */
+export interface ClawbotOutgoingMessage {
+    to_user_id: string;
+    client_id: string;
+    message_type: 2;
+    message_state: 2;
+    context_token: string;
+    item_list: MessageItem[];
+}
+export interface GetUpdatesRequest {
+    get_updates_buf: string;
+    base_info?: {
+        channel_version?: string;
+    };
+}
+export interface GetUpdatesResponse {
+    ret: number;
+    msgs?: ClawbotIncomingMessage[];
+    get_updates_buf?: string;
+    longpolling_timeout_ms?: number;
+}
+export interface SendMessageRequest {
+    msg: ClawbotOutgoingMessage;
+    base_info?: {
+        channel_version?: string;
+    };
+}
+export interface SendMessageResponse {
+    ret: number;
+    errcode?: number;
+    errmsg?: string;
+}
+export interface GetConfigResponse {
+    ret: number;
+    typing_ticket?: string;
+}
+export interface GetUploadUrlRequest {
+    file_name?: string;
+    file_size?: number;
+    content_type?: string;
+}
+export interface GetUploadUrlResponse {
+    ret: number;
+    upload_url?: string;
+    errcode?: number;
+    errmsg?: string;
+}
+export declare class ClawbotAPIError extends Error {
+    ret?: number | undefined;
+    errcode?: number | undefined;
+    constructor(message: string, ret?: number | undefined, errcode?: number | undefined);
+    /** errcode:-14 表示 session timeout / bot_token 过期 */
+    get isSessionTimeout(): boolean;
+}
+export declare class ClawbotClient {
+    private baseUrl;
+    private botToken;
+    private httpTimeoutMs;
+    private channelVersion;
+    constructor(baseUrl: string, botToken: string, httpTimeoutMs?: number, channelVersion?: string);
+    /** 更新 bot_token（授权成功 / 重新扫码后调用） */
+    setBotToken(token: string): void;
+    /** 生成 X-WECHAT-UIN 防重放随机值 */
+    private generateWechatUin;
+    /** 构建 POST 请求的鉴权头 */
+    private authHeaders;
+    private post;
+    private get;
+    /**
+     * 获取绑定二维码，发起授权流程。
+     * bot_type 固定为 3。
+     *
+     * v2.x 使用 POST 方式，支持 local_token_list 参数。
+     */
+    getQRCode(localTokenList?: string[]): Promise<QRCodeResult>;
+    /** 轮询扫码状态，返回状态及 token 信息 */
+    getQRCodeStatus(qrcode: string): Promise<QRCodeStatusResult>;
+    /**
+     * 长轮询接收用户消息。
+     * 服务端挂起超时约 35s，有消息立即返回，无消息等待至超时返回空。
+     *
+     * @param getUpdatesBuf 上次返回的 opaque blob，首次传空字符串
+     */
+    getUpdates(getUpdatesBuf: string): Promise<GetUpdatesResponse>;
+    /**
+     * 向微信 ClawBot 会话发送消息。
+     *
+     * @param toUserId 接收方 ID（ilink_user_id，格式 xxx@im.wechat）
+     * @param contextToken 对应用户消息的上下文令牌（必填）
+     * @param text 文本内容
+     * @param images 图片列表（已上传到 CDN 的 URL）
+     */
+    sendMessage(toUserId: string, contextToken: string, text: string, images?: Array<{
+        url: string;
+        width?: number;
+        height?: number;
+    }>): Promise<SendMessageResponse>;
+    /**
+     * 分片发送长文本消息。
+     * 保守上限 2000 字符/条，优先在 \n\n 处切割，其次 \n 处，再次空格处。
+     * 每条分片使用不同的 client_id。
+     *
+     * @returns 发送的分片数量
+     */
+    sendMessageChunked(toUserId: string, contextToken: string, text: string, chunkLimit?: number): Promise<number>;
+    /** 文本分片：优先在 \n\n、\n、空格处切割 */
+    private splitText;
+    /**
+     * 向用户发送「正在输入」状态提示。
+     * 需要先调用 getConfig 获取 typing_ticket。
+     */
+    sendTyping(toUserId: string, contextToken: string, typingTicket: string): Promise<void>;
+    /** 获取服务端配置（含 typing_ticket），用于 sendTyping */
+    getConfig(): Promise<GetConfigResponse>;
+    /**
+     * 获取媒体文件上传地址。
+     * 上传完成后通过 sendMessage 引用该媒体文件。
+     */
+    getUploadUrl(fileName: string, fileSize: number, contentType: string): Promise<GetUploadUrlResponse>;
+    private sleep;
+}
+//# sourceMappingURL=clawbot-client.d.ts.map

package/dist/channels/plugins/clawbot/clawbot-client.js

@@ -0,0 +1,312 @@
+// ============================================================
+// ClawbotClient — 封装 ClawBot iLink API 全部 HTTP 调用
+// ============================================================
+//
+// 底层协议：iLink（智联）协议，标准 HTTP/JSON
+// 主域名：https://ilinkai.weixin.qq.com
+// CDN 域名：https://novac2c.cdn.weixin.qq.com/c2c
+//
+// 全部 7 个接口：
+//   1. getQRCode           — 获取登录二维码
+//   2. getQRCodeStatus     — 轮询扫码状态
+//   3. getUpdates          — 长轮询接收消息
+//   4. sendMessage         — 发送/回复消息
+//   5. sendTyping          — 发送「正在输入」状态
+//   6. getConfig           — 获取配置（typing_ticket 等）
+//   7. getUploadUrl        — 获取媒体上传地址
+// ============================================================
+import crypto from 'node:crypto';
+// ── 错误类型 ──────────────────────────────────────────────────
+export class ClawbotAPIError extends Error {
+    ret;
+    errcode;
+    constructor(message, ret, errcode) {
+        super(message);
+        this.ret = ret;
+        this.errcode = errcode;
+        this.name = 'ClawbotAPIError';
+    }
+    /** errcode:-14 表示 session timeout / bot_token 过期 */
+    get isSessionTimeout() {
+        return this.errcode === -14 || this.ret === -14;
+    }
+}
+// ── ClawbotClient ─────────────────────────────────────────────
+export class ClawbotClient {
+    baseUrl;
+    botToken;
+    httpTimeoutMs;
+    channelVersion;
+    constructor(baseUrl, botToken, httpTimeoutMs = 30_000, channelVersion = '1.0.0') {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.botToken = botToken;
+        this.httpTimeoutMs = httpTimeoutMs;
+        this.channelVersion = channelVersion;
+    }
+    /** 更新 bot_token（授权成功 / 重新扫码后调用） */
+    setBotToken(token) {
+        this.botToken = token;
+    }
+    // ── 鉴权 ────────────────────────────────────────────────────
+    /** 生成 X-WECHAT-UIN 防重放随机值 */
+    generateWechatUin() {
+        return crypto.randomBytes(16).toString('base64');
+    }
+    /** 构建 POST 请求的鉴权头 */
+    authHeaders() {
+        return {
+            'Content-Type': 'application/json',
+            'AuthorizationType': 'ilink_bot_token',
+            'Authorization': `Bearer ${this.botToken}`,
+            'X-WECHAT-UIN': this.generateWechatUin(),
+        };
+    }
+    // ── HTTP 底层 ───────────────────────────────────────────────
+    async post(path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.httpTimeoutMs);
+        try {
+            const resp = await fetch(url, {
+                method: 'POST',
+                headers: this.authHeaders(),
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            const json = await resp.json();
+            // 检查业务错误码
+            const err = json;
+            if ((err.ret !== undefined && err.ret !== 0) || (err.errcode !== undefined && err.errcode !== 0)) {
+                throw new ClawbotAPIError(err.errmsg ?? err.err_msg ?? `API error: ret=${err.ret}, errcode=${err.errcode}`, err.ret, err.errcode);
+            }
+            return json;
+        }
+        catch (err) {
+            if (err instanceof ClawbotAPIError)
+                throw err;
+            if (err instanceof DOMException && err.name === 'AbortError') {
+                throw new ClawbotAPIError(`HTTP timeout after ${this.httpTimeoutMs}ms: ${path}`);
+            }
+            throw new ClawbotAPIError(`HTTP request failed: ${path} — ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async get(path) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.httpTimeoutMs);
+        try {
+            const resp = await fetch(url, { signal: controller.signal });
+            const json = await resp.json();
+            const err = json;
+            if (err.ret !== undefined && err.ret !== 0) {
+                throw new ClawbotAPIError(err.err_msg ?? `API error: ret=${err.ret}`, err.ret);
+            }
+            return json;
+        }
+        catch (err) {
+            if (err instanceof ClawbotAPIError)
+                throw err;
+            throw new ClawbotAPIError(`HTTP request failed: ${path} — ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ── 1. 获取登录二维码 ──────────────────────────────────────
+    /**
+     * 获取绑定二维码，发起授权流程。
+     * bot_type 固定为 3。
+     *
+     * v2.x 使用 POST 方式，支持 local_token_list 参数。
+     */
+    async getQRCode(localTokenList = []) {
+        const result = await this.post(`/ilink/bot/get_bot_qrcode?bot_type=3`, { local_token_list: localTokenList });
+        return result;
+    }
+    // ── 2. 轮询扫码授权状态 ────────────────────────────────────
+    /** 轮询扫码状态，返回状态及 token 信息 */
+    async getQRCodeStatus(qrcode) {
+        const result = await this.get(`/ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`);
+        return result;
+    }
+    // ── 3. 长轮询接收消息 ──────────────────────────────────────
+    /**
+     * 长轮询接收用户消息。
+     * 服务端挂起超时约 35s，有消息立即返回，无消息等待至超时返回空。
+     *
+     * @param getUpdatesBuf 上次返回的 opaque blob，首次传空字符串
+     */
+    async getUpdates(getUpdatesBuf) {
+        const body = {
+            get_updates_buf: getUpdatesBuf,
+            base_info: { channel_version: this.channelVersion },
+        };
+        // 长轮询超时要比普通 HTTP 请求长（服务端 35s + 5s 缓冲）
+        const pollUrl = `${this.baseUrl}/ilink/bot/getupdates`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 40_000);
+        try {
+            const resp = await fetch(pollUrl, {
+                method: 'POST',
+                headers: this.authHeaders(),
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            const json = await resp.json();
+            // ret !== 0 且不是超时（无消息）时抛出错误
+            if (json.ret !== undefined && json.ret !== 0 && !json.msgs) {
+                throw new ClawbotAPIError(`getUpdates error: ret=${json.ret}`, json.ret);
+            }
+            return json;
+        }
+        catch (err) {
+            if (err instanceof ClawbotAPIError)
+                throw err;
+            if (err instanceof DOMException && err.name === 'AbortError') {
+                // 超时是正常的——服务端 35s 无消息，返回空结果
+                return { ret: 0, msgs: [], get_updates_buf: getUpdatesBuf };
+            }
+            throw new ClawbotAPIError(`getUpdates failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ── 4. 发送/回复消息 ────────────────────────────────────────
+    /**
+     * 向微信 ClawBot 会话发送消息。
+     *
+     * @param toUserId 接收方 ID（ilink_user_id，格式 xxx@im.wechat）
+     * @param contextToken 对应用户消息的上下文令牌（必填）
+     * @param text 文本内容
+     * @param images 图片列表（已上传到 CDN 的 URL）
+     */
+    async sendMessage(toUserId, contextToken, text, images) {
+        const itemList = [];
+        // 先图片后文本
+        if (images?.length) {
+            for (const img of images) {
+                itemList.push({
+                    type: 2,
+                    image_item: {
+                        url: img.url,
+                        width: img.width,
+                        height: img.height,
+                    },
+                });
+            }
+        }
+        if (text) {
+            itemList.push({
+                type: 1,
+                text_item: { text },
+            });
+        }
+        const msg = {
+            to_user_id: toUserId,
+            client_id: `clawbot:${Date.now()}-${crypto.randomBytes(4).toString('hex')}`,
+            message_type: 2,
+            message_state: 2,
+            context_token: contextToken,
+            item_list: itemList,
+        };
+        const body = {
+            msg,
+            base_info: { channel_version: this.channelVersion },
+        };
+        return this.post('/ilink/bot/sendmessage', body);
+    }
+    /**
+     * 分片发送长文本消息。
+     * 保守上限 2000 字符/条，优先在 \n\n 处切割，其次 \n 处，再次空格处。
+     * 每条分片使用不同的 client_id。
+     *
+     * @returns 发送的分片数量
+     */
+    async sendMessageChunked(toUserId, contextToken, text, chunkLimit = 2000) {
+        if (text.length <= chunkLimit) {
+            await this.sendMessage(toUserId, contextToken, text);
+            return 1;
+        }
+        const chunks = this.splitText(text, chunkLimit);
+        for (let i = 0; i < chunks.length; i++) {
+            // 每条分片等待一小段时间，避免限流
+            if (i > 0)
+                await this.sleep(200);
+            const chunk = chunks[i];
+            const suffix = chunks.length > 1 ? ` (${i + 1}/${chunks.length})` : '';
+            await this.sendMessage(toUserId, contextToken, chunk + suffix);
+        }
+        return chunks.length;
+    }
+    /** 文本分片：优先在 \n\n、\n、空格处切割 */
+    splitText(text, limit) {
+        const chunks = [];
+        let remaining = text;
+        while (remaining.length > limit) {
+            let cutAt = limit;
+            // 优先找双换行
+            const doubleNewline = remaining.lastIndexOf('\n\n', limit);
+            if (doubleNewline > limit * 0.5) {
+                cutAt = doubleNewline + 2;
+            }
+            else {
+                // 其次找单换行
+                const singleNewline = remaining.lastIndexOf('\n', limit);
+                if (singleNewline > limit * 0.5) {
+                    cutAt = singleNewline + 1;
+                }
+                else {
+                    // 最后找空格
+                    const space = remaining.lastIndexOf(' ', limit);
+                    if (space > limit * 0.5) {
+                        cutAt = space + 1;
+                    }
+                }
+            }
+            chunks.push(remaining.slice(0, cutAt).trim());
+            remaining = remaining.slice(cutAt).trim();
+        }
+        if (remaining)
+            chunks.push(remaining);
+        return chunks;
+    }
+    // ── 5. 发送「正在输入」状态 ────────────────────────────────
+    /**
+     * 向用户发送「正在输入」状态提示。
+     * 需要先调用 getConfig 获取 typing_ticket。
+     */
+    async sendTyping(toUserId, contextToken, typingTicket) {
+        await this.post('/ilink/bot/sendtyping', {
+            to_user_id: toUserId,
+            context_token: contextToken,
+            typing_ticket: typingTicket,
+        });
+    }
+    // ── 6. 获取配置 ────────────────────────────────────────────
+    /** 获取服务端配置（含 typing_ticket），用于 sendTyping */
+    async getConfig() {
+        return this.post('/ilink/bot/getconfig', {});
+    }
+    // ── 7. 获取媒体上传地址 ────────────────────────────────────
+    /**
+     * 获取媒体文件上传地址。
+     * 上传完成后通过 sendMessage 引用该媒体文件。
+     */
+    async getUploadUrl(fileName, fileSize, contentType) {
+        const body = {
+            file_name: fileName,
+            file_size: fileSize,
+            content_type: contentType,
+        };
+        return this.post('/ilink/bot/getuploadurl', body);
+    }
+    // ── 工具 ────────────────────────────────────────────────────
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=clawbot-client.js.map

package/dist/channels/plugins/clawbot/clawbot-config.d.ts

@@ -0,0 +1,30 @@
+/** ClawBot 渠道配置 */
+export interface ClawbotChannelConfig {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** bot_token（可选，留空则首次自动走扫码授权流程） */
+    botToken?: string;
+    /** bot 用户 ID（ilink_bot_id，授权后自动填充，格式 xxx@im.bot） */
+    botId?: string;
+    /** 用户 ID（ilink_user_id，授权后自动填充，格式 xxx@im.wechat） */
+    userId?: string;
+    /** iLink API 根域名（默认 https://ilinkai.weixin.qq.com） */
+    baseUrl?: string;
+    /** 长轮询等待时长（秒），默认 28（服务端超时 35s，留 7s 缓冲） */
+    pollTimeoutSec?: number;
+    /** 轮询失败重试间隔（毫秒），默认 3000 */
+    pollRetryIntervalMs?: number;
+    /** 是否同步到 TUI 界面 */
+    tuiSync?: boolean;
+    /** 发送文本消息的最大长度（字符），默认 2000（微信实际限制保守值） */
+    textChunkLimit?: number;
+    /** 是否自动刷新 bot_token（提前 2 天告警提示重新扫码） */
+    autoRefreshToken?: boolean;
+    /** HTTP 请求超时（毫秒），默认 30_000 */
+    httpTimeoutMs?: number;
+}
+/** 带默认值的完整配置 */
+export declare function resolveClawbotConfig(raw: Partial<ClawbotChannelConfig>): ClawbotChannelConfig;
+/** 校验配置是否完备（启动时不强制要求 botToken，可以运行时扫码授权） */
+export declare function validateClawbotConfig(config: ClawbotChannelConfig): string | null;
+//# sourceMappingURL=clawbot-config.d.ts.map

package/dist/channels/plugins/clawbot/clawbot-config.js

@@ -0,0 +1,28 @@
+// ============================================================
+// ClawBot 渠道配置类型
+// ============================================================
+//
+// ClawBot 是微信官方 AI 助手连接插件，只支持单会话收发。
+// 配置比飞书简单很多——没有群聊、DM 策略、访问控制列表等概念。
+// ============================================================
+/** 带默认值的完整配置 */
+export function resolveClawbotConfig(raw) {
+    return {
+        enabled: raw.enabled ?? true,
+        botToken: raw.botToken ?? '',
+        botId: raw.botId ?? '',
+        userId: raw.userId ?? '',
+        baseUrl: raw.baseUrl ?? 'https://ilinkai.weixin.qq.com',
+        pollTimeoutSec: raw.pollTimeoutSec ?? 28,
+        pollRetryIntervalMs: raw.pollRetryIntervalMs ?? 3000,
+        tuiSync: raw.tuiSync ?? false,
+        textChunkLimit: raw.textChunkLimit ?? 2000,
+        autoRefreshToken: raw.autoRefreshToken ?? true,
+        httpTimeoutMs: raw.httpTimeoutMs ?? 30_000,
+    };
+}
+/** 校验配置是否完备（启动时不强制要求 botToken，可以运行时扫码授权） */
+export function validateClawbotConfig(config) {
+    return null; // 无必填项——即使没有 botToken，也可以在运行时走扫码授权
+}
+//# sourceMappingURL=clawbot-config.js.map

package/dist/channels/plugins/clawbot/clawbot-message-queue.d.ts

@@ -0,0 +1,27 @@
+import type { ChannelEvent } from '../../interface.js';
+type Logger = {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+    warn?: (msg: string) => void;
+};
+type ProcessFn = (event: ChannelEvent) => Promise<void>;
+export declare class ClawbotMessageQueue {
+    private queues;
+    private processing;
+    private processFn;
+    private logger;
+    private static MAX_QUEUE_SIZE;
+    constructor(logger?: Logger);
+    /** 设置消息处理函数 */
+    setProcessFn(fn: ProcessFn): void;
+    /** 入队消息（fire-and-forget，立即返回） */
+    enqueue(sessionId: string, event: ChannelEvent): void;
+    /** 串行处理下一条消息 */
+    private processNext;
+    /** 获取指定 session 的队列长度 */
+    getQueueSize(sessionId: string): number;
+    /** 清理所有队列 */
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=clawbot-message-queue.d.ts.map