@code4bug/jarvis-agent 1.0.3 → 1.1.4

package/README.md

@@ -32,9 +32,48 @@
 - 内置工具系统：文件读写、命令执行、目录浏览、内容搜索
 - 外部 Skill 扩展机制，支持 Python 脚本作为工具
 - 多智能体切换，通过 Markdown 定义智能体人格与能力
+- 多智能体通信，支持智能体之间分工、协同与结果汇总
 - 会话持久化，自动保存历史与 Token 消耗统计
 - 安全围栏，危险命令自动拦截并交互式确认
 - 终端 UI 优化，清晰的状态指示与结构化消息展示
+- **并行任务执行**，多工具调用自动并行，显著提升执行效率
+
+## 并行任务
+
+当 LLM 在单轮推理中返回多个工具调用时，Jarvis 会自动判断是否可以并行执行，而不是逐个串行等待。
+
+### 工作原理
+
+```
+LLM 返回多个工具调用
+        ↓
+  canRunInParallel() 判断
+        ↓
+  ┌─────────────────────────────┐
+  │ 可并行（全部为只读操作）      │  → 每个工具在独立 Worker 线程中同时执行
+  │ 不可并行（含写操作/Bash）     │  → 串行执行，保证顺序与安全
+  └─────────────────────────────┘
+        ↓
+  所有结果汇总后统一写入 transcript
+```
+
+每个并行工具运行在独立的 Node.js Worker 线程中（`worker_threads`），主线程不阻塞，TUI 实时更新每个工具的执行状态。
+
+### 并行条件
+
+| 场景 | 是否并行 |
+|------|----------|
+| 多个只读工具（ReadFile / ListDirectory / SearchFiles / SemanticSearch） | 是 |
+| 含任意写操作（WriteFile） | 否 |
+| 含 Bash 命令 | 否（副作用无法静态分析） |
+| 多个只读 Skill | 是 |
+
+### 安全保障
+
+- 写-写冲突、读-写竞态：通过工具类型静态分析提前规避
+- 并行模式下的危险 Bash 命令：直接跳过并提示（无法弹出交互式确认）
+- 任意工具出错：终止当前轮次，不影响已完成的并行结果
+- 用户按 ESC 中断：所有正在运行的 Worker 均收到中断信号
 
 ## 快速开始
 
@@ -144,6 +183,30 @@ src/
 
 运行时通过 `/agent <name>` 切换，选择会持久化到 `~/.jarvis/agent.json`。
 
+## 多智能体通信
+
+Jarvis 在多智能体能力基础上进一步支持智能体之间的通信与协作，不再局限于单个智能体独立完成任务。
+
+这不只是能力的叠加，而是一种协作方式的跃迁。一个智能体擅长理解需求，另一个智能体擅长架构设计，还有智能体专注编码、测试、评审与复盘。当它们开始彼此沟通、相互补位，整个系统就不再只是“一个 AI 在工作”，而像是一支真正持续运转的数字化团队。
+
+你可以让不同角色的智能体围绕同一目标协同工作，例如：
+
+- 产品经理智能体负责拆解需求、输出任务边界
+- 架构师智能体负责设计技术方案与模块划分
+- 开发智能体负责编码实现与联调
+- 测试智能体负责验证、回归与问题反馈
+
+通过多智能体通信机制，多个智能体可以围绕同一上下文进行信息传递、任务接力和结果汇总，从而搭配实现各种多人协作场景构建。
+
+从单点问答，到多角色联动；从工具调用，到团队协作流程编排。多智能体带来的不是简单的“多开几个助手”，而是面向复杂任务的组织能力升级，也为产品构建、研发协同、流程自动化打开了近乎无限的可能。
+
+适用场景包括：
+
+- 需求分析 + 方案设计 + 开发落地的一体化协作流程
+- 前端、后端、测试等不同角色的分工配合
+- 代码评审、缺陷修复、回归验证的闭环协同
+- 模拟真实团队的多人协作交付流程
+
 详见 [AGENT_INSTRUCTIONS.md](./AGENT_INSTRUCTIONS.md)。
 
 ## Skill 扩展

package/dist/agents/jarvis.md

