@next-open-ai/openclawx 0.8.32 → 0.8.36

package/README.md

@@ -21,7 +21,7 @@
 | **使用指南** | [CLI 使用](docs/zh/guides/cli-usage.md) | 命令行对话、登录、模型与技能、开机自启 |
 | | [桌面端使用](docs/zh/guides/desktop-usage.md) | Desktop 安装与启动、智能体/会话/技能/设置；对话内 `//` 指令查询与切换智能体 |
 | | [Web 与 Gateway](docs/zh/guides/gateway-web.md) | 启动网关、端口与路径、Web 端连接 |
-| | [使用场景](docs/zh/guides/usage-scenarios.md) | 整理下载目录、创建/切换智能体、安装技能、MCP、定时任务等 |
+| | [使用场景](docs/zh/guides/usage-scenarios.md) | 整理下载目录、创建/切换智能体、B站下载助手、安装技能、MCP、定时任务等 |
 | **配置** | [配置概览](docs/zh/configuration/config-overview.md) | 配置目录、config.json 与 agents.json |
 | | [智能体配置](docs/zh/configuration/agents.md) | 本机/Coze/OpenClawX 执行方式与模型 |
 | | [通道配置](docs/zh/configuration/channels.md) | 飞书、钉钉、Telegram 启用与配置项 |
@@ -75,10 +75,10 @@ docs/
 | **长期记忆** | 向量存储（Vectra）+ 本地嵌入，支持经验总结与会话压缩（compaction） |
 | **多端接入** | CLI、WebSocket 网关、Electron 桌面端，同一套 Agent 核心；各端技术栈见下方「各端技术栈」 |
 | **多通道接入** | 飞书、钉钉、Telegram 等 IM 通道，Gateway 根据配置注册；入站经统一格式进 Agent，回复经通道回传 |
