@code4bug/jarvis-agent 1.0.4 → 1.1.5

package/dist/tools/publishMessage.js

@@ -0,0 +1,41 @@
+import { getBus } from '../core/busAccess.js';
+export const publishMessage = {
+    name: 'publish_message',
+    description: [
+        '向指定频道发布一条消息，供其他 SubAgent 或主 Agent 订阅接收。',
+        '适用场景：',
+        '  - SubAgent 完成阶段性任务后，将中间结果广播给协作的其他 SubAgent',
+        '  - 多 Agent 流水线中，上游 Agent 通知下游 Agent 开始处理',
+        '  - Agent 间共享数据，无需等待主 Agent 中转',
+        '注意：消息会保留在频道历史中，可通过 read_channel 工具查看。',
+    ].join('\n'),
+    parameters: {
+        channel: {
+            type: 'string',
+            description: '频道名称，建议使用语义化命名，如 "research-result" / "code-review-done"',
+            required: true,
+        },
+        payload: {
+            type: 'string',
+            description: '消息内容，可以是纯文本、JSON 字符串或任意结构化数据',
+            required: true,
+        },
+        agent_id: {
+            type: 'string',
+            description: '可选。发布者标识，默认为 "unknown"。建议填入当前 Agent 的 taskId 或角色名',
+            required: false,
+        },
+    },
+    execute: async (args) => {
+        const channel = (args.channel || '').trim();
+        const payload = (args.payload || '').trim();
+        const agentId = (args.agent_id || 'unknown').trim();
+        if (!channel)
+            throw new Error('缺少必填参数: channel');
+        if (!payload)
+            throw new Error('缺少必填参数: payload');
+        const bus = await getBus();
+        await bus.publish(agentId, channel, payload);
+        return `已向频道 "${channel}" 发布消息（来自: ${agentId}）`;
+    },
+};

package/dist/tools/readChannel.d.ts

@@ -0,0 +1,8 @@
+/**
+ * read_channel 工具
+ *
+ * 读取频道历史消息（非阻塞），支持查看所有活跃频道列表。
+ * 主 Agent 可用此工具汇总所有 SubAgent 的通讯记录。
+ */
+import { Tool } from '../types/index.js';
+export declare const readChannel: Tool;

package/dist/tools/readChannel.js

@@ -0,0 +1,44 @@
+import { getBus } from '../core/busAccess.js';
+export const readChannel = {
+    name: 'read_channel',
+    description: [
+        '读取指定频道的历史消息，或列出所有活跃频道。非阻塞，立即返回。',
+        '适用场景：',
+        '  - 主 Agent 汇总所有 SubAgent 的通讯结果',
+        '  - 查看某个频道的完整消息历史',
+        '  - 调试多 Agent 协作流程',
+    ].join('\n'),
+    parameters: {
+        channel: {
+            type: 'string',
+            description: '频道名称。若填 "*" 则列出所有活跃频道名称',
+            required: true,
+        },
+        limit: {
+            type: 'string',
+            description: '可选。最多返回最近 N 条消息，默认返回全部',
+            required: false,
+        },
+    },
+    execute: async (args) => {
+        const channel = (args.channel || '').trim();
+        if (!channel)
+            throw new Error('缺少必填参数: channel');
+        const bus = await getBus();
+        if (channel === '*') {
+            const channels = await bus.listChannels();
+            if (channels.length === 0)
+                return '当前没有活跃频道';
+            return `活跃频道列表（${channels.length} 个）:\n${channels.map((c) => `  - ${c}`).join('\n')}`;
+        }
+        const limit = args.limit ? parseInt(args.limit, 10) : undefined;
+        const msgs = await bus.getHistory(channel, limit);
+        if (msgs.length === 0)
+            return `频道 "${channel}" 暂无消息`;
+        const lines = msgs.map((msg, i) => {
+            const time = new Date(msg.timestamp).toISOString();
+            return `[${i + 1}] [来自: ${msg.from}] [${time}]\n${msg.payload}`;
+        });
+        return `频道 "${channel}" 共 ${msgs.length} 条消息:\n\n${lines.join('\n\n---\n\n')}`;
+    },
+};

