hyacinth-ai 0.9.20 → 0.9.21

package/dist/channels/dispatcher.d.ts

@@ -0,0 +1,25 @@
+import type { Tool } from '../tools/interface.js';
+import type { ChannelManager } from './manager.js';
+/**
+ * MessageDispatcher — 统一分发层。
+ * 查目标渠道 → 调其 send() → 返回结果。
+ */
+export declare class MessageDispatcher {
+    private channelManager;
+    constructor(channelManager: ChannelManager);
+    send(args: {
+        channel: string;
+        to: string;
+        targetType?: 'user' | 'chat';
+        text?: string;
+        images?: Array<{
+            data: string;
+            media_type: string;
+        }>;
+    }): Promise<string>;
+}
+/**
+ * send_channel_message 工具——暴露给 Agent 的跨渠道发送能力。
+ */
+export declare function createSendChannelMessageTool(dispatcher: MessageDispatcher): Tool;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/channels/dispatcher.js

@@ -0,0 +1,96 @@
+// ============================================================
+// MessageDispatcher — 跨渠道消息分发层
+// ============================================================
+//
+// 允许 Agent 从任意会话借用其他渠道的发送能力。
+// 消息是一次性的——不创建 session、不写 conversation、不影响任何渠道的对话状态。
+// 被借用的渠道对"谁借了道"完全无感。
+// ============================================================
+/**
+ * MessageDispatcher — 统一分发层。
+ * 查目标渠道 → 调其 send() → 返回结果。
+ */
+export class MessageDispatcher {
+    channelManager;
+    constructor(channelManager) {
+        this.channelManager = channelManager;
+    }
+    async send(args) {
+        const state = this.channelManager.get(args.channel);
+        if (!state || state.status !== 'active') {
+            return `渠道 "${args.channel}" 未连接或未启动。可用渠道: ${this.channelManager.getStatusSummary().map(s => s.id).join(', ') || '无'}`;
+        }
+        const handler = state.handler;
+        if (!handler.send) {
+            return `渠道 "${args.channel}" (${handler.name}) 不支持主动发送。`;
+        }
+        const target = {
+            type: args.targetType ?? 'user',
+            id: args.to,
+        };
+        try {
+            const result = await handler.send(target, {
+                content: args.text ?? '',
+                images: args.images,
+            });
+            return result;
+        }
+        catch (err) {
+            return `发送失败: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+}
+/**
+ * send_channel_message 工具——暴露给 Agent 的跨渠道发送能力。
+ */
+export function createSendChannelMessageTool(dispatcher) {
+    return {
+        name: 'send_channel_message',
+        description: '借用指定渠道发送消息到目标用户或群聊。纯借用渠道能力——不创建会话、不写入对话记录、不影响其他渠道。' +
+            '适用于从当前渠道（如 TUI）通过飞书/微信等渠道向用户发送通知、图片或文件。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                channel: {
+                    type: 'string',
+                    description: '目标渠道 ID。可用 channel_info 查看已连接渠道。如 "feishu"、"clawbot"。',
+                },
+                to: {
+                    type: 'string',
+                    description: '目标用户 ID 或群聊 ID。飞书为 open_id 或 chat_id，微信为 wxid。',
+                },
+                target_type: {
+                    type: 'string',
+                    enum: ['user', 'chat'],
+                    description: '目标类型。user=私聊，chat=群聊。默认 user。',
+                },
+                text: {
+                    type: 'string',
+                    description: '要发送的文本内容。',
+                },
+                images: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            data: { type: 'string', description: '图片的 base64 数据' },
+                            media_type: { type: 'string', description: 'MIME 类型，如 image/png' },
+                        },
+                    },
+                    description: '要发送的图片列表（base64 + MIME 类型）。',
+                },
+            },
+            required: ['channel', 'to'],
+        },
+        async execute(args) {
+            return dispatcher.send({
+                channel: args.channel,
+                to: args.to,
+                targetType: args.target_type ?? 'user',
+                text: args.text || undefined,
+                images: args.images,
+            });
+        },
+    };
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/channels/interface.d.ts

@@ -45,6 +45,13 @@ export interface ChannelReply {
     }>;
     metadata?: Record<string, unknown>;
 }
+/** 主动发送的目标（跨渠道借用能力时指定接收方） */
+export interface ChannelTarget {
+    /** 目标类型 */
+    type: 'user' | 'chat';
+    /** 用户 ID 或群聊 ID */
+    id: string;
+}
 /** 输出处理器（渠道消息收集用） */
 export interface ChannelOutputHandler {
     onText?(content: string): void;
@@ -137,6 +144,16 @@ export interface ChannelHandler {
      * 获取渠道状态
      */
     getStatus(): ChannelStatus;
+    /**
+     * 主动发送消息到渠道（跨 session，不关联任何 AgentLoop、不落盘）。
+     * 用于从其他渠道借用本渠道的发送能力（如 TUI 中的 Agent 通过飞书发消息）。
+     * 未实现 = 该渠道不支持被外部借用。
+     *
+     * @param target 目标用户或群聊
+     * @param content 消息内容
+     * @returns 发送结果描述
+     */
+    send?(target: ChannelTarget, content: ChannelReply): Promise<string>;
 }
 export type ChannelStatus = 'registered' | 'starting' | 'active' | 'stopped' | 'error';
 export interface ChannelState {

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

@@ -1,4 +1,4 @@
-import type { ChannelHandler, ChannelEvent, ChannelReply, ChannelConfig, ChannelStatus, ChannelMessageEvent, AgentFactory, ReplyFn } from '../../interface.js';
+import type { ChannelHandler, ChannelEvent, ChannelReply, ChannelTarget, ChannelConfig, ChannelStatus, ChannelMessageEvent, AgentFactory, ReplyFn } from '../../interface.js';
 export declare class FeishuChannel implements ChannelHandler {
     readonly id = "feishu";
     readonly name = "Feishu (\u98DE\u4E66)";
@@ -32,6 +32,8 @@ export declare class FeishuChannel implements ChannelHandler {
     onEvent(handler: (event: ChannelEvent) => Promise<void>): void;
     reply(sessionId: string, reply: ChannelReply): Promise<void>;
     getStatus(): ChannelStatus;
+    send(target: ChannelTarget, content: ChannelReply): Promise<string>;
+    private uploadImage;
     /** 获取 tenant access token（缓存，提前 60s 刷新，token 有效期 2h） */
     private getTenantAccessToken;
     /**

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

@@ -14,7 +14,7 @@
 import { resolveFeishuConfig, validateFeishuConfig, } from './feishu-config.js';
 import { FeishuTransport } from './feishu-transport.js';
 import { parseFeishuMessageEvent, FeishuDedupeStore, checkDmAccess, checkGroupAccess, } from './feishu-event.js';
-import { sendText, sendCard, getSenderInfo } from './feishu-send.js';
+import { sendText, sendCard, sendImage, getSenderInfo } from './feishu-send.js';
 import { ChannelSessionPool, createCollectHandler } from './feishu-session.js';
 import { FeishuMessageQueue } from './feishu-message-queue.js';
 import { generateSessionId } from '../../../memory/session.js';
@@ -176,6 +176,109 @@ export class FeishuChannel {
     getStatus() {
         return this.status;
     }
+    // ================================================================
+    // send() — 跨渠道借用能力入口
+    // ================================================================
+    //
+    // 设计意图：
+    //   每个渠道有自己独特的发送能力（飞书能发卡片和图片、微信能发文件、
+    //   TUI 只能显示文本）。send() 将这些能力暴露给外部，使得其他渠道
+    //   的 Agent 可以借用本渠道的能力发送消息。
+    //
+    // 行为保证（"纯借用"语义）：
+    //   - 不创建 session —— 消息是一次性的，没有对应的 AgentLoop
+    //   - 不写 conversation.jsonl —— 不污染任何渠道的对话历史
+    //   - 不影响 ChannelHandler 内部状态 —— sessionMap、消息队列等完全不变
+    //   - 被借用方对"谁借的"完全无感 —— 不需要知道调用方是哪个渠道
+    //
+    // 调用链：
+    //   Agent → send_channel_message 工具 → MessageDispatcher
+    //        → ChannelManager.get('feishu') → FeishuChannel.send()
+    //
+    // 支持的消息类型（按优先级）：
+    //   1. 卡片消息（content.metadata.card 存在时）—— 飞书交互式卡片
+    //   2. 文本消息（默认）—— Post 格式，支持 Markdown 子集
+    //   3. 图片消息（content.images 存在时）—— 先上传获取 image_key，再发送
+    //      ↑ 图片在文本/卡片之后独立发送，失败不影响前面的消息
+    //
+    // 注意：
+    //   - 图片上传需要 tenant_access_token（通过 getTenantAccessToken 获取）
+    //   - 每条图片独立上传 + 发送，某张失败不阻塞其他图片
+    //   - 图片 base64 直接传给飞书 API，不在本地落盘
+    // ================================================================
+    async send(target, content) {
+        if (this.status !== 'active')
+            return '飞书渠道未连接，无法发送';
+        const config = this.config;
+        // 飞书 SDK 的 receive_id_type 由 ID 前缀推断（ou_→open_id, oc_→chat_id）
+        // sendText/sendCard/sendImage 内部调用 resolveSendTarget 自动处理
+        const to = target.type === 'chat' ? `chat:${target.id}` : `user:${target.id}`;
+        try {
+            // ① 主消息：卡片优先，否则文本
+            if (content.metadata?.card) {
+                await sendCard(config, { to, card: content.metadata.card });
+            }
+            else {
+                await sendText(config, { to, text: content.content });
+            }
+            // ② 图片：在文本/卡片之后独立发送
+            // 飞书的图片消息和文本消息是两条独立的消息，不支持图文混排
+            if (content.images && content.images.length > 0) {
+                const token = await this.getTenantAccessToken();
+                if (token) {
+                    for (const img of content.images) {
+                        try {
+                            // 飞书图片发送两步：上传拿 image_key → 调用 im.message.create 发送
+                            const imageKey = await this.uploadImage(token, img.data);
+                            await sendImage(config, { to, imageKey });
+                        }
+                        catch {
+                            // 某张图片失败不阻塞其他图片和整体流程
+                        }
+                    }
+                }
+            }
+            return `已通过飞书发送到 ${to}`;
+        }
+        catch (err) {
+            return `飞书发送失败: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    // ================================================================
+    // uploadImage() — 飞书图片上传
+    // ================================================================
+    //
+    // 飞书发送图片必须先上传到飞书服务器获取 image_key，
+    // 再用 image_key 调用 im.message.create（msg_type='image'）发送。
+    //
+    // API: POST https://open.feishu.cn/open-apis/im/v1/images
+    // 参数: image_type='message'（消息用图，非头像），image=base64（不含 data:xxx;base64, 前缀）
+    // 返回: { code: 0, data: { image_key: 'img_xxx' } }
+    //
+    // 注意：
+    //   - token 由调用方传入（来自 getTenantAccessToken 的缓存结果）
+    //   - mediaType 参数保留供未来扩展（如格式校验），当前仅透传 base64
+    //   - 飞书 image_key 有时效性（约 2 小时），不持久化缓存
+    // ================================================================
+    async uploadImage(token, base64Data, _mediaType) {
+        const domain = this.config?.domain ?? 'https://open.feishu.cn';
+        const resp = await fetch(`${domain}/open-apis/im/v1/images`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                image_type: 'message',
+                image: base64Data,
+            }),
+        });
+        const json = await resp.json();
+        if (json.code !== 0 || !json.data?.image_key) {
+            throw new Error(`飞书图片上传失败: code=${json.code}`);
+        }
+        return json.data.image_key;
+    }
     /** 获取 tenant access token（缓存，提前 60s 刷新，token 有效期 2h） */
     async getTenantAccessToken() {
         if (this.cachedToken && Date.now() < this.tokenExpiresAt - 60_000) {

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

@@ -41,4 +41,11 @@ export declare function getSenderInfo(config: FeishuChannelConfig, userId: strin
     name?: string;
     avatar?: string;
 } | null>;
+/**
+ * 发送图片消息（需先通过上传 API 获取 image_key）。
+ */
+export declare function sendImage(config: FeishuChannelConfig, params: {
+    to: string;
+    imageKey: string;
+}): Promise<FeishuSendResult>;
 //# sourceMappingURL=feishu-send.d.ts.map

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

@@ -229,4 +229,27 @@ export async function getSenderInfo(config, userId, userIdType = 'open_id') {
         return null;
     }
 }
+/**
+ * 发送图片消息（需先通过上传 API 获取 image_key）。
+ */
+export async function sendImage(config, params) {
+    const client = await createFeishuClient(config);
+    const { receiveId, receiveIdType } = resolveSendTarget(params.to);
+    const content = JSON.stringify({ image_key: params.imageKey });
+    const res = await client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+            receive_id: receiveId,
+            content,
+            msg_type: 'image',
+        },
+    });
+    if (res.code !== 0) {
+        throw new Error(`飞书图片发送失败: ${res.msg || `code ${res.code}`}`);
+    }
+    return {
+        messageId: res.data?.message_id ?? '',
+        chatId: receiveId,
+    };
+}
 //# sourceMappingURL=feishu-send.js.map

package/dist/gateway/tui.js

@@ -970,6 +970,12 @@ export async function runTui(provider, sessionId, shouldContinue, maxTurns, maxC
     }
     // 启动所有渠道（每个渠道自行处理消息）
     await channelManager.startAll(agentFactory);
+    // 注册跨渠道发送工具（TUI 模式）
+    if (agent) {
+        const { MessageDispatcher, createSendChannelMessageTool } = await import('../channels/dispatcher.js');
+        const dispatcher = new MessageDispatcher(channelManager);
+        agent.toolRegistry.register(createSendChannelMessageTool(dispatcher));
+    }
     // ── ASCII Art loader ──────────────────────────────────────────────
     async function loadAsciiArt(maxWidth = 54) {
         const asciiDir = path.join(os.homedir(), '.agent', 'ascii');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyacinth-ai",
-  "version": "0.9.20",
+  "version": "0.9.21",
   "description": "Hyacinth 🪻 — multi-provider AI agent with tool system and context management",
   "type": "module",
   "main": "dist/index.js",