acp-ts 1.1.3 → 1.1.5

package/dist/agentcp.d.ts

@@ -1,19 +1,28 @@
 import { IAgentCP, IAgentIdentity } from "./interfaces";
 import { MessageStore } from "./messagestore";
 import { AgentMdOptions } from "./agentmd";
+import { ACPGroupClient, GroupOperations, ACPGroupEventHandler, CursorStore, GroupMessageStore, GroupMessage } from "./group";
 declare class AgentCP implements IAgentCP {
     private seedPassword;
     private apUrl;
     private msgUrl;
     private activeAid;
+    private _basePath;
     private _messageStore;
     private agentMdPath;
     private agentMdUploaded;
     private autoGenerateAgentMd;
     private agentMdOptions;
+    groupClient: ACPGroupClient | null;
+    groupOps: GroupOperations | null;
+    groupMessageStore: GroupMessageStore | null;
+    private _groupTargetAid;
+    private _groupSessionId;
+    private _persistGroupMessages;
     get messageStore(): MessageStore;
     constructor(apiUrl: string, seedPassword?: string, basePath?: string, options?: {
         persistMessages?: boolean;
+        persistGroupMessages?: boolean;
     });
     /**
      * 初始化并预热加密模块
@@ -43,6 +52,110 @@ declare class AgentCP implements IAgentCP {
     private getAgentMdMarkerPath;
     private checkAgentMdMarker;
     private saveAgentMdMarker;
+    /**
+     * 获取群组目标AID
+     */
+    getGroupTargetAid(): string;
+    /**
+     * 初始化群组客户端。
+     * 需要外部提供 sendRaw 函数和 sessionId，因为 AgentCP 本身不管理 WebSocket 连接。
+     *
+     * @param sendRaw 发送原始消息的函数: (message, to, sessionId) => void
+     * @param sessionId 与 group.{issuer} 的会话ID
+     * @param targetAid 目标群组AID，默认 "group.{issuer}"
+     */
+    initGroupClient(sendRaw: (message: string, to: string, sessionId: string) => void, sessionId: string, targetAid?: string): void;
+    /**
+     * 初始化跨AP群组客户端。
+     *
+     * @param sendRaw 发送原始消息的函数
+     * @param sessionId 与目标群组AID的会话ID
+     * @param targetAid 目标群组AID (如 "group.aid.com")
+     */
+    initGroupClientCrossAp(sendRaw: (message: string, to: string, sessionId: string) => void, sessionId: string, targetAid: string): void;
+    /**
+     * 处理群组协议消息路由。
+     * 当收到 session_message 时，检查 sender 是否为群组目标AID，
+     * 如果是则路由到 groupClient.handleIncoming()。
+     *
+     * @returns true 如果消息被群组客户端处理
+     */
+    handleGroupMessage(message: any): boolean;
+    /**
+     * 设置群组事件处理器
+     */
+    setGroupEventHandler(handler: ACPGroupEventHandler): void;
+    /**
+     * 设置群组游标存储
+     */
+    setGroupCursorStore(store: CursorStore): void;
+    /**
+     * 关闭群组客户端
+     */
+    closeGroupClient(): void;
+    /**
+     * 初始化群消息持久化存储
+     */
+    initGroupMessageStore(options?: {
+        maxMessagesPerGroup?: number;
+        maxEventsPerGroup?: number;
+    }): Promise<void>;
+    /**
+     * 确保群消息持久化存储已初始化并加载完成。
+     * 如果已初始化则直接返回，否则初始化并等待磁盘数据加载完成。
+     */
+    ensureGroupMessageStore(): Promise<void>;
+    /**
+     * 从服务端拉取群组列表并同步到本地存储。
+     * 返回群组列表（含 group_id, name, member_count 等）。
+     */
+    syncGroupList(): Promise<Array<{
+        group_id: string;
+        name: string;
+        member_count?: number;
+    }>>;
+    /**
+     * 获取本地存储的群组列表。
+     * 如果持久化存储已初始化，从存储中读取；否则返回空数组。
+     */
+    getLocalGroupList(): Array<{
+        group_id: string;
+        name: string;
+        member_count?: number;
+    }>;
+    /**
+     * 添加群组到本地存储
+     */
+    addGroupToStore(groupId: string, name: string): void;
+    /**
+     * 从本地存储删除群组
+     */
+    removeGroupFromStore(groupId: string): Promise<void>;
+    /**
+     * 获取本地存储的群消息
+     */
+    getLocalGroupMessages(groupId: string, limit?: number): GroupMessage[];
+    /**
+     * 添加群消息到本地存储
+     */
+    addGroupMessageToStore(groupId: string, msg: GroupMessage): void;
+    /**
+     * 批量添加群消息到本地存储
+     */
+    addGroupMessagesToStore(groupId: string, msgs: GroupMessage[]): void;
+    /**
+     * 获取本地存储中群组的最新消息ID（用于增量拉取）
+     */
+    getGroupLastMsgId(groupId: string): number;
+    /**
+     * 从服务端拉取新消息并同步到本地存储。
+     * 返回所有本地缓存的消息（包括新拉取的）。
+     */
+    pullAndStoreGroupMessages(groupId: string, limit?: number): Promise<GroupMessage[]>;
+    /**
+     * 关闭群消息存储，刷新所有未写入的数据
+     */
+    closeGroupMessageStore(): Promise<void>;
     private handleError;
 }
 export { AgentCP };

