keepwork-sdk 1.0.0

package/dist-npm/types/src/core/AgentRouter.d.ts

@@ -0,0 +1,342 @@
+/**
+ * AgentRouter.ts — 跨 iframe Agent 注册、发现与任务转发路由器
+ *
+ * 每个 KeepworkSDK 实例（在任意 window / iframe 中）持有一个 AgentRouter。
+ * 命名 ChatSession 可向本地路由器注册；路由器通过 `window.postMessage`
+ * 在整个 iframe 树中广播可用性，使任何 `submitTask` 调用都能发现并委托远程 agent。
+ *
+ * ## 协议约定
+ * - 所有 AgentRouter 消息携带 `is_agent_router: true` 标志
+ * - NPL 模块使用 `is_paracraft_message: true`，两者互不干扰
+ * - 同一消息的 `instanceId` / `sourceInstanceId` 等于本路由器 ID 时视为自回显，丢弃
+ *
+ * ## 使用示例
+ * ```ts
+ * // 在拥有 agent 的 iframe 中
+ * const router = window.keepwork.agentRouter;
+ * router.register('codeHelper', session);
+ *
+ * // 在父页面或其他 iframe 中
+ * const router = window.keepwork.agentRouter;
+ * router.addChildWindow(iframe.contentWindow);
+ * const result = await router.submitTask('codeHelper', { task: 'Explain KeepworkSDK' });
+ * ```
+ */
+/** AgentRouter 协议消息类型字符串 */
+declare const MSG: {
+    readonly REGISTER: "agent_register";
+    readonly REGISTER_ACK: "agent_register_ack";
+    readonly REGISTER_REJECT: "agent_register_reject";
+    readonly UNREGISTER: "agent_unregister";
+    readonly WINDOW_DISCONNECT: "agent_window_disconnect";
+    readonly TASK: "agent_task";
+    readonly TASK_RESULT: "agent_task_result";
+    readonly STREAM: "agent_stream";
+    readonly SYNC_ACK: "agent_sync_ack";
+};
+type MsgType = typeof MSG[keyof typeof MSG];
+/** AgentRouter 协议消息信封 */
+interface RouterMessage {
+    is_agent_router: true;
+    type: MsgType;
+    agentName?: string;
+    instanceId?: string;
+    sourceInstanceId?: string;
+    taskId?: string;
+    payload?: TaskPayload;
+    result?: unknown;
+    error?: string | null;
+    reason?: string;
+    syncId?: string;
+    request?: boolean;
+    syncBackfill?: boolean;
+    streamType?: string;
+    content?: unknown;
+    fullResponse?: unknown;
+    isRestartAgentSignal?: boolean;
+    promptFile?: string;
+    tools?: unknown[];
+    options?: Record<string, unknown>;
+}
+/** 任务载荷（submitTask 时传入） */
+export interface TaskPayload {
+    task?: string;
+    description?: string;
+    /** LLM 工具列表（传给 session.send） */
+    tools?: unknown;
+    maxIterations?: number;
+    systemPrompt?: string;
+    model?: string;
+    thinking?: unknown;
+    callbackMode?: string;
+    debounceSeconds?: number;
+    /** 是否绕过 LLM 直接执行工具 */
+    toolCallOnly?: boolean;
+    fnName?: string;
+    fnArgs?: unknown;
+    [key: string]: unknown;
+}
+/** 路由表条目 */
+interface RouteRecord {
+    windowRef: WindowProxy | NPLWindowProxy;
+    sourceInstanceId: string;
+    learnedFrom: WindowProxy | NPLWindowProxy;
+    updatedAt: number;
+}
+/** 任务注册表条目 */
+interface OriginTaskRecord {
+    kind: 'origin';
+    agentName: string;
+    createdAt: number;
+    outboundWindow: WindowProxy | NPLWindowProxy;
+    replyWindow: null;
+    onStream: ((msg: RouterMessage) => void) | null;
+    resolve: (value: unknown) => void;
+    reject: (reason: unknown) => void;
+    timeoutId: ReturnType<typeof setTimeout> | null;
+}
+interface RelayTaskRecord {
+    kind: 'relay';
+    agentName: string;
+    createdAt: number;
+    outboundWindow: WindowProxy | NPLWindowProxy;
+    replyWindow: WindowProxy | NPLWindowProxy;
+    onStream: null;
+    resolve: null;
+    reject: null;
+    timeoutId: null;
+}
+type TaskRecord = OriginTaskRecord | RelayTaskRecord;
+/** 本地 agent session 接口（ChatSession 的最小接口） */
+interface AgentSession {
+    handleTask?: (taskId: string, payload: TaskPayload, streamCb: (event: unknown) => void) => Promise<unknown>;
+    executeTool?: (fnName: string, fnArgs: unknown) => Promise<unknown>;
+    clear?: () => void;
+    send?: (task: string, options: Record<string, unknown>) => Promise<unknown>;
+    messages?: unknown[];
+    options?: Record<string, unknown>;
+}
+/** submitTask 的回调选项 */
+export interface SubmitTaskCallbacks {
+    onStream?: (msg: RouterMessage) => void;
+}
+/**
+ * NPLWindowProxy — 通过 NPLJS 向 Lua 端转发 postMessage 的虚拟 WindowProxy。
+ *
+ * 从 AgentRouter 的视角，此对象与真实 WindowProxy 完全等价：
+ * 同样存储在 `connectedWindows` 和 `routeTable` 中。
+ * `_sendTo()` 通过检测 `_isNPLWindowProxy` 标志选择 NPLJS 通道而非 postMessage。
+ */
+declare class NPLWindowProxy {
+    readonly _isNPLWindowProxy = true;
+    private _npljs;
+    private _sendEventName;
+    /**
+     * @param npljs         - NPLJS 实例（需暴露 SendMsg / OnMsg）
+     * @param sendEventName - JS→Lua 方向的 NPLJS 事件名
+     */
+    constructor(npljs: {
+        SendMsg: (event: string, msg: unknown) => void;
+    }, sendEventName: string);
+    /**
+     * 模拟 window.postMessage，通过 NPLJS 发送消息到 Lua 端。
+     * @param msg - 要发送的消息对象
+     */
+    postMessage(msg: unknown): void;
+}
+declare class AgentRouter {
+    /** 开启详细日志（调试用）。 */
+    static debug: boolean;
+    static _log(msgOrFn: string | (() => string), ...rest: unknown[]): void;
+    /** 此路由器实例的唯一 ID。 */
+    readonly instanceId: string;
+    /** 本地注册的 agent（agentName → session）。 */
+    readonly localAgents: Map<string, {
+        session: AgentSession;
+    }>;
+    /**
+     * 远程 agent 路由表（agentName → RouteRecord）。
+     * 记录消息应该发往哪个 windowRef 才能抵达对应 agent。
+     */
+    readonly routeTable: Map<string, RouteRecord>;
+    /**
+     * 任务注册表（taskId → TaskRecord）。
+     * origin 任务：由本路由器提交，持有 resolve/reject 回调。
+     * relay 任务：上游转发过来，需要将结果/流转发回 replyWindow。
+     */
+    readonly taskRegistry: Map<string, TaskRecord>;
+    /** window → 从该 window 学到的 agent 名集合（O(1) 清理索引）。 */
+    readonly windowAgents: Map<Window | NPLWindowProxy, Set<string>>;
+    /** window → 通过该 window 流转的 taskId 集合（O(1) 清理索引）。 */
+    readonly windowTasks: Map<Window | NPLWindowProxy, Set<string>>;
+    /** 已连接的子 iframe window 集合。 */
+    readonly connectedWindows: Set<Window | NPLWindowProxy>;
+    private _isDestroyed;
+    private _disconnectAnnounced;
+    private _messageHandler;
+    private _lifecycleHandler;
+    private _pendingSyncs;
+    private _nplWindowProxy;
+    private _nplRecvEventName;
+    /** 关联的 SDK 实例（用于读取 timeout 配置）。 */
+    _sdk?: {
+        timeout?: number;
+    };
+    constructor();
+    /**
+     * 在本路由器注册命名 agent，并向 iframe 树广播可用性。
+     * 若名称已被占用（本地或远程），返回 false。
+     *
+     * @param agentName - agent 唯一名称
+     * @param session   - 处理该 agent 任务的 ChatSession 实例
+     * @returns 注册成功返回 true，名称冲突返回 false
+     */
+    register(agentName: string, session: AgentSession): boolean;
+    /**
+     * 注销本地 agent 并广播移除消息。
+     * @param agentName - 要注销的 agent 名称
+     */
+    unregister(agentName: string): void;
+    /**
+     * 检查 agent（本地或远程）是否已知。
+     * @param agentName - agent 名称
+     */
+    hasAgent(agentName: string): boolean;
+    /**
+     * 检查 agent 是否只存在于路由表（即在另一个 iframe 中）。
+     * @param agentName - agent 名称
+     */
+    hasRemoteAgent(agentName: string): boolean;
+    /**
+     * 等待 agent 出现（轮询路由表 / 注册事件），若已存在则立即 resolve。
+     *
+     * @param agentName - agent 名称
+     * @param timeout   - 最大等待毫秒数（默认 5000）
+     */
+    waitForAgent(agentName: string, timeout?: number): Promise<void>;
+    /**
+     * 向远程 agent 提交任务，返回 Promise 等待结果。
+     *
+     * @param agentName - 目标 agent 名称
+     * @param payload   - 任务载荷（task / tools / maxIterations / systemPrompt / model 等）
+     * @param callbacks - 可选：onStream 流式回调
+     * @returns agent 任务结果
+     */
+    submitTask(agentName: string, payload: TaskPayload, callbacks?: SubmitTaskCallbacks): Promise<unknown>;
+    /**
+     * 注册子 iframe 的 contentWindow 以加入路由树。
+     * 自动发起同步重试，直到子窗口确认。
+     *
+     * @param windowRef - 子 iframe 的 contentWindow（或 NPLWindowProxy）
+     */
+    addChildWindow(windowRef: WindowProxy | NPLWindowProxy): void;
+    /**
+     * 移除子 iframe window，清理其相关路由和任务。
+     * @param windowRef - 要移除的 window
+     */
+    removeChildWindow(windowRef: WindowProxy | NPLWindowProxy): void;
+    /**
+     * 销毁路由器：广播断开通知、注销所有 agent、拒绝所有待处理任务、清理监听器。
+     * 调用后此实例不可再使用。
+     */
+    destroy(): void;
+    /**
+     * 将本路由器与 Lua 侧 AgentRouter.lua 通过 NPLJS 连接。
+     *
+     * 创建 NPLWindowProxy 并将其插入现有路由基础设施，
+     * AgentRouter 协议消息通过 NPLJS 透明转发，而非 postMessage。
+     *
+     * @param npljs   - NPLJS 实例（需提供 SendMsg / OnMsg）
+     * @param options - sendEventName（JS→Lua）/ recvEventName（Lua→JS）
+     * @returns this（链式调用）
+     */
+    attachNPLJS(npljs: {
+        SendMsg: (event: string, msg: unknown) => void;
+        OnMsg: (event: string, cb: (data: unknown) => void) => void;
+        OffMsg: (event: string) => void;
+    }, options?: {
+        sendEventName?: string;
+        recvEventName?: string;
+    }): this;
+    /**
+     * 断开通过 attachNPLJS 建立的 NPLJS 桥接。
+     *
+     * @param npljs - 与 attachNPLJS 相同的 NPLJS 实例
+     */
+    detachNPLJS(npljs: {
+        OffMsg: (event: string) => void;
+    }): void;
+    /**
+     * 向指定 window 发送消息。
+     * NPLWindowProxy 通过 NPLJS 路由，普通 WindowProxy 通过 postMessage。
+     * @private
+     */
+    private _sendTo;
+    /**
+     * 广播消息到父窗口和所有子 iframe，排除指定 window（防止回显循环）。
+     * @private
+     */
+    private _broadcast;
+    /** @private 主消息事件处理器。 */
+    private _onMessage;
+    /** @private 处理 agent_register 消息：存储路由并转发。 */
+    private _handleRegister;
+    /** @private 处理 agent_register_ack（当前仅记录日志）。 */
+    private _handleRegisterAck;
+    /** @private 处理 agent_register_reject（回滚本地乐观注册）。 */
+    private _handleRegisterReject;
+    /** @private 处理 agent_unregister（验证来源后删除路由，防止劫持）。 */
+    private _handleUnregister;
+    /** @private 处理 agent_window_disconnect：清理该 window 的所有路由和任务。 */
+    private _handleWindowDisconnect;
+    /** @private 处理 agent_task：本地执行或转发到正确的 window。 */
+    private _handleTask;
+    /** @private 在本地 session 上执行任务（handleTask 接口 或 legacy send 接口）。 */
+    private _executeLocalTask;
+    /**
+     * @private 直接执行工具调用（bypasses LLM，payload.toolCallOnly=true 时调用）。
+     * 支持 RestartAgentSignal 跨 iframe 序列化。
+     */
+    private _executeLocalToolCall;
+    /** @private 处理 agent_task_result：resolve origin 任务或向上游中继。 */
+    private _handleTaskResult;
+    /** @private 处理 agent_stream：转发给 origin 回调或向上游中继。 */
+    private _handleStream;
+    /** @private 处理 agent_sync_ack：响应或确认同步。 */
+    private _handleSyncAck;
+    /** @private 创建 origin 任务记录（带超时自动拒绝）。 */
+    private _createOriginTask;
+    /** @private 创建 relay 任务记录（转发上游任务）。 */
+    private _createRelayTask;
+    /**
+     * @private 幂等移除任务：清理超时、删除 window 索引，返回被删除的记录（已删除返回 null）。
+     */
+    private _clearTask;
+    private _indexWindowAgent;
+    private _indexWindowTask;
+    private _isExpectedTaskSource;
+    /**
+     * @private 断开 window 时的确定性清理：
+     * 1. 从 connectedWindows 删除
+     * 2. 删除该 window 持有的所有路由，广播 UNREGISTER
+     * 3. 失败该 window 关联的所有任务（origin reject / relay 通知上游）
+     */
+    private _cleanupWindow;
+    /**
+     * @private 将已知的所有 agent（本地 + 路由表）同步到指定 window。
+     * backfill 消息携带 syncBackfill:true，防止接收方递归回传。
+     */
+    private _syncKnownAgentsToWindow;
+    /**
+     * @private 带重试的 agent 同步（Phase 1 快速重试 ~5s，Phase 2 每 5s 一次）。
+     * 子窗口确认后停止。
+     */
+    private _syncWithRetry;
+    /** @private 广播 window_disconnect 通知（幂等）。 */
+    private _announceWindowDisconnect;
+    /** @private 页面生命周期钩子：pagehide 时销毁（bfcache 保留的页面除外）。 */
+    private _handleLifecycleTeardown;
+}
+export default AgentRouter;
+export { NPLWindowProxy };
+//# sourceMappingURL=AgentRouter.d.ts.map

