hyacinth-ai 0.9.6

package/dist/channels/plugins/feishu/feishu-message-queue.js

@@ -0,0 +1,112 @@
+// ============================================================
+// FeishuMessageQueue — 飞书渠道 per-session 消息队列
+// ============================================================
+//
+// 解决的问题：
+//   1. SDK handler 阻塞 ACK → 飞书重传 → 重复消息
+//   2. 并发 loop.run() → conversation.jsonl 交叉写入
+//
+// 设计：
+//   - handler 收到消息后入队即返回（fire-and-forget），ACK 立即发出
+//   - 队列按 sessionId 串行消费，保证同一 session 不会并发处理
+//   - 队列内二次去重，防止重传消息漏过外层去重窗口
+//   - 背压控制：最大 100 条/queue，超出丢弃最旧消息
+// ============================================================
+/** 从 ChannelEvent 中提取 messageId（仅 message 类型有） */
+function getMessageId(event) {
+    if (event.type === 'message') {
+        return event.metadata?.messageId;
+    }
+    return undefined;
+}
+export class FeishuMessageQueue {
+    queues = new Map();
+    processing = new Map();
+    processFn = null;
+    logger;
+    static MAX_QUEUE_SIZE = 100;
+    constructor(logger) {
+        this.logger = logger ?? {
+            info: (msg) => process.stderr.write(`[feishu-queue] ${msg}\n`),
+            error: (msg) => process.stderr.write(`[feishu-queue] ${msg}\n`),
+            warn: (msg) => process.stderr.write(`[feishu-queue] ${msg}\n`),
+        };
+    }
+    /** 设置消息处理函数 */
+    setProcessFn(fn) {
+        this.processFn = fn;
+    }
+    /** 入队消息（fire-and-forget，立即返回） */
+    enqueue(sessionId, event) {
+        // 1. 队列内去重：检查是否已有相同 messageId
+        const messageId = getMessageId(event);
+        if (messageId) {
+            const queue = this.queues.get(sessionId);
+            if (queue?.some(item => getMessageId(item.event) === messageId)) {
+                this.logger.info(`queue dedup: dropping duplicate message ${messageId.slice(0, 12)}...`);
+                return;
+            }
+        }
+        // 2. 获取或创建队列
+        let queue = this.queues.get(sessionId);
+        if (!queue) {
+            queue = [];
+            this.queues.set(sessionId, queue);
+        }
+        // 3. 背压控制：超出最大长度时丢弃最旧的消息
+        if (queue.length >= FeishuMessageQueue.MAX_QUEUE_SIZE) {
+            const dropped = queue.shift();
+            const droppedId = getMessageId(dropped?.event ?? {});
+            (this.logger.warn ?? this.logger.error)(`queue overflow: dropping oldest message ${droppedId?.slice(0, 12) ?? 'unknown'}...`);
+        }
+        // 4. 入队
+        queue.push({ event });
+        this.logger.info(`enqueued message for session ${sessionId.slice(0, 16)}... (queue size: ${queue.length})`);
+        // 5. 触发处理（如果当前没有在处理）
+        this.processNext(sessionId);
+    }
+    /** 串行处理下一条消息 */
+    processNext(sessionId) {
+        if (this.processing.get(sessionId)) {
+            return; // 正在处理中，等当前处理完会自动调用 processNext
+        }
+        const queue = this.queues.get(sessionId);
+        if (!queue || queue.length === 0) {
+            return;
+        }
+        if (!this.processFn) {
+            this.logger.error('no processFn set, message will stay in queue');
+            return;
+        }
+        const item = queue.shift();
+        this.processing.set(sessionId, true);
+        // 异步处理，不阻塞入队
+        this.processFn(item.event)
+            .catch((err) => {
+            this.logger.error(`process error for session ${sessionId.slice(0, 16)}...: ${String(err instanceof Error ? err.message : err)}`);
+        })
+            .finally(() => {
+            this.processing.set(sessionId, false);
+            // 处理完后检查队列中是否还有消息
+            const remaining = this.queues.get(sessionId);
+            if (remaining && remaining.length > 0) {
+                this.processNext(sessionId);
+            }
+            else {
+                // 队列空了，清理
+                this.queues.delete(sessionId);
+                this.processing.delete(sessionId);
+            }
+        });
+    }
+    /** 获取指定 session 的队列长度 */
+    getQueueSize(sessionId) {
+        return this.queues.get(sessionId)?.length ?? 0;
+    }
+    /** 清理所有队列 */
+    clear() {
+        this.queues.clear();
+        this.processing.clear();
+    }
+}
+//# sourceMappingURL=feishu-message-queue.js.map