package/dist/tools/runAgent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * run_agent 工具
+ *
+ * 允许主 Agent 在独立 Worker 线程中创建并运行一个 SubAgent，
+ * SubAgent 拥有完整的 react_loop 能力，可自主调用工具完成子任务。
+ *
+ * 主 Agent 调用此工具后会阻塞等待 SubAgent 完成，并返回其最终输出。
+ * 若需并行执行多个子任务，主 Agent 可在同一轮中多次调用此工具（并行工具调用）。
+ */
+import { Tool } from '../types/index.js';
+export declare const runAgent: Tool;

package/dist/tools/runAgent.js

@@ -0,0 +1,111 @@
+/**
+ * run_agent 工具
+ *
+ * 允许主 Agent 在独立 Worker 线程中创建并运行一个 SubAgent，
+ * SubAgent 拥有完整的 react_loop 能力，可自主调用工具完成子任务。
+ *
+ * 主 Agent 调用此工具后会阻塞等待 SubAgent 完成，并返回其最终输出。
+ * 若需并行执行多个子任务，主 Agent 可在同一轮中多次调用此工具（并行工具调用）。
+ */
+import { v4 as uuid } from 'uuid';
+import { SubAgentBridge } from '../core/SubAgentBridge.js';
+/** 将 task_id / role 转换为可读的 Agent 标签，例如 "ResearchAgent" */
+function resolveAgentLabel(taskId, role) {
+    if (role) {
+        // 从角色描述中提取关键词，例如 "你是一个代码审查助手" → "代码审查Agent"
+        const match = role.match(/[\u4e00-\u9fa5a-zA-Z0-9]+/g);
+        if (match && match.length > 0) {
+            // 取前两个词拼接，最长 8 个字符
+            const label = match.slice(0, 2).join('').slice(0, 8);
+            return `${label}Agent`;
+        }
+    }
+    // 回退：用 taskId 前 8 位
+    return `SubAgent-${taskId.slice(0, 8)}`;
+}
+export const runAgent = {
+    name: 'run_agent',
+    description: [
+        '在独立线程中同步运行一个 SubAgent，阻塞等待其完成后返回最终结果。',
+        '适用场景：',
+        '  - 将复杂任务拆解为多个独立子任务并行执行',
+        '  - 需要隔离执行上下文的子任务（如沙箱式文件操作）',
+        '  - 多角色协同：为不同子任务指定不同的角色和工具权限',
+        '注意：SubAgent 与主 Agent 共享文件系统，但拥有独立的对话上下文。',
+    ].join('\n'),
+    parameters: {
+        instruction: {
+            type: 'string',
+            description: '发给 SubAgent 的任务指令，应清晰描述目标、输入和期望输出格式',
+            required: true,
+        },
+        role: {
+            type: 'string',
+            description: '可选。SubAgent 的角色描述，用于约束其行为，例如"你是一个专注于代码审查的助手"',
+            required: false,
+        },
+        allowed_tools: {
+            type: 'string',
+            description: '可选。逗号分隔的工具名列表，限制 SubAgent 可用的工具范围，例如 "read_file,search_files"。为空则继承全部工具',
+            required: false,
+        },
+        task_id: {
+            type: 'string',
+            description: '可选。任务唯一标识，用于在并行场景中区分多个 SubAgent。不填则自动生成',
+            required: false,
+        },
+    },
+    execute: async (args, _abortSignal, toolCallbacks) => {
+        const instruction = (args.instruction || '').trim();
+        if (!instruction) {
+            throw new Error('缺少必填参数: instruction（SubAgent 任务指令）');
+        }
+        const role = (args.role || '').trim() || undefined;
+        const taskId = (args.task_id || '').trim() || uuid();
+        // 解析 allowed_tools
+        const allowedToolsRaw = (args.allowed_tools || '').trim();
+        const allowedTools = allowedToolsRaw
+            ? allowedToolsRaw.split(',').map((s) => s.trim()).filter(Boolean)
+            : undefined;
+        // 构造任务指令：若指定了 role，将其注入到 instruction 前缀
+        const fullInstruction = role
+            ? `[角色设定] ${role}\n\n[任务]\n${instruction}`
+            : instruction;
+        // 生成 UI 展示用的 Agent 标签，例如 "代码审查Agent"
+        const agentLabel = resolveAgentLabel(taskId, role);
+        const bridge = new SubAgentBridge();
+        const result = await bridge.run({
+            taskId,
+            instruction: fullInstruction,
+            allowedTools,
+        }, {
+            // 将 SubAgent 消息注入 subAgentId 后推送到主线程 UI
+            onMessage: (_tid, msg) => {
+                const tagged = { ...msg, subAgentId: agentLabel };
+                toolCallbacks?.onSubAgentMessage?.(tagged);
+            },
+            onUpdateMessage: (_tid, id, updates) => {
+                toolCallbacks?.onSubAgentUpdateMessage?.(id, updates);
+            },
+            onStreamText: () => { },
+            onLoopStateChange: () => { },
+            // 危险命令确认：SubAgent 默认取消，避免无人值守时阻塞
+            onConfirmDangerousCommand: async () => 'cancel',
+        });
+        if (result.status === 'error') {
+            throw new Error(`SubAgent [${taskId}] 执行失败: ${result.error}`);
+        }
+        if (result.status === 'aborted') {
+            return `SubAgent [${taskId}] 已中断，部分结果：\n${result.output || '（无输出）'}`;
+        }
+        // 构造返回给主 Agent 的摘要
+        const lines = [
+            `SubAgent [${taskId}] 执行完成`,
+            `执行步骤数: ${result.messages.length}`,
+            '',
+            '=== 最终输出 ===',
+            result.output || '（SubAgent 未产生文本输出）',
+        ];
+        return lines.join('\n');
+    },
+};