@@ -33,6 +33,17 @@ vibe: 你的全能助手，有问必答，随时待命。
 - 技术选型建议与对比分析
 - API 设计与数据模型规划
 
+### 多智能体协作与对话模拟
+- 使用 `start_agent` 异步启动后台子 Agent，立即返回 `task_id`，不阻塞主流程
+- 使用 `send_to_agent` 向指定子 Agent 发送消息（主 Agent → 子 Agent）
+- 使用 `subscribe_message` 订阅 `agent-reply:{task_id}` 频道等待子 Agent 回复
+- 使用 `create_subagent` 启动一次性子任务（阻塞等待结果）
+- 多轮对话模式（如老师-学生）：
+  1. `start_agent` 启动子 Agent，instruction 中告知其订阅 inbox 并循环回复
+  2. `send_to_agent` 发送第一条消息
+  3. `subscribe_message` 等待回复，读取后继续发下一条
+  4. 发送约定的结束信号（如 `[END]`）终止子 Agent 循环
+
 ### 脚本执行与自动化
 - 通过 Bash 工具直接执行 Shell 命令和脚本（`Bash(command)`）
 - 支持执行 Python / Node.js / Shell 等脚本文件

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { APP_VERSION } from './config/constants';
-import { startJarvis } from './index';
+import { APP_VERSION } from './config/constants.js';
+import { startJarvis } from './index.js';
 const arg = process.argv[2];
 if (arg === '--version' || arg === '-v' || arg === 'version') {
     console.log(APP_VERSION);

package/dist/commands/index.js

@@ -26,8 +26,8 @@ const toolCommands = [
     { name: 'create_skill', description: '创建新的 Skill 到 ~/.jarvis/skills/', category: 'builtin' },
 ];
 /** 智能体子命令：从 agents 目录动态加载（二级菜单） */
-import { loadAllAgents } from '../agents/index';
-import { listSkills } from '../skills/index';
+import { loadAllAgents } from '../agents/index.js';
+import { listSkills } from '../skills/index.js';
 let _agentSubCommands = null;
 export function getAgentSubCommands() {
     if (_agentSubCommands)

package/dist/commands/init.js

@@ -7,7 +7,7 @@
 import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
-import { APP_NAME, APP_VERSION } from '../config/constants';
+import { APP_NAME, APP_VERSION } from '../config/constants.js';
 // ===== 辅助函数 =====
 /** 安全执行命令 */
 function safeExec(cmd) {

package/dist/components/MessageItem.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Message } from '../types/index';
+import { Message } from '../types/index.js';
 declare function MessageItem({ msg, showDetails }: {
     msg: Message;
     showDetails?: boolean;

package/dist/components/MessageItem.js

@@ -1,8 +1,8 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import React from 'react';
 import { Box, Text } from 'ink';
 import Spinner from 'ink-spinner';
-import MarkdownText from './MarkdownText';
+import MarkdownText from './MarkdownText.js';
 // 状态圆点 icon，根据消息类型 + 状态决定颜色
 // reasoning 完成 → 白色 / tool_exec 成功 → 绿色 / error → 红色 / aborted → 黄色 / pending → 黄色
 function statusDot(status, type) {
@@ -52,7 +52,7 @@ function MessageItem({ msg, showDetails = false }) {
     }
     // thinking 完成后持久化渲染，Ctrl+O 展开/折叠
     if (msg.type === 'thinking' && msg.status === 'success' && msg.think) {
-        return (_jsxs(Box, { flexDirection: "column", marginBottom: 0, children: [_jsxs(Box, { children: [_jsxs(Text, { color: "cyan", children: ['○', " "] }), _jsx(Text, { color: "gray", children: "Thinking" }), _jsxs(Text, { color: "gray", dimColor: true, children: [" (", msg.think.length, " chars)"] }), !showDetails && _jsx(Text, { color: "gray", dimColor: true, children: "  [Ctrl+O \u5C55\u5F00]" })] }), showDetails && (_jsx(Box, { marginLeft: 2, flexDirection: "column", children: _jsx(Text, { color: "gray", dimColor: true, wrap: "wrap", children: msg.think }) }))] }));
+        return (_jsxs(Box, { flexDirection: "column", marginBottom: 0, children: [_jsxs(Box, { children: [_jsxs(Text, { color: "cyan", children: ['○', " "] }), msg.subAgentId && (_jsxs(Text, { color: "blue", dimColor: true, children: [msg.subAgentId, " \u203A "] })), _jsx(Text, { color: "gray", children: "Thinking" }), _jsxs(Text, { color: "gray", dimColor: true, children: [" (", msg.think.length, " chars)"] }), !showDetails && _jsx(Text, { color: "gray", dimColor: true, children: "  [Ctrl+O \u5C55\u5F00]" })] }), showDetails && (_jsx(Box, { marginLeft: 2, flexDirection: "column", children: _jsx(Text, { color: "gray", dimColor: true, wrap: "wrap", children: msg.think }) }))] }));
     }
     if (msg.type === 'tool_exec') {
         // Bash 工具直接显示命令内容
@@ -67,16 +67,20 @@ function MessageItem({ msg, showDetails = false }) {
         const toolLabel = isBash && bashCmd ? `Bash(${bashCmd})` : (msg.toolName || 'tool');
         // 并行组标识
         const isParallel = !!msg.parallelGroupId;
-        return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { children: [isParallel && _jsx(Text, { color: "cyan", dimColor: true, children: "\u21C9 " }), _jsxs(Text, { color: dotColor, children: [dot, " "] }), isBash && bashCmd ? (_jsxs(Text, { children: [_jsx(Text, { color: "white", bold: true, children: "Bash" }), _jsxs(Text, { color: "gray", children: ["(", bashCmd, ")"] })] })) : isSkill ? (_jsxs(Text, { children: [_jsx(Text, { color: "cyan", bold: true, children: skillName }), _jsxs(Text, { color: "gray", children: ["(", skillArgsSummary, ")"] })] })) : (_jsx(Text, { color: "magenta", bold: true, children: toolLabel }))] }), showDetails && msg.toolArgs && !isBash && (_jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "gray", dimColor: true, wrap: "wrap", children: JSON.stringify(msg.toolArgs) }) })), showDetails && msg.toolResult && (_jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "gray", wrap: "wrap", children: msg.toolResult.length > 300 ? msg.toolResult.slice(0, 300) + '…' : msg.toolResult }) })), _jsx(MessageStats, { msg: msg, show: showDetails })] }));
+        // SubAgent 前缀，例如 "代码审查Agent"
+        const subAgentPrefix = msg.subAgentId ? `${msg.subAgentId} - ` : '';
+        return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { children: [isParallel && _jsx(Text, { color: "cyan", dimColor: true, children: "\u21C9 " }), _jsxs(Text, { color: dotColor, children: [dot, " "] }), subAgentPrefix ? (_jsx(Text, { color: "blue", dimColor: true, children: subAgentPrefix })) : null, isBash && bashCmd ? (_jsxs(Text, { children: [_jsx(Text, { color: "white", bold: true, children: "Bash" }), _jsxs(Text, { color: "gray", children: ["(", bashCmd, ")"] })] })) : isSkill ? (_jsxs(Text, { children: [_jsx(Text, { color: "cyan", bold: true, children: skillName }), _jsxs(Text, { color: "gray", children: ["(", skillArgsSummary, ")"] })] })) : (_jsx(Text, { color: "magenta", bold: true, children: toolLabel }))] }), showDetails && msg.toolArgs && !isBash && (_jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "gray", dimColor: true, wrap: "wrap", children: JSON.stringify(msg.toolArgs) }) })), showDetails && msg.toolResult && (_jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "gray", wrap: "wrap", children: msg.toolResult.length > 300 ? msg.toolResult.slice(0, 300) + '…' : msg.toolResult }) })), _jsx(MessageStats, { msg: msg, show: showDetails })] }));
     }
     if (msg.type === 'error') {
         return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Text, { color: "red", children: [_jsx(Text, { color: dotColor, children: dot }), " ", msg.content] }), _jsx(MessageStats, { msg: msg, show: showDetails })] }));
     }
     if (msg.type === 'reasoning') {
-        return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: dotColor, children: dot }), _jsx(Box, { marginLeft: 1, children: _jsx(MarkdownText, { text: msg.content }) })] }), _jsx(MessageStats, { msg: msg, show: showDetails })] }));
+        return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [msg.subAgentId ? (
+                // 有 subAgentId 时：标题行 + 内容分两行，避免内容粘连
+                _jsxs(_Fragment, { children: [_jsxs(Box, { children: [_jsxs(Text, { color: dotColor, children: [dot, " "] }), _jsxs(Text, { color: "blue", dimColor: true, children: [msg.subAgentId, " \u203A "] })] }), _jsx(Box, { marginLeft: 2, flexDirection: "column", children: _jsx(MarkdownText, { text: msg.content }) })] })) : (_jsxs(Box, { flexDirection: "row", alignItems: "flex-start", children: [_jsxs(Text, { color: dotColor, children: [dot, " "] }), _jsx(Box, { flexDirection: "column", flexShrink: 1, children: _jsx(MarkdownText, { text: msg.content }) })] })), _jsx(MessageStats, { msg: msg, show: showDetails })] }));
     }
     if (msg.status !== 'pending' && msg.content) {
-        return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: dotColor, children: dot }), _jsx(Box, { marginLeft: 1, children: _jsx(MarkdownText, { text: msg.content, color: "gray" }) })] }), _jsx(MessageStats, { msg: msg, show: showDetails })] }));
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: dotColor, children: dot }), _jsx(Box, { marginLeft: 2, flexDirection: "column", children: _jsx(MarkdownText, { text: msg.content, color: "gray" }) }), _jsx(MessageStats, { msg: msg, show: showDetails })] }));
     }
     return null;
 }