package/dist/channels/plugins/feishu/feishu-send.d.ts

@@ -0,0 +1,44 @@
+import type { FeishuChannelConfig } from './feishu-config.js';
+export interface FeishuSendResult {
+    messageId: string;
+    chatId: string;
+}
+/**
+ * 发送文本消息
+ */
+export declare function sendText(config: FeishuChannelConfig, params: {
+    to: string;
+    text: string;
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+}): Promise<FeishuSendResult>;
+/**
+ * 发送交互式卡片消息
+ */
+export declare function sendCard(config: FeishuChannelConfig, params: {
+    to: string;
+    card: Record<string, unknown>;
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+}): Promise<FeishuSendResult>;
+/**
+ * 构建简单的 Markdown 卡片
+ * 用于 Markdown 渲染（代码块、表格、链接等）
+ */
+export declare function buildMarkdownCard(text: string): Record<string, unknown>;
+/**
+ * 更新已发送的卡片消息
+ * 用于流式输出：先发送占位卡片，然后不断更新内容
+ */
+export declare function patchCard(config: FeishuChannelConfig, params: {
+    messageId: string;
+    card: Record<string, unknown>;
+}): Promise<void>;
+/**
+ * 获取发送者信息
+ */
+export declare function getSenderInfo(config: FeishuChannelConfig, userId: string, userIdType?: 'open_id' | 'user_id'): Promise<{
+    name?: string;
+    avatar?: string;
+} | null>;
+//# sourceMappingURL=feishu-send.d.ts.map

package/dist/channels/plugins/feishu/feishu-send.js