package/dist/tools/runCommand.js

@@ -1,10 +1,12 @@
 import { exec } from 'child_process';
 import { sanitizeOutput } from '../core/safeguard.js';
+import { logError, logInfo, logWarn } from '../core/logger.js';
 /**
  * 异步执行命令，支持通过 abortSignal 中断子进程
  */
 function execAsync(command, options, abortSignal) {
     return new Promise((resolve, reject) => {
+        logInfo('bash.exec.start', { command });
         const child = exec(command, options, (error, stdout, stderr) => {
             // 清理轮询
             if (pollTimer !== null)
@@ -12,6 +14,10 @@ function execAsync(command, options, abortSignal) {
             // 被中断时直接返回已有输出，不视为错误
             if (abortSignal?.aborted) {
                 const partial = sanitizeOutput(String(stdout ?? '').trim());
+                logWarn('bash.exec.aborted', {
+                    command,
+                    stdoutLength: String(stdout ?? '').length,
+                });
                 resolve(partial ? `(命令被中断)\n${partial}` : '(命令被中断)');
                 return;
             }
@@ -25,9 +31,18 @@ function execAsync(command, options, abortSignal) {
                     parts.push(`[exit code] ${error.code}`);
                 if (parts.length === 0)
                     parts.push(error.message);
+                logError('bash.exec.failed', error, {
+                    command,
+                    stdoutLength: String(stdout ?? '').length,
+                    stderrLength: String(stderr ?? '').length,
+                });
                 reject(new Error(`命令执行失败:\n${parts.join('\n')}`));
                 return;
             }
+            logInfo('bash.exec.done', {
+                command,
+                stdoutLength: String(stdout ?? '').length,
+            });
             resolve(sanitizeOutput(String(stdout).trim()) || '(命令执行完成，无输出)');
         });
         // 轮询 abortSignal，检测到中断时 kill 子进程
@@ -38,6 +53,7 @@ function execAsync(command, options, abortSignal) {
                     if (pollTimer !== null)
                         clearInterval(pollTimer);
                     pollTimer = null;
+                    logWarn('bash.exec.kill_requested', { command, pid: child.pid });
                     // 先尝试 SIGTERM，给进程优雅退出的机会
                     try {
                         child.kill('SIGTERM');

package/dist/tools/sendToAgent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * send_to_agent 工具
+ *
+ * 主 Agent 向指定后台子 Agent 发送消息。
+ * 本质是向 "agent-inbox:{task_id}" 频道 publish，
+ * 子 Agent 通过 subscribe_message 订阅该频道接收。
+ *
+ * 配合 spawn_agent 使用，实现主 Agent ↔ 子 Agent 的多轮对话。
+ */
+import { Tool } from '../types/index.js';
+export declare const sendToAgent: Tool;

package/dist/tools/sendToAgent.js

@@ -0,0 +1,35 @@
+import { getBus } from '../core/busAccess.js';
+export const sendToAgent = {
+    name: 'send_to_agent',
+    description: [
+        '向指定后台子 Agent 发送一条消息，子 Agent 会从其收件箱频道接收。',
+        '前提：子 Agent 必须已通过 spawn_agent 启动，且在其 instruction 中包含订阅收件箱的逻辑。',
+        '',
+        '消息流向：主 Agent → agent-inbox:{task_id} → 子 Agent',
+        '等待回复：使用 subscribe_message 订阅 "agent-reply:{task_id}" 频道。',
+    ].join('\n'),
+    parameters: {
+        task_id: {
+            type: 'string',
+            description: '目标子 Agent 的 task_id（由 spawn_agent 返回）',
+            required: true,
+        },
+        message: {
+            type: 'string',
+            description: '要发送给子 Agent 的消息内容',
+            required: true,
+        },
+    },
+    execute: async (args) => {
+        const taskId = (args.task_id || '').trim();
+        const message = (args.message || '').trim();
+        if (!taskId)
+            throw new Error('缺少必填参数: task_id');
+        if (!message)
+            throw new Error('缺少必填参数: message');
+        const inboxChannel = `agent-inbox:${taskId}`;
+        const bus = await getBus();
+        await bus.publish('main-agent', inboxChannel, message);
+        return `消息已发送至子 Agent [${taskId}]\n频道: ${inboxChannel}\n内容: ${message}`;
+    },
+};

package/dist/tools/spawnAgent.d.ts

@@ -0,0 +1,6 @@
+import { Tool } from '../types/index.js';
+/**
+ * 在主线程侧直接启动 SubAgent（供 WorkerBridge 调用）
+ */
+export declare function spawnSubAgentInMainThread(taskId: string, instruction: string, agentLabel: string, allowedTools?: string[]): string;
+export declare const spawnAgent: Tool;

package/dist/tools/spawnAgent.js

@@ -0,0 +1,180 @@
+/**
+ * spawn_agent 工具
+ *
+ * 异步启动一个 SubAgent（不阻塞主 Agent），子 Agent 在后台独立运行。
+ * 主 Agent 可通过 send_to_agent 工具向其发送消息，子 Agent 通过
+ * subscribe_message 订阅自己的 inbox 频道（agent-inbox:{task_id}）接收。
+ *
+ * 重要：SubAgentBridge 必须在主线程创建，才能访问共享的 agentMessageBus 单例。
+ * 因此本工具通过 IPC（parentPort）将 spawn 请求委托给主线程（WorkerBridge）执行。
+ */
+import { v4 as uuid } from 'uuid';
+import { isMainThread, parentPort } from 'worker_threads';
+import { SubAgentBridge } from '../core/SubAgentBridge.js';
+import { agentUIBus } from '../core/AgentRegistry.js';
+import { agentMessageBus } from '../core/AgentMessageBus.js';
+import { getBus } from '../core/busAccess.js';
+import { pendingSpawnRequests, incrementActiveAgents, decrementActiveAgents } from '../core/spawnRegistry.js';
+import { logError, logInfo } from '../core/logger.js';
+/** 运行中的 task_id 集合（主线程侧，防止重复启动） */
+const runningAgents = new Set();
+function resolveAgentLabel(taskId, role) {
+    if (role) {
+        const match = role.match(/[\u4e00-\u9fa5a-zA-Z0-9]+/g);
+        if (match && match.length > 0) {
+            return `${match.slice(0, 2).join('').slice(0, 8)}Agent`;
+        }
+    }
+    return `SubAgent-${taskId.slice(0, 8)}`;
+}
+/**
+ * 在主线程侧直接启动 SubAgent（供 WorkerBridge 调用）
+ */
+export function spawnSubAgentInMainThread(taskId, instruction, agentLabel, allowedTools) {
+    if (runningAgents.has(taskId)) {
+        logInfo('spawn_agent.duplicate', { taskId, agentLabel });
+        return `子 Agent [${taskId}] 已在运行中，请使用 send_to_agent 向其发送消息，或使用不同的 task_id 启动新实例。`;
+    }
+    const replyChannel = `agent-reply:${taskId}`;
+    const bridge = new SubAgentBridge();
+    runningAgents.add(taskId);
+    incrementActiveAgents();
+    logInfo('spawn_agent.started', {
+        taskId,
+        agentLabel,
+        allowedTools,
+    });
+    bridge.run({ taskId, instruction, allowedTools }, {
+        onMessage: (_tid, msg) => {
+            const tagged = { ...msg, subAgentId: agentLabel };
+            agentUIBus.push(tagged);
+        },
+        onUpdateMessage: (_tid, id, updates) => {
+            agentUIBus.update(id, updates);
+        },
+        onStreamText: () => { },
+        onLoopStateChange: () => { },
+        onConfirmDangerousCommand: async () => 'cancel',
+    }).then((result) => {
+        runningAgents.delete(taskId);
+        decrementActiveAgents();
+        logInfo('spawn_agent.done', {
+            taskId,
+            agentLabel,
+            status: result.status,
+            outputLength: result.output.length,
+        });
+        agentMessageBus.publish(taskId, replyChannel, `[AGENT_DONE] ${result.output || '子 Agent 已完成'}`);
+    }).catch((err) => {
+        runningAgents.delete(taskId);
+        decrementActiveAgents();
+        logError('spawn_agent.failed', err, {
+            taskId,
+            agentLabel,
+        });
+        agentMessageBus.publish(taskId, replyChannel, `[AGENT_ERROR] ${err.message}`);
+    });
+    const inboxChannel = `agent-inbox:${taskId}`;
+    return [
+        `子 Agent 已在后台启动`,
+        `task_id: ${taskId}`,
+        `角色标签: ${agentLabel}`,
+        `收件箱频道: ${inboxChannel}`,
+        `回复频道: ${replyChannel}`,
+        ``,
+        `使用 send_to_agent 向其发送消息，使用 subscribe_message 订阅 "${replyChannel}" 等待回复。`,
+    ].join('\n');
+}
+export const spawnAgent = {
+    name: 'spawn_agent',
+    description: [
+        '异步启动一个 SubAgent，立即返回 task_id，子 Agent 在后台独立运行。',
+        '与 run_agent 的区别：',
+        '  - run_agent：阻塞等待子 Agent 完成后返回结果（适合一次性子任务）',
+        '  - spawn_agent：立即返回，主 Agent 可继续执行，通过消息总线与子 Agent 双向通信（适合多轮对话）',
+        '',
+        '子 Agent 通信约定：',
+        '  - 主 Agent → 子 Agent：使用 send_to_agent 工具，或向 "agent-inbox:{task_id}" 频道 publish',
+        '  - 子 Agent → 主 Agent：子 Agent 向 "agent-reply:{task_id}" 频道 publish，主 Agent 用 subscribe_message 接收',
+        '  - 子 Agent 的 instruction 中应包含订阅自己 inbox 的指令，例如：',
+        '    "每次回复前先调用 subscribe_message 订阅频道 agent-inbox:{task_id} 获取新问题"',
+        '',
+        '查看后台 Agent 状态：使用 read_channel 工具查看 "agent-reply:{task_id}" 频道历史。',
+    ].join('\n'),
+    parameters: {
+        instruction: {
+            type: 'string',
+            description: [
+                '发给子 Agent 的初始指令。',
+                '若需要多轮交互，指令中应告知子 Agent：',
+                '  1. 订阅频道 "agent-inbox:{task_id}" 等待主 Agent 的消息',
+                '  2. 处理后将回复发布到 "agent-reply:{task_id}" 频道',
+                '  3. 循环执行直到收到结束信号',
+            ].join('\n'),
+            required: true,
+        },
+        role: {
+            type: 'string',
+            description: '可选。子 Agent 的角色描述，例如"你是一个好奇的物理学学生"',
+            required: false,
+        },
+        task_id: {
+            type: 'string',
+            description: '可选。任务唯一标识，建议使用语义化名称如 "student-agent"。不填则自动生成',
+            required: false,
+        },
+        allowed_tools: {
+            type: 'string',
+            description: '可选。逗号分隔的工具名列表，限制子 Agent 可用工具。为空则继承全部工具',
+            required: false,
+        },
+    },
+    execute: async (args) => {
+        const instruction = (args.instruction || '').trim();
+        if (!instruction)
+            throw new Error('缺少必填参数: instruction');
+        const role = (args.role || '').trim() || undefined;
+        const taskId = (args.task_id || '').trim() || uuid();
+        const allowedToolsRaw = (args.allowed_tools || '').trim();
+        const allowedTools = allowedToolsRaw
+            ? allowedToolsRaw.split(',').map((s) => s.trim()).filter(Boolean)
+            : undefined;
+        const agentLabel = resolveAgentLabel(taskId, role);
+        const inboxChannel = `agent-inbox:${taskId}`;
+        const replyChannel = `agent-reply:${taskId}`;
+        // 获取当前 inbox offset（通过 bus 代理，确保跨线程正确）
+        const bus = await getBus();
+        const currentOffset = await bus.getOffset(inboxChannel);
+        const fullInstruction = [
+            role ? `[角色设定] ${role}` : '',
+            '',
+            '[通信约定]',
+            `- 你的收件箱频道：${inboxChannel}`,
+            `- 订阅时必须传入 from_offset: "${currentOffset}"，确保不错过已发布的消息`,
+            `- 你的回复频道：${replyChannel}（用 publish_message 发送回复，agent_id 填 "${taskId}"）`,
+            '',
+            '[任务]',
+            instruction,
+        ].filter((l, i) => i !== 0 || l).join('\n').trim();
+        // 若在主线程（直接调用场景），直接启动
+        if (isMainThread) {
+            return spawnSubAgentInMainThread(taskId, fullInstruction, agentLabel, allowedTools);
+        }
+        // 在 Worker 线程中：通过 IPC 委托主线程创建 SubAgentBridge
+        // SubAgentBridge 必须在主线程运行，才能访问共享的 agentMessageBus 单例
+        if (!parentPort)
+            throw new Error('spawn_agent: 无法访问 parentPort');
+        const requestId = `spawn-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        return new Promise((resolve) => {
+            pendingSpawnRequests.set(requestId, resolve);
+            parentPort.postMessage({
+                type: 'spawn_subagent',
+                requestId,
+                taskId,
+                instruction: fullInstruction,
+                agentLabel,
+                allowedTools,
+            });
+        });
+    },
+};

package/dist/tools/subscribeMessage.d.ts

@@ -0,0 +1,8 @@
+/**
+ * subscribe_message 工具
+ *
+ * 允许 SubAgent 订阅指定频道，阻塞等待下一条消息到达。
+ * 若频道已有历史消息且 read_latest=true，则立即返回最新一条，不阻塞。
+ */
+import { Tool } from '../types/index.js';
+export declare const subscribeMessage: Tool;

package/dist/tools/subscribeMessage.js

@@ -0,0 +1,59 @@
+import { getBus } from '../core/busAccess.js';
+export const subscribeMessage = {
+    name: 'subscribe_message',
+    description: [
+        '订阅指定频道，等待其他 Agent 发布消息后返回内容。',
+        '适用场景：',
+        '  - SubAgent B 等待 SubAgent A 完成并发布结果后再继续执行',
+        '  - 实现 Agent 间的同步协调（生产者-消费者模式）',
+        '  - 读取频道最新历史消息（设置 read_latest=true 时不阻塞）',
+        '注意：默认超时 30 秒，超时后返回 null，Agent 应处理超时情况。',
+    ].join('\n'),
+    parameters: {
+        channel: {
+            type: 'string',
+            description: '要订阅的频道名称',
+            required: true,
+        },
+        read_latest: {
+            type: 'string',
+            description: '可选。设为 "true" 时，若频道已有历史消息则立即返回最新一条，不阻塞等待。默认 false',
+            required: false,
+        },
+        from_offset: {
+            type: 'string',
+            description: '可选。从指定位置（0-based）开始消费。若该位置已有消息则立即返回，否则阻塞等待。用于避免错过在订阅前已发布的消息',
+            required: false,
+        },
+        timeout_seconds: {
+            type: 'string',
+            description: '可选。等待超时秒数，默认 30 秒。超时返回空结果',
+            required: false,
+        },
+    },
+    execute: async (args) => {
+        const channel = (args.channel || '').trim();
+        if (!channel)
+            throw new Error('缺少必填参数: channel');
+        const readLatest = (args.read_latest || '').toLowerCase() === 'true';
+        const timeoutSec = parseInt(args.timeout_seconds || '30', 10);
+        const timeoutMs = Math.max(1000, Math.min(timeoutSec * 1000, 300_000));
+        const fromOffsetRaw = (args.from_offset || '').trim();
+        const fromOffset = fromOffsetRaw !== '' ? parseInt(fromOffsetRaw, 10) : undefined;
+        const bus = await getBus();
+        if (readLatest) {
+            const history = await bus.getHistory(channel, 1);
+            if (history.length === 0)
+                return `频道 "${channel}" 暂无历史消息`;
+            return formatMessage(history[0]);
+        }
+        const msg = await bus.subscribe(channel, timeoutMs, fromOffset);
+        if (!msg)
+            return `订阅频道 "${channel}" 超时（${timeoutSec}s），未收到消息`;
+        return formatMessage(msg);
+    },
+};
+function formatMessage(msg) {
+    const time = new Date(msg.timestamp).toISOString();
+    return `[频道: ${msg.channel}] [来自: ${msg.from}] [时间: ${time}]\n${msg.payload}`;
+}

package/dist/types/index.d.ts

@@ -24,6 +24,8 @@ export interface Message {
     abortHint?: string;
     /** 并行执行组 ID，同组工具同时运行 */
     parallelGroupId?: string;
+    /** 来源 SubAgent 标识，格式如 "ResearchAgent"，用于 UI 前缀展示 */
+    subAgentId?: string;
 }
 export type ContentBlock = {
     type: 'text';
@@ -45,11 +47,18 @@ export interface ToolParameter {
     description: string;
     required?: boolean;
 }
+/** 工具执行时可选的额外回调，用于特殊工具（如 dispatch_subagent）向主线程推送实时事件 */
+export interface ToolCallbacks {
+    /** SubAgent 产生新消息时推送到主线程 UI */
+    onSubAgentMessage?: (msg: Message) => void;
+    /** SubAgent 更新已有消息 */
+    onSubAgentUpdateMessage?: (id: string, updates: Partial<Message>) => void;
+}
 export interface Tool {
     name: string;
     description: string;
     parameters: Record<string, ToolParameter>;
-    execute: (args: Record<string, unknown>, abortSignal?: AbortSignal) => Promise<string>;
+    execute: (args: Record<string, unknown>, abortSignal?: AbortSignal, toolCallbacks?: ToolCallbacks) => Promise<string>;
 }
 export interface Session {
     id: string;
@@ -93,3 +102,42 @@ export interface TranscriptMessage {
 export interface LLMService {
     streamMessage: (transcript: TranscriptMessage[], tools: Tool[], callbacks: StreamCallbacks, abortSignal?: AbortSignal) => Promise<void>;
 }
+/** SubAgent 状态 */
+export type SubAgentStatus = 'idle' | 'running' | 'done' | 'error' | 'aborted';
+/** SubAgent 任务描述 */
+export interface SubAgentTask {
+    /** 任务唯一 ID */
+    taskId: string;
+    /** 任务描述（发给 SubAgent 的指令） */
+    instruction: string;
+    /** 可选：限制 SubAgent 可用的工具名列表（为空则继承全部工具） */
+    allowedTools?: string[];
+    /** 可选：SubAgent 角色描述，注入 system prompt */
+    role?: string;
+    /** 可选：初始上下文 transcript */
+    contextTranscript?: TranscriptMessage[];
+    /** 可选：直接指定 SubAgent 的 system prompt，跳过主 Agent 的 agent 文件加载 */
+    systemPrompt?: string;
+}
+/** SubAgent 执行结果 */
+export interface SubAgentResult {
+    taskId: string;
+    status: 'done' | 'error' | 'aborted';
+    /** 最终输出文本 */
+    output: string;
+    /** 执行过程中产生的消息列表（用于主 Agent 展示） */
+    messages: Message[];
+    /** 更新后的 transcript */
+    transcript: TranscriptMessage[];
+    /** 错误信息（status=error 时） */
+    error?: string;
+}
+/** AgentManager 向外暴露的任务派发回调 */
+export interface AgentManagerCallbacks {
+    /** SubAgent 产生新消息时（用于 UI 展示） */
+    onSubAgentMessage: (taskId: string, msg: Message) => void;
+    /** SubAgent 状态变更 */
+    onSubAgentStatusChange: (taskId: string, status: SubAgentStatus) => void;
+    /** 所有 SubAgent 完成后汇总回调 */
+    onAllDone: (results: SubAgentResult[]) => void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code4bug/jarvis-agent",
-  "version": "1.0.4",
+  "version": "1.1.5",
   "description": "基于 React + TypeScript + Ink 构建的命令行智能体交互界面",
   "type": "module",
   "main": "dist/index.js",