package/dist/components/SlashCommandMenu.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { SlashCommand } from '../commands/index';
+import { SlashCommand } from '../commands/index.js';
 interface SlashCommandMenuProps {
     commands: SlashCommand[];
     selectedIndex: number;

package/dist/components/StatusBar.d.ts

@@ -2,7 +2,8 @@ import React from 'react';
 interface StatusBarProps {
     width: number;
     totalTokens: number;
+    activeAgents?: number;
 }
-declare function StatusBar({ width, totalTokens }: StatusBarProps): import("react/jsx-runtime").JSX.Element;
+declare function StatusBar({ width, totalTokens, activeAgents }: StatusBarProps): import("react/jsx-runtime").JSX.Element;
 declare const _default: React.MemoExoticComponent<typeof StatusBar>;
 export default _default;

package/dist/components/StatusBar.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from 'react';
 import { Box, Text } from 'ink';
-import { MODEL_NAME, PROJECT_NAME, ENABLE_THINKING_MODE_TOGGLE, CONTEXT_TOKEN_LIMIT } from '../config/constants';
+import { MODEL_NAME, PROJECT_NAME, ENABLE_THINKING_MODE_TOGGLE, CONTEXT_TOKEN_LIMIT } from '../config/constants.js';
 /** 生成 token 用量进度条 */
 function tokenProgressBar(used, limit, barWidth) {
     const ratio = Math.min(used / limit, 1);
@@ -11,16 +11,17 @@ function tokenProgressBar(used, limit, barWidth) {
     const color = ratio >= 0.9 ? 'red' : ratio >= 0.7 ? 'yellow' : 'green';
     return { bar, color };
 }
-function StatusBar({ width, totalTokens }) {
+function StatusBar({ width, totalTokens, activeAgents = 0 }) {
     const left = ` ${MODEL_NAME} │ ${PROJECT_NAME}`;
-    // 右侧：token 进度条 + 思考模式切换（可选）
+    // 右侧：智能体数量（有后台 Agent 时显示）+ token 进度条 + 思考模式切换（可选）
+    const agentPart = activeAgents > 0 ? `⬡ ${activeAgents} agent${activeAgents > 1 ? 's' : ''} │ ` : '';
     const tokenLabel = `${totalTokens}/${CONTEXT_TOKEN_LIMIT}`;
     const barWidth = 10;
     const { bar, color } = tokenProgressBar(totalTokens, CONTEXT_TOKEN_LIMIT, barWidth);
     const effortPart = ENABLE_THINKING_MODE_TOGGLE ? ' │ ● medium · /effort' : '';
     // 右侧完整文本长度（用于计算间距）
-    const rightLen = tokenLabel.length + 1 + barWidth + effortPart.length + 1;
+    const rightLen = agentPart.length + tokenLabel.length + 1 + barWidth + effortPart.length + 1;
     const gap = Math.max(width - left.length - rightLen, 1);
-    return (_jsxs(Box, { children: [_jsx(Text, { color: "gray", children: left }), _jsx(Text, { children: ' '.repeat(gap) }), _jsxs(Text, { color: "gray", children: [tokenLabel, " "] }), _jsx(Text, { color: color, children: bar }), ENABLE_THINKING_MODE_TOGGLE && _jsx(Text, { color: "gray", children: effortPart }), _jsx(Text, { children: " " })] }));
+    return (_jsxs(Box, { children: [_jsx(Text, { color: "gray", children: left }), _jsx(Text, { children: ' '.repeat(gap) }), activeAgents > 0 && _jsx(Text, { color: "cyan", children: agentPart }), _jsxs(Text, { color: "gray", children: [tokenLabel, " "] }), _jsx(Text, { color: color, children: bar }), ENABLE_THINKING_MODE_TOGGLE && _jsx(Text, { color: "gray", children: effortPart }), _jsx(Text, { children: " " })] }));
 }
 export default React.memo(StatusBar);

package/dist/components/StreamingText.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from 'react';
 import { Box, Text } from 'ink';
-import MarkdownText from './MarkdownText';
+import MarkdownText from './MarkdownText.js';
 function StreamingText({ text }) {
     if (!text)
         return null;

package/dist/components/WelcomeHeader.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from 'react';
 import { Box, Text } from 'ink';
-import { APP_NAME, APP_VERSION, MODEL_NAME } from '../config/constants';
+import { APP_NAME, APP_VERSION, MODEL_NAME } from '../config/constants.js';
 function truncatePath(p, max) {
     if (p.length <= max)
         return p;

package/dist/config/constants.js

@@ -24,7 +24,7 @@ export const SESSIONS_DIR = path.join(os.homedir(), '.jarvis', 'sessions');
 /** 输入后是否隐藏 WelcomeHeader，默认 false（不隐藏） */
 export const HIDE_WELCOME_AFTER_INPUT = false;
 /** 从配置文件获取当前模型名称 */
-import { loadConfig, getActiveModel } from './loader';
+import { loadConfig, getActiveModel } from './loader.js';
 const _cfg = loadConfig();
 function resolveModelName() {
     try {
@@ -50,8 +50,8 @@ export const DEFAULT_AGENT_COLOR = 'green';
 /** 智能体默认标识符 */
 export const DEFAULT_AGENT_EMOJI = '>';
 // ===== 动态应用名称（跟随激活智能体） =====
-import { getAgent } from '../agents/index';
-import { getActiveAgent } from './agentState';
+import { getAgent } from '../agents/index.js';
+import { getActiveAgent } from './agentState.js';
 /** 当前激活的智能体名称 — 启动时从 ~/.jarvis/agent.json 读取，运行时可切换 */
 export const DEFAULT_AGENT = getActiveAgent(DEFAULT_AGENT_FALLBACK);
 function resolveAppName() {

package/dist/core/AgentMessageBus.d.ts

@@ -0,0 +1,63 @@
+/**
+ * AgentMessageBus — SubAgent 间通讯总线（进程内单例）
+ *
+ * 提供发布/订阅机制，允许：
+ *   - SubAgent 向命名频道发布消息
+ *   - SubAgent 订阅频道，等待其他 Agent 发布的消息
+ *   - 主 Agent 观察所有频道历史
+ *
+ * 线程安全说明：
+ *   Node.js Worker 线程之间不共享内存，因此 MessageBus 运行在
+ *   主线程（queryWorker）中，SubAgent Worker 通过 IPC 消息与其交互。
+ *   SubAgentBridge 负责在主线程侧代理 publish/subscribe 请求。
+ */
+export interface BusMessage {
+    /** 发布者 Agent 标识 */
+    from: string;
+    /** 频道名 */
+    channel: string;
+    /** 消息内容 */
+    payload: string;
+    /** 发布时间戳 */
+    timestamp: number;
+}
+declare class AgentMessageBus {
+    /** 频道历史消息，key = channel */
+    private history;
+    /** 订阅者，key = channel，value = 等待中的 resolve 列表 */
+    private waiters;
+    /**
+     * 向频道发布消息
+     * @param from 发布者标识（agentId / taskId）
+     * @param channel 频道名
+     * @param payload 消息内容
+     */
+    publish(from: string, channel: string, payload: string): void;
+    /**
+     * 订阅频道，返回下一条消息（Promise）
+     * - 若 fromOffset 指定，且历史中该 offset 之后已有消息，立即返回（不阻塞）
+     * - 否则阻塞等待新消息到达
+     * @param channel 频道名
+     * @param timeoutMs 超时毫秒，默认 30s，超时返回 null
+     * @param fromOffset 从第几条开始消费（0-based），不传则只等新消息
+     */
+    subscribe(channel: string, timeoutMs?: number, fromOffset?: number): Promise<BusMessage | null>;
+    /**
+     * 获取频道当前消息总数（用于记录 offset）
+     */
+    getOffset(channel: string): number;
+    /**
+     * 读取频道历史消息（不阻塞）
+     * @param channel 频道名
+     * @param limit 最多返回条数，默认全部
+     */
+    getHistory(channel: string, limit?: number): BusMessage[];
+    /** 列出所有活跃频道 */
+    listChannels(): string[];
+    /** 清空指定频道（测试用） */
+    clearChannel(channel: string): void;
+    /** 清空所有频道 */
+    clearAll(): void;
+}
+export declare const agentMessageBus: AgentMessageBus;
+export {};

package/dist/core/AgentMessageBus.js

@@ -0,0 +1,107 @@
+/**
+ * AgentMessageBus — SubAgent 间通讯总线（进程内单例）
+ *
+ * 提供发布/订阅机制，允许：
+ *   - SubAgent 向命名频道发布消息
+ *   - SubAgent 订阅频道，等待其他 Agent 发布的消息
+ *   - 主 Agent 观察所有频道历史
+ *
+ * 线程安全说明：
+ *   Node.js Worker 线程之间不共享内存，因此 MessageBus 运行在
+ *   主线程（queryWorker）中，SubAgent Worker 通过 IPC 消息与其交互。
+ *   SubAgentBridge 负责在主线程侧代理 publish/subscribe 请求。
+ */
+class AgentMessageBus {
+    /** 频道历史消息，key = channel */
+    history = new Map();
+    /** 订阅者，key = channel，value = 等待中的 resolve 列表 */
+    waiters = new Map();
+    /**
+     * 向频道发布消息
+     * @param from 发布者标识（agentId / taskId）
+     * @param channel 频道名
+     * @param payload 消息内容
+     */
+    publish(from, channel, payload) {
+        const msg = { from, channel, payload, timestamp: Date.now() };
+        // 存入历史
+        if (!this.history.has(channel))
+            this.history.set(channel, []);
+        this.history.get(channel).push(msg);
+        // 通知等待中的订阅者
+        const waiters = this.waiters.get(channel);
+        if (waiters && waiters.length > 0) {
+            const toNotify = [...waiters];
+            // 移除 once 订阅者
+            this.waiters.set(channel, waiters.filter((w) => !w.once));
+            for (const w of toNotify) {
+                w.resolve(msg);
+            }
+        }
+    }
+    /**
+     * 订阅频道，返回下一条消息（Promise）
+     * - 若 fromOffset 指定，且历史中该 offset 之后已有消息，立即返回（不阻塞）
+     * - 否则阻塞等待新消息到达
+     * @param channel 频道名
+     * @param timeoutMs 超时毫秒，默认 30s，超时返回 null
+     * @param fromOffset 从第几条开始消费（0-based），不传则只等新消息
+     */
+    subscribe(channel, timeoutMs = 30_000, fromOffset) {
+        // 如果指定了 offset 且历史中已有该位置之后的消息，立即返回
+        if (fromOffset !== undefined) {
+            const history = this.history.get(channel) ?? [];
+            if (fromOffset < history.length) {
+                return Promise.resolve(history[fromOffset]);
+            }
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                // 超时：从等待列表移除
+                const list = this.waiters.get(channel);
+                if (list) {
+                    this.waiters.set(channel, list.filter((w) => w.resolve !== resolve));
+                }
+                resolve(null);
+            }, timeoutMs);
+            const wrappedResolve = (msg) => {
+                clearTimeout(timer);
+                resolve(msg);
+            };
+            if (!this.waiters.has(channel))
+                this.waiters.set(channel, []);
+            this.waiters.get(channel).push({ resolve: wrappedResolve, once: true });
+        });
+    }
+    /**
+     * 获取频道当前消息总数（用于记录 offset）
+     */
+    getOffset(channel) {
+        return (this.history.get(channel) ?? []).length;
+    }
+    /**
+     * 读取频道历史消息（不阻塞）
+     * @param channel 频道名
+     * @param limit 最多返回条数，默认全部
+     */
+    getHistory(channel, limit) {
+        const msgs = this.history.get(channel) ?? [];
+        return limit ? msgs.slice(-limit) : [...msgs];
+    }
+    /** 列出所有活跃频道 */
+    listChannels() {
+        return [...this.history.keys()];
+    }
+    /** 清空指定频道（测试用） */
+    clearChannel(channel) {
+        this.history.delete(channel);
+        this.waiters.delete(channel);
+    }
+    /** 清空所有频道 */
+    clearAll() {
+        this.history.clear();
+        this.waiters.clear();
+    }
+}
+// 进程内单例
+export const agentMessageBus = new AgentMessageBus();

package/dist/core/AgentRegistry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AgentUIBus — 后台子 Agent 向 UI 推送消息的持久通道
+ *
+ * 解决问题：spawn_agent 启动的后台子 Agent 生命周期跨越多个 queryWorker，
+ * 而 toolCallbacks 只在单次 LLM 调用期间有效。
+ *
+ * 方案：后台子 Agent 的消息通过此模块的全局回调推送，
+ * QueryEngine 在初始化时注册回调，生命周期与应用一致。
+ */
+import { Message } from '../types/index.js';
+type UIMessageCallback = (msg: Message) => void;
+type UIUpdateCallback = (id: string, updates: Partial<Message>) => void;
+declare class AgentUIBus {
+    private onMessage;
+    private onUpdateMessage;
+    /** QueryEngine 初始化时注册，生命周期与应用一致 */
+    register(onMessage: UIMessageCallback, onUpdateMessage: UIUpdateCallback): void;
+    push(msg: Message): void;
+    update(id: string, updates: Partial<Message>): void;
+}
+export declare const agentUIBus: AgentUIBus;
+export {};

package/dist/core/AgentRegistry.js

@@ -0,0 +1,16 @@
+class AgentUIBus {
+    onMessage = null;
+    onUpdateMessage = null;
+    /** QueryEngine 初始化时注册，生命周期与应用一致 */
+    register(onMessage, onUpdateMessage) {
+        this.onMessage = onMessage;
+        this.onUpdateMessage = onUpdateMessage;
+    }
+    push(msg) {
+        this.onMessage?.(msg);
+    }
+    update(id, updates) {
+        this.onUpdateMessage?.(id, updates);
+    }
+}
+export const agentUIBus = new AgentUIBus();

package/dist/core/QueryEngine.d.ts

@@ -1,5 +1,5 @@
 import { Message, Session, LoopState } from '../types/index.js';
-import { DangerConfirmResult } from './query';
+import { DangerConfirmResult } from './query.js';
 export interface EngineCallbacks {
     onMessage: (msg: Message) => void;
     onUpdateMessage: (id: string, updates: Partial<Message>) => void;
@@ -10,6 +10,10 @@ export interface EngineCallbacks {
     onSessionUpdate: (session: Session) => void;
     /** 危险命令交互式确认 */
     onConfirmDangerousCommand?: (command: string, reason: string, ruleName: string) => Promise<DangerConfirmResult>;
+    /** SubAgent 产生消息时推送到 UI（带 subAgentId 前缀） */
+    onSubAgentMessage?: (msg: Message) => void;
+    /** SubAgent 更新已有消息 */
+    onSubAgentUpdateMessage?: (id: string, updates: Partial<Message>) => void;
 }
 export declare class QueryEngine {
     private service;
@@ -17,6 +21,8 @@ export declare class QueryEngine {
     private transcript;
     private workerBridge;
     constructor();
+    /** 注册持久 UI 回调，供后台 spawn_agent 子 Agent 推送消息 */
+    registerUIBus(onMessage: (msg: Message) => void, onUpdateMessage: (id: string, updates: Partial<Message>) => void): void;
     private createSession;
     private ensureSessionDir;
     /** 处理用户输入（在独立 Worker 线程中执行） */

package/dist/core/QueryEngine.js

@@ -1,13 +1,14 @@
 import { v4 as uuid } from 'uuid';
 import fs from 'fs';
 import path from 'path';
-import { WorkerBridge } from './WorkerBridge';
-import { MockService } from '../services/api/mock';
-import { LLMServiceImpl } from '../services/api/llm';
-import { loadConfig, getActiveModel } from '../config/loader';
-import { SESSIONS_DIR } from '../config/constants';
-import { setActiveAgent } from '../config/agentState';
-import { clearAuthorizations } from './safeguard';
+import { WorkerBridge } from './WorkerBridge.js';
+import { MockService } from '../services/api/mock.js';
+import { LLMServiceImpl } from '../services/api/llm.js';
+import { loadConfig, getActiveModel } from '../config/loader.js';
+import { SESSIONS_DIR } from '../config/constants.js';
+import { setActiveAgent } from '../config/agentState.js';
+import { clearAuthorizations } from './safeguard.js';
+import { agentUIBus } from './AgentRegistry.js';
 export class QueryEngine {
     service;
     session;
@@ -31,6 +32,10 @@ export class QueryEngine {
         this.session = this.createSession();
         this.ensureSessionDir();
     }
+    /** 注册持久 UI 回调，供后台 spawn_agent 子 Agent 推送消息 */
+    registerUIBus(onMessage, onUpdateMessage) {
+        agentUIBus.register(onMessage, onUpdateMessage);
+    }
     createSession() {
         return {
             id: uuid(),
@@ -73,6 +78,12 @@ export class QueryEngine {
             onLoopStateChange: callbacks.onLoopStateChange,
             onSessionUpdate: callbacks.onSessionUpdate,
             onConfirmDangerousCommand: callbacks.onConfirmDangerousCommand,
+            onSubAgentMessage: (msg) => {
+                // SubAgent 消息也存入会话，方便持久化
+                this.session.messages.push(msg);
+                callbacks.onSubAgentMessage?.(msg);
+            },
+            onSubAgentUpdateMessage: callbacks.onSubAgentUpdateMessage,
         };
         try {
             this.transcript = await this.workerBridge.run(userInput, this.transcript, bridgeCallbacks);

package/dist/core/SubAgentBridge.d.ts

@@ -0,0 +1,20 @@
+import { Message, LoopState, SubAgentTask, SubAgentResult } from '../types/index.js';
+import { DangerConfirmResult } from './query.js';
+export interface SubAgentBridgeCallbacks {
+    onMessage: (taskId: string, msg: Message) => void;
+    onUpdateMessage: (taskId: string, id: string, updates: Partial<Message>) => void;
+    onStreamText: (taskId: string, text: string) => void;
+    onLoopStateChange: (taskId: string, state: LoopState) => void;
+    /** 危险命令确认，委托给主线程 UI */
+    onConfirmDangerousCommand?: (taskId: string, command: string, reason: string, ruleName: string) => Promise<DangerConfirmResult>;
+}
+export declare class SubAgentBridge {
+    private worker;
+    /**
+     * 在独立 Worker 线程中执行 SubAgent 任务
+     * @returns SubAgentResult（包含最终输出、消息列表、transcript）
+     */
+    run(task: SubAgentTask, callbacks: SubAgentBridgeCallbacks): Promise<SubAgentResult>;
+    /** 中断 SubAgent 执行 */
+    abort(): void;
+}