package/dist/agentcp.js

@@ -43,17 +43,25 @@ const utils_1 = require("./utils");
 const messagestore_1 = require("./messagestore");
 const filesync_1 = require("./filesync");
 const agentmd_1 = require("./agentmd");
+const group_1 = require("./group");
 class AgentCP {
     get messageStore() {
         return this._messageStore;
     }
     constructor(apiUrl, seedPassword = "", basePath, options) {
-        var _a;
+        var _a, _b;
         this.activeAid = '';
         this.agentMdPath = null;
         this.agentMdUploaded = false;
         this.autoGenerateAgentMd = false;
         this.agentMdOptions = {};
+        // Group client properties
+        this.groupClient = null;
+        this.groupOps = null;
+        this.groupMessageStore = null;
+        this._groupTargetAid = '';
+        this._groupSessionId = '';
+        this._persistGroupMessages = false;
         if (!apiUrl) {
             this.handleError("参数缺失：apiUrl不应为空");
         }
@@ -65,11 +73,13 @@ class AgentCP {
         }
         const baseUrl = `https://acp3.${apiUrl}`;
         this.seedPassword = seedPassword;
+        this._basePath = basePath || process.cwd();
         this.apUrl = `${baseUrl}/api/accesspoint`;
         this.msgUrl = `${baseUrl}/api/message`;
+        this._persistGroupMessages = (_a = options === null || options === void 0 ? void 0 : options.persistGroupMessages) !== null && _a !== void 0 ? _a : false;
         this._messageStore = new messagestore_1.MessageStore({
-            persistMessages: (_a = options === null || options === void 0 ? void 0 : options.persistMessages) !== null && _a !== void 0 ? _a : false,
-            basePath: basePath || process.cwd(),
+            persistMessages: (_b = options === null || options === void 0 ? void 0 : options.persistMessages) !== null && _b !== void 0 ? _b : false,
+            basePath: this._basePath,
         });
         // 预热加密模块
         this.initializeCrypto();
@@ -293,6 +303,285 @@ class AgentCP {
             console.warn('保存 agent.md 标记文件失败:', err);
         }
     }
+    // ============================================================
+    // Group Client Integration
+    // ============================================================
+    /**
+     * 获取群组目标AID
+     */
+    getGroupTargetAid() {
+        return this._groupTargetAid;
+    }
+    /**
+     * 初始化群组客户端。
+     * 需要外部提供 sendRaw 函数和 sessionId，因为 AgentCP 本身不管理 WebSocket 连接。
+     *
+     * @param sendRaw 发送原始消息的函数: (message, to, sessionId) => void
+     * @param sessionId 与 group.{issuer} 的会话ID
+     * @param targetAid 目标群组AID，默认 "group.{issuer}"
+     */
+    initGroupClient(sendRaw, sessionId, targetAid) {
+        if (!targetAid) {
+            const parts = this.activeAid.split(".", 1);
+            const issuer = this.activeAid.substring(parts[0].length + 1) || this.activeAid;
+            targetAid = `group.${issuer}`;
+        }
+        this._groupTargetAid = targetAid;
+        this._groupSessionId = sessionId;
+        const sendFunc = (target, payload) => {
+            sendRaw(payload, target, this._groupSessionId);
+        };
+        this.groupClient = new group_1.ACPGroupClient(this.activeAid, sendFunc);
+        this.groupOps = new group_1.GroupOperations(this.groupClient);
+    }
+    /**
+     * 初始化跨AP群组客户端。
+     *
+     * @param sendRaw 发送原始消息的函数
+     * @param sessionId 与目标群组AID的会话ID
+     * @param targetAid 目标群组AID (如 "group.aid.com")
+     */
+    initGroupClientCrossAp(sendRaw, sessionId, targetAid) {
+        this._groupTargetAid = targetAid;
+        this._groupSessionId = sessionId;
+        const sendFunc = (target, payload) => {
+            sendRaw(payload, target, this._groupSessionId);
+        };
+        this.groupClient = new group_1.ACPGroupClient(this.activeAid, sendFunc);
+        this.groupOps = new group_1.GroupOperations(this.groupClient);
+    }
+    /**
+     * 处理群组协议消息路由。
+     * 当收到 session_message 时，检查 sender 是否为群组目标AID，
+     * 如果是则路由到 groupClient.handleIncoming()。
+     *
+     * @returns true 如果消息被群组客户端处理
+     */
+    handleGroupMessage(message) {
+        var _a, _b;
+        if (this.groupClient == null || !this._groupTargetAid) {
+            console.log(`[Group] handleGroupMessage skipped: groupClient=${this.groupClient != null}, targetAid=${this._groupTargetAid}`);
+            return false;
+        }
+        const data = message.data || message;
+        const sender = (_a = data.sender) !== null && _a !== void 0 ? _a : "";
+        // console.log(`[Group] handleGroupMessage: sender="${sender}" targetAid="${this._groupTargetAid}" match=${sender === this._groupTargetAid}`);
+        if (sender === this._groupTargetAid) {
+            try {
+                const rawMsg = (_b = data.message) !== null && _b !== void 0 ? _b : "";
+                // console.log(`[Group] rawMsg type=${typeof rawMsg}, length=${typeof rawMsg === 'string' ? rawMsg.length : 'N/A'}, first 300 chars: ${typeof rawMsg === 'string' ? rawMsg.substring(0, 300) : JSON.stringify(rawMsg).substring(0, 300)}`);
+                if (typeof rawMsg === 'string' && rawMsg) {
+                    this.groupClient.handleIncoming(rawMsg);
+                }
+                else {
+                    console.warn(`[Group] rawMsg is not a non-empty string, skipping handleIncoming`);
+                }
+                return true;
+            }
+            catch (e) {
+                console.error("[Group] handleIncoming error:", e);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * 设置群组事件处理器
+     */
+    setGroupEventHandler(handler) {
+        if (this.groupClient) {
+            this.groupClient.setEventHandler(handler);
+        }
+    }
+    /**
+     * 设置群组游标存储
+     */
+    setGroupCursorStore(store) {
+        if (this.groupClient) {
+            this.groupClient.setCursorStore(store);
+        }
+    }
+    /**
+     * 关闭群组客户端
+     */
+    closeGroupClient() {
+        if (this.groupClient) {
+            try {
+                this.groupClient.close();
+            }
+            catch (e) {
+                console.error("[Group] group_client close error:", e);
+            }
+            this.groupClient = null;
+            this.groupOps = null;
+        }
+    }
+    /**
+     * 初始化群消息持久化存储
+     */
+    async initGroupMessageStore(options) {
+        this.groupMessageStore = new group_1.GroupMessageStore({
+            persistMessages: this._persistGroupMessages,
+            basePath: this._basePath,
+            maxMessagesPerGroup: options === null || options === void 0 ? void 0 : options.maxMessagesPerGroup,
+            maxEventsPerGroup: options === null || options === void 0 ? void 0 : options.maxEventsPerGroup,
+        });
+        if (this.activeAid) {
+            try {
+                await this.groupMessageStore.loadGroupsForAid(this.activeAid);
+            }
+            catch (e) {
+                console.warn('[AgentCP] 加载群消息存储失败:', e);
+            }
+        }
+    }
+    /**
+     * 确保群消息持久化存储已初始化并加载完成。
+     * 如果已初始化则直接返回，否则初始化并等待磁盘数据加载完成。
+     */
+    async ensureGroupMessageStore() {
+        if (this.groupMessageStore)
+            return;
+        if (this._persistGroupMessages) {
+            await this.initGroupMessageStore();
+        }
+    }
+    // ============================================================
+    // Group Storage Management (CRUD API)
+    // ============================================================
+    /**
+     * 从服务端拉取群组列表并同步到本地存储。
+     * 返回群组列表（含 group_id, name, member_count 等）。
+     */
+    async syncGroupList() {
+        if (!this.groupOps || !this._groupTargetAid) {
+            throw new Error('群组客户端未初始化，请先调用 initGroupClient');
+        }
+        const result = await this.groupOps.listMyGroups(this._groupTargetAid);
+        const groups = [];
+        for (const membership of result.groups) {
+            // 尝试获取群组详细信息
+            let name = membership.group_id;
+            let memberCount;
+            try {
+                const info = await this.groupOps.getGroupInfo(this._groupTargetAid, membership.group_id);
+                name = info.name || membership.group_id;
+                memberCount = info.member_count;
+            }
+            catch (_) { }
+            groups.push({ group_id: membership.group_id, name, member_count: memberCount });
+            // 同步到本地存储
+            if (this.groupMessageStore) {
+                this.groupMessageStore.getOrCreateGroup(membership.group_id, this._groupTargetAid, name);
+            }
+        }
+        return groups;
+    }
+    /**
+     * 获取本地存储的群组列表。
+     * 如果持久化存储已初始化，从存储中读取；否则返回空数组。
+     */
+    getLocalGroupList() {
+        if (!this.groupMessageStore)
+            return [];
+        return this.groupMessageStore.getGroupList().map(r => ({
+            group_id: r.groupId,
+            name: r.groupName,
+        }));
+    }
+    /**
+     * 添加群组到本地存储
+     */
+    addGroupToStore(groupId, name) {
+        if (!this.groupMessageStore)
+            return;
+        this.groupMessageStore.getOrCreateGroup(groupId, this._groupTargetAid, name);
+    }
+    /**
+     * 从本地存储删除群组
+     */
+    async removeGroupFromStore(groupId) {
+        if (!this.groupMessageStore)
+            return;
+        await this.groupMessageStore.deleteGroup(groupId);
+    }
+    /**
+     * 获取本地存储的群消息
+     */
+    getLocalGroupMessages(groupId, limit) {
+        if (!this.groupMessageStore)
+            return [];
+        if (limit) {
+            return this.groupMessageStore.getLatestMessages(groupId, limit);
+        }
+        return this.groupMessageStore.getMessages(groupId);
+    }
+    /**
+     * 添加群消息到本地存储
+     */
+    addGroupMessageToStore(groupId, msg) {
+        if (!this.groupMessageStore)
+            return;
+        this.groupMessageStore.addMessage(groupId, msg);
+    }
+    /**
+     * 批量添加群消息到本地存储
+     */
+    addGroupMessagesToStore(groupId, msgs) {
+        if (!this.groupMessageStore)
+            return;
+        this.groupMessageStore.addMessages(groupId, msgs);
+    }
+    /**
+     * 获取本地存储中群组的最新消息ID（用于增量拉取）
+     */
+    getGroupLastMsgId(groupId) {
+        var _a;
+        if (!this.groupMessageStore)
+            return 0;
+        const record = this.groupMessageStore.getGroup(groupId);
+        return (_a = record === null || record === void 0 ? void 0 : record.lastMsgId) !== null && _a !== void 0 ? _a : 0;
+    }
+    /**
+     * 从服务端拉取新消息并同步到本地存储。
+     * 返回所有本地缓存的消息（包括新拉取的）。
+     */
+    async pullAndStoreGroupMessages(groupId, limit = 50) {
+        if (!this.groupOps || !this._groupTargetAid) {
+            throw new Error('群组客户端未初始化');
+        }
+        const lastMsgId = this.getGroupLastMsgId(groupId);
+        try {
+            const pulled = await this.groupOps.pullMessages(this._groupTargetAid, groupId, lastMsgId, limit);
+            if (pulled.messages && pulled.messages.length > 0) {
+                const msgs = pulled.messages.map(m => {
+                    var _a, _b, _c, _d, _e, _f;
+                    return ({
+                        msg_id: (_a = m.msg_id) !== null && _a !== void 0 ? _a : 0,
+                        sender: (_b = m.sender) !== null && _b !== void 0 ? _b : '',
+                        content: (_c = m.content) !== null && _c !== void 0 ? _c : '',
+                        content_type: (_d = m.content_type) !== null && _d !== void 0 ? _d : 'text',
+                        timestamp: (_e = m.timestamp) !== null && _e !== void 0 ? _e : 0,
+                        metadata: (_f = m.metadata) !== null && _f !== void 0 ? _f : null,
+                    });
+                });
+                this.addGroupMessagesToStore(groupId, msgs);
+            }
+        }
+        catch (e) {
+            console.warn('[AgentCP] pullMessages error:', e.message);
+        }
+        return this.getLocalGroupMessages(groupId);
+    }
+    /**
+     * 关闭群消息存储，刷新所有未写入的数据
+     */
+    async closeGroupMessageStore() {
+        if (this.groupMessageStore) {
+            await this.groupMessageStore.close();
+            this.groupMessageStore = null;
+        }
+    }
     handleError(error, customMessage) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         throw new Error(`${customMessage || '操作失败'}: ${errorMessage}`);

package/dist/agentws.d.ts

@@ -57,6 +57,19 @@ declare class AgentWS implements IAgentWS {
      * @param identifyingCode 邀请码
      */
     send(msg: string, to: string, sessionId: string, identifyingCode: string): void;
+    /**
+     * 发送原始消息（不做 URL 编码），用于群组协议等需要原始 JSON 的场景
+     * @param message 原始消息字符串
+     * @param to 接收者智能体ID
+     * @param sessionId 会话ID
+     * @returns true 发送成功，false 连接未建立
+     */
+    sendRaw(message: string, to: string, sessionId: string): boolean;
+    /**
+     * 设置原始消息拦截器。回调函数返回 true 表示已处理（拦截），不再继续分发。
+     * 用于群组协议消息路由。
+     */
+    onRawMessage(cb: (message: any) => boolean): void;
     /**
      * 设置WebSocket连接状态变更的监听函数
      * @param cb 状态变更回调函数
@@ -71,6 +84,10 @@ declare class AgentWS implements IAgentWS {
      * 断开WebSocket连接
      */
     disconnect(): void;
+    /**
+     * 重连 WebSocket（心跳重连成功后调用）
+     */
+    reconnect(): Promise<void>;
     /**
      * 接受来自心跳通道的邀请
      * 当心跳客户端收到邀请时，调用此方法通过 WebSocket 加入会话

package/dist/agentws.js

@@ -103,6 +103,23 @@ class AgentWS {
     send(msg, to, sessionId, identifyingCode) {
         this.msgClient.send(msg, to, sessionId, identifyingCode);
     }
+    /**
+     * 发送原始消息（不做 URL 编码），用于群组协议等需要原始 JSON 的场景
+     * @param message 原始消息字符串
+     * @param to 接收者智能体ID
+     * @param sessionId 会话ID
+     * @returns true 发送成功，false 连接未建立
+     */
+    sendRaw(message, to, sessionId) {
+        return this.msgClient.sendRaw(message, to, sessionId);
+    }
+    /**
+     * 设置原始消息拦截器。回调函数返回 true 表示已处理（拦截），不再继续分发。
+     * 用于群组协议消息路由。
+     */
+    onRawMessage(cb) {
+        this.msgClient.onRawMessage(cb);
+    }
     /**
      * 设置WebSocket连接状态变更的监听函数
      * @param cb 状态变更回调函数
@@ -127,6 +144,12 @@ class AgentWS {
     disconnect() {
         this.msgClient.disconnect();
     }
+    /**
+     * 重连 WebSocket（心跳重连成功后调用）
+     */
+    async reconnect() {
+        await this.msgClient.reconnect();
+    }
     /**
      * 接受来自心跳通道的邀请
      * 当心跳客户端收到邀请时，调用此方法通过 WebSocket 加入会话

package/dist/datamanager.js

@@ -163,7 +163,14 @@ class CertAndKeyStore {
                 return [];
             }
             const entries = fs.readdirSync(aidsDir, { withFileTypes: true });
-            return entries.filter(e => e.isDirectory()).map(e => e.name);
+            return entries.filter(e => {
+                if (!e.isDirectory())
+                    return false;
+                const aidName = e.name;
+                const keyPath = path.join(aidsDir, aidName, 'private', `${aidName}.key`);
+                const crtPath = path.join(aidsDir, aidName, 'public', `${aidName}.crt`);
+                return fs.existsSync(keyPath) && fs.existsSync(crtPath);
+            }).map(e => e.name);
         }
         catch (e) {
             console.error('扫描 AIDs 目录失败:', e);

package/dist/group/client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ACP Group Client - core request/response transport.
+ * Mirrors Python SDK: agentcp/group/client.py
+ *
+ * Key difference: Python uses queue.Queue blocking; TypeScript uses Promise + Deferred pattern.
+ * JS single-threaded: no locks needed.
+ */
+import { GroupResponse } from './types';
+import { ACPGroupEventHandler } from './events';
+import { CursorStore } from './cursor_store';
+/** Type alias: send_func(targetAid, payload) -> void */
+export type SendFunc = (targetAid: string, payload: string) => void;
+export declare class ACPGroupClient {
+    private _agentId;
+    private _sendFunc;
+    private _pendingReqs;
+    private _handler;
+    private _cursorStore;
+    private _reqTimeout;
+    private _seqId;
+    constructor(agentId: string, sendFunc: SendFunc);
+    setEventHandler(handler: ACPGroupEventHandler): void;
+    setCursorStore(store: CursorStore): void;
+    getCursorStore(): CursorStore | null;
+    setTimeout(timeout: number): void;
+    private _nextRequestId;
+    /**
+     * Send a request and wait for response (Promise-based).
+     * Rejects with TimeoutError on timeout, Error on send failure.
+     */
+    sendRequest(targetAid: string, groupId: string, action: string, params?: Record<string, any> | null, timeout?: number): Promise<GroupResponse>;
+    /**
+     * Handle an incoming ACP message (response or notification).
+     * Called by the message dispatch chain in AgentCP.
+     */
+    handleIncoming(payload: string): void;
+    /**
+     * Close client, cancel all pending requests.
+     */
+    close(): void;
+}