@code4bug/jarvis-agent 1.0.3 → 1.1.4

package/dist/services/api/mock.d.ts

@@ -1,4 +1,4 @@
-import { LLMService, StreamCallbacks, TranscriptMessage, Tool, AbortSignal as AppAbortSignal } from '../../types/index';
+import { LLMService, StreamCallbacks, TranscriptMessage, Tool, AbortSignal as AppAbortSignal } from '../../types/index.js';
 /**
  * Mock LLM 服务 - 模拟智能体行为，支持工具调用
  */

package/dist/skills/index.d.ts

@@ -9,8 +9,8 @@
  * 如果 skill 目录下存在 skill.py，execute 时直接调用 Python 脚本获取真实结果；
  * 否则回退为返回 skill 指令文本（由 LLM 解释执行）。
  */
-import { Tool } from '../types/index';
-import { SkillDefinition } from './loader';
+import { Tool } from '../types/index.js';
+import { SkillDefinition } from './loader.js';
 /** 加载所有外部 skills（带缓存） */
 export declare function loadExternalSkills(): SkillDefinition[];
 /** 获取合并后的所有工具：内置 tools + 外部 skills */

package/dist/skills/index.js

@@ -12,8 +12,8 @@
 import { exec } from 'child_process';
 import fs from 'fs';
 import path from 'path';
-import { scanExternalSkills, getExternalSkillsDir } from './loader';
-import { allTools as builtinTools } from '../tools/index';
+import { scanExternalSkills, getExternalSkillsDir } from './loader.js';
+import { allTools as builtinTools } from '../tools/index.js';
 // ===== 缓存 =====
 let _skillCache = null;
 let _mergedTools = null;

package/dist/tools/createSkill.d.ts

@@ -4,5 +4,5 @@
  * 根据用户需求，调用 LLM 基于 SKILL_INSTRUCTIONS.md 规范自动生成 skill，
  * 并写入 ~/.jarvis/skills/ 目录。
  */
-import { Tool } from '../types/index';
+import { Tool } from '../types/index.js';
 export declare const createSkill: Tool;

package/dist/tools/createSkill.js

