@lmcl/ailo-mcp-sdk 0.0.3 → 0.1.0

package/dist/ailo-client.d.ts

@@ -1,31 +1,47 @@
-import type { BridgeMessage } from "./types.js";
+import type { BridgeMessage, ChannelStorage, ContextTag } from "./types.js";
+/** 按 kind 查找第一个匹配标签的 value */
+export declare function tagValue(tags: ContextTag[], kind: string): string;
+export interface AiloClientConfig {
+    url: string;
+    token: string;
+    channel: string;
+    displayName: string;
+    defaultRequiresResponse?: boolean;
+    channelPrompt?: string;
+}
 /**
- * 反向 WebSocket 信号客户端。
- *
- * 连接 Ailo 网关，connect 时一并传入 channel 与 prompt，一步完成注册。
- * 负责 channel.accept（入站信号投递）。
+ * 反向 WebSocket 客户端。
  *
- * 出站（AI → 平台）由 MCP stdio 工具处理，不经过此客户端。
+ * 连接 Ailo 网关，自动重连（指数退避）、心跳（ping/pong）、请求超时。
+ * 实现 ChannelStorage 接口，可直接作为 ctx.storage 使用。
  */
-export declare class AiloClient {
+export declare class AiloClient implements ChannelStorage {
     private ws;
-    private url;
-    private token;
-    private channel;
-    private channelPrompt;
-    private reconnectTimer;
+    private cfg;
     private reqId;
-    constructor(url: string, token: string, channel: string, channelPrompt?: string);
-    private request;
+    private pending;
+    private heartbeatTimer;
+    private pongTimer;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private intentionalClose;
+    constructor(config: AiloClientConfig);
+    /** 建立连接并完成握手。首次调用；后续断线由内部自动重连。 */
     connect(): Promise<void>;
-    private scheduleReconnect;
-    sendMessage(msg: BridgeMessage): Promise<{
-        text?: string;
-    }>;
-    /** 简单 KV，数据存 AILO 本体，自动持久化 */
+    private dial;
+    private handshake;
+    private attachHandlers;
+    private request;
     getData(key: string): Promise<string | null>;
     setData(key: string, value: string): Promise<void>;
     deleteData(key: string): Promise<void>;
+    sendMessage(msg: BridgeMessage): Promise<void>;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private onDisconnect;
+    private rejectAllPending;
+    private scheduleReconnect;
+    /** 主动关闭连接（不触发自动重连） */
     close(): void;
 }
 //# sourceMappingURL=ailo-client.d.ts.map

package/dist/ailo-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ailo-client.d.ts","sourceRoot":"","sources":["../src/ailo-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,YAAY,CAAC;AAqB5D;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,KAAK,CAAK;gBAEN,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,SAAK;IAO3E,OAAO,CAAC,OAAO;IAuBf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAwDxB,OAAO,CAAC,iBAAiB;IAUzB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAU3D,8BAA8B;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQ5C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,KAAK,IAAI,IAAI;CAUd"}
+{"version":3,"file":"ailo-client.d.ts","sourceRoot":"","sources":["../src/ailo-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAsB5E,8BAA8B;AAC9B,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,cAAc;IAC/C,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,GAAG,CAAmB;IAC9B,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,gBAAgB,CAAS;gBAErB,MAAM,EAAE,gBAAgB;IAIpC,kCAAkC;IAC5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAO9B,OAAO,CAAC,IAAI;IA6BZ,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,OAAO;IAmBT,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAK5C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5C,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9C,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,iBAAiB;IAczB,sBAAsB;IACtB,KAAK,IAAI,IAAI;CAOd"}

package/dist/ailo-client.js

@@ -1,126 +1,138 @@
 import WebSocket from "ws";
-function tagValue(tags, desc) {
+const REQUEST_TIMEOUT_MS = 30_000;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
+/** 按 kind 查找第一个匹配标签的 value */
+export function tagValue(tags, kind) {
     for (const t of tags) {
-        if (t.desc === desc)
+        if (t.kind === kind)
             return t.value;
     }
     return "";
 }
 /**
- * 反向 WebSocket 信号客户端。
+ * 反向 WebSocket 客户端。
  *
- * 连接 Ailo 网关，connect 时一并传入 channel 与 prompt，一步完成注册。
- * 负责 channel.accept（入站信号投递）。
- *
- * 出站（AI → 平台）由 MCP stdio 工具处理，不经过此客户端。
+ * 连接 Ailo 网关，自动重连（指数退避）、心跳（ping/pong）、请求超时。
+ * 实现 ChannelStorage 接口，可直接作为 ctx.storage 使用。
  */
 export class AiloClient {
     ws = null;
-    url;
-    token;
-    channel;
-    channelPrompt;
-    reconnectTimer = null;
+    cfg;
     reqId = 0;
-    constructor(url, token, channel, channelPrompt = "") {
-        this.url = url;
-        this.token = token;
-        this.channel = channel;
-        this.channelPrompt = channelPrompt;
+    pending = new Map();
+    heartbeatTimer = null;
+    pongTimer = null;
+    reconnectTimer = null;
+    reconnectAttempt = 0;
+    intentionalClose = false;
+    constructor(config) {
+        this.cfg = config;
     }
-    request(method, params) {
-        return new Promise((resolve, reject) => {
-            if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-                reject(new Error("Ailo WebSocket not connected"));
-                return;
-            }
-            const id = `${method}-${++this.reqId}`;
-            const handler = (raw) => {
-                const frame = JSON.parse(raw.toString());
-                if (frame.type === "res" && frame.id === id) {
-                    this.ws?.off("message", handler);
-                    if (frame.ok) {
-                        resolve(frame.payload ?? {});
-                    }
-                    else {
-                        reject(new Error(frame.error?.message ?? `${method} failed`));
-                    }
-                }
-            };
-            this.ws.on("message", handler);
-            this.ws.send(JSON.stringify({ type: "req", id, method, params }));
-        });
+    /** 建立连接并完成握手。首次调用；后续断线由内部自动重连。 */
+    async connect() {
+        this.intentionalClose = false;
+        await this.dial();
     }
-    connect() {
+    // ── 连接/握手 ──
+    dial() {
         return new Promise((resolve, reject) => {
-            const ws = new WebSocket(this.url);
-            this.ws = ws;
+            const ws = new WebSocket(this.cfg.url);
+            let settled = false;
+            const settle = (ok, err) => {
+                if (settled)
+                    return;
+                settled = true;
+                ok ? resolve() : reject(err);
+            };
             ws.on("open", async () => {
                 try {
-                    const id = `connect-${++this.reqId}`;
-                    ws.send(JSON.stringify({
-                        type: "req",
-                        id,
-                        method: "connect",
-                        params: {
-                            role: "channel",
-                            token: this.token,
-                            channel: this.channel,
-                            prompt: this.channelPrompt,
-                            capabilities: ["text", "media"],
-                            direction: "bidirectional",
-                        },
-                    }));
-                    await new Promise((res, rej) => {
-                        const onMsg = (raw) => {
-                            const frame = JSON.parse(raw.toString());
-                            if (frame.type === "res" && frame.id === id) {
-                                ws.off("message", onMsg);
-                                if (frame.ok) {
-                                    res();
-                                }
-                                else {
-                                    rej(new Error(frame.error?.message ?? "connect failed"));
-                                }
-                            }
-                        };
-                        ws.on("message", onMsg);
-                    });
-                    resolve();
+                    await this.handshake(ws);
+                    this.ws = ws;
+                    this.reconnectAttempt = 0;
+                    this.attachHandlers(ws);
+                    this.startHeartbeat();
+                    settle(true);
                 }
                 catch (err) {
-                    reject(err);
+                    ws.close();
+                    settle(false, err);
                 }
             });
-            ws.on("close", () => {
-                this.ws = null;
-                this.scheduleReconnect(resolve);
-            });
-            ws.on("error", (err) => {
-                reject(err);
-            });
+            ws.on("error", (err) => settle(false, err));
+            ws.on("close", () => settle(false, new Error("closed before handshake")));
         });
     }
-    scheduleReconnect(onReconnect) {
-        if (this.reconnectTimer)
-            return;
-        this.reconnectTimer = setTimeout(() => {
-            this.reconnectTimer = null;
-            this.connect()
-                .then(() => onReconnect?.())
-                .catch(() => this.scheduleReconnect(onReconnect));
-        }, 3000);
+    handshake(ws) {
+        const id = `connect-${++this.reqId}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                ws.off("message", handler);
+                reject(new Error("handshake timeout"));
+            }, REQUEST_TIMEOUT_MS);
+            const handler = (raw) => {
+                const frame = JSON.parse(raw.toString());
+                if (frame.type === "res" && frame.id === id) {
+                    clearTimeout(timer);
+                    ws.off("message", handler);
+                    frame.ok ? resolve() : reject(new Error(frame.error?.message ?? "connect rejected"));
+                }
+            };
+            ws.on("message", handler);
+            ws.send(JSON.stringify({
+                type: "req", id, method: "connect",
+                params: {
+                    role: "channel",
+                    token: this.cfg.token,
+                    channel: this.cfg.channel,
+                    displayName: this.cfg.displayName,
+                    defaultRequiresResponse: this.cfg.defaultRequiresResponse ?? true,
+                    prompt: this.cfg.channelPrompt ?? "",
+                },
+            }));
+        });
     }
-    sendMessage(msg) {
-        const chatId = tagValue(msg.contextTags, "会话") || "main";
-        return this.request("channel.accept", {
-            chatId,
-            text: msg.text,
-            contextTags: msg.contextTags,
-            attachments: msg.attachments ?? [],
+    attachHandlers(ws) {
+        ws.on("message", (raw) => {
+            const frame = JSON.parse(raw.toString());
+            if (frame.type === "res" && frame.id) {
+                const req = this.pending.get(frame.id);
+                if (!req)
+                    return;
+                this.pending.delete(frame.id);
+                clearTimeout(req.timer);
+                frame.ok
+                    ? req.resolve(frame.payload ?? {})
+                    : req.reject(new Error(frame.error?.message ?? "request failed"));
+            }
+        });
+        ws.on("close", () => this.onDisconnect());
+        ws.on("pong", () => {
+            if (this.pongTimer) {
+                clearTimeout(this.pongTimer);
+                this.pongTimer = null;
+            }
         });
     }
-    /** 简单 KV，数据存 AILO 本体，自动持久化 */
+    // ── 请求/响应 ──
+    request(method, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+                reject(new Error("not connected"));
+                return;
+            }
+            const id = `${method}-${++this.reqId}`;
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`${method} timeout (${REQUEST_TIMEOUT_MS}ms)`));
+            }, REQUEST_TIMEOUT_MS);
+            this.pending.set(id, { resolve: resolve, reject, timer });
+            this.ws.send(JSON.stringify({ type: "req", id, method, params }));
+        });
+    }
+    // ── ChannelStorage ──
     async getData(key) {
         const res = await this.request("channel.data.get", { key });
         return res.found ? (res.value ?? null) : null;
@@ -131,11 +143,81 @@ export class AiloClient {
     async deleteData(key) {
         await this.request("channel.data.delete", { key });
     }
+    // ── 消息投递 ──
+    sendMessage(msg) {
+        const chatId = tagValue(msg.contextTags, "chat_id") || "main";
+        const params = {
+            chatId,
+            text: msg.text ?? "",
+            contextTags: msg.contextTags,
+            attachments: msg.attachments ?? [],
+        };
+        if (msg.requiresResponse !== undefined) {
+            params.requiresResponse = msg.requiresResponse;
+        }
+        return this.request("channel.accept", params).then(() => { });
+    }
+    // ── 心跳 ──
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+                return;
+            this.ws.ping();
+            this.pongTimer = setTimeout(() => {
+                console.error("[ailo-client] pong timeout, closing");
+                this.ws?.terminate();
+            }, HEARTBEAT_TIMEOUT_MS);
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.pongTimer) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+    }
+    // ── 断线/重连 ──
+    onDisconnect() {
+        this.ws = null;
+        this.stopHeartbeat();
+        this.rejectAllPending(new Error("disconnected"));
+        if (!this.intentionalClose)
+            this.scheduleReconnect();
+    }
+    rejectAllPending(err) {
+        for (const [, req] of this.pending) {
+            clearTimeout(req.timer);
+            req.reject(err);
+        }
+        this.pending.clear();
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        const delay = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempt, RECONNECT_MAX_MS);
+        this.reconnectAttempt++;
+        console.error(`[ailo-client] reconnecting in ${delay}ms (attempt ${this.reconnectAttempt})`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.dial().catch((err) => {
+                console.error("[ailo-client] reconnect failed:", err.message);
+                this.scheduleReconnect();
+            });
+        }, delay);
+    }
+    /** 主动关闭连接（不触发自动重连） */
     close() {
+        this.intentionalClose = true;
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        this.stopHeartbeat();
+        this.rejectAllPending(new Error("client closed"));
         if (this.ws) {
             this.ws.close();
             this.ws = null;

package/dist/bootstrap.d.ts

@@ -9,16 +9,17 @@ import type { BridgeHandler } from "./types.js";
 export interface McpChannelConfig {
     /** MCP 名称（如 channel:feishu），connect 时与 token 一起发送供服务端校验。不传则从 AILO_MCP_NAME 读取 */
     channelName?: string;
+    /** 中文通道显示名（如 "飞书"），握手时锁定，框架自动注入 TagChannel */
+    displayName: string;
+    /** 通道默认行为：true=主动信号（触发 LLM 处理），false=被动感知（仅记录）。默认 true */
+    defaultRequiresResponse?: boolean;
     /** 平台 Handler 实例（需实现 BridgeHandler 接口） */
     handler: BridgeHandler;
     /** Ailo WebSocket 网关地址。不传则从 AILO_WS_URL 读取 */
     ailoWsUrl?: string;
     /** Ailo 网关认证 Token。不传则从 AILO_TOKEN 读取 */
     ailoToken?: string;
-    /**
-     * 构建通道静态提示词（connect 时注册）。
-     * 连接时调用一次，注册该通道的特殊规则。
-     */
+    /** 构建通道静态提示词（connect 时注册）。逐步废弃：通道指令应迁移到 MCP 工具定义中。 */
     buildChannelPrompt?: () => string;
     /** 预配置的 MCP Server 实例（已注册好工具） */
     mcpServer: McpServer;
@@ -34,12 +35,12 @@ export declare function runMcp(mcpServer: McpServer): void;
 /**
  * 启动 MCP 通道
  *
- * 通用流程：
+ * 流程：
  *   1. stdio-guard 已在 index 入口加载，console.log 等自动重定向到 stderr
  *   2. 启动 MCP stdio server（暴露出站工具）
  *   3. 建立反向 WebSocket 连接（connect 时传入 channel + prompt，一步完成注册）
- *   4. 接线入站：handler.setOnMessage → 组装 contextTags → channel.accept
- *   5. 启动平台 Handler
+ *   4. 组装 ChannelContext（accept + storage）
+ *   5. handler.start(ctx) —— handler 拿到一切就绪的上下文
  *   6. 注册 SIGINT / SIGTERM 优雅退出
  */
 export declare function runMcpChannel(config: McpChannelConfig): void;

package/dist/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,MAAM,CAAC;IAClC,iCAAiC;IACjC,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CASjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAkF5D"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,YAAY,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,0CAA0C;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,MAAM,MAAM,CAAC;IAClC,iCAAiC;IACjC,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAQjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CA0E5D"}

package/dist/bootstrap.js

@@ -10,7 +10,6 @@ export function defaultBuildChannelPrompt() {
  * stdout 被 MCP stdio 占用，日志自动重定向到 stderr。
  */
 export function runMcp(mcpServer) {
-    // stdio-guard 需在入口 import，runMcp 使用者应 import 自 @lmcl/ailo-mcp-sdk
     const transport = new StdioServerTransport();
     mcpServer.connect(transport).then(() => {
         console.log("[mcp] MCP stdio server started");
@@ -22,12 +21,12 @@ export function runMcp(mcpServer) {
 /**
  * 启动 MCP 通道
  *
- * 通用流程：
+ * 流程：
  *   1. stdio-guard 已在 index 入口加载，console.log 等自动重定向到 stderr
  *   2. 启动 MCP stdio server（暴露出站工具）
  *   3. 建立反向 WebSocket 连接（connect 时传入 channel + prompt，一步完成注册）
- *   4. 接线入站：handler.setOnMessage → 组装 contextTags → channel.accept
- *   5. 启动平台 Handler
+ *   4. 组装 ChannelContext（accept + storage）
+ *   5. handler.start(ctx) —— handler 拿到一切就绪的上下文
  *   6. 注册 SIGINT / SIGTERM 优雅退出
  */
 export function runMcpChannel(config) {
@@ -39,66 +38,63 @@ export function runMcpChannel(config) {
         console.error("Missing AILO_WS_URL, AILO_TOKEN or AILO_MCP_NAME. Channel must be started by Ailo MCP.");
         process.exit(1);
     }
-    // stdio-guard 已在 index 入口加载，console.log 等已重定向到 stderr
     const tag = `[${channelName}]`;
-    const channelPrompt = config.buildChannelPrompt
-        ? config.buildChannelPrompt()
-        : defaultBuildChannelPrompt();
-    const client = new AiloClient(ailoWsUrl, ailoToken, channelName, channelPrompt);
-    // 入站：平台 → Ailo（channel.accept），msg 必须自带 contextTags
-    handler.setOnMessage(async (msg) => {
-        const hasContent = msg.text.trim() !== "" || (msg.attachments?.length ?? 0) > 0;
-        if (!hasContent) {
-            console.log(`${tag} skipped (no text or attachments)`);
-            return;
-        }
-        console.log(`${tag} ${msg.text.slice(0, 80)}`);
-        try {
-            await client.sendMessage(msg);
-        }
-        catch (err) {
-            console.error(`${tag} send to Ailo failed:`, err);
-        }
+    const channelPrompt = config.buildChannelPrompt?.() ?? defaultBuildChannelPrompt();
+    const defaultRequiresResponse = config.defaultRequiresResponse ?? true;
+    const client = new AiloClient({
+        url: ailoWsUrl,
+        token: ailoToken,
+        channel: channelName,
+        displayName: config.displayName,
+        defaultRequiresResponse,
+        channelPrompt,
     });
-    // 优雅退出
     const shutdown = () => {
         console.log(`${tag} shutting down...`);
-        handler.stop?.();
+        Promise.resolve(handler.stop()).catch(() => { });
         client.close();
         process.exit(0);
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
     (async () => {
-        // 1. 启动 MCP stdio server
+        // 1. MCP stdio
         const transport = new StdioServerTransport();
         await mcpServer.connect(transport);
         console.log(`${tag} MCP stdio server started`);
-        // 2. 建立反向 WebSocket 连接
+        // 2. Ailo WebSocket
         try {
             await client.connect();
-            console.log(`${tag} reverse WebSocket connected`);
+            console.log(`${tag} Ailo WebSocket connected`);
         }
         catch (err) {
-            console.error(`${tag} reverse WebSocket connect failed:`, err);
+            console.error(`${tag} Ailo WebSocket connect failed:`, err);
             process.exit(1);
         }
-        // 3. 注入持久化存储
-        if (handler.setDataProvider) {
-            handler.setDataProvider(client);
-        }
-        // 4. 启动平台 Handler
+        // 3. ChannelContext: accept + storage，一次性就绪
+        const ctx = {
+            accept: async (msg) => {
+                const hasContent = (msg.text?.trim() ?? "") !== ""
+                    || (msg.attachments?.length ?? 0) > 0
+                    || msg.contextTags.length > 0;
+                if (!hasContent) {
+                    console.log(`${tag} skipped (empty message)`);
+                    return;
+                }
+                console.log(`${tag} ${(msg.text ?? "").slice(0, 80)}`);
+                await client.sendMessage(msg);
+            },
+            storage: client,
+        };
+        // 4. Start handler
         console.log(`${tag} starting handler...`);
-        const startResult = handler.start();
-        if (startResult && typeof startResult.then === "function") {
-            try {
-                await startResult;
-                console.log(`${tag} handler started successfully`);
-            }
-            catch (err) {
-                console.error(`${tag} handler start failed:`, err);
-                process.exit(1);
-            }
+        try {
+            await handler.start(ctx);
+            console.log(`${tag} handler started`);
+        }
+        catch (err) {
+            console.error(`${tag} handler start failed:`, err);
+            process.exit(1);
         }
     })();
 }

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import "./stdio-guard.js";
-export { AiloClient } from "./ailo-client.js";
+export { AiloClient, tagValue } from "./ailo-client.js";
+export type { AiloClientConfig } from "./ailo-client.js";
 export { getWorkDir } from "./workdir.js";
 export { runMcp, runMcpChannel, defaultBuildChannelPrompt } from "./bootstrap.js";
 export type { McpChannelConfig } from "./bootstrap.js";
-export type { Attachment, BridgeHandler, BridgeMessage, ContextTag, } from "./types.js";
+export type { Attachment, BridgeHandler, BridgeMessage, ChannelContext, ChannelStorage, ContextTag, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAClF,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,aAAa,EACb,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAClF,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,aAAa,EACb,aAAa,EACb,cAAc,EACd,cAAc,EACd,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
 import "./stdio-guard.js"; // 必须最先：stdout 被 MCP stdio 占用，框架层统一拦截非 JSON-RPC 输出
-export { AiloClient } from "./ailo-client.js";
+export { AiloClient, tagValue } from "./ailo-client.js";
 export { getWorkDir } from "./workdir.js";
 export { runMcp, runMcpChannel, defaultBuildChannelPrompt } from "./bootstrap.js";

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 /**
- * 附件类型（图片/音频/视频/文件等）
+ * 附件（入站/出站通用）
+ *
  * 入站图片：path/url/base64 三选一，直接使用 LLM 多模态。其他类型：path/url/ref+channel/base64。
  * 出站：file_path 或 base64 或 url。
  */
@@ -15,38 +16,60 @@ export type Attachment = {
     file_path?: string;
 };
 /**
- * 时空场标签：desc+value+core，全中文。
+ * 时空场标签。
+ *
+ * kind: 受控词汇（channel/participant/group/conv_type/location/device/modality/chat_id/sender_id）
+ * streamKey: 参与 stream_key 推导（标识事件流归属）
+ * routing: 仅路由用途——不嵌入向量，不展示在历史邮戳
  */
 export type ContextTag = {
-    desc: string;
+    kind: string;
     value: string;
-    core: boolean;
+    streamKey: boolean;
+    routing?: boolean;
 };
 /**
- * 桥接器入站消息（平台 → Ailo）
+ * 入站消息（平台 → Ailo）
  *
  * 时空场模型：通道自己定义，全在 contextTags 里。
  */
 export type BridgeMessage = {
-    text: string;
+    text?: string;
     contextTags: ContextTag[];
     attachments?: Attachment[];
+    /** 本条消息是否需要 LLM 响应（覆盖通道级 defaultRequiresResponse） */
+    requiresResponse?: boolean;
 };
-/** setDataProvider 接收的对象，SDK 注入，直接用 get/set/delete 即可 */
-type ChannelStorage = {
+/**
+ * 通道级 KV 存储（数据持久化在 Ailo 侧）
+ */
+export interface ChannelStorage {
     getData(key: string): Promise<string | null>;
     setData(key: string, value: string): Promise<void>;
     deleteData(key: string): Promise<void>;
-};
+}
 /**
- * 通道 Handler 统一接口
+ * 通道运行时上下文
+ *
+ * SDK 在调用 handler.start() 时注入，handler 通过 ctx 与 Ailo 交互。
+ * 替代旧版 setOnMessage + setDataProvider 的 setter 注入模式——
+ * 所有依赖在 start() 一次性就绪，无时序歧义。
+ */
+export interface ChannelContext {
+    /** 投递入站消息到 Ailo（平台 → Ailo）。SDK 内部做空消息过滤。 */
+    accept(msg: BridgeMessage): Promise<void>;
+    /** 通道级 KV 存储 */
+    storage: ChannelStorage;
+}
+/**
+ * 通道 Handler 接口
+ *
+ * 通道需实现此接口。SDK 保证 start(ctx) 调用时 ctx 已就绪。
  */
 export interface BridgeHandler {
-    setOnMessage(handler: (msg: BridgeMessage) => void | Promise<void>): void;
-    start(): void | Promise<void>;
-    stop?(): void;
-    /** 可选，SDK 连接后注入带 get/set/delete 的对象，直接用 */
-    setDataProvider?(storage: ChannelStorage): void;
+    /** 启动 Handler。ctx 包含与 Ailo 交互所需的一切。 */
+    start(ctx: ChannelContext): void | Promise<void>;
+    /** 优雅停止。SDK 在 SIGINT/SIGTERM 时调用。 */
+    stop(): void | Promise<void>;
 }
-export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;CAC5B,CAAC;AAEF,yDAAyD;AACzD,KAAK,cAAc,GAAG;IACpB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1E,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,IAAI,IAAI,CAAC;IACd,2CAA2C;IAC3C,eAAe,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;CACjD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,gBAAgB;IAChB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,qCAAqC;IACrC,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lmcl/ailo-mcp-sdk",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Ailo MCP SDK - 通道通过 MCP 注册发送消息能力，用于开发感知通道",
   "type": "module",
   "main": "dist/index.js",