hyacinth-ai 0.9.19 → 0.9.21

package/dist/agents/delegate-tool.d.ts

@@ -25,6 +25,14 @@ export interface SubAgentContext {
     sandboxRoot?: string;
     /** 创建带独立 userId 的 Provider（子Agent 之间 + 与主Agent 的 KVCache 隔离） */
     createSubProvider(userId: string): Provider;
+    /** 异步子Agent 结果推送队列（主 loop 的 pendingAsyncResults，完成后自动注入对话） */
+    pendingAsyncResults?: Array<{
+        handle: string;
+        agentName: string;
+        status: 'completed' | 'failed';
+        result?: string;
+        error?: string;
+    }>;
 }
 /** 注册正在运行的子 Agent loop */
 export declare function registerRunningLoop(instanceId: string, loop: AgentLoop): void;
@@ -32,6 +40,29 @@ export declare function registerRunningLoop(instanceId: string, loop: AgentLoop)
 export declare function unregisterRunningLoop(instanceId: string): void;
 /** 中断指定子 Agent */
 export declare function interruptSubAgentLoop(instanceId: string): boolean;
+export interface AsyncSubAgentTask {
+    handle: string;
+    agentName: string;
+    instanceId: string;
+    task: string;
+    status: 'running' | 'completed' | 'failed';
+    startTime: string;
+    endTime?: string;
+    result?: string;
+    error?: string;
+}
+/** 注册异步子 Agent 任务，返回 handle */
+export declare function registerAsyncTask(agentName: string, instanceId: string, task: string): string;
+/** 标记异步任务为已完成 */
+export declare function completeAsyncTask(handle: string, result: string): void;
+/** 标记异步任务为失败 */
+export declare function failAsyncTask(handle: string, error: string): void;
+/** 获取所有异步任务列表 */
+export declare function listAsyncTasks(): AsyncSubAgentTask[];
+/** 按 handle 获取异步任务 */
+export declare function getAsyncTask(handle: string): AsyncSubAgentTask | undefined;
+/** 等待所有运行中的异步子 Agent 任务完成（用于优雅关闭） */
+export declare function waitForAsyncTasks(timeoutMs?: number): Promise<void>;
 /** 销毁子 Agent session 目录（清理 conversation/events/stats/meta） */
 export declare function destroySubAgentSession(parentSessionDir: string, instanceId: string): Promise<boolean>;
 /**
@@ -73,6 +104,14 @@ export declare class DelegateToAgentTool implements Tool {
                 type: "string";
                 description: string;
             };
+            async: {
+                type: "boolean";
+                description: string;
+            };
+            across_turns: {
+                type: "boolean";
+                description: string;
+            };
         };
         required: string[];
     };
@@ -81,7 +120,14 @@ export declare class DelegateToAgentTool implements Tool {
     constructor(agentRegistry: AgentRegistry, parentContext: SubAgentContext);
     execute(args: Record<string, unknown>): Promise<string>;
     /**
-     * 委托模式：单个子 Agent 执行任务
+     * 异步委托：在后台启动子 Agent，立即返回任务句柄。
+     * 子 Agent 的 loop.run() 在后台 Promise 中执行，完成后结果写入 AsyncSubAgentTask。
+     */
+    private executeAsync;
+    /** 后台执行子 Agent 任务 */
+    private runAsyncInBackground;
+    /**
+     * 委托模式：单个子 Agent 执行任务（同步阻塞）
      */
     private executeDelegate;
     /**

package/dist/agents/delegate-tool.js

@@ -33,6 +33,57 @@ export function interruptSubAgentLoop(instanceId) {
     loop.interrupt();
     return true;
 }
+const asyncTasks = new Map();
+let asyncTaskCounter = 0;
+/** 注册异步子 Agent 任务，返回 handle */
+export function registerAsyncTask(agentName, instanceId, task) {
+    const handle = `sub_${String(++asyncTaskCounter).padStart(3, '0')}`;
+    asyncTasks.set(handle, {
+        handle,
+        agentName,
+        instanceId,
+        task,
+        status: 'running',
+        startTime: new Date().toISOString(),
+    });
+    return handle;
+}
+/** 标记异步任务为已完成 */
+export function completeAsyncTask(handle, result) {
+    const t = asyncTasks.get(handle);
+    if (t) {
+        t.status = 'completed';
+        t.endTime = new Date().toISOString();
+        t.result = result;
+    }
+}
+/** 标记异步任务为失败 */
+export function failAsyncTask(handle, error) {
+    const t = asyncTasks.get(handle);
+    if (t) {
+        t.status = 'failed';
+        t.endTime = new Date().toISOString();
+        t.error = error;
+    }
+}
+/** 获取所有异步任务列表 */
+export function listAsyncTasks() {
+    return [...asyncTasks.values()];
+}
+/** 按 handle 获取异步任务 */
+export function getAsyncTask(handle) {
+    return asyncTasks.get(handle);
+}
+/** 等待所有运行中的异步子 Agent 任务完成（用于优雅关闭） */
+export async function waitForAsyncTasks(timeoutMs = 5000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const running = listAsyncTasks().filter(t => t.status === 'running');
+        if (running.length === 0)
+            return;
+        await new Promise(resolve => setTimeout(resolve, 200));
+    }
+}
 /** 销毁子 Agent session 目录（清理 conversation/events/stats/meta） */
 export async function destroySubAgentSession(parentSessionDir, instanceId) {
     const subDir = path.join(parentSessionDir, 'sub-agents', instanceId);
@@ -57,6 +108,11 @@ export async function createSubAgentLoop(agentDef, task, parentContext) {
     const instanceId = agentDef.instanceId ?? `${agentDef.name}-default`;
     const subSessionDir = path.join(parentContext.sessionDir, 'sub-agents', instanceId);
     const ttlMinutes = agentDef.sessionTtlMinutes ?? 10;
+    // 并发保护：同一 instanceId 已有活跃 loop 时拒绝，防止会话文件并发写入冲突
+    if (runningLoops.has(instanceId)) {
+        throw new Error(`子 Agent "${agentDef.name}" (${instanceId}) 正在执行中，不能同时委派第二个任务。` +
+            '等待当前任务完成后重试，或使用 spawn_sub_agent 创建独立实例来并行执行。');
+    }
     // TTL 检查：过期则清理重建
     let isNew = false;
     try {
@@ -163,6 +219,7 @@ export class DelegateToAgentTool {
         '"parallel"（并行分工）：同时启动多个子 Agent 并行执行，汇总结果。' +
         '编排场景：当你有一个复杂计划时，自己负责规划和决策，将其中可并行的子任务分别委派给多个子 Agent 同步执行——spawn_sub_agent 可克隆多份实例，配合不同的 instance_id 并发调度，大幅缩短总耗时。' +
         '会话复用：子 Agent 会话在 TTL 窗口内持久化（默认 10 分钟），相同 instance_id 再次委派时自动恢复完整对话记忆，无需重新交代背景。' +
+        '异步执行：设置 async=true 后子 Agent 在后台运行，主 Agent 立即获得任务句柄（如 sub_001）并可继续其他工作。之后用 list_sub_agent_tasks 查看所有异步任务状态，get_sub_agent_result <handle> 获取已完成任务的结果。默认 async=false（同步阻塞，等待结果返回）。' +
         '使用 list_sub_agents 查看可用 Agent 及其实例 ID，create_sub_agent 创建新 Agent，spawn_sub_agent 克隆以支持并行，destroy_sub_agent 清理不再需要的实例。';
     inputSchema = {
         type: 'object',
@@ -183,6 +240,14 @@ export class DelegateToAgentTool {
                 type: 'string',
                 description: '可选的附加上下文（如相关代码片段、文件路径、背景信息）。',
             },
+            async: {
+                type: 'boolean',
+                description: '是否异步执行。默认 false（阻塞等待结果）。设为 true 时立即返回任务句柄（如 sub_001），子 Agent 在后台执行，主 Agent 可继续其他工具调用。',
+            },
+            across_turns: {
+                type: 'boolean',
+                description: '异步结果是否允许跨 turn。默认 false——子Agent完成后结果在当前 turn 内自动注入对话，LLM 立即看到并继续处理。设为 true 时结果不自动注入，需手动用 get_sub_agent_result 获取（适用于需要跨多轮对话的后台任务）。仅在 async=true 时生效。',
+            },
         },
         required: ['task'],
     };
@@ -197,6 +262,8 @@ export class DelegateToAgentTool {
         const agentName = args.agent_name;
         const task = args.task;
         const context = args.context;
+        const runAsync = args.async === true;
+        const acrossTurns = args.across_turns === true;
         if (!agentName && !instanceId) {
             return 'Error: either agent_name or instance_id is required. Use list_sub_agents to see available agents and their instance IDs.';
         }
@@ -219,19 +286,23 @@ export class DelegateToAgentTool {
         if (!agentDef) {
             return 'Error: no sub-agent found matching the provided criteria.';
         }
+        // 异步模式下不支持 adversarial 和 parallel（这两种本身就是多Agent协同，异步应逐个个委派）
+        if (runAsync && agentDef.collaborationMode !== 'delegate') {
+            return `错误：异步模式仅支持 collaborationMode="delegate"。当前模式为 "${agentDef.collaborationMode}"。请用 spawn_sub_agent 克隆独立实例，然后对每个实例分别用 async=true 委派。`;
+        }
         // 构造完整任务描述
         const fullTask = context ? `${task}\n\nAdditional Context:\n${context}` : task;
         try {
+            if (runAsync) {
+                return await this.executeAsync(agentDef, fullTask, acrossTurns);
+            }
             if (agentDef.collaborationMode === 'adversarial') {
-                // 对抗审查模式：找一个不同角色的子 Agent 同时审查
                 return await this.executeAdversarial(agentDef, fullTask);
             }
             else if (agentDef.collaborationMode === 'parallel') {
-                // 并行分工模式：所有 parallel 模式的子 Agent 并行执行
                 return await this.executeParallel(agentDef, fullTask);
             }
             else {
-                // 委托模式：直接委托给子 Agent
                 return await this.executeDelegate(agentDef, fullTask);
             }
         }
@@ -241,7 +312,54 @@ export class DelegateToAgentTool {
         }
     }
     /**
-     * 委托模式：单个子 Agent 执行任务
+     * 异步委托：在后台启动子 Agent，立即返回任务句柄。
+     * 子 Agent 的 loop.run() 在后台 Promise 中执行，完成后结果写入 AsyncSubAgentTask。
+     */
+    async executeAsync(agentDef, task, acrossTurns) {
+        const instanceId = agentDef.instanceId;
+        const handle = registerAsyncTask(agentDef.name, instanceId, task);
+        // 在后台启动子 Agent，不阻塞。catch 兜底防止未处理的 Promise rejection
+        this.runAsyncInBackground(handle, agentDef, task, acrossTurns).catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            failAsyncTask(handle, message);
+            if (!acrossTurns) {
+                this.parentContext.pendingAsyncResults?.push({ handle, agentName: agentDef.name, status: 'failed', error: message });
+            }
+        });
+        const hint = acrossTurns
+            ? `跨 turn 模式——任务完成后需手动用 get_sub_agent_result ${handle} 获取结果。`
+            : '回合内模式——子Agent完成后结果将自动注入当前对话。';
+        return `异步子 Agent 任务已启动。\n句柄: ${handle}\nAgent: ${agentDef.name} (${instanceId})\n${hint}\n任务: ${task.slice(0, 100)}${task.length > 100 ? '...' : ''}`;
+    }
+    /** 后台执行子 Agent 任务 */
+    async runAsyncInBackground(handle, agentDef, task, acrossTurns) {
+        const instanceId = agentDef.instanceId;
+        try {
+            const { loop, sessionDir, isNew } = await createSubAgentLoop(agentDef, task, this.parentContext);
+            registerRunningLoop(instanceId, loop);
+            if (!isNew) {
+                await fs.utimes(path.join(sessionDir, 'meta.json'), new Date(), new Date()).catch(() => { });
+            }
+            await loop.run(task);
+            unregisterRunningLoop(instanceId);
+            const result = await this.collectResult(agentDef, task);
+            completeAsyncTask(handle, result);
+            if (!acrossTurns) {
+                // 回合内模式：推送到主 loop 队列，当前 turn 自动注入结果
+                this.parentContext.pendingAsyncResults?.push({ handle, agentName: agentDef.name, status: 'completed', result });
+            }
+        }
+        catch (error) {
+            unregisterRunningLoop(instanceId);
+            const message = error instanceof Error ? error.message : String(error);
+            failAsyncTask(handle, message);
+            if (!acrossTurns) {
+                this.parentContext.pendingAsyncResults?.push({ handle, agentName: agentDef.name, status: 'failed', error: message });
+            }
+        }
+    }
+    /**
+     * 委托模式：单个子 Agent 执行任务（同步阻塞）
      */
     async executeDelegate(agentDef, task) {
         const instanceId = agentDef.instanceId;

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/factory.js

@@ -424,12 +424,15 @@ export async function createAgent(options, supervisor) {
     for (const agent of agents) {
         agentRegistry.register(agent);
     }
+    // 异步子Agent 结果队列——先创建引用，后续赋给 loop
+    const pendingAsyncResults = [];
     const delegateTool = new DelegateToAgentTool(agentRegistry, {
         modelRouter,
         toolRegistry,
         sessionDir,
         maxContextTokens: maxContext,
         dependencyAnalyzer,
+        pendingAsyncResults,
         createSubProvider: (userId) => {
             if (!subProviderApiKey || !subProviderBaseType) {
                 throw new Error('Cannot create sub-agent provider: main provider not configured.');
@@ -517,6 +520,7 @@ export async function createAgent(options, supervisor) {
     const loop = new AgentLoop(provider, contextComposer, compressor, orchestrator, toolExecutor, toolRegistry, conversationStore, eventStore, statsManager, sessionDir, summaryStore, effectiveMaxTurns, maxContext, outputHandler, skillRegistry, mcpSystem.getBridge(), dependencyAnalyzer, agentRegistry, effectivePersonaDir, flowRegistry, providerRouter, new Set(config.safety?.dangerousTools ?? ['write', 'bash']), new Set(), configCenter, modelRouter, turnRecorder);
     // 注入知识库状态引用
     loop.kbState = kbState;
+    loop.pendingAsyncResults = pendingAsyncResults; // 异步子Agent结果队列（和 delegateTool 共享引用）
     loopRef = loop; // wire fallback notification
     // 注入旁路 Provider 引用（供模式切换时 setBypassUserId 使用）
     if (bypassProvider)

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/dist/lifecycle/supervisor.js

@@ -1,5 +1,6 @@
 import { ProcessManager } from './manager.js';
 import { LocalModelManager } from './local-model.js';
+import { waitForAsyncTasks } from '../agents/delegate-tool.js';
 /**
  * LifecycleSupervisor — 统一管理所有受管进程的生命周期。
  *
@@ -184,6 +185,8 @@ export class LifecycleSupervisor {
         if (this.backgroundRegistry) {
             await this.backgroundRegistry.shutdownAll().catch(() => { });
         }
+        // 等待异步子 Agent 任务完成（最多等 5 秒）
+        await waitForAsyncTasks(5000).catch(() => { });
         const results = this.entities.map((e) => e.manager.stop().catch(() => {
             // 单个关闭失败不影响其他
         }));

package/dist/orchestrator/loop.d.ts

@@ -151,6 +151,14 @@ export declare class AgentLoop {
         name: string;
         firedAt: string;
     }>;
+    /** 异步子Agent 完成后的结果队列（delegate-tool 写入，主循环消费） */
+    pendingAsyncResults: Array<{
+        handle: string;
+        agentName: string;
+        status: 'completed' | 'failed';
+        result?: string;
+        error?: string;
+    }>;
     /** 当前正在执行的定时任务名（供 TUI 显示上下文），run 前设置，run 后清除 */
     pendingTaskName: string | null;
     /** 知识库状态引用（factory 注入） */

package/dist/orchestrator/loop.js

@@ -203,6 +203,8 @@ export class AgentLoop {
     schedulerInitialized = false;
     /** 定时任务触发后待注入对话的通知 */
     pendingTaskNotifications = [];
+    /** 异步子Agent 完成后的结果队列（delegate-tool 写入，主循环消费） */
+    pendingAsyncResults = [];
     /** 当前正在执行的定时任务名（供 TUI 显示上下文），run 前设置，run 后清除 */
     pendingTaskName = null;
     /** 知识库状态引用（factory 注入） */
@@ -1159,6 +1161,23 @@ export class AgentLoop {
                 turnCount++;
                 if (result.toolCalled)
                     toolWasCalled = true;
+                // ── 异步子Agent 结果回合内注入 ─────────────────────────
+                // delegate-tool 中异步任务完成后会将结果推送到此队列。
+                // 本轮迭代结束后检查：有已完成的结果→注入对话→强制继续迭代，
+                // 让 LLM 在当前 turn 内拿到结果并做出反应，无需跨 turn 手动查。
+                if (this.pendingAsyncResults.length > 0) {
+                    const results = this.pendingAsyncResults.splice(0);
+                    for (const r of results) {
+                        const content = r.status === 'completed'
+                            ? `[异步子Agent ${r.handle} (${r.agentName}) 已完成]\n${r.result ?? ''}`
+                            : `[异步子Agent ${r.handle} (${r.agentName}) 执行失败]\n${r.error ?? ''}`;
+                        await this.conversationStore.append(this.sessionDir, {
+                            role: 'user',
+                            content: [{ type: 'text', text: content }],
+                        });
+                    }
+                    result.stop = false; // 强制继续迭代，让 LLM 看到注入的异步结果
+                }
                 // 更新 stats
                 await this.statsManager.increment(this.sessionDir, 'turn_count', 1);
                 // ── 旁路Agent 迭代审查（每次 LLM 回复后） ──────────

package/dist/registry/tool.registry.js

@@ -3,7 +3,7 @@ import { getActiveRouterName } from '../context/profiles.js';
 import path from 'node:path';
 import fs from 'node:fs';
 import { createGetConfigTool, createUpdateConfigTool, createConfigSchemaTool, createResetConfigTool, } from '../tools/config.js';
-import { createSwitchProviderTool, createListProvidersTool, createProviderInfoTool, createSwitchToAutoRouteTool, createToggleToolTool, createListToolsTool, createToggleSkillTool, createListSkillsTool, createToggleSubAgentTool, createListSubAgentsTool, createSpawnSubAgentTool, createCreateSubAgentTool, createUpdateSubAgentTool, createInterruptTool, createSessionStatsTool, createCurrentSessionTool, createListSessionsTool, createNewSessionTool, createSwitchSessionTool, createDeleteSessionTool, createAllowToolTool, createDisallowToolTool, createListAllowlistTool, createAddTaskTool, createRemoveTaskTool, createListTasksTool, createToggleTaskTool, createMcpStatusTool, createListModelChannelsTool, createAddModelChannelTool, createRemoveModelChannelTool, createSetChannelRoleTool, createSetChannelModelTool, createResetChannelModelTool, createChannelInfoTool, } from '../tools/runtime-control.js';
+import { createSwitchProviderTool, createListProvidersTool, createProviderInfoTool, createSwitchToAutoRouteTool, createToggleToolTool, createListToolsTool, createToggleSkillTool, createListSkillsTool, createToggleSubAgentTool, createListSubAgentsTool, createSpawnSubAgentTool, createCreateSubAgentTool, createUpdateSubAgentTool, createListSubAgentTasksTool, createGetSubAgentResultTool, createInterruptTool, createSessionStatsTool, createCurrentSessionTool, createListSessionsTool, createNewSessionTool, createSwitchSessionTool, createDeleteSessionTool, createAllowToolTool, createDisallowToolTool, createListAllowlistTool, createAddTaskTool, createRemoveTaskTool, createListTasksTool, createToggleTaskTool, createMcpStatusTool, createListModelChannelsTool, createAddModelChannelTool, createRemoveModelChannelTool, createSetChannelRoleTool, createSetChannelModelTool, createResetChannelModelTool, createChannelInfoTool, } from '../tools/runtime-control.js';
 /**
  * 工具注册表
  * 负责注册、查询工具，以及生成 LLM 格式的工具定义
@@ -110,6 +110,9 @@ export class ToolRegistry extends GenericRegistry {
         this.register(createSpawnSubAgentTool(agentRegistry));
         this.register(createCreateSubAgentTool(agentRegistry, cwd));
         this.register(createUpdateSubAgentTool(agentRegistry));
+        // ── 异步子 Agent 任务工具 (2) ─────────────────────────────────
+        this.register(createListSubAgentTasksTool());
+        this.register(createGetSubAgentResultTool());
         // destroy_sub_agent needs factory.ts sessionDir; register in factory.ts after loop is created
         // (handled by importing and registering createDestroySubAgentTool directly in factory.ts)
         // ── Session control tools (7) ────────────────────────

package/dist/tools/runtime-control.d.ts

@@ -51,6 +51,14 @@ export declare function createToggleSubAgentTool(agentRegistry: AgentRegistry, c
  * list_sub_agents — list all registered sub-agents with their enabled/disabled status and instance IDs.
  */
 export declare function createListSubAgentsTool(agentRegistry: any): Tool;
+/**
+ * list_sub_agent_tasks — 列出所有异步子 Agent 任务及其状态。
+ */
+export declare function createListSubAgentTasksTool(): Tool;
+/**
+ * get_sub_agent_result — 获取异步子 Agent 任务的执行结果。
+ */
+export declare function createGetSubAgentResultTool(): Tool;
 /**
  * spawn_sub_agent — clone an existing sub-agent to create a parallel instance (分身).
  */

package/dist/tools/runtime-control.js

@@ -1,5 +1,6 @@
 import { clearPromptCache } from '../prompts/loader.js';
 import { switchRouter } from '../context/profiles.js';
+import { listAsyncTasks, getAsyncTask } from '../agents/delegate-tool.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -359,6 +360,69 @@ export function createListSubAgentsTool(agentRegistry) {
         },
     };
 }
+// ── 异步子 Agent 任务管理工具 ──
+/**
+ * list_sub_agent_tasks — 列出所有异步子 Agent 任务及其状态。
+ */
+export function createListSubAgentTasksTool() {
+    return {
+        name: 'list_sub_agent_tasks',
+        description: '列出所有通过 delegate_to_agent(async=true) 启动的异步子 Agent 任务。包含句柄、Agent 名称、任务描述、状态（running/completed/failed）、启动时间和结果摘要。',
+        inputSchema: { type: 'object', properties: {} },
+        async execute(_args) {
+            const tasks = listAsyncTasks();
+            if (tasks.length === 0) {
+                return '暂无异步子 Agent 任务。使用 delegate_to_agent 并设置 async=true 来启动异步任务。';
+            }
+            const lines = [`异步子 Agent 任务（共 ${tasks.length} 个）：`];
+            for (const t of tasks) {
+                const statusLabel = t.status === 'running' ? '执行中' : t.status === 'completed' ? '已完成' : '失败';
+                const statusIcon = t.status === 'running' ? '🔄' : t.status === 'completed' ? '✅' : '❌';
+                lines.push(`  ${statusIcon} ${t.handle} [${statusLabel}] ${t.agentName} (instance: ${t.instanceId}): ${t.task.slice(0, 60)}${t.task.length > 60 ? '...' : ''}`);
+                if (t.status !== 'running' && t.result) {
+                    const summary = t.result.split('\n').find(l => l.trim())?.slice(0, 80) ?? '';
+                    lines.push(`     ↳ ${summary}${summary.length >= 80 ? '...' : ''}`);
+                }
+            }
+            lines.push('');
+            lines.push('使用 get_sub_agent_result <handle> 获取已完成任务的完整结果。');
+            return lines.join('\n');
+        },
+    };
+}
+/**
+ * get_sub_agent_result — 获取异步子 Agent 任务的执行结果。
+ */
+export function createGetSubAgentResultTool() {
+    return {
+        name: 'get_sub_agent_result',
+        description: '获取指定异步子 Agent 任务的执行结果。running 时返回仍在执行中，completed 时返回完整结果，failed 时返回错误信息。句柄从 list_sub_agent_tasks 获取。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handle: {
+                    type: 'string',
+                    description: '异步任务句柄（如 sub_001），从 list_sub_agent_tasks 获取。',
+                },
+            },
+            required: ['handle'],
+        },
+        async execute(args) {
+            const handle = args.handle;
+            const task = getAsyncTask(handle);
+            if (!task) {
+                return `错误：未找到异步任务 "${handle}"。使用 list_sub_agent_tasks 查看所有任务及其句柄。`;
+            }
+            if (task.status === 'running') {
+                return `任务 ${handle}（${task.agentName}）仍在执行中。任务：${task.task.slice(0, 100)}${task.task.length > 100 ? '...' : ''}\n启动时间：${task.startTime}\n请稍后再次调用 get_sub_agent_result 查询。`;
+            }
+            if (task.status === 'failed') {
+                return `任务 ${handle}（${task.agentName}）执行失败。\n错误：${task.error}\n任务：${task.task}`;
+            }
+            return `任务 ${handle}（${task.agentName}）已完成。\n\n${task.result}`;
+        },
+    };
+}
 /**
  * spawn_sub_agent — clone an existing sub-agent to create a parallel instance (分身).
  */

package/package.json

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