@code4bug/jarvis-agent 1.0.4 → 1.1.4

package/dist/core/workerBusProxy.js

@@ -0,0 +1,57 @@
+/**
+ * workerBusProxy — Worker 线程侧 MessageBus IPC 代理
+ *
+ * 在 SubAgent Worker 线程中，通过 parentPort 消息将 bus 操作
+ * 转发给主线程（SubAgentBridge）代理执行，绕过线程内存隔离。
+ *
+ * 此文件独立于 subAgentWorker.ts，避免循环依赖。
+ * subAgentWorker.ts 负责注册 pendingBusRequests 的回复分发。
+ */
+import { parentPort } from 'worker_threads';
+/** 等待中的 bus 请求，key = requestId */
+export const pendingBusRequests = new Map();
+function requestId() {
+    return `bus-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+function send(msg) {
+    if (!parentPort)
+        throw new Error('workerBusProxy: 不在 Worker 线程中');
+    parentPort.postMessage(msg);
+}
+export const workerBusProxy = {
+    publish(from, channel, payload) {
+        return new Promise((resolve) => {
+            const reqId = requestId();
+            pendingBusRequests.set(reqId, () => resolve());
+            send({ type: 'bus_publish', requestId: reqId, from, channel, payload });
+        });
+    },
+    subscribe(channel, timeoutMs = 30_000, fromOffset) {
+        return new Promise((resolve) => {
+            const reqId = requestId();
+            pendingBusRequests.set(reqId, (msg) => resolve(msg));
+            send({ type: 'bus_subscribe', requestId: reqId, channel, timeoutMs, fromOffset });
+        });
+    },
+    getHistory(channel, limit) {
+        return new Promise((resolve) => {
+            const reqId = requestId();
+            pendingBusRequests.set(reqId, (msgs) => resolve(msgs));
+            send({ type: 'bus_read_history', requestId: reqId, channel, limit });
+        });
+    },
+    getOffset(channel) {
+        return new Promise((resolve) => {
+            const reqId = requestId();
+            pendingBusRequests.set(reqId, (offset) => resolve(offset));
+            send({ type: 'bus_get_offset', requestId: reqId, channel });
+        });
+    },
+    listChannels() {
+        return new Promise((resolve) => {
+            const reqId = requestId();
+            pendingBusRequests.set(reqId, (channels) => resolve(channels));
+            send({ type: 'bus_list_channels', requestId: reqId });
+        });
+    },
+};

package/dist/hooks/useSlashMenu.d.ts

@@ -13,6 +13,8 @@ interface UseSlashMenuOptions {
     setInput: React.Dispatch<React.SetStateAction<string>>;
     /** resume 时重置所有流式状态（含 thinkingIdRef） */
     stopAll: () => void;
+    /** /new 命令：开启新会话 */
+    onNewSession: () => void;
 }
 /**
  * 斜杠命令菜单状态管理 hook

package/dist/hooks/useSlashMenu.js

@@ -9,7 +9,7 @@ import { executeSlashCommand } from '../screens/slashCommands.js';
  * 管理菜单可见性、选中项、二级菜单（agent / resume）等。
  */
 export function useSlashMenu(opts) {
-    const { engineRef, sessionRef, tokenCountRef, setMessages, setDisplayTokens, setLoopState, setIsProcessing, setShowWelcome, setInput, stopAll, } = opts;
+    const { engineRef, sessionRef, tokenCountRef, setMessages, setDisplayTokens, setLoopState, setIsProcessing, setShowWelcome, setInput, stopAll, onNewSession, } = opts;
     const [slashMenuVisible, setSlashMenuVisible] = useState(false);
     const [slashMenuItems, setSlashMenuItems] = useState([]);
     const [slashMenuIndex, setSlashMenuIndex] = useState(0);
@@ -138,6 +138,10 @@ export function useSlashMenu(opts) {
         if (cmd.category === 'builtin') {
             setInput('');
             setSlashMenuVisible(false);
+            if (cmd.name === 'new') {
+                onNewSession();
+                return;
+            }
             const msg = executeSlashCommand(cmd.name);
             if (msg)
                 setMessages((prev) => [...prev, msg]);

package/dist/hooks/useTokenDisplay.d.ts

@@ -9,5 +9,6 @@ export declare function useTokenDisplay(): {
     startTokenTimer: () => void;
     stopTokenTimer: () => void;
     updateTokenCount: (count: number) => void;
+    syncTokenDisplay: (count: number) => void;
     resetTokens: () => void;
 };

package/dist/hooks/useTokenDisplay.js

@@ -25,6 +25,10 @@ export function useTokenDisplay() {
     const updateTokenCount = useCallback((count) => {
         tokenCountRef.current = count;
     }, []);
+    const syncTokenDisplay = useCallback((count) => {
+        tokenCountRef.current = count;
+        setDisplayTokens(count);
+    }, []);
     const resetTokens = useCallback(() => {
         tokenCountRef.current = 0;
         setDisplayTokens(0);
@@ -40,6 +44,7 @@ export function useTokenDisplay() {
         startTokenTimer,
         stopTokenTimer,
         updateTokenCount,
+        syncTokenDisplay,
         resetTokens,
     };
 }

package/dist/screens/repl.js

@@ -20,6 +20,7 @@ import { executeSlashCommand } from './slashCommands.js';
 import { QueryEngine } from '../core/QueryEngine.js';
 import { HIDE_WELCOME_AFTER_INPUT } from '../config/constants.js';
 import { generateAgentHint } from '../core/hint.js';
+import { subscribeAgentCount, getActiveAgentCount } from '../core/spawnRegistry.js';
 export default function REPL() {
     const { exit } = useApp();
     const width = useTerminalWidth();
@@ -33,6 +34,7 @@ export default function REPL() {
     const [showWelcome, setShowWelcome] = useState(true);
     const [showDetails, setShowDetails] = useState(false);
     const [placeholder, setPlaceholder] = useState('');
+    const [activeAgents, setActiveAgents] = useState(getActiveAgentCount());
     const lastEscRef = useRef(0);
     const sessionRef = useRef({
         id: '', messages: [], createdAt: 0, updatedAt: 0, totalTokens: 0, totalCost: 0,
@@ -40,24 +42,45 @@ export default function REPL() {
     const engineRef = useRef(null);
     // 节流 hooks
     const { streamText, streamBufferRef, startStreamTimer, stopStreamTimer, appendStreamChunk, clearStream, handleThinkingUpdate, finishThinking, thinkingIdRef, stopAll, } = useStreamThrottle(setMessages);
-    const { displayTokens, tokenCountRef, startTokenTimer, stopTokenTimer, updateTokenCount, resetTokens, } = useTokenDisplay();
+    const { displayTokens, tokenCountRef, startTokenTimer, stopTokenTimer, updateTokenCount, syncTokenDisplay, resetTokens, } = useTokenDisplay();
+    // ===== 新会话逻辑 =====
+    const handleNewSession = useCallback(() => {
+        if (engineRef.current) {
+            engineRef.current.reset();
+            sessionRef.current = engineRef.current.getSession();
+        }
+        setMessages([]);
+        clearStream();
+        setLoopState(null);
+        setIsProcessing(false);
+        setShowWelcome(true);
+        resetTokens();
+        generateAgentHint().then((hint) => setPlaceholder(hint)).catch(() => { });
+    }, [clearStream, resetTokens]);
     // 斜杠菜单
     const slashMenu = useSlashMenu({
         engineRef, sessionRef, tokenCountRef,
         setMessages,
-        setDisplayTokens: (n) => updateTokenCount(n),
+        setDisplayTokens: (n) => syncTokenDisplay(n),
         setLoopState, setIsProcessing, setShowWelcome, setInput,
         stopAll,
+        onNewSession: handleNewSession,
     });
     // 危险命令确认
     const [dangerConfirm, setDangerConfirm] = useState(null);
     useEffect(() => {
         engineRef.current = new QueryEngine();
         sessionRef.current = engineRef.current.getSession();
+        // 注册持久 UI 回调，供 spawn_agent 后台子 Agent 跨轮次推送消息
+        engineRef.current.registerUIBus((msg) => setMessages((prev) => [...prev, msg]), (id, updates) => setMessages((prev) => prev.map((m) => (m.id === id ? { ...m, ...updates } : m))));
         generateAgentHint().then((hint) => setPlaceholder(hint)).catch((err) => {
             console.error('[hint] 初始化提示失败:', err);
         });
     }, []);
+    // 订阅后台 SubAgent 计数变化
+    useEffect(() => {
+        return subscribeAgentCount((count) => setActiveAgents(count));
+    }, []);
     // ===== Engine Callbacks =====
     const callbacks = {
         onMessage: (msg) => {
@@ -106,6 +129,12 @@ export default function REPL() {
                 setDangerConfirm({ command, reason, ruleName, resolve });
             });
         },
+        onSubAgentMessage: (msg) => {
+            setMessages((prev) => [...prev, msg]);
+        },
+        onSubAgentUpdateMessage: (id, updates) => {
+            setMessages((prev) => prev.map((msg) => (msg.id === id ? { ...msg, ...updates } : msg)));
+        },
     };
     // ===== 提交处理 =====
     const handleSubmit = useCallback(async (value) => {
@@ -121,18 +150,7 @@ export default function REPL() {
                 setInput('');
                 slashMenu.setSlashMenuVisible(false);
                 if (cmdName === 'new') {
-                    // 新会话：重置引擎 + 清空所有状态
-                    if (engineRef.current) {
-                        engineRef.current.reset();
-                        sessionRef.current = engineRef.current.getSession();
-                    }
-                    setMessages([]);
-                    clearStream();
-                    setLoopState(null);
-                    setIsProcessing(false);
-                    setShowWelcome(true);
-                    resetTokens();
-                    generateAgentHint().then((hint) => setPlaceholder(hint)).catch(() => { });
+                    handleNewSession();
                 }
                 else if (cmdName === 'session_clear') {
                     if (engineRef.current) {
@@ -228,7 +246,7 @@ export default function REPL() {
         setInput('');
         clearStream();
         await engineRef.current.handleQuery(trimmed, callbacks);
-    }, [isProcessing, pushHistory, clearStream, resetTokens, slashMenu]);
+    }, [isProcessing, pushHistory, clearStream, resetTokens, slashMenu, handleNewSession]);
     // ===== 输入处理 =====
     const handleUpArrow = useCallback(() => {
         const result = navigateUp(input);
@@ -366,5 +384,5 @@ export default function REPL() {
     return (_jsxs(Box, { flexDirection: "column", width: width, children: [showWelcome && _jsx(WelcomeHeader, { width: width }), _jsxs(Box, { flexDirection: "column", paddingX: 1, marginTop: showWelcome ? 0 : 1, children: [messages.map((msg) => (_jsx(MessageItem, { msg: msg, showDetails: showDetails }, msg.id))), streamText && _jsx(StreamingText, { text: streamText }), dangerConfirm && (_jsx(DangerConfirm, { command: dangerConfirm.command, reason: dangerConfirm.reason, ruleName: dangerConfirm.ruleName, onSelect: (choice) => {
                             dangerConfirm.resolve(choice);
                             setDangerConfirm(null);
-                        } })), loopState?.isRunning && (_jsxs(Box, { children: [_jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), _jsxs(Text, { color: "gray", children: [" iteration ", loopState.iteration, "/", loopState.maxIterations] })] }))] }), _jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { color: "gray", children: '─'.repeat(Math.max(width - 2, 1)) }), slashMenu.slashMenuVisible && !isProcessing && (_jsx(SlashCommandMenu, { commands: slashMenu.slashMenuItems, selectedIndex: slashMenu.slashMenuIndex })), _jsx(Box, { children: countdown !== null ? (_jsxs(Box, { children: [_jsx(Text, { color: "gray", dimColor: true, children: "\u276F " }), _jsx(Text, { color: "yellow", children: "Press " }), _jsx(Text, { color: "yellow", bold: true, children: "Ctrl+C" }), _jsx(Text, { color: "yellow", children: " again to exit " }), _jsxs(Text, { color: "gray", dimColor: true, children: ["(", countdown, "s)"] })] })) : isProcessing ? (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", bold: true, children: "\u276F " }), _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { color: "gray", italic: true, children: " processing..." })] })) : (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", bold: true, children: "\u276F " }), _jsx(MultilineInput, { value: input, onChange: handleInputChange, onSubmit: handleSubmit, onUpArrow: handleUpArrow, onDownArrow: handleDownArrow, placeholder: placeholder, isActive: !isProcessing, showCursor: windowFocused && !isProcessing, slashMenuActive: slashMenu.slashMenuVisible, onSlashMenuUp: slashMenu.handleSlashMenuUp, onSlashMenuDown: slashMenu.handleSlashMenuDown, onSlashMenuSelect: slashMenu.handleSlashMenuSelect, onSlashMenuClose: slashMenu.handleSlashMenuClose, onTabFillPlaceholder: handleTabFillPlaceholder })] })) }), _jsx(Text, { color: "gray", children: '─'.repeat(Math.max(width - 2, 1)) }), _jsx(StatusBar, { width: width - 2, totalTokens: displayTokens })] })] }));
+                        } })), loopState?.isRunning && (_jsxs(Box, { children: [_jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), _jsxs(Text, { color: "gray", children: [" iteration ", loopState.iteration, "/", loopState.maxIterations] })] }))] }), _jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { color: "gray", children: '─'.repeat(Math.max(width - 2, 1)) }), slashMenu.slashMenuVisible && !isProcessing && (_jsx(SlashCommandMenu, { commands: slashMenu.slashMenuItems, selectedIndex: slashMenu.slashMenuIndex })), _jsx(Box, { children: countdown !== null ? (_jsxs(Box, { children: [_jsx(Text, { color: "gray", dimColor: true, children: "\u276F " }), _jsx(Text, { color: "yellow", children: "Press " }), _jsx(Text, { color: "yellow", bold: true, children: "Ctrl+C" }), _jsx(Text, { color: "yellow", children: " again to exit " }), _jsxs(Text, { color: "gray", dimColor: true, children: ["(", countdown, "s)"] })] })) : isProcessing ? (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", bold: true, children: "\u276F " }), _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { color: "gray", italic: true, children: " processing..." })] })) : (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", bold: true, children: "\u276F " }), _jsx(MultilineInput, { value: input, onChange: handleInputChange, onSubmit: handleSubmit, onUpArrow: handleUpArrow, onDownArrow: handleDownArrow, placeholder: placeholder, isActive: !isProcessing, showCursor: windowFocused && !isProcessing, slashMenuActive: slashMenu.slashMenuVisible, onSlashMenuUp: slashMenu.handleSlashMenuUp, onSlashMenuDown: slashMenu.handleSlashMenuDown, onSlashMenuSelect: slashMenu.handleSlashMenuSelect, onSlashMenuClose: slashMenu.handleSlashMenuClose, onTabFillPlaceholder: handleTabFillPlaceholder })] })) }), _jsx(Text, { color: "gray", children: '─'.repeat(Math.max(width - 2, 1)) }), _jsx(StatusBar, { width: width - 2, totalTokens: displayTokens, activeAgents: activeAgents })] })] }));
 }

package/dist/screens/slashCommands.js

@@ -89,7 +89,8 @@ export function executeSlashCommand(cmdName) {
             const parts = [];
             parts.push('### Built-in Tools\n');
             allTools.forEach((t, i) => {
-                parts.push(`${i + 1}. \`${t.name}\` - ${t.description.slice(0, 60)}`);
+                const summary = t.description.split('\n')[0].slice(0, 80);
+                parts.push(`${i + 1}. \`${t.name}\` - ${summary}`);
             });
             parts.push('');
             parts.push(`### External Skills\n`);

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

