@f2a/openclaw-f2a 0.2.24 → 0.3.0

package/dist/connector.js

@@ -10,6 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.F2AOpenClawAdapter = void 0;
+exports.isValidPeerId = isValidPeerId;
 const path_1 = require("path");
 const os_1 = require("os");
 const node_manager_js_1 = require("./node-manager.js");
@@ -25,6 +26,166 @@ 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");
+// ============================================================================
+// 安全常量和验证工具
+// ============================================================================
+/** P1-7: 消息内容最大长度限制 (1MB)，防止内存耗尽 */
+const MAX_MESSAGE_LENGTH = 1024 * 1024;
+/** P1-6: PeerID 格式正则（libp2p 格式：12D3KooW...） */
+const PEER_ID_REGEX = /^12D3KooW[A-Za-z1-9]{44}$/;
+/** P1-4: URL 编码的路径遍历模式 */
+const PATH_TRAVERSAL_PATTERNS = [
+    '%2e%2e', // URL 编码的 ..
+    '%2E%2E', // URL 编码的 .. (大写)
+    '%252e', // 双重 URL 编码
+    '%c0%ae', // UTF-8 overlong encoding
+    '%c1%9c', // UTF-8 overlong encoding
+];
+/**
+ * P1-6: 验证 PeerID 格式
+ * @param peerId - 待验证的 Peer ID
+ * @returns 是否为有效的 libp2p Peer ID 格式
+ */
+function isValidPeerId(peerId) {
+    return typeof peerId === 'string' && PEER_ID_REGEX.test(peerId);
+}
+/**
+ * P0-1, P1-4: 验证路径安全性，防止路径遍历攻击
+ *
+ * 增强版本，处理：
+ * - 符号链接（通过 realpath 验证）
+ * - URL 编码绕过
+ * - 双重编码绕过
+ * - UTF-8 overlong encoding
+ *
+ * @param path - 待验证的路径
+ * @param options - 可选的额外验证选项
+ * @returns 如果路径安全返回 true，否则返回 false
+ */
+function isPathSafe(path, options) {
+    if (typeof path !== 'string' || path.length === 0) {
+        return false;
+    }
+    // 拒绝绝对路径
+    if ((0, path_1.isAbsolute)(path)) {
+        return false;
+    }
+    // 拒绝包含路径遍历字符
+    if (path.includes('..') || path.includes('\0')) {
+        return false;
+    }
+    // 拒绝以 ~ 开头的路径（用户目录展开）
+    if (path.startsWith('~')) {
+        return false;
+    }
+    // P1-4: 检查 URL 编码的路径遍历模式
+    const lowerPath = path.toLowerCase();
+    for (const pattern of PATH_TRAVERSAL_PATTERNS) {
+        if (lowerPath.includes(pattern.toLowerCase())) {
+            return false;
+        }
+    }
+    // P1-4: 解码 URL 编码后再次检查
+    try {
+        const decodedPath = decodeURIComponent(path);
+        // 解码后再次检查路径遍历
+        if (decodedPath.includes('..') || decodedPath.includes('\0')) {
+            return false;
+        }
+        // 检查解码后是否变成绝对路径
+        if ((0, path_1.isAbsolute)(decodedPath)) {
+            return false;
+        }
+    }
+    catch {
+        // 解码失败可能是恶意构造，拒绝
+        return false;
+    }
+    // P1-4: 如果指定了允许的根目录，验证路径不会逃逸
+    if (options?.allowedRoot) {
+        try {
+            const resolvedPath = (0, path_1.join)(options.allowedRoot, path);
+            // 检查解析后的路径是否仍在允许的根目录下
+            if (!resolvedPath.startsWith(options.allowedRoot)) {
+                return false;
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * P1-2: 统一错误提取工具函数
+ * 从各种错误格式中提取错误消息，添加循环引用保护
+ * @param error - 任意错误对象
+ * @returns 错误消息字符串
+ */
+function extractErrorMessage(error) {
+    try {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        if (typeof error === 'string') {
+            return error;
+        }
+        if (typeof error === 'object' && error !== null) {
+            // 尝试常见的错误属性
+            const err = error;
+            if (typeof err.message === 'string') {
+                return err.message;
+            }
+            if (typeof err.error === 'string') {
+                return err.error;
+            }
+            if (typeof err.msg === 'string') {
+                return err.msg;
+            }
+        }
+        // P1-2: 使用 try-catch 保护 String() 调用，防止循环引用异常
+        return String(error);
+    }
+    catch {
+        // 如果 String() 抛出异常（如循环引用），返回安全的默认消息
+        return '[Error: Unable to extract error message - possible circular reference]';
+    }
+}
+/**
+ * Issue #96: 从 IDENTITY.md 读取 agent 名字
+ * @param workspace - agent workspace 目录
+ * @returns agent 名字，如果读取失败返回 null
+ */
+function readAgentNameFromIdentity(workspace) {
+    if (!workspace) {
+        return null;
+    }
+    try {
+        const identityPath = (0, path_1.join)(workspace, 'IDENTITY.md');
+        const fs = require('fs');
+        if (!fs.existsSync(identityPath)) {
+            return null;
+        }
+        const content = fs.readFileSync(identityPath, 'utf-8');
+        // 解析 IDENTITY.md 中的 Name 字段
+        // 格式: - **Name:** 猫咕噜 (Cat Guru)
+        const nameMatch = content.match(/-\s*\*\*Name:\*\*\s*(.+?)(?:\s*\([^)]*\))?$/m);
+        if (nameMatch && nameMatch[1]) {
+            const name = nameMatch[1].trim();
+            // 移除可能的英文别名（括号内的内容已在正则中处理）
+            return name;
+        }
+        return null;
+    }
+    catch (err) {
+        // 读取失败，返回 null
+        return null;
+    }
+}
 class F2AOpenClawAdapter {
     name = 'f2a-openclaw-f2a';
     version = '0.3.0';
@@ -44,6 +205,16 @@ class F2AOpenClawAdapter {
     // 处理器实例（延迟初始化）
     _toolHandlers;
     _claimHandlers;
+    // Issue #98 & #99: 通讯录和握手机制
+    _contactManager;
+    _handshakeProtocol;
+    // P1-3: 消息哈希去重缓存，防止恶意节点绕过 echo 检测
+    // 存储最近处理过的消息哈希，避免重复处理
+    _processedMessageHashes = new Map();
+    /** P1-3: 消息去重缓存最大条目数 */
+    static MAX_MESSAGE_HASH_CACHE_SIZE = 10000;
+    /** P1-3: 消息去重缓存条目最大存活时间（毫秒） */
+    static MESSAGE_HASH_TTL_MS = 5 * 60 * 1000; // 5 分钟
     config;
     nodeConfig;
     capabilities = [];
@@ -62,18 +233,125 @@ class F2AOpenClawAdapter {
     }
     /**
      * 获取默认的 F2A 数据目录
-     * 优先级：workspace/.f2a > ~/.f2a（兼容旧版本）
-     * 注意：config.dataDir 的处理在 mergeConfig() 中，这里只处理未配置的情况
+     *
+     * 优先级：
+     * 1. config.dataDir（用户显式配置）
+     * 2. workspace/.f2a（agent workspace 目录）
+     * 3. ~/.f2a（兼容旧版本）
+     *
+     * 安全：
+     * - P0-1: 验证 workspace 路径，防止路径遍历攻击
+     * - P1-1: 优先检查 config.dataDir
      */
     getDefaultDataDir() {
+        // P1-1: 优先使用用户配置的 dataDir
+        if (this.config?.dataDir) {
+            return this.config.dataDir;
+        }
         // 默认：使用 agent workspace 目录
         const workspace = this.api?.config?.agents?.defaults?.workspace;
-        if (workspace) {
+        // P0-1: 验证 workspace 路径安全性
+        if (isPathSafe(workspace)) {
             return (0, path_1.join)(workspace, '.f2a');
         }
         // 兼容旧版本
         return (0, path_1.join)((0, os_1.homedir)(), '.f2a');
     }
+    /**
+     * P1-2, P1-5, P1-3: 检测是否为回声消息（避免循环）
+     *
+     * 使用多层验证策略：
+     * 1. 检查 metadata 中的特定标记（不仅仅是 type === 'reply'）
+     * 2. 检查消息来源可信度
+     * 3. 检查消息内容的特殊标记
+     * 4. P1-3: 基于消息内容哈希的去重机制（防止恶意绕过）
+     *
+     * @param msg - 接收到的消息
+     * @returns 是否为应该跳过的回声消息
+     */
+    isEchoMessage(msg) {
+        const { metadata, content, from } = msg;
+        // 层1: 检查 metadata 中的标记
+        // P1-5: 不能只依赖 metadata.type，恶意节点可以伪造
+        // 我们检查更具体的标记组合
+        if (metadata) {
+            // 检查是否是我们自己发出的回复标记
+            if (metadata.type === 'reply' && metadata.replyTo) {
+                // 进一步验证：检查是否来自可信源（我们自己发出的消息）
+                // 如果有 replyTo，说明这是一个回复消息
+                return true;
+            }
+            // 检查显式的跳过标记
+            if (metadata._f2a_skip_echo === true || metadata['x-openclaw-skip'] === true) {
+                return true;
+            }
+        }
+        // 层2: 检查消息内容中的特殊标记
+        // P1-2: 使用更严格的匹配，避免误判正常消息
+        if (content) {
+            // 使用特殊的标记格式 [[F2A:REPLY:...]]
+            // 而不是简单的 "NO_REPLY" 字符串
+            if (content.includes('[[F2A:REPLY:') || content.includes('[[reply_to_current]]')) {
+                return true;
+            }
+            // 检查是否以 NO_REPLY 标记开头（更严格）
+            if (content.startsWith('NO_REPLY:') || content.startsWith('[NO_REPLY]')) {
+                return true;
+            }
+        }
+        // 层3: 检查消息来源是否是我们自己的 peerId（防止自循环）
+        if (this._f2a && from === this._f2a.peerId) {
+            return true;
+        }
+        // 层4 (P1-3): 基于消息内容哈希的去重机制
+        // 防止恶意节点构造不含特定标记的消息绕过检测
+        if (content) {
+            const messageHash = this.computeMessageHash(from, content);
+            const now = Date.now();
+            // 检查是否已处理过相同的消息内容
+            if (this._processedMessageHashes.has(messageHash)) {
+                const processedTime = this._processedMessageHashes.get(messageHash);
+                // 如果在 TTL 内，认为是重复消息
+                if (now - processedTime < F2AOpenClawAdapter.MESSAGE_HASH_TTL_MS) {
+                    this._logger?.debug?.(`[F2A Adapter] 检测到重复消息（哈希去重）: ${messageHash.slice(0, 16)}...`);
+                    return true;
+                }
+            }
+            // 记录此消息哈希
+            this._processedMessageHashes.set(messageHash, now);
+            // 清理过期的条目（防止内存泄漏）
+            if (this._processedMessageHashes.size > F2AOpenClawAdapter.MAX_MESSAGE_HASH_CACHE_SIZE) {
+                this.cleanupMessageHashCache(now);
+            }
+        }
+        return false;
+    }
+    /**
+     * P1-3: 计算消息内容哈希
+     * 用于基于内容的去重
+     */
+    computeMessageHash(from, content) {
+        // 使用简单的哈希算法，避免依赖 crypto 模块
+        const data = `${from}:${content}`;
+        let hash = 0;
+        for (let i = 0; i < data.length; i++) {
+            const char = data.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return `msg-${hash.toString(16)}-${data.length}`;
+    }
+    /**
+     * P1-3: 清理过期的消息哈希缓存
+     */
+    cleanupMessageHashCache(now) {
+        const ttl = F2AOpenClawAdapter.MESSAGE_HASH_TTL_MS;
+        for (const [hash, timestamp] of this._processedMessageHashes.entries()) {
+            if (now - timestamp > ttl) {
+                this._processedMessageHashes.delete(hash);
+            }
+        }
+    }
     /**
      * 获取网络客户端（懒加载）
      * 新架构：直接使用 F2A 实例的方法，不再通过 HTTP
@@ -171,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;
+    }
     /**
      * 检查是否已初始化（用于判断是否需要启动服务）
      */
@@ -205,7 +505,7 @@ class F2AOpenClawAdapter {
                     return { success: true, data: agents };
                 }
                 catch (err) {
-                    return { success: false, error: { message: err instanceof Error ? err.message : String(err) } };
+                    return { success: false, error: { message: extractErrorMessage(err) } };
                 }
             },
             getConnectedPeers: async () => {
@@ -218,7 +518,7 @@ class F2AOpenClawAdapter {
                     return { success: true, data: peers };
                 }
                 catch (err) {
-                    return { success: false, error: { message: err instanceof Error ? err.message : String(err) } };
+                    return { success: false, error: { message: extractErrorMessage(err) } };
                 }
             }
         };
@@ -299,8 +599,16 @@ class F2AOpenClawAdapter {
             debugLog(`[F2A Adapter] 使用数据目录: ${dataDir}`);
             debugLog(`[F2A Adapter] workspace: ${this.api?.config?.agents?.defaults?.workspace}`);
             debugLog(`[F2A Adapter] config.dataDir: ${this.config.dataDir}`);
+            // Issue #96: 从 IDENTITY.md 读取 agent 名字
+            const workspace = this.api?.config?.agents?.defaults?.workspace;
+            const identityName = readAgentNameFromIdentity(workspace);
+            // 优先级：IDENTITY.md > config.agentName > 默认值
+            const displayName = identityName || this.config.agentName || 'OpenClaw Agent';
+            if (identityName) {
+                debugLog(`[F2A Adapter] 从 IDENTITY.md 读取 agent 名字: ${identityName}`);
+            }
             this._f2a = await network_1.F2A.create({
-                displayName: this.config.agentName || 'OpenClaw Agent',
+                displayName,
                 dataDir,
                 network: {
                     listenPort: this.config.p2pPort || 0,
@@ -311,7 +619,17 @@ class F2AOpenClawAdapter {
             });
             // 监听 P2P 消息，调用 OpenClaw Agent 生成回复
             this._f2a.on('message', async (msg) => {
-                const logMsg = `[F2A Adapter] 收到 P2P 消息: from=${msg.from?.slice(0, 16)}, content=${msg.content?.slice(0, 50)}`;
+                // P1-6: 验证 PeerID 格式
+                if (!isValidPeerId(msg.from)) {
+                    this._logger?.warn(`[F2A Adapter] 拒绝来自无效 PeerID 的消息: ${String(msg.from).slice(0, 20)}`);
+                    return;
+                }
+                // P1-7: 检查消息长度限制
+                if (msg.content && msg.content.length > MAX_MESSAGE_LENGTH) {
+                    this._logger?.warn(`[F2A Adapter] 消息过长 (${msg.content.length} bytes)，拒绝处理`);
+                    return;
+                }
+                const logMsg = `[F2A Adapter] 收到 P2P 消息: from=${msg.from.slice(0, 16)}, content=${msg.content?.slice(0, 50)}`;
                 this._logger?.info(logMsg);
                 // 写入文件日志
                 try {
@@ -321,10 +639,9 @@ class F2AOpenClawAdapter {
                 }
                 catch { }
                 try {
-                    // 检查是否是 Agent 回复（避免回声循环）
-                    const isReply = msg.metadata?.type === 'reply' ||
-                        msg.content?.includes('[[reply_to_current]]') ||
-                        msg.content?.includes('NO_REPLY');
+                    // P1-2, P1-5: 改进的回声循环检测
+                    // 使用更严格的检测逻辑，防止恶意绕过
+                    const isReply = this.isEchoMessage(msg);
                     if (isReply) {
                         this._logger?.info('[F2A Adapter] 跳过 Agent 回复，避免回声循环');
                         return;
@@ -338,7 +655,7 @@ class F2AOpenClawAdapter {
                     }
                 }
                 catch (err) {
-                    this._logger?.error('[F2A Adapter] 处理消息失败', { error: err instanceof Error ? err.message : String(err) });
+                    this._logger?.error('[F2A Adapter] 处理消息失败', { error: extractErrorMessage(err) });
                 }
             });
             // 监听其他事件
@@ -367,7 +684,7 @@ class F2AOpenClawAdapter {
             });
         }
         catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
+            const errorMsg = extractErrorMessage(err);
             this._logger?.error(`[F2A Adapter] 创建 F2A 实例失败: ${errorMsg}`);
             this._logger?.warn('[F2A Adapter] F2A Adapter 将以降级模式运行，P2P 功能不可用');
             // 清理失败的实例
@@ -386,7 +703,7 @@ class F2AOpenClawAdapter {
             this._logger?.info(`[F2A Adapter] Webhook 服务器已启动: ${this._webhookServer.getUrl()}`);
         }
         catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
+            const errorMsg = extractErrorMessage(err);
             this._logger?.warn(`[F2A Adapter] Webhook 服务器启动失败: ${errorMsg}`);
         }
         // 启动兜底轮询
@@ -418,7 +735,7 @@ class F2AOpenClawAdapter {
                 this._logger?.info('[F2A Adapter] 回复已发送', { to: fromPeerId.slice(0, 16) });
             }
             catch (err) {
-                this._logger?.error('[F2A Adapter] 发送回复失败', { error: err instanceof Error ? err.message : String(err) });
+                this._logger?.error('[F2A Adapter] 发送回复失败', { error: extractErrorMessage(err) });
             }
         };
         // 返回 dispatcher 对象，格式与 OpenClaw 兼容
@@ -481,7 +798,7 @@ class F2AOpenClawAdapter {
                 return undefined; // dispatcher 会自动发送回复
             }
             catch (err) {
-                debugLog(`[F2A Adapter] Channel API 失败: ${err instanceof Error ? err.message : String(err)}`);
+                debugLog(`[F2A Adapter] Channel API 失败: ${extractErrorMessage(err)}`);
             }
         }
         // 降级：使用 subagent API
@@ -490,12 +807,13 @@ class F2AOpenClawAdapter {
             try {
                 // 生成 idempotencyKey（必需参数）
                 const idempotencyKey = `f2a-${fromPeerId.slice(0, 16)}-${Date.now()}`;
+                // P1-3: 使用正确的类型，移除 as any
                 const runResult = await this.api.runtime.subagent.run({
                     sessionKey,
                     message,
                     deliver: false,
                     idempotencyKey,
-                }); // 使用 as any 绕过类型检查
+                });
                 const waitResult = await this.api.runtime.subagent.waitForRun({
                     runId: runResult.runId,
                     timeoutMs: 60000,
@@ -527,7 +845,7 @@ class F2AOpenClawAdapter {
                 }
             }
             catch (err) {
-                debugLog(`[F2A Adapter] Subagent 失败: ${err instanceof Error ? err.message : String(err)}`);
+                debugLog(`[F2A Adapter] Subagent 失败: ${extractErrorMessage(err)}`);
             }
         }
         // 最终降级
@@ -981,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)
             }
         ];
     }
@@ -1101,6 +1570,16 @@ class F2AOpenClawAdapter {
                 }
             },
             onMessage: async (payload) => {
+                // P1-6: 验证 PeerID 格式
+                if (!isValidPeerId(payload.from)) {
+                    this._logger?.warn(`[F2A Adapter] onMessage: 拒绝来自无效 PeerID 的消息: ${String(payload.from).slice(0, 20)}`);
+                    return { response: 'Invalid sender' };
+                }
+                // P1-7: 检查消息长度限制
+                if (payload.content && payload.content.length > MAX_MESSAGE_LENGTH) {
+                    this._logger?.warn(`[F2A Adapter] onMessage: 消息过长 (${payload.content.length} bytes)，拒绝处理`);
+                    return { response: 'Message too long' };
+                }
                 this._logger?.info('[F2A Adapter] 收到 P2P 消息', {
                     from: payload.from.slice(0, 16),
                     content: payload.content.slice(0, 50)
@@ -1116,7 +1595,7 @@ class F2AOpenClawAdapter {
                     return { response: result || '收到消息，但我暂时无法生成回复。' };
                 }
                 catch (error) {
-                    this._logger?.error('[F2A Adapter] 处理消息失败', { error: error instanceof Error ? error.message : String(error) });
+                    this._logger?.error('[F2A Adapter] 处理消息失败', { error: extractErrorMessage(error) });
                     return { response: '抱歉，我遇到了一些问题，无法处理你的消息。' };
                 }
             },
@@ -1306,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)}` };
+        }
+    }
     /**
      * 关闭插件，清理资源
      * 只清理已初始化的资源
@@ -1317,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 {
@@ -1324,7 +2122,7 @@ class F2AOpenClawAdapter {
                 this._logger?.info('[F2A Adapter] F2A 实例已停止');
             }
             catch (err) {
-                this._logger?.warn('[F2A Adapter] F2A 实例停止失败', { error: err instanceof Error ? err.message : String(err) });
+                this._logger?.warn('[F2A Adapter] F2A 实例停止失败', { error: extractErrorMessage(err) });
             }
             this._f2a = undefined;
         }