package/dist-npm/types/src/core/AgentRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRouter.d.ts","sourceRoot":"","sources":["../../../../src/core/AgentRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,4BAA4B;AAC5B,QAAA,MAAM,GAAG;;;;;;;;;;CAUC,CAAC;AAEX,KAAK,OAAO,GAAG,OAAO,GAAG,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AAE5C,yBAAyB;AACzB,UAAU,aAAa;IACrB,eAAe,EAAE,IAAI,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,2BAA2B;AAC3B,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,YAAY;AACZ,UAAU,WAAW;IACnB,SAAS,EAAE,WAAW,GAAG,cAAc,CAAC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,WAAW,GAAG,cAAc,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,cAAc;AACd,UAAU,gBAAgB;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,WAAW,GAAG,cAAc,CAAC;IAC7C,WAAW,EAAE,IAAI,CAAC;IAClB,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAChD,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,SAAS,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAC;CACjD;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,WAAW,GAAG,cAAc,CAAC;IAC7C,WAAW,EAAE,WAAW,GAAG,cAAc,CAAC;IAC1C,QAAQ,EAAE,IAAI,CAAC;IACf,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,IAAI,CAAC;IACb,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,KAAK,UAAU,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAErD,6CAA6C;AAC7C,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5G,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,uBAAuB;AACvB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC;CACzC;AAyBD;;;;;;GAMG;AACH,cAAM,cAAc;IAClB,QAAQ,CAAC,iBAAiB,QAAQ;IAClC,OAAO,CAAC,MAAM,CAAqD;IACnE,OAAO,CAAC,cAAc,CAAS;IAE/B;;;OAGG;gBACS,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,EAAE,aAAa,EAAE,MAAM;IAK5F;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;CAGhC;AAID,cAAM,WAAW;IACf,mBAAmB;IACnB,MAAM,CAAC,KAAK,UAAS;IAErB,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMvE,oBAAoB;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,wCAAwC;IACxC,QAAQ,CAAC,WAAW;iBAA8B,YAAY;OAAM;IAEpE;;;OAGG;IACH,QAAQ,CAAC,UAAU,2BAAkC;IAErD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,0BAAiC;IAEtD,mDAAmD;IACnD,QAAQ,CAAC,YAAY,4CAAwD;IAE7E,oDAAoD;IACpD,QAAQ,CAAC,WAAW,4CAAwD;IAE5E,8BAA8B;IAC9B,QAAQ,CAAC,gBAAgB,+BAA2C;IAEpE,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,iBAAiB,CAAyB;IAClD,OAAO,CAAC,aAAa,CAAiC;IACtD,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,iBAAiB,CAAuB;IAChD,mCAAmC;IACnC,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;;IAc5B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO;IAY3D;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAOnC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIpC;;;OAGG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI1C;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9D;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,GAAE,mBAAwB,GAAG,OAAO,CAAC,OAAO,CAAC;IAkB1G;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,WAAW,GAAG,cAAc,GAAG,IAAI;IAM7D;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,WAAW,GAAG,cAAc,GAAG,IAAI;IAIhE;;;OAGG;IACH,OAAO,IAAI,IAAI;IAgCf;;;;;;;;;OASG;IACH,WAAW,CACT,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,KAAK,IAAI,CAAC;QAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,EACvJ,OAAO,GAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/D,IAAI;IA8BP;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,GAAG,IAAI;IAW7D;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAYf;;;OAGG;IACH,OAAO,CAAC,UAAU;IAYlB,yBAAyB;IACzB,OAAO,CAAC,UAAU;IAuBlB,6CAA6C;IAC7C,OAAO,CAAC,eAAe;IAsCvB,+CAA+C;IAC/C,OAAO,CAAC,kBAAkB;IAI1B,mDAAmD;IACnD,OAAO,CAAC,qBAAqB;IAQ7B,oDAAoD;IACpD,OAAO,CAAC,iBAAiB;IAezB,+DAA+D;IAC/D,OAAO,CAAC,uBAAuB;IAO/B,iDAAiD;YACnC,WAAW;IAwBzB,kEAAkE;YACpD,iBAAiB;IA6D/B;;;OAGG;YACW,qBAAqB;IAwCnC,6DAA6D;IAC7D,OAAO,CAAC,iBAAiB;IAwBzB,oDAAoD;IACpD,OAAO,CAAC,aAAa;IAarB,0CAA0C;IAC1C,OAAO,CAAC,cAAc;IAWtB,wCAAwC;IACxC,OAAO,CAAC,iBAAiB;IAiBzB,sCAAsC;IACtC,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACH,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,qBAAqB;IAI7B;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IA+BtB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAehC;;;OAGG;IACH,OAAO,CAAC,cAAc;IAoBtB,4CAA4C;IAC5C,OAAO,CAAC,yBAAyB;IAMjC,uDAAuD;IACvD,OAAO,CAAC,wBAAwB;CAIjC;AAED,eAAe,WAAW,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist-npm/types/src/core/NPL.d.ts

