@f2a/openclaw-f2a 0.2.25 → 0.3.0

package/dist/connector.d.ts

@@ -14,6 +14,13 @@ import type { OpenClawPlugin, OpenClawPluginApi, Tool, F2APluginConfig, AgentInf
  * @returns 是否为有效的 libp2p Peer ID 格式
  */
 export declare function isValidPeerId(peerId: string | undefined | null): peerId is string;
+/** OpenClaw API Logger 类型 */
+export interface ApiLogger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug?(message: string, ...args: unknown[]): void;
+}
 /** 广播结果类型 */
 interface BroadcastResult {
     agent: string;
@@ -37,6 +44,8 @@ export declare class F2AOpenClawAdapter implements OpenClawPlugin {
     private _f2a?;
     private _toolHandlers?;
     private _claimHandlers?;
+    private _contactManager?;
+    private _handshakeProtocol?;
     private _processedMessageHashes;
     /** P1-3: 消息去重缓存最大条目数 */
     private static readonly MAX_MESSAGE_HASH_CACHE_SIZE;
@@ -121,6 +130,15 @@ export declare class F2AOpenClawAdapter implements OpenClawPlugin {
      * 获取认领处理器（延迟初始化）
      */
     private get claimHandlers();
+    /**
+     * Issue #98: 获取联系人管理器（延迟初始化）
+     */
+    private get contactManager();
+    /**
+     * Issue #99: 获取握手协议处理器（延迟初始化）
+     * 依赖 F2A 实例和 ContactManager
+     */
+    private get handshakeProtocol();
     /**
      * 检查是否已初始化（用于判断是否需要启动服务）
      */
@@ -247,6 +265,30 @@ export declare class F2AOpenClawAdapter implements OpenClawPlugin {
      * 解析 Agent 引用（公共方法，供测试和外部调用）
      */
     resolveAgent(agentRef: string): Promise<AgentInfo | null>;
+    /**
+     * 处理通讯录工具
+     */
+    private handleContacts;
+    /**
+     * 处理分组管理工具
+     */
+    private handleContactGroups;
+    /**
+     * 处理好友请求工具
+     */
+    private handleFriendRequest;
+    /**
+     * 处理待处理请求工具
+     */
+    private handlePendingRequests;
+    /**
+     * 处理导出通讯录工具
+     */
+    private handleContactsExport;
+    /**
+     * 处理导入通讯录工具
+     */
+    private handleContactsImport;
     /**
      * 关闭插件，清理资源
      * 只清理已初始化的资源

package/dist/connector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../src/connector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../src/connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,IAAI,EAIJ,eAAe,EACf,SAAS,EAIV,MAAM,YAAY,CAAC;AAuCpB;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,IAAI,MAAM,CAEjF;AAwJD,6BAA6B;AAC7B,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACnD;AAED,aAAa;AACb,UAAU,eAAe;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAmB,YAAW,cAAc;IACvD,IAAI,SAAsB;IAC1B,OAAO,SAAW;IAGlB,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,cAAc,CAAC,CAAmB;IAC1C,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,iBAAiB,CAAC,CAAmB;IAC7C,OAAO,CAAC,OAAO,CAAC,CAAY;IAC5B,OAAO,CAAC,mBAAmB,CAAC,CAAqB;IACjD,OAAO,CAAC,UAAU,CAAC,CAAY;IAC/B,OAAO,CAAC,kBAAkB,CAAC,CAAoB;IAC/C,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,gBAAgB,CAAC,CAAkB;IAG3C,OAAO,CAAC,IAAI,CAAC,CAAM;IAGnB,OAAO,CAAC,aAAa,CAAC,CAAe;IACrC,OAAO,CAAC,cAAc,CAAC,CAAgB;IAGvC,OAAO,CAAC,eAAe,CAAC,CAAiB;IACzC,OAAO,CAAC,kBAAkB,CAAC,CAAoB;IAI/C,OAAO,CAAC,uBAAuB,CAAkC;IACjE,wBAAwB;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,2BAA2B,CAAS;IAC5D,+BAA+B;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAiB;IAE5D,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,GAAG,CAAC,CAAoB;IAChC,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,YAAY,CAAS;IAI7B;;OAEG;IACH,OAAO,KAAK,WAAW,GAKtB;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAyErB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;;OAGG;IACH,OAAO,KAAK,aAAa,GAKxB;IAED;;;OAGG;IACH,OAAO,KAAK,SAAS,GAapB;IAED;;OAEG;IACH,OAAO,KAAK,gBAAgB,GAa3B;IAED;;OAEG;IACH,OAAO,KAAK,kBAAkB,GAK7B;IAED;;OAEG;IACH,OAAO,KAAK,iBAAiB,GAS5B;IAED;;OAEG;IACH,OAAO,KAAK,eAAe,GAW1B;IAED;;OAEG;IACH,OAAO,KAAK,YAAY,GAKvB;IAED;;OAEG;IACH,OAAO,KAAK,aAAa,GAKxB;IAED;;OAEG;IACH,OAAO,KAAK,cAAc,GAOzB;IAED;;;OAGG;IACH,OAAO,KAAK,iBAAiB,GAU5B;IAED;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,YAAY,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAWtE;;;OAGG;IACH,IAAI,SAAS;sCAE2B,MAAM;;;;;;;;;;;;;;;;;;;;;;MAwB7C;IAED;;;;;;;OAOG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6C/F;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAuK7B;;;OAGG;IACH;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAmChC;;;OAGG;YACW,mBAAmB;IA8GjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAgC/B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA6C5B;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;IA2BpC;;OAEG;IACH,QAAQ,IAAI,IAAI,EAAE;IA4elB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA2L5B;;OAEG;YACW,cAAc;IAa5B;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,eAAe;IAiClF,OAAO,CAAC,aAAa;IASrB;;;OAGG;YACW,iBAAiB;IA0B/B;;;OAGG;YACW,iBAAiB;IAiD/B;;OAEG;IACH,sBAAsB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM;IAQ1D;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAgC/D;;OAEG;YACW,cAAc;IAgK5B;;OAEG;YACW,mBAAmB;IAmEjC;;OAEG;YACW,mBAAmB;IAyCjC;;OAEG;YACW,qBAAqB;IA8DnC;;OAEG;YACW,oBAAoB;IAqBlC;;OAEG;YACW,oBAAoB;IA6BlC;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAkEhC;AAGD,eAAe,kBAAkB,CAAC"}

package/dist/connector.js

@@ -26,6 +26,10 @@ const task_guard_js_1 = require("./task-guard.js");
 const tool_handlers_js_1 = require("./tool-handlers.js");
 const claim_handlers_js_1 = require("./claim-handlers.js");
 const network_1 = require("@f2a/network");
+// Issue #98 & #99: 通讯录和握手机制
+const contact_manager_js_1 = require("./contact-manager.js");
+const handshake_protocol_js_1 = require("./handshake-protocol.js");
+const contact_types_js_1 = require("./contact-types.js");
 // ============================================================================
 // 安全常量和验证工具
 // ============================================================================
@@ -201,6 +205,9 @@ class F2AOpenClawAdapter {
     // 处理器实例（延迟初始化）
     _toolHandlers;
     _claimHandlers;
+    // Issue #98 & #99: 通讯录和握手机制
+    _contactManager;
+    _handshakeProtocol;
     // P1-3: 消息哈希去重缓存，防止恶意节点绕过 echo 检测
     // 存储最近处理过的消息哈希，避免重复处理
     _processedMessageHashes = new Map();
@@ -442,6 +449,28 @@ class F2AOpenClawAdapter {
         }
         return this._claimHandlers;
     }
+    /**
+     * Issue #98: 获取联系人管理器（延迟初始化）
+     */
+    get contactManager() {
+        if (!this._contactManager) {
+            const dataDir = this.getDefaultDataDir();
+            this._contactManager = new contact_manager_js_1.ContactManager(dataDir, this._logger);
+            this._logger?.info('[F2A Adapter] ContactManager 已初始化');
+        }
+        return this._contactManager;
+    }
+    /**
+     * Issue #99: 获取握手协议处理器（延迟初始化）
+     * 依赖 F2A 实例和 ContactManager
+     */
+    get handshakeProtocol() {
+        if (!this._handshakeProtocol && this._f2a && this._contactManager) {
+            this._handshakeProtocol = new handshake_protocol_js_1.HandshakeProtocol(this._f2a, this._contactManager, this._logger);
+            this._logger?.info('[F2A Adapter] HandshakeProtocol 已初始化');
+        }
+        return this._handshakeProtocol;
+    }
     /**
      * 检查是否已初始化（用于判断是否需要启动服务）
      */
@@ -1270,6 +1299,157 @@ class F2AOpenClawAdapter {
                     }
                 },
                 handler: this.toolHandlers.handleGetCapabilities.bind(this.toolHandlers)
+            },
+            // ========== Issue #98 & #99: 通讯录和握手机制工具 ==========
+            {
+                name: 'f2a_contacts',
+                description: '管理通讯录联系人。Actions: list（列出联系人）, get（获取详情）, add（添加）, remove（删除）, update（更新）, block（拉黑）, unblock（解除拉黑）',
+                parameters: {
+                    action: {
+                        type: 'string',
+                        description: '操作类型: list, get, add, remove, update, block, unblock',
+                        required: true,
+                        enum: ['list', 'get', 'add', 'remove', 'update', 'block', 'unblock']
+                    },
+                    contact_id: {
+                        type: 'string',
+                        description: '联系人 ID（get/remove/update/block/unblock 时需要）',
+                        required: false
+                    },
+                    peer_id: {
+                        type: 'string',
+                        description: 'Peer ID（add 时需要，get/remove 时可选）',
+                        required: false
+                    },
+                    name: {
+                        type: 'string',
+                        description: '联系人名称（add/update 时需要）',
+                        required: false
+                    },
+                    groups: {
+                        type: 'array',
+                        description: '分组列表',
+                        required: false
+                    },
+                    tags: {
+                        type: 'array',
+                        description: '标签列表',
+                        required: false
+                    },
+                    notes: {
+                        type: 'string',
+                        description: '备注信息',
+                        required: false
+                    },
+                    status: {
+                        type: 'string',
+                        description: '按状态过滤（list 时可选）: stranger, pending, friend, blocked',
+                        required: false,
+                        enum: ['stranger', 'pending', 'friend', 'blocked']
+                    },
+                    group: {
+                        type: 'string',
+                        description: '按分组过滤（list 时可选）',
+                        required: false
+                    }
+                },
+                handler: this.handleContacts.bind(this)
+            },
+            {
+                name: 'f2a_contact_groups',
+                description: '管理联系人分组。Actions: list（列出分组）, create（创建）, update（更新）, delete（删除）',
+                parameters: {
+                    action: {
+                        type: 'string',
+                        description: '操作类型: list, create, update, delete',
+                        required: true,
+                        enum: ['list', 'create', 'update', 'delete']
+                    },
+                    group_id: {
+                        type: 'string',
+                        description: '分组 ID（update/delete 时需要）',
+                        required: false
+                    },
+                    name: {
+                        type: 'string',
+                        description: '分组名称（create/update 时需要）',
+                        required: false
+                    },
+                    description: {
+                        type: 'string',
+                        description: '分组描述',
+                        required: false
+                    },
+                    color: {
+                        type: 'string',
+                        description: '分组颜色（十六进制，如 #FF5733）',
+                        required: false
+                    }
+                },
+                handler: this.handleContactGroups.bind(this)
+            },
+            {
+                name: 'f2a_friend_request',
+                description: '发送好友请求给指定 Agent',
+                parameters: {
+                    peer_id: {
+                        type: 'string',
+                        description: '目标 Agent 的 Peer ID',
+                        required: true
+                    },
+                    message: {
+                        type: 'string',
+                        description: '附加消息',
+                        required: false
+                    }
+                },
+                handler: this.handleFriendRequest.bind(this)
+            },
+            {
+                name: 'f2a_pending_requests',
+                description: '查看和处理待处理的好友请求。Actions: list（列出请求）, accept（接受）, reject（拒绝）',
+                parameters: {
+                    action: {
+                        type: 'string',
+                        description: '操作类型: list, accept, reject',
+                        required: true,
+                        enum: ['list', 'accept', 'reject']
+                    },
+                    request_id: {
+                        type: 'string',
+                        description: '请求 ID（accept/reject 时需要）',
+                        required: false
+                    },
+                    reason: {
+                        type: 'string',
+                        description: '拒绝原因（reject 时可选）',
+                        required: false
+                    }
+                },
+                handler: this.handlePendingRequests.bind(this)
+            },
+            {
+                name: 'f2a_contacts_export',
+                description: '导出通讯录数据',
+                parameters: {},
+                handler: this.handleContactsExport.bind(this)
+            },
+            {
+                name: 'f2a_contacts_import',
+                description: '导入通讯录数据',
+                parameters: {
+                    data: {
+                        type: 'object',
+                        description: '导入的通讯录数据（JSON 格式）',
+                        required: true
+                    },
+                    merge: {
+                        type: 'boolean',
+                        description: '是否合并（true）或覆盖（false），默认 true',
+                        required: false
+                    }
+                },
+                handler: this.handleContactsImport.bind(this)
             }
         ];
     }