@@ -16,6 +16,8 @@ export interface LLMConfig {
     temperature?: number;
     /** 额外请求体参数，直接合并到 API 请求 body */
     extraBody?: Record<string, unknown>;
+    /** 直接指定 system prompt，跳过 agent 文件加载（SubAgent 场景使用） */
+    systemPrompt?: string;
 }
 /** 从配置文件构建 LLMConfig，找不到则回退环境变量 */
 export declare function getDefaultConfig(): LLMConfig;

package/dist/services/api/llm.js

@@ -142,6 +142,11 @@ export class LLMServiceImpl {
         if (!this.config.apiKey) {
             throw new Error('API_KEY 未配置。请在 .jarvis/config.json 或环境变量中设置。');
         }
+        // 若外部直接传入 systemPrompt（SubAgent 场景），直接使用，跳过 agent 文件加载
+        if (this.config.systemPrompt) {
+            this.systemPrompt = this.config.systemPrompt;
+            return;
+        }
         // 从当前激活的智能体加载 system prompt（运行时动态读取）
         const currentAgent = getActiveAgent(DEFAULT_AGENT);
         const agent = getAgent(currentAgent);
@@ -157,7 +162,16 @@ export class LLMServiceImpl {
             '安全围栏会自动处理拦截和用户确认流程。';
         // 追加系统环境信息，帮助 LLM 感知用户运行环境
         const systemInfo = getSystemInfoPrompt();
-        this.systemPrompt = agentPrompt + roleBoundary + systemInfo;
+        // 追加当前激活模型信息
+        const jarvisCfg = loadConfig();
+        const activeModelCfg = getActiveModel(jarvisCfg);
+        const activeModelKey = jarvisCfg.system.model ?? 'unknown';
+        const modelInfo = '\n\n---\n[当前模型] 以下是本次会话使用的 LLM 模型信息：' +
+            `\n- 模型标识: ${activeModelKey}` +
+            `\n- 模型名称: ${activeModelCfg?.model ?? 'unknown'}` +
+            `\n- API 地址: ${activeModelCfg?.api_url ?? 'unknown'}` +
+            `\n- 最大 Token: ${activeModelCfg?.max_tokens ?? 'unknown'}`;
+        this.systemPrompt = agentPrompt + roleBoundary + systemInfo + modelInfo;
     }
     async streamMessage(transcript, tools, callbacks, abortSignal) {
         const messages = toOpenAIMessages(transcript, this.systemPrompt);

package/dist/tools/index.d.ts

@@ -6,7 +6,13 @@ import { listDirectory } from './listDirectory.js';
 import { searchFiles } from './searchFiles.js';
 import { semanticSearch } from './semanticSearch.js';
 import { createSkill } from './createSkill.js';
-export { readFile, writeFile, runCommand, listDirectory, searchFiles, semanticSearch, createSkill };
+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

@@ -5,9 +5,20 @@ import { listDirectory } from './listDirectory.js';
 import { searchFiles } from './searchFiles.js';
 import { semanticSearch } from './semanticSearch.js';
 import { createSkill } from './createSkill.js';
-export { readFile, writeFile, runCommand, listDirectory, searchFiles, semanticSearch, createSkill };
+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);

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