@@ -0,0 +1,251 @@
+/**
+ * NPL.ts — Paracraft / NPL（神经并行语言）通信桥接模块
+ *
+ * 提供 Keepwork 前端与 Paracraft 引擎之间的双向消息通信能力：
+ * - `NPLUtil`：静态工具集（postMessage 监听、系统检测、微信检测）
+ * - `NPLJS`：高级 NPL 通信类，带消息 ID 回调和加载握手
+ * - `ParacraftEvent`：Keepwork↔Paracraft 事件总线（前缀隔离）
+ *
+ * ## 使用前提
+ * 打开 HTML 时需在 URL 中带以下参数之一（由 Paracraft /open 命令自动注入）：
+ * - `?asWebviewInParacraftClient=true`
+ * - `?asIframeInWebParacraft=true`
+ *
+ * ## 快速上手
+ * ```ts
+ * // 初始化监听（由 index.ts 自动调用）
+ * NPLUtil.initializeMessageListeners();
+ *
+ * // 高级通信
+ * window.NPLJSInstance = new NPLJS();
+ * window.paracraftEvent = new ParacraftEvent(window.NPLJSInstance);
+ * ```
+ *
+ * ## 消息前缀约定
+ * - 进入方向（Paracraft → Keepwork）：`@keepwork_`
+ * - 发出方向（Keepwork → Paracraft）：`@webparacraft_`
+ */
+/**
+ * 从 URL search 参数读取指定参数值。
+ * @param name - 参数名
+ * @returns 参数值，不存在时返回空字符串
+ */
+declare function getQueryString(name: string): string;
+/** 微信浏览器检测结果 */
+interface WxEnv {
+    isWeChat: boolean;
+    isMiniProgram: boolean;
+    isWorkWeChat: boolean;
+    isAnyWeChat: boolean;
+}
+/**
+ * 检测当前是否运行在微信系列环境中。
+ * 非浏览器环境（SSR）返回全 false。
+ */
+declare function isWeChatBrowser(): WxEnv;
+/**
+ * 获取当前运行平台标识。
+ * 优先读取 `window.paracraft_platform`，然后 URL 参数，最后 UA 检测。
+ */
+declare function getSystem(): string;
+/**
+ * NPL 底层通信对象。
+ * 根据当前平台（iOS/macOS/Windows WebView/Emscripten/Android）选择对应的通信机制。
+ */
+declare const NPL: {
+    /**
+     * 向 Paracraft 发送 NPL 消息（跨平台派发）。
+     *
+     * @param filename - NPL 文件名（作为消息路由 key）
+     * @param msg      - 消息体（任意可序列化对象）
+     */
+    activate: (filename: string, msg: unknown) => void;
+    /**
+     * 注册指定文件名的消息接收回调。
+     *
+     * @param callback - 消息回调函数
+     * @param params   - 包含 filename 的参数对象
+     */
+    this: (callback: (msg: unknown) => void, params?: {
+        filename?: string;
+    }) => void;
+    /**
+     * 接收来自 Paracraft 的 NPL 消息并派发给已注册的回调。
+     *
+     * @param filename - NPL 文件名（消息路由 key）
+     * @param msg      - 消息体
+     */
+    receive: (filename: string, msg: unknown) => void;
+};
+/**
+ * 初始化全局 window.message 监听器（Emscripten/iframe 环境）。
+ *
+ * 仅当非 WebView / Android / iOS 原生环境（或处于微信环境）时注册，
+ * 防止与原生通道冲突。由 `index.ts` 在 SDK 加载时自动调用。
+ */
+declare function initializeMessageListeners(): void;
+/**
+ * NPLUtil — NPL 通信静态工具集。
+ * 暴露底层 NPL 对象和初始化方法，供外部直接调用。
+ */
+declare class NPLUtil {
+    static readonly allMsg: Record<string, (msg: unknown) => void>;
+    static readonly NPL: {
+        /**
+         * 向 Paracraft 发送 NPL 消息（跨平台派发）。
+         *
+         * @param filename - NPL 文件名（作为消息路由 key）
+         * @param msg      - 消息体（任意可序列化对象）
+         */
+        activate: (filename: string, msg: unknown) => void;
+        /**
+         * 注册指定文件名的消息接收回调。
+         *
+         * @param callback - 消息回调函数
+         * @param params   - 包含 filename 的参数对象
+         */
+        this: (callback: (msg: unknown) => void, params?: {
+            filename?: string;
+        }) => void;
+        /**
+         * 接收来自 Paracraft 的 NPL 消息并派发给已注册的回调。
+         *
+         * @param filename - NPL 文件名（消息路由 key）
+         * @param msg      - 消息体
+         */
+        receive: (filename: string, msg: unknown) => void;
+    };
+    static readonly initializeMessageListeners: typeof initializeMessageListeners;
+    static readonly getSystem: typeof getSystem;
+    static readonly getQueryString: typeof getQueryString;
+    static readonly isWeChatBrowser: typeof isWeChatBrowser;
+}
+/** NPLJS 消息体结构 */
+interface NPLJSMessage {
+    msgid?: string;
+    msgname?: string;
+    msgdata?: unknown;
+    request_reply?: boolean;
+    response_reply?: boolean;
+}
+/**
+ * NPLJS — 高级 NPL 通信类，提供消息 ID 回调、加载握手、消息订阅/发布。
+ *
+ * 通常以单例形式使用：
+ * ```ts
+ * window.NPLJSInstance = new NPLJS();
+ * window.NPLJSInstance.OnLoad(() => { console.log('ready'); });
+ * ```
+ */
+declare class NPLJS {
+    private m_msg_callbacks;
+    private m_ready;
+    private m_msgid;
+    private m_msgid_callbacks;
+    private m_loaded;
+    private m_onload_callback;
+    private m_onload_timerid;
+    constructor();
+    /** 是否已与 Paracraft WebView 建立连接。 */
+    IsLoaded(): boolean;
+    /**
+     * 触发加载握手流程（向 Paracraft 发送 'load' 消息，等待确认）。
+     * 若已加载则立即返回。
+     */
+    Load(): void;
+    /** @private 处理 Paracraft 返回的 load 确认消息。 */
+    private HandleLoadMsg;
+    /**
+     * 注册加载完成回调（若已加载则立即触发）。
+     * @param callback - 连接建立后的回调
+     */
+    OnLoad(callback: () => void): void;
+    /** @private 生成自增消息 ID（格式：`js_N`）。 */
+    private GetNextMsgId;
+    /** @private 发送原始 NPL 消息到 NPLJS 文件。 */
+    private Send;
+    /**
+     * 发送命名消息（可选回调）。
+     *
+     * @param msgname - 消息名
+     * @param msgdata - 消息数据
+     * @param msgid   - 消息 ID（可选，用于回调关联）
+     * @param callback - 收到响应时触发的回调
+     */
+    SendMsg(msgname: string, msgdata?: unknown, msgid?: string, callback?: (data: unknown) => void): void;
+    /**
+     * 接收并派发来自 Paracraft 的 NPLJS 消息。
+     * @private
+     */
+    RecvMsg(msg: NPLJSMessage): void;
+    /**
+     * 订阅指定消息名（可同时有多个订阅者）。
+     * @param msgname  - 消息名
+     * @param callback - 回调函数
+     */
+    OnMsg(msgname: string, callback: (data: unknown, msgid?: string) => void): void;
+    /**
+     * 取消订阅指定消息名的回调。
+     * @param msgname  - 消息名
+     * @param callback - 要取消的回调
+     */
+    OffMsg(msgname: string, callback: (data: unknown, msgid?: string) => void): void;
+    /** @private 派发消息给所有订阅者。 */
+    private EmitMsg;
+    /**
+     * 检测 WebView 环境并在就绪时调用 Load()。
+     * 仅在 Windows + Edge 环境下执行，最多重试 3 次（每次间隔 1s）。
+     * @private
+     */
+    private CheckLoadWebview;
+    /**
+     * 注册 NPLJS 文件的消息接收回调（构造函数内自动调用）。
+     * @private
+     */
+    private registerNPLJSReceive;
+}
+/**
+ * ParacraftEvent — Keepwork ↔ Paracraft 事件总线。
+ *
+ * 通过消息前缀隔离，防止与其他 postMessage 用途冲突：
+ * - 进入方向（Paracraft → Keepwork）使用前缀 `@keepwork_`
+ * - 发出方向（Keepwork → Paracraft）使用前缀 `@webparacraft_`
+ *
+ * @param npljsInstance - 可选的 NPLJS 实例；不提供时回退到 window.NPLJSInstance
+ */
+declare class ParacraftEvent {
+    private npljsInstance;
+    private asIframeInWebParacraft;
+    private asWebviewInParacraftClient;
+    /** 进入消息前缀（Paracraft → Keepwork） */
+    readonly eventPrefix = "@keepwork_";
+    /** 发出消息前缀（Keepwork → Paracraft） */
+    readonly msgPrefix = "@webparacraft_";
+    private events;
+    constructor(npljsInstance?: NPLJS);
+    /** 获取当前有效的 NPLJS 实例（优先构造时注入，回退 window.NPLJSInstance）。 */
+    getNPLJSInstance(): NPLJS | null;
+    /** 是否需要通过 NPLJS 发送出站消息（处于 iframe 或 WebView 模式）。 */
+    outGoingMsgNeedToBeSent(): boolean;
+    /**
+     * 订阅来自 Paracraft 的事件消息。
+     *
+     * @param name     - 事件名（不含前缀）
+     * @param callback - 事件处理回调
+     */
+    onMsg(name: string, callback: (data: unknown) => void): void;
+    /**
+     * 向 Paracraft 发送消息事件。
+     *
+     * @param name - 事件名（不含前缀）
+     * @param data - 消息数据
+     */
+    sendMsg(name: string, data?: unknown): void;
+    /**
+     * window message 事件监听器（在构造函数中绑定）。
+     * 仅处理带 eventPrefix 前缀的消息。
+     */
+    messageListener(event: MessageEvent): void;
+}
+export { NPL, NPLUtil, NPLJS, ParacraftEvent };
+//# sourceMappingURL=NPL.d.ts.map

package/dist-npm/types/src/core/NPL.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NPL.d.ts","sourceRoot":"","sources":["../../../../src/core/NPL.ts"],"names":[],"mappings":"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"}