@@ -1605,6 +1785,313 @@ class F2AOpenClawAdapter {
             (a.displayName?.toLowerCase().includes(agentRef.toLowerCase()) ?? false));
         return fuzzy || null;
     }
+    // ============================================================================
+    // Issue #98 & #99: 通讯录和握手机制工具处理方法
+    // ============================================================================
+    /**
+     * 处理通讯录工具
+     */
+    async handleContacts(params, _context) {
+        try {
+            const cm = this.contactManager;
+            switch (params.action) {
+                case 'list': {
+                    const filter = {};
+                    if (params.status) {
+                        filter.status = params.status;
+                    }
+                    if (params.group) {
+                        filter.group = params.group;
+                    }
+                    const contacts = cm.getContacts(filter, { field: 'name', order: 'asc' });
+                    const stats = cm.getStats();
+                    return {
+                        content: `📋 **通讯录** (${stats.total} 个联系人)\n\n` +
+                            contacts.map(c => {
+                                const statusIcon = {
+                                    [contact_types_js_1.FriendStatus.FRIEND]: '💚',
+                                    [contact_types_js_1.FriendStatus.STRANGER]: '⚪',
+                                    [contact_types_js_1.FriendStatus.PENDING]: '🟡',
+                                    [contact_types_js_1.FriendStatus.BLOCKED]: '🔴',
+                                }[c.status];
+                                return `${statusIcon} **${c.name}**\n   Peer: ${c.peerId.slice(0, 16)}...\n   信誉: ${c.reputation} | 状态: ${c.status}`;
+                            }).join('\n\n') || '暂无联系人'
+                    };
+                }
+                case 'get': {
+                    let contact;
+                    if (params.contact_id) {
+                        contact = cm.getContact(params.contact_id);
+                    }
+                    else if (params.peer_id) {
+                        contact = cm.getContactByPeerId(params.peer_id);
+                    }
+                    else {
+                        return { content: '❌ 需要提供 contact_id 或 peer_id' };
+                    }
+                    if (!contact) {
+                        return { content: '❌ 联系人不存在' };
+                    }
+                    return {
+                        content: `👤 **${contact.name}**\n` +
+                            `   ID: ${contact.id}\n` +
+                            `   Peer ID: ${contact.peerId}\n` +
+                            `   状态: ${contact.status}\n` +
+                            `   信誉: ${contact.reputation}\n` +
+                            `   分组: ${contact.groups.join(', ') || '无'}\n` +
+                            `   标签: ${contact.tags.join(', ') || '无'}\n` +
+                            `   最后通信: ${contact.lastCommunicationTime ? new Date(contact.lastCommunicationTime).toLocaleString() : '从未'}\n` +
+                            (contact.notes ? `   备注: ${contact.notes}` : '')
+                    };
+                }
+                case 'add': {
+                    if (!params.peer_id || !params.name) {
+                        return { content: '❌ 需要提供 peer_id 和 name' };
+                    }
+                    const contact = cm.addContact({
+                        name: params.name,
+                        peerId: params.peer_id,
+                        groups: params.groups,
+                        tags: params.tags,
+                        notes: params.notes,
+                    });
+                    return { content: `✅ 已添加联系人: ${contact.name} (${contact.peerId.slice(0, 16)})` };
+                }
+                case 'remove': {
+                    let contactId = params.contact_id;
+                    if (!contactId && params.peer_id) {
+                        const contact = cm.getContactByPeerId(params.peer_id);
+                        contactId = contact?.id;
+                    }
+                    if (!contactId) {
+                        return { content: '❌ 需要提供 contact_id 或 peer_id' };
+                    }
+                    const success = cm.removeContact(contactId);
+                    return { content: success ? '✅ 已删除联系人' : '❌ 联系人不存在' };
+                }
+                case 'update': {
+                    let contactId = params.contact_id;
+                    if (!contactId && params.peer_id) {
+                        const contact = cm.getContactByPeerId(params.peer_id);
+                        contactId = contact?.id;
+                    }
+                    if (!contactId) {
+                        return { content: '❌ 需要提供 contact_id 或 peer_id' };
+                    }
+                    const contact = cm.updateContact(contactId, {
+                        name: params.name,
+                        groups: params.groups,
+                        tags: params.tags,
+                        notes: params.notes,
+                    });
+                    return { content: contact ? `✅ 已更新联系人: ${contact.name}` : '❌ 联系人不存在' };
+                }
+                case 'block': {
+                    let contactId = params.contact_id;
+                    if (!contactId && params.peer_id) {
+                        const contact = cm.getContactByPeerId(params.peer_id);
+                        contactId = contact?.id;
+                    }
+                    if (!contactId) {
+                        return { content: '❌ 需要提供 contact_id 或 peer_id' };
+                    }
+                    const success = cm.blockContact(contactId);
+                    return { content: success ? '✅ 已拉黑联系人' : '❌ 联系人不存在' };
+                }
+                case 'unblock': {
+                    let contactId = params.contact_id;
+                    if (!contactId && params.peer_id) {
+                        const contact = cm.getContactByPeerId(params.peer_id);
+                        contactId = contact?.id;
+                    }
+                    if (!contactId) {
+                        return { content: '❌ 需要提供 contact_id 或 peer_id' };
+                    }
+                    const success = cm.unblockContact(contactId);
+                    return { content: success ? '✅ 已解除拉黑' : '❌ 联系人不存在' };
+                }
+                default:
+                    return { content: '❌ 未知操作' };
+            }
+        }
+        catch (err) {
+            return { content: `❌ 操作失败: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    /**
+     * 处理分组管理工具
+     */
+    async handleContactGroups(params, _context) {
+        try {
+            const cm = this.contactManager;
+            switch (params.action) {
+                case 'list': {
+                    const groups = cm.getGroups();
+                    return {
+                        content: `📁 **分组列表** (${groups.length} 个)\n\n` +
+                            groups.map(g => `• **${g.name}** (${g.id})\n   ${g.description || '无描述'}`).join('\n\n')
+                    };
+                }
+                case 'create': {
+                    if (!params.name) {
+                        return { content: '❌ 需要提供分组名称' };
+                    }
+                    const group = cm.createGroup({
+                        name: params.name,
+                        description: params.description,
+                        color: params.color,
+                    });
+                    return { content: `✅ 已创建分组: ${group.name}` };
+                }
+                case 'update': {
+                    if (!params.group_id) {
+                        return { content: '❌ 需要提供 group_id' };
+                    }
+                    const group = cm.updateGroup(params.group_id, {
+                        name: params.name,
+                        description: params.description,
+                        color: params.color,
+                    });
+                    return { content: group ? `✅ 已更新分组: ${group.name}` : '❌ 分组不存在' };
+                }
+                case 'delete': {
+                    if (!params.group_id) {
+                        return { content: '❌ 需要提供 group_id' };
+                    }
+                    const success = cm.deleteGroup(params.group_id);
+                    return { content: success ? '✅ 已删除分组' : '❌ 无法删除（分组不存在或为默认分组）' };
+                }
+                default:
+                    return { content: '❌ 未知操作' };
+            }
+        }
+        catch (err) {
+            return { content: `❌ 操作失败: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    /**
+     * 处理好友请求工具
+     */
+    async handleFriendRequest(params, _context) {
+        try {
+            if (!this._f2a) {
+                return { content: '❌ F2A 实例未初始化' };
+            }
+            if (!this._contactManager) {
+                // 确保联系人管理器已初始化
+                this.contactManager;
+            }
+            if (!this._handshakeProtocol) {
+                // 初始化握手协议
+                this.handshakeProtocol;
+            }
+            if (!this._handshakeProtocol) {
+                return { content: '❌ 握手协议未初始化' };
+            }
+            const requestId = await this._handshakeProtocol.sendFriendRequest(params.peer_id, params.message);
+            if (requestId) {
+                return { content: `✅ 好友请求已发送\n请求 ID: ${requestId}\n等待对方响应...` };
+            }
+            else {
+                return { content: '❌ 发送好友请求失败' };
+            }
+        }
+        catch (err) {
+            return { content: `❌ 发送失败: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    /**
+     * 处理待处理请求工具
+     */
+    async handlePendingRequests(params, _context) {
+        try {
+            const cm = this.contactManager;
+            switch (params.action) {
+                case 'list': {
+                    const pending = cm.getPendingHandshakes();
+                    if (pending.length === 0) {
+                        return { content: '📭 暂无待处理的好友请求' };
+                    }
+                    return {
+                        content: `📬 **待处理的好友请求** (${pending.length} 个)\n\n` +
+                            pending.map(p => `• **${p.fromName}**\n   Peer: ${p.from.slice(0, 16)}...\n   请求 ID: ${p.requestId}\n   收到: ${new Date(p.receivedAt).toLocaleString()}` +
+                                (p.message ? `\n   消息: ${p.message}` : '')).join('\n\n')
+                    };
+                }
+                case 'accept': {
+                    if (!params.request_id) {
+                        return { content: '❌ 需要提供 request_id' };
+                    }
+                    if (!this._handshakeProtocol) {
+                        return { content: '❌ 握手协议未初始化' };
+                    }
+                    const success = await this._handshakeProtocol.acceptRequest(params.request_id);
+                    return { content: success ? '✅ 已接受好友请求，双方已成为好友' : '❌ 接受失败' };
+                }
+                case 'reject': {
+                    if (!params.request_id) {
+                        return { content: '❌ 需要提供 request_id' };
+                    }
+                    if (!this._handshakeProtocol) {
+                        return { content: '❌ 握手协议未初始化' };
+                    }
+                    const success = await this._handshakeProtocol.rejectRequest(params.request_id, params.reason);
+                    return { content: success ? '✅ 已拒绝好友请求' : '❌ 拒绝失败' };
+                }
+                default:
+                    return { content: '❌ 未知操作' };
+            }
+        }
+        catch (err) {
+            return { content: `❌ 操作失败: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    /**
+     * 处理导出通讯录工具
+     */
+    async handleContactsExport(_params, _context) {
+        try {
+            const cm = this.contactManager;
+            const data = cm.exportContacts(this._f2a?.peerId);
+            return {
+                content: `📤 **通讯录导出成功**\n\n` +
+                    `联系人: ${data.contacts.length} 个\n` +
+                    `分组: ${data.groups.length} 个\n` +
+                    `导出时间: ${new Date(data.exportedAt).toLocaleString()}\n\n` +
+                    '```json\n' + JSON.stringify(data, null, 2) + '\n```',
+                data,
+            };
+        }
+        catch (err) {
+            return { content: `❌ 导出失败: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    /**
+     * 处理导入通讯录工具
+     */
+    async handleContactsImport(params, _context) {
+        try {
+            const cm = this.contactManager;
+            const result = cm.importContacts(params.data, params.merge ?? true);
+            if (result.success) {
+                return {
+                    content: `📥 **通讯录导入完成**\n\n` +
+                        `✅ 导入联系人: ${result.importedContacts} 个\n` +
+                        `✅ 导入分组: ${result.importedGroups} 个\n` +
+                        `⏭️ 跳过联系人: ${result.skippedContacts} 个` +
+                        (result.errors.length ? `\n\n⚠️ 错误:\n${result.errors.join('\n')}` : '')
+                };
+            }
+            else {
+                return {
+                    content: `❌ 导入失败\n\n错误:\n${result.errors.join('\n')}`
+                };
+            }
+        }
+        catch (err) {
+            return { content: `❌ 导入失败: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
     /**
      * 关闭插件，清理资源
      * 只清理已初始化的资源
@@ -1616,6 +2103,18 @@ class F2AOpenClawAdapter {
             clearInterval(this.pollTimer);
             this.pollTimer = undefined;
         }
+        // Issue #99: 关闭握手协议
+        if (this._handshakeProtocol) {
+            this._handshakeProtocol.shutdown();
+            this._logger?.info('[F2A Adapter] HandshakeProtocol 已关闭');
+            this._handshakeProtocol = undefined;
+        }
+        // Issue #98: 刷新通讯录数据
+        if (this._contactManager) {
+            this._contactManager.flush();
+            this._logger?.info('[F2A Adapter] ContactManager 数据已保存');
+            this._contactManager = undefined;
+        }
         // 停止 F2A 实例（新架构直接管理）
         if (this._f2a) {
             try {