-| **代理模式** | 智能体执行方式可选 **本机** / **Coze** / **OpenClawX** / **OpenCode**；本机使用当前模型与 Skills，代理则将对话转发至对应平台 |
-| **Coze 接入** | 支持 Coze 国内站（api.coze.cn）与国际站（api.coze.com）；按站点分别配置 Bot ID 与 Access Token（PAT/OAuth/JWT），桌面端与通道均可选用 Coze 智能体 |
-| **OpenClawX 多节点协作** | 可将智能体代理到另一台 OpenClawX 实例（baseUrl + 可选 API Key），实现多节点分工、负载与协作 |
-| **OpenCode 代理** | 可将智能体代理至 [OpenCode](https://opencode.ai/) 官方 Server（本地 `opencode serve` 或远程）；支持流式回复、斜杠指令 `/init`、`/undo`、`/redo`、`/share`、`/help`，与 TUI 使用方式一致 |
+| **代理模式** | 智能体执行方式可选 **本机** / **Coze** / **OpenClawX** / **OpenCode**；本机使用当前模型与 Skills，**代理模式下本机 0 Token 消耗**，推理与消息处理在对方平台完成 |
+| **Coze 接入** | 支持 Coze 国内站（api.coze.cn）与国际站（api.coze.com）；按站点分别配置 Bot ID 与 Access Token（PAT/OAuth/JWT），桌面端与通道均可选用 Coze 智能体；**0 Token 消耗**，适合 Coze 侧大量消息与长对话场景 |
+| **OpenClawX 多节点协作** | 可将智能体代理到另一台 OpenClawX 实例（baseUrl + 可选 API Key），实现多节点分工、负载与协作；本机 0 Token 消耗 |
+| **OpenCode 代理** | 可将智能体代理至 [OpenCode](https://opencode.ai/) 官方 Server（本地 `opencode serve` 或远程）；支持流式回复、斜杠指令 `/init`、`/undo`、`/redo`、`/share`、`/help`，与 TUI 使用方式一致；**0 Token 消耗**，适合 OpenCode 侧大量代码与长上下文能力 |
 | **MCP** | 已支持 [MCP](https://modelcontextprotocol.io/)（Model Context Protocol）：智能体可配置 stdio/SSE 两种连接方式，按智能体绑定 MCP 服务器，会话内自动加载对应工具，降低 Token 消耗与大模型幻觉 |
 | **RPA（影刀）** | 通过 MCP 可接入影刀 RPA：在智能体 MCP 配置中添加 [yingdao-mcp-server](https://www.npmjs.com/package/yingdao-mcp-server)（命令 `npx -y yingdao-mcp-server`，可选 env 如 `RPA_MODEL`、`SHADOWBOT_PATH`、`USER_FOLDER`），即可在对话中调用影刀自动化能力 |
 
@@ -217,7 +217,7 @@ docker compose up -d
 docker compose -f deploy/docker-compose.yaml up -d
 ```
 
-默认使用镜像 `ccr.ccs.tencentyun.com/windwithlife/openclawx:latest`。若需指定版本，可修改 `deploy/docker-compose.yaml` 中 `image` 的 tag（如 `0.8.28` 或 CI 生成的 `build-ci-openbot-<BUILD_NUMBER>`）。
+默认使用镜像 `ccr.ccs.tencentyun.com/windwithlife/openclawx:latest`。若需指定版本，可修改 `deploy/docker-compose.yaml` 中 `image` 的 tag（如 `0.8.32`、`0.8.28`、`0.8.26` 或 CI 生成的 `build-ci-openbot-<BUILD_NUMBER>`）。
 
 ### 方式二：本地构建并运行（开发/无 CI 时）
 
@@ -396,7 +396,7 @@ openclawx gateway --port 38080
 
 ### 2.4.1 代理模式与多节点协作
 
-智能体除在本机运行（**local**）外，可配置为**代理模式**，将对话转发至 Coze 或另一台 OpenClawX，实现生态接入与多节点协作。
+智能体除在本机运行（**local**）外，可配置为**代理模式**，将对话转发至 Coze、OpenCode 或另一台 OpenClawX，实现生态接入与多节点协作。**代理智能体为本机 0 Token 消耗模式**：推理与消息处理均在对方平台完成，本机仅做转发与展示，不占用本机模型 API 的 Token。特别适合 **Coze**、**OpenCode** 等具备大量消息、长上下文或代码协作能力的平台，在桌面端与通道中直接使用其能力而无需消耗本机配额。
 
 | 模式 | 说明 | 配置要点 |
 |------|------|----------|

package/dist/core/agent/agent-manager.js

@@ -259,7 +259,10 @@ For downloads, provide either a direct URL or a selector to click.`;
             ls: createLsTool(sessionWorkspaceDir),
         };
         const useLongMemory = options.useLongMemory !== false;
-        const mcpTools = await createMcpToolsForSession({ mcpServers: options.mcpServers });
+        const mcpTools = await createMcpToolsForSession({
+            mcpServers: options.mcpServers,
+            sessionId,
+        });
         const customTools = [
             createBrowserTool(sessionWorkspaceDir),
             createSaveExperienceTool(sessionId),

package/dist/core/mcp/client.d.ts

@@ -7,6 +7,10 @@ import type { McpServerConfig } from "./types.js";
 export interface McpClientOptions {
     initTimeoutMs?: number;
     requestTimeoutMs?: number;
+    /** stdio：初始化失败时的重试次数（默认 1） */
+    initRetries?: number;
+    /** stdio：初始化重试间隔毫秒（默认 3000） */
+    initRetryDelayMs?: number;
 }
 export declare class McpClient {
     private transport;

package/dist/core/mcp/client.js

@@ -16,6 +16,8 @@ export class McpClient {
             this.transport = createTransport(configOrTransport, {
                 initTimeoutMs: options.initTimeoutMs,
                 requestTimeoutMs: options.requestTimeoutMs,
+                initRetries: options.initRetries,
+                initRetryDelayMs: options.initRetryDelayMs,
             });
         }
     }

package/dist/core/mcp/index.d.ts

@@ -7,12 +7,14 @@ import type { McpServerConfig, McpServersStandardFormat } from "./types.js";
 export type { McpServerConfig, McpServerConfigStdio, McpServerConfigSse, McpServerConfigStandardEntry, McpServersStandardFormat, McpTool, } from "./types.js";
 export { resolveMcpServersForSession, standardFormatToArray, arrayToStandardFormat, stdioConfigKey, sseConfigKey, mcpConfigKey, } from "./config.js";
 export { McpClient } from "./client.js";
-export { getMcpToolDefinitions, shutdownMcpClients } from "./operator.js";
+export { getMcpToolDefinitions, shutdownMcpClients, type GetMcpToolDefinitionsOptions } from "./operator.js";
 export { mcpToolToToolDefinition, mcpToolsToToolDefinitions } from "./adapter.js";
 /**
  * 根据会话选项中的 mcpServers 配置，返回该会话可用的 MCP 工具（ToolDefinition 数组）。
  * 支持数组或标准 JSON 对象格式；在 AgentManager.getOrCreateSession 中调用，并入 customTools。
+ * 若提供 sessionId，MCP 连接/重试进度将经全局 sendSessionMessage 以系统消息推送。
  */
 export declare function createMcpToolsForSession(options: {
     mcpServers?: McpServerConfig[] | McpServersStandardFormat;
+    sessionId?: string;
 }): Promise<ToolDefinition[]>;

package/dist/core/mcp/index.js

@@ -11,10 +11,13 @@ export { mcpToolToToolDefinition, mcpToolsToToolDefinitions } from "./adapter.js
 /**
  * 根据会话选项中的 mcpServers 配置，返回该会话可用的 MCP 工具（ToolDefinition 数组）。
  * 支持数组或标准 JSON 对象格式；在 AgentManager.getOrCreateSession 中调用，并入 customTools。
+ * 若提供 sessionId，MCP 连接/重试进度将经全局 sendSessionMessage 以系统消息推送。
  */
 export async function createMcpToolsForSession(options) {
     const configs = resolveMcpServersForSession(options.mcpServers);
     if (configs.length === 0)
         return [];
-    return getMcpToolDefinitions(configs);
+    return getMcpToolDefinitions(configs, {
+        sessionId: options.sessionId,
+    });
 }

package/dist/core/mcp/operator.d.ts

@@ -4,11 +4,26 @@
  */
 import type { McpServerConfig } from "./types.js";
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+/** getMcpToolDefinitions 的可选参数：超时、重试与 sessionId（用于经 sendSessionMessage 推送进度） */
+export interface GetMcpToolDefinitionsOptions {
+    /** 连接或 list_tools 失败时的重试次数（不含首次，默认 1） */
+    connectRetries?: number;
+    /** 重试间隔（毫秒，默认 3000） */
+    retryDelayMs?: number;
+    /** stdio 初始化超时（毫秒） */
+    initTimeoutMs?: number;
+    /** stdio 初始化重试次数（默认 1） */
+    initRetries?: number;
+    /** stdio 初始化重试间隔（毫秒，默认 3000） */
+    initRetryDelayMs?: number;
+    /** 会话 ID，用于经全局 sendSessionMessage 推送 MCP 进度系统消息 */
+    sessionId?: string;
+}
 /**
  * 为给定 MCP 服务器配置列表获取或创建客户端，并返回其工具对应的 ToolDefinition 数组。
- * 连接失败或 list_tools 失败的 server 会被跳过并打日志，不阻塞整体。
+ * 连接失败或 list_tools 失败的 server 会按 options 重试，仍失败则跳过并打日志，不阻塞整体。
  */
-export declare function getMcpToolDefinitions(serverConfigs: McpServerConfig[]): Promise<ToolDefinition[]>;
+export declare function getMcpToolDefinitions(serverConfigs: McpServerConfig[], options?: GetMcpToolDefinitionsOptions): Promise<ToolDefinition[]>;
 /**
  * 关闭并移除所有缓存的 MCP 客户端（进程退出或显式清理时调用）。
  */

package/dist/core/mcp/operator.js

@@ -5,6 +5,7 @@
 import { mcpConfigKey } from "./config.js";
 import { McpClient } from "./client.js";
 import { mcpToolsToToolDefinitions } from "./adapter.js";
+import { sendSessionMessage } from "../session-outlet/index.js";
 /** 按配置键缓存的客户端 */
 const clientCache = new Map();
 function configLabel(config) {
@@ -12,53 +13,119 @@ function configLabel(config) {
         return config.command;
     return config.url;
 }
+/** 用于系统消息展示的 MCP 名称：stdio 优先用首参（如 akshare-tools），否则 command；sse 用 URL 主机或路径末段 */
+function mcpDisplayName(config) {
+    if (config.transport === "stdio") {
+        const args = config.args;
+        const first = args?.[0];
+        if (typeof first === "string" && first.trim() && !first.includes("/") && !first.includes("\\")) {
+            return first.trim();
+        }
+        return config.command;
+    }
+    try {
+        const u = new URL(config.url);
+        const host = u.hostname || u.pathname?.replace(/\/$/, "").split("/").pop() || "MCP";
+        return host;
+    }
+    catch {
+        return config.url;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
 /**
  * 为给定 MCP 服务器配置列表获取或创建客户端，并返回其工具对应的 ToolDefinition 数组。
- * 连接失败或 list_tools 失败的 server 会被跳过并打日志，不阻塞整体。
+ * 连接失败或 list_tools 失败的 server 会按 options 重试，仍失败则跳过并打日志，不阻塞整体。
  */
-export async function getMcpToolDefinitions(serverConfigs) {
+export async function getMcpToolDefinitions(serverConfigs, options = {}) {
+    const connectRetries = options.connectRetries ?? 1;
+    const retryDelayMs = options.retryDelayMs ?? 3_000;
+    const sessionId = options.sessionId;
+    const clientOptions = {
+        initTimeoutMs: options.initTimeoutMs,
+        initRetries: options.initRetries,
+        initRetryDelayMs: options.initRetryDelayMs,
+    };
+    const emitProgress = (displayMessage, phase, detail) => {
+        if (sessionId) {
+            sendSessionMessage(sessionId, {
+                type: "system",
+                code: "mcp.progress",
+                payload: { phase, message: displayMessage, serverLabel: detail },
+            });
+        }
+    };
     const allTools = [];
     for (let i = 0; i < serverConfigs.length; i++) {
         const config = serverConfigs[i];
         const key = mcpConfigKey(config);
+        const label = configLabel(config);
+        const displayName = mcpDisplayName(config);
         let client = clientCache.get(key);
-        if (!client) {
-            client = new McpClient(config);
-            try {
-                await client.connect();
-                clientCache.set(key, client);
+        if (!client || !client.isConnected) {
+            if (client) {
+                clientCache.delete(key);
+                try {
+                    await client.close();
+                }
+                catch { }
             }
-            catch (err) {
-                console.warn(`[mcp] 连接失败 (${configLabel(config)}):`, err instanceof Error ? err.message : err);
-                continue;
+            emitProgress(`${displayName} MCP connecting`, "connecting");
+            let connected = false;
+            for (let attempt = 0; attempt <= connectRetries; attempt++) {
+                if (attempt > 0) {
+                    emitProgress(`${displayName} MCP retrying (${attempt + 1}/${connectRetries + 1})`, "retrying", "connect");
+                    await sleep(retryDelayMs);
+                }
+                try {
+                    client = new McpClient(config, clientOptions);
+                    await client.connect();
+                    clientCache.set(key, client);
+                    connected = true;
+                    emitProgress(`${displayName} MCP ready`, "ready");
+                    break;
+                }
+                catch (err) {
+                    if (client)
+                        try {
+                            await client.close();
+                        }
+                        catch { }
+                    if (attempt === connectRetries) {
+                        console.warn(`[mcp] 连接失败 (${label}):`, err instanceof Error ? err.message : err);
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        emitProgress(`${displayName} MCP failed: ${errMsg}`, "skipped", errMsg);
+                    }
+                }
             }
+            if (!connected)
+                continue;
         }
-        if (!client.isConnected) {
-            clientCache.delete(key);
-            try {
-                await client.close();
+        client = clientCache.get(key);
+        let toolsListed = false;
+        for (let attempt = 0; attempt <= connectRetries; attempt++) {
+            if (attempt > 0) {
+                emitProgress(`${displayName} MCP retrying list tools (${attempt + 1}/${connectRetries + 1})`, "retrying", "list_tools");
+                await sleep(retryDelayMs);
             }
-            catch { }
-            const newClient = new McpClient(config);
             try {
-                await newClient.connect();
-                clientCache.set(key, newClient);
-                client = newClient;
+                const tools = await client.listTools();
+                const serverId = `mcp${i}`;
+                const definitions = mcpToolsToToolDefinitions(tools, client, serverId);
+                allTools.push(...definitions);
+                toolsListed = true;
+                break;
             }
             catch (err) {
-                console.warn(`[mcp] 重连失败 (${configLabel(config)}):`, err instanceof Error ? err.message : err);
-                continue;
+                if (attempt === connectRetries) {
+                    console.warn(`[mcp] list_tools 失败 (${label}):`, err instanceof Error ? err.message : err);
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    emitProgress(`${displayName} MCP list tools failed: ${errMsg}`, "skipped", errMsg);
+                }
             }
         }
-        try {
-            const tools = await client.listTools();
-            const serverId = `mcp${i}`;
-            const definitions = mcpToolsToToolDefinitions(tools, client, serverId);
-            allTools.push(...definitions);
-        }
-        catch (err) {
-            console.warn(`[mcp] list_tools 失败 (${configLabel(config)}):`, err instanceof Error ? err.message : err);
-        }
     }
     return allTools;
 }

package/dist/core/mcp/transport/index.d.ts

@@ -2,6 +2,10 @@ import type { McpServerConfig, IMcpTransport } from "../types.js";
 export interface TransportOptions {
     initTimeoutMs?: number;
     requestTimeoutMs?: number;
+    /** stdio：初始化失败时的重试次数（默认 1） */
+    initRetries?: number;
+    /** stdio：初始化重试间隔毫秒（默认 3000） */
+    initRetryDelayMs?: number;
 }
 /**
  * 根据配置创建对应的传输层实例。

package/dist/core/mcp/transport/index.js

@@ -5,7 +5,12 @@ import { SseTransport } from "./sse.js";
  */
 export function createTransport(config, options) {
     if (config.transport === "stdio") {
-        return new StdioTransport(config, options);
+        return new StdioTransport(config, {
+            initTimeoutMs: options?.initTimeoutMs,
+            requestTimeoutMs: options?.requestTimeoutMs,
+            initRetries: options?.initRetries,
+            initRetryDelayMs: options?.initRetryDelayMs,
+        });
     }
     if (config.transport === "sse") {
         return new SseTransport(config, options);

package/dist/core/mcp/transport/stdio.d.ts

@@ -8,12 +8,18 @@ export interface StdioTransportOptions {
     initTimeoutMs?: number;
     /** 单次请求超时（毫秒） */
     requestTimeoutMs?: number;
+    /** 初始化失败时的重试次数（不含首次，默认 1，即最多 2 次尝试） */
+    initRetries?: number;
+    /** 初始化重试间隔（毫秒，默认 3000） */
+    initRetryDelayMs?: number;
 }
 export declare class StdioTransport {
     private process;
     private config;
     private initTimeoutMs;
     private requestTimeoutMs;
+    private initRetries;
+    private initRetryDelayMs;
     private nextId;
     private pending;
     private buffer;

package/dist/core/mcp/transport/stdio.js

@@ -8,6 +8,8 @@ export class StdioTransport {
     config;
     initTimeoutMs;
     requestTimeoutMs;
+    initRetries;
+    initRetryDelayMs;
     nextId = 1;
     pending = new Map();
     buffer = "";
@@ -15,6 +17,8 @@ export class StdioTransport {
         this.config = config;
         this.initTimeoutMs = options.initTimeoutMs ?? 10_000;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.initRetries = options.initRetries ?? 1;
+        this.initRetryDelayMs = options.initRetryDelayMs ?? 3_000;
     }
     /** 启动子进程并完成 MCP initialize 握手 */
     async start() {
@@ -43,7 +47,24 @@ export class StdioTransport {
             this.rejectAll(new Error(`MCP process exited: code=${code} signal=${signal}`));
             this.process = null;
         });
-        await this.initialize();
+        const maxAttempts = 1 + this.initRetries;
+        let lastErr = null;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                await this.initialize();
+                lastErr = null;
+                break;
+            }
+            catch (e) {
+                lastErr = e instanceof Error ? e : new Error(String(e));
+                const isTransient = lastErr.message.includes("timeout") || lastErr.message.includes("MCP process exited");
+                if (!isTransient || attempt >= maxAttempts) {
+                    throw lastErr;
+                }
+                console.warn(`[mcp stdio] initialize 超时或失败，${this.initRetryDelayMs}ms 后重试 (${attempt}/${maxAttempts}):`, lastErr.message);
+                await new Promise((r) => setTimeout(r, this.initRetryDelayMs));
+            }
+        }
     }
     flushLines() {
         const lines = this.buffer.split("\n");

package/dist/core/session-outlet/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 会话消息统一出口：各模块仅需 sessionId + 消息即可通过统一出口准确送达当前会话对应的 Web/Desktop 或通道。
+ */
+import type { SessionMessageInput, ISessionOutlet } from "./types.js";
+export type { SessionMessage, SessionMessageInput, SessionMessageConsumer, ISessionOutlet } from "./types.js";
+export { SessionOutlet } from "./outlet.js";
+/**
+ * 获取当前使用的出口实例（Gateway 启动时通过 setSessionOutlet 注入）。
+ */
+export declare function getSessionOutlet(): ISessionOutlet | null;
+/**
+ * 设置全局出口实例；传 null 可清空（测试用）。
+ */
+export declare function setSessionOutlet(outlet: ISessionOutlet | null): void;
+/**
+ * 解耦 API：任意模块携带 sessionId 即可发送会话消息，由统一出口路由到正确端。
+ * 若未设置出口或 sessionId 为空，则静默忽略。
+ */
+export declare function sendSessionMessage(sessionId: string, message: Omit<SessionMessageInput, "sessionId">): void;

package/dist/core/session-outlet/index.js

@@ -0,0 +1,33 @@
+/**
+ * 会话消息统一出口：各模块仅需 sessionId + 消息即可通过统一出口准确送达当前会话对应的 Web/Desktop 或通道。
+ */
+export { SessionOutlet } from "./outlet.js";
+let defaultOutlet = null;
+/**
+ * 获取当前使用的出口实例（Gateway 启动时通过 setSessionOutlet 注入）。
+ */
+export function getSessionOutlet() {
+    return defaultOutlet;
+}
+/**
+ * 设置全局出口实例；传 null 可清空（测试用）。
+ */
+export function setSessionOutlet(outlet) {
+    defaultOutlet = outlet;
+}
+/**
+ * 解耦 API：任意模块携带 sessionId 即可发送会话消息，由统一出口路由到正确端。
+ * 若未设置出口或 sessionId 为空，则静默忽略。
+ */
+export function sendSessionMessage(sessionId, message) {
+    if (!sessionId || !message)
+        return;
+    const outlet = getSessionOutlet();
+    if (!outlet)
+        return;
+    outlet.emit(sessionId, {
+        type: message.type,
+        code: message.code,
+        payload: message.payload ?? {},
+    });
+}

package/dist/core/session-outlet/outlet.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 会话消息出口实现：按 sessionId 维护消费者集合，emit 时扇出到该会话所有消费者。
+ */
+import type { SessionMessage, SessionMessageConsumer } from "./types.js";
+export declare class SessionOutlet {
+    private readonly consumersBySession;
+    /**
+     * 向指定会话注册消费者；返回取消注册函数。
+     */
+    registerConsumer(sessionId: string, consumer: SessionMessageConsumer): () => void;
+    /**
+     * 向指定会话发送消息；将 sessionId、timestamp 注入后扇出到该会话所有消费者。
+     */
+    emit(sessionId: string, message: Omit<SessionMessage, "sessionId" | "timestamp">): void;
+}

package/dist/core/session-outlet/outlet.js

@@ -0,0 +1,49 @@
+/**
+ * 会话消息出口实现：按 sessionId 维护消费者集合，emit 时扇出到该会话所有消费者。
+ */
+export class SessionOutlet {
+    consumersBySession = new Map();
+    /**
+     * 向指定会话注册消费者；返回取消注册函数。
+     */
+    registerConsumer(sessionId, consumer) {
+        let set = this.consumersBySession.get(sessionId);
+        if (!set) {
+            set = new Set();
+            this.consumersBySession.set(sessionId, set);
+        }
+        set.add(consumer);
+        return () => {
+            const s = this.consumersBySession.get(sessionId);
+            if (s) {
+                s.delete(consumer);
+                if (s.size === 0)
+                    this.consumersBySession.delete(sessionId);
+            }
+        };
+    }
+    /**
+     * 向指定会话发送消息；将 sessionId、timestamp 注入后扇出到该会话所有消费者。
+     */
+    emit(sessionId, message) {
+        const full = {
+            ...message,
+            sessionId,
+            timestamp: Date.now(),
+        };
+        const set = this.consumersBySession.get(sessionId);
+        if (!set || set.size === 0)
+            return;
+        for (const consumer of set) {
+            try {
+                const result = consumer.send(full);
+                if (result && typeof result.catch === "function") {
+                    result.catch((err) => console.warn("[SessionOutlet] consumer.send rejected:", err));
+                }
+            }
+            catch (err) {
+                console.warn("[SessionOutlet] consumer.send threw:", err);
+            }
+        }
+    }
+}

package/dist/core/session-outlet/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 会话消息出口：统一消息类型与消费者接口。
+ * 所有发给各端（Web/Desktop、通道）的会话消息经此抽象，由出口按 sessionId 路由到已注册的消费者。
+ */
+/** 消息类型：对话内容 vs 系统消息（MCP 进度、// 命令结果等） */
+export type SessionMessageType = "chat" | "system";
+/** 系统消息子类型，便于各端区分展示 */
+export type SessionMessageCode = "agent.chunk" | "agent.tool" | "turn_end" | "message_complete" | "agent_end" | "conversation_end" | "mcp.progress" | "command.result";
+/**
+ * 统一会话消息：出口只认 sessionId + 本结构，不关心具体传输。
+ */
+export interface SessionMessage {
+    type: SessionMessageType;
+    code?: SessionMessageCode;
+    payload: Record<string, unknown>;
+    sessionId: string;
+    timestamp?: number;
+}
+/** 发送时调用方可不带 sessionId，由出口注入 */
+export type SessionMessageInput = Omit<SessionMessage, "sessionId"> & {
+    sessionId?: string;
+};
+/**
+ * 消费者接口：各端（Web、通道）注册后，出口将消息推送给 send(message)。
+ */
+export interface SessionMessageConsumer {
+    send(message: SessionMessage): void | Promise<void>;
+}
+/**
+ * 出口接口：支持注册消费者与发送消息，便于注入与测试。
+ */
+export interface ISessionOutlet {
+    emit(sessionId: string, message: Omit<SessionMessage, "sessionId" | "timestamp">): void;
+    registerConsumer(sessionId: string, consumer: SessionMessageConsumer): () => void;
+}

package/dist/core/session-outlet/types.js

@@ -0,0 +1,5 @@
+/**
+ * 会话消息出口：统一消息类型与消费者接口。
+ * 所有发给各端（Web/Desktop、通道）的会话消息经此抽象，由出口按 sessionId 路由到已注册的消费者。
+ */
+export {};

package/dist/gateway/channel/channel-core.d.ts

@@ -1,5 +1,6 @@
 /**
  * 通道核心：收 UnifiedMessage → 会话映射 → 调 Agent → 选 Outbound → 发 UnifiedReply。
+ * 系统消息（// 命令结果、MCP 进度）经统一出口推送，通道注册消费者后按 outbound 发送。
  */
 import type { UnifiedMessage, IChannel } from "./types.js";
 /**