@code4bug/jarvis-agent 1.0.4 → 1.1.4

package/dist/tools/spawnAgent.js

@@ -0,0 +1,163 @@
+/**
+ * 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';
+/** 运行中的 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)) {
+        return `子 Agent [${taskId}] 已在运行中，请使用 send_to_agent 向其发送消息，或使用不同的 task_id 启动新实例。`;
+    }
+    const replyChannel = `agent-reply:${taskId}`;
+    const bridge = new SubAgentBridge();
+    runningAgents.add(taskId);
+    incrementActiveAgents();
+    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();
+        agentMessageBus.publish(taskId, replyChannel, `[AGENT_DONE] ${result.output || '子 Agent 已完成'}`);
+    }).catch((err) => {
+        runningAgents.delete(taskId);
+        decrementActiveAgents();
+        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.4",
   "description": "基于 React + TypeScript + Ink 构建的命令行智能体交互界面",
   "type": "module",
   "main": "dist/index.js",