@@ -7,9 +7,9 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import { getExternalSkillsDir } from '../skills/loader';
-import { reloadSkills } from '../skills/index';
-import { LLMServiceImpl, getDefaultConfig } from '../services/api/llm';
+import { getExternalSkillsDir } from '../skills/loader.js';
+import { reloadSkills } from '../skills/index.js';
+import { LLMServiceImpl, getDefaultConfig } from '../services/api/llm.js';
 // SKILL_INSTRUCTIONS.md 查找路径：项目根目录 > 用户主目录
 function loadSkillInstructions() {
     const candidates = [

package/dist/tools/index.d.ts

@@ -1,12 +1,18 @@
-import { Tool } from '../types/index';
-import { readFile } from './readFile';
-import { writeFile } from './writeFile';
-import { runCommand } from './runCommand';
-import { listDirectory } from './listDirectory';
-import { searchFiles } from './searchFiles';
-import { semanticSearch } from './semanticSearch';
-import { createSkill } from './createSkill';
-export { readFile, writeFile, runCommand, listDirectory, searchFiles, semanticSearch, createSkill };
+import { Tool } from '../types/index.js';
+import { readFile } from './readFile.js';
+import { writeFile } from './writeFile.js';
+import { runCommand } from './runCommand.js';
+import { listDirectory } from './listDirectory.js';
+import { searchFiles } from './searchFiles.js';
+import { semanticSearch } from './semanticSearch.js';
+import { createSkill } from './createSkill.js';
+import { runAgent } from './runAgent.js';
+import { spawnAgent } from './spawnAgent.js';
+import { sendToAgent } from './sendToAgent.js';
+import { publishMessage } from './publishMessage.js';
+import { subscribeMessage } from './subscribeMessage.js';
+import { readChannel } from './readChannel.js';
+export { readFile, writeFile, runCommand, listDirectory, searchFiles, semanticSearch, createSkill, runAgent, spawnAgent, sendToAgent, publishMessage, subscribeMessage, readChannel, };
 /** 所有内置工具 */
 export declare const allTools: Tool[];
 /** 按名称查找内置工具 */

package/dist/tools/index.js

@@ -1,19 +1,30 @@
-import { readFile } from './readFile';
-import { writeFile } from './writeFile';
-import { runCommand } from './runCommand';
-import { listDirectory } from './listDirectory';
-import { searchFiles } from './searchFiles';
-import { semanticSearch } from './semanticSearch';
-import { createSkill } from './createSkill';
-export { readFile, writeFile, runCommand, listDirectory, searchFiles, semanticSearch, createSkill };
+import { readFile } from './readFile.js';
+import { writeFile } from './writeFile.js';
+import { runCommand } from './runCommand.js';
+import { listDirectory } from './listDirectory.js';
+import { searchFiles } from './searchFiles.js';
+import { semanticSearch } from './semanticSearch.js';
+import { createSkill } from './createSkill.js';
+import { runAgent } from './runAgent.js';
+import { spawnAgent } from './spawnAgent.js';
+import { sendToAgent } from './sendToAgent.js';
+import { publishMessage } from './publishMessage.js';
+import { subscribeMessage } from './subscribeMessage.js';
+import { readChannel } from './readChannel.js';
+export { readFile, writeFile, runCommand, listDirectory, searchFiles, semanticSearch, createSkill, runAgent, spawnAgent, sendToAgent, publishMessage, subscribeMessage, readChannel, };
 /** 所有内置工具 */
-export const allTools = [readFile, writeFile, runCommand, listDirectory, searchFiles, semanticSearch, createSkill];
+export const allTools = [
+    readFile, writeFile, runCommand, listDirectory, searchFiles,
+    semanticSearch, createSkill,
+    runAgent, spawnAgent, sendToAgent,
+    publishMessage, subscribeMessage, readChannel,
+];
 /** 按名称查找内置工具 */
 export function findTool(name) {
     return allTools.find((t) => t.name === name);
 }
 // ===== 合并工具（内置 + 外部 Skills）=====
-import { getMergedTools, findMergedTool } from '../skills/index';
+import { getMergedTools, findMergedTool } from '../skills/index.js';
 /** 获取所有工具（内置 + 外部 skills），供 QueryEngine 使用 */
 export function getAllTools() {
     return getMergedTools();

package/dist/tools/listDirectory.d.ts

@@ -1,2 +1,2 @@
-import { Tool } from '../types/index';
+import { Tool } from '../types/index.js';
 export declare const listDirectory: Tool;

package/dist/tools/publishMessage.d.ts

@@ -0,0 +1,8 @@
+/**
+ * publish_message 工具
+ *
+ * 允许 SubAgent（或主 Agent）向命名频道发布消息，
+ * 其他正在订阅该频道的 Agent 会立即收到通知。
+ */
+import { Tool } from '../types/index.js';
+export declare const publishMessage: Tool;

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/readFile.d.ts

@@ -1,2 +1,2 @@
-import { Tool } from '../types/index';
+import { Tool } from '../types/index.js';
 export declare const readFile: Tool;

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.d.ts

@@ -1,2 +1,2 @@
-import { Tool } from '../types/index';
+import { Tool } from '../types/index.js';
 export declare const runCommand: Tool;

package/dist/tools/runCommand.js

@@ -1,5 +1,5 @@
 import { exec } from 'child_process';
-import { sanitizeOutput } from '../core/safeguard';
+import { sanitizeOutput } from '../core/safeguard.js';
 /**
  * 异步执行命令，支持通过 abortSignal 中断子进程
  */

package/dist/tools/searchFiles.d.ts

@@ -1,2 +1,2 @@
-import { Tool } from '../types/index';
+import { Tool } from '../types/index.js';
 export declare const searchFiles: Tool;

package/dist/tools/semanticSearch.d.ts

@@ -5,5 +5,5 @@
  * 再用扩展后的词集合在文件中进行匹配搜索，实现"相似搜索"能力。
  * 未配置大模型时降级为普通关键词搜索。
  */
-import { Tool } from '../types/index';
+import { Tool } from '../types/index.js';
 export declare const semanticSearch: Tool;

package/dist/tools/semanticSearch.js

@@ -7,7 +7,7 @@
  */
 import fs from 'fs';
 import path from 'path';
-import { loadConfig, getActiveModel } from '../config/loader';
+import { loadConfig, getActiveModel } from '../config/loader.js';
 /** 通过 LLM 扩展关键词，返回扩展后的词列表（含原始关键词） */
 async function expandKeywords(keyword) {
     const config = loadConfig();

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,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;