@@ -0,0 +1,232 @@
+// ============================================================
+// Feishu 消息发送
+// ============================================================
+//
+// 封装飞书消息发送 API：
+//   - sendText: 发送文本（使用 post 格式支持富文本）
+//   - sendCard: 发送交互式卡片
+//   - replyInThread: 话题回复
+// ============================================================
+import { createFeishuClient } from './feishu-client.js';
+/**
+ * 解析发送目标
+ * 支持格式：user:open_id, chat:chat_id, open_id, chat_id
+ */
+function resolveSendTarget(to) {
+    const trimmed = to.trim();
+    // 去掉前缀（user: / chat: / open_id:），只保留裸 ID
+    let id = trimmed;
+    if (trimmed.startsWith('user:'))
+        id = trimmed.slice(5);
+    else if (trimmed.startsWith('chat:'))
+        id = trimmed.slice(5);
+    else if (trimmed.startsWith('open_id:'))
+        id = trimmed.slice(8);
+    // 根据 ID 前缀推断正确的 receive_id_type
+    // 飞书：ou_ → open_id, oc_ → chat_id
+    if (id.startsWith('oc_')) {
+        return { receiveId: id, receiveIdType: 'chat_id' };
+    }
+    if (id.startsWith('ou_')) {
+        return { receiveId: id, receiveIdType: 'open_id' };
+    }
+    // 有显式前缀时按前缀语义处理
+    if (trimmed.startsWith('chat:')) {
+        return { receiveId: id, receiveIdType: 'chat_id' };
+    }
+    if (trimmed.startsWith('open_id:') || trimmed.startsWith('user:')) {
+        return { receiveId: id, receiveIdType: 'open_id' };
+    }
+    // 无法推断，默认按 open_id 处理
+    return { receiveId: id, receiveIdType: 'open_id' };
+}
+// ── 构建 Post 消息体 ──
+/**
+ * 构建 Feishu Post 格式消息（支持 Markdown 子集）
+ */
+function buildPostContent(text) {
+    return JSON.stringify({
+        zh_cn: {
+            content: [
+                [
+                    {
+                        tag: 'md',
+                        text,
+                    },
+                ],
+            ],
+        },
+    });
+}
+// ── 发送消息 ──
+/**
+ * 发送文本消息
+ */
+export async function sendText(config, params) {
+    const client = await createFeishuClient(config);
+    const { receiveId, receiveIdType } = resolveSendTarget(params.to);
+    const content = buildPostContent(params.text);
+    // 如果有回复目标，使用 reply 接口
+    if (params.replyToMessageId) {
+        try {
+            const res = await client.im.message.reply({
+                path: { message_id: params.replyToMessageId },
+                data: {
+                    content,
+                    msg_type: 'post',
+                    ...(params.replyInThread ? { reply_in_thread: true } : {}),
+                },
+            });
+            if (res.code !== 0) {
+                throw new Error(`Feishu reply failed: ${res.msg || `code ${res.code}`}`);
+            }
+            return {
+                messageId: res.data?.message_id ?? '',
+                chatId: receiveId,
+            };
+        }
+        catch (err) {
+            enrichFeishuError(err, { api: 'reply', receiveId, receiveIdType });
+            throw err;
+        }
+    }
+    // 直接发送
+    try {
+        const res = await client.im.message.create({
+            params: { receive_id_type: receiveIdType },
+            data: {
+                receive_id: receiveId,
+                content,
+                msg_type: 'post',
+            },
+        });
+        if (res.code !== 0) {
+            throw new Error(`Feishu send failed: ${res.msg || `code ${res.code}`}`);
+        }
+        return {
+            messageId: res.data?.message_id ?? '',
+            chatId: receiveId,
+        };
+    }
+    catch (err) {
+        enrichFeishuError(err, { api: 'send', receiveId, receiveIdType });
+        throw err;
+    }
+}
+/** 将飞书请求上下文注入到错误对象上，便于上层日志记录 */
+function enrichFeishuError(err, ctx) {
+    if (err instanceof Error) {
+        const enriched = err;
+        enriched.feishuContext = ctx;
+        // 尝试从 SDK 错误对象上提取响应体
+        const sdkErr = err;
+        if (sdkErr.response?.data) {
+            enriched.feishuResponse = sdkErr.response.data;
+        }
+        else if (sdkErr.data) {
+            enriched.feishuResponse = sdkErr.data;
+        }
+    }
+}
+/**
+ * 发送交互式卡片消息
+ */
+export async function sendCard(config, params) {
+    const client = await createFeishuClient(config);
+    const { receiveId, receiveIdType } = resolveSendTarget(params.to);
+    const content = JSON.stringify(params.card);
+    if (params.replyToMessageId) {
+        const res = await client.im.message.reply({
+            path: { message_id: params.replyToMessageId },
+            data: {
+                content,
+                msg_type: 'interactive',
+                ...(params.replyInThread ? { reply_in_thread: true } : {}),
+            },
+        });
+        if (res.code !== 0) {
+            throw new Error(`Feishu card reply failed: ${res.msg || `code ${res.code}`}`);
+        }
+        return {
+            messageId: res.data?.message_id ?? '',
+            chatId: receiveId,
+        };
+    }
+    const res = await client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+            receive_id: receiveId,
+            content,
+            msg_type: 'interactive',
+        },
+    });
+    if (res.code !== 0) {
+        throw new Error(`Feishu card send failed: ${res.msg || `code ${res.code}`}`);
+    }
+    return {
+        messageId: res.data?.message_id ?? '',
+        chatId: receiveId,
+    };
+}
+/**
+ * 构建简单的 Markdown 卡片
+ * 用于 Markdown 渲染（代码块、表格、链接等）
+ */
+export function buildMarkdownCard(text) {
+    return {
+        schema: '2.0',
+        config: {
+            width_mode: 'fill',
+        },
+        body: {
+            elements: [
+                {
+                    tag: 'markdown',
+                    content: text,
+                },
+            ],
+        },
+    };
+}
+/**
+ * 更新已发送的卡片消息
+ * 用于流式输出：先发送占位卡片，然后不断更新内容
+ */
+export async function patchCard(config, params) {
+    const client = await createFeishuClient(config);
+    const content = JSON.stringify(params.card);
+    const res = await client.im.message.patch({
+        path: { message_id: params.messageId },
+        data: {
+            content: JSON.stringify({
+                type: 'interactive',
+                content,
+            }),
+        },
+    });
+    if (res.code !== 0) {
+        throw new Error(`Feishu card patch failed: ${res.msg || `code ${res.code}`}`);
+    }
+}
+/**
+ * 获取发送者信息
+ */
+export async function getSenderInfo(config, userId, userIdType = 'open_id') {
+    try {
+        const client = await createFeishuClient(config);
+        const res = await client.contact.user.get({
+            path: { user_id: userId },
+            params: { user_id_type: userIdType },
+        });
+        if (res.code !== 0)
+            return null;
+        return {
+            name: res.data?.user?.name || undefined,
+            avatar: res.data?.user?.avatar?.avatar_72 || undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=feishu-send.js.map

package/dist/channels/plugins/feishu/feishu-session.d.ts

@@ -0,0 +1,44 @@
+import type { OutputHandler } from '../../../orchestrator/loop.js';
+import type { FeishuChannelConfig } from './feishu-config.js';
+export interface CollectHandler extends OutputHandler {
+    getResponse(): string;
+    reset(): void;
+}
+export interface SessionRunner {
+    run(input: string): Promise<void>;
+}
+export interface SessionEntry {
+    loop: SessionRunner;
+    collectHandler: CollectHandler;
+}
+export type SessionMode = 'shared' | 'per_chat' | 'per_user';
+export declare class ChannelSessionPool {
+    private sessions;
+    /**
+     * 获取或创建 session。
+     *
+     * @param config 飞书渠道配置（含 sessionMode）
+     * @param chatId 聊天 ID
+     * @param senderOpenId 发送者 open_id
+     * @param createFn 创建新 session 的回调，返回 { loop, collectHandler }
+     */
+    getOrCreate(config: FeishuChannelConfig, chatId: string, senderOpenId: string, createFn: () => Promise<SessionEntry>): Promise<SessionEntry>;
+    /**
+     * 根据 sessionMode 解析 sessionId。
+     */
+    resolveSessionId(config: FeishuChannelConfig, chatId: string, senderOpenId: string): string;
+    /**
+     * 清理指定 session。
+     */
+    evict(sessionId: string): void;
+    /**
+     * 清理所有 session。
+     */
+    clear(): void;
+    /**
+     * 获取当前活跃 session 数量。
+     */
+    get size(): number;
+}
+export declare function createCollectHandler(): CollectHandler;
+//# sourceMappingURL=feishu-session.d.ts.map

package/dist/channels/plugins/feishu/feishu-session.js

@@ -0,0 +1,84 @@
+// ============================================================
+// Feishu Session Pool — 飞书渠道 session 持久化管理
+// ============================================================
+//
+// 维护 sessionId → AgentLoop 映射，确保同一对话源的消息
+// 路由到同一 AgentLoop，保持上下文连续性。
+//
+// sessionMode 决定 sessionId 的生成方式：
+//   - shared   → 使用主 loop（不创建新 session）
+//   - per_chat → 按 chatId 生成 sessionId
+//   - per_user → 按 senderOpenId 生成 sessionId
+// ============================================================
+// ── SessionPool ──
+export class ChannelSessionPool {
+    sessions = new Map();
+    /**
+     * 获取或创建 session。
+     *
+     * @param config 飞书渠道配置（含 sessionMode）
+     * @param chatId 聊天 ID
+     * @param senderOpenId 发送者 open_id
+     * @param createFn 创建新 session 的回调，返回 { loop, collectHandler }
+     */
+    async getOrCreate(config, chatId, senderOpenId, createFn) {
+        const sessionId = this.resolveSessionId(config, chatId, senderOpenId);
+        const existing = this.sessions.get(sessionId);
+        if (existing) {
+            return existing;
+        }
+        const entry = await createFn();
+        this.sessions.set(sessionId, entry);
+        return entry;
+    }
+    /**
+     * 根据 sessionMode 解析 sessionId。
+     */
+    resolveSessionId(config, chatId, senderOpenId) {
+        const mode = config.sessionMode ?? 'per_user';
+        switch (mode) {
+            case 'shared':
+                return '__shared__';
+            case 'per_chat':
+                return `feishu_chat_${chatId}`;
+            case 'per_user':
+            default:
+                return `feishu_${senderOpenId}`;
+        }
+    }
+    /**
+     * 清理指定 session。
+     */
+    evict(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    /**
+     * 清理所有 session。
+     */
+    clear() {
+        this.sessions.clear();
+    }
+    /**
+     * 获取当前活跃 session 数量。
+     */
+    get size() {
+        return this.sessions.size;
+    }
+}
+// ── Factory ──
+export function createCollectHandler() {
+    const texts = [];
+    return {
+        onText(content) { texts.push(content); },
+        // 飞书端只展示最终文本回复，工具调用和状态消息不发送给用户
+        onToolUse(_name, _inputSummary) { },
+        onStatus(_message) { },
+        // 每个新 turn 清空之前累积的文本，只保留最后一轮的输出
+        onTurnStart() { texts.length = 0; },
+        onFlush() { },
+        onInterrupt() { },
+        getResponse() { return texts.join(''); },
+        reset() { texts.length = 0; },
+    };
+}
+//# sourceMappingURL=feishu-session.js.map

package/dist/channels/plugins/feishu/feishu-streaming.d.ts

@@ -0,0 +1,49 @@
+import type { FeishuChannelConfig } from './feishu-config.js';
+type StreamingState = 'idle' | 'started' | 'streaming' | 'finished' | 'aborted';
+export declare class FeishuStreamingCard {
+    private config;
+    private state;
+    private messageId;
+    private chatId;
+    private replyToMessageId;
+    private replyInThread;
+    private buffer;
+    private lastSentText;
+    private updateTimer;
+    private updateIntervalMs;
+    private pendingUpdate;
+    private onError?;
+    constructor(config: FeishuChannelConfig, options?: {
+        replyToMessageId?: string;
+        replyInThread?: boolean;
+        updateIntervalMs?: number;
+        onError?: (err: Error) => void;
+    });
+    /**
+     * 启动流式输出：发送占位卡片
+     */
+    start(to: string): Promise<void>;
+    /**
+     * 追加文本内容
+     * 内部会按间隔触发卡片更新
+     */
+    append(text: string): void;
+    /**
+     * 重置缓冲区（不清除已发送的卡片，仅清空内存中的累积文本）。
+     * 在 Agent 循环的每个新 turn 开始时调用，确保只保留最后一轮输出。
+     */
+    resetBuffer(): void;
+    /**
+     * 完成流式输出：发送最终内容
+     */
+    finish(finalText?: string): Promise<void>;
+    /**
+     * 中止流式输出
+     */
+    abort(reason?: string): Promise<void>;
+    private flushUpdate;
+    getMessageId(): string | null;
+    getState(): StreamingState;
+}
+export {};
+//# sourceMappingURL=feishu-streaming.d.ts.map