@henryxiaoyang/wechat-access-unqclawed 1.0.0

package/common/agent-events.ts

@@ -0,0 +1,49 @@
+import type { onAgentEvent as OnAgentEventType } from "openclaw/plugin-sdk";
+
+export type AgentEventStream = "lifecycle" | "tool" | "assistant" | "error" | (string & {});
+
+export type AgentEventPayload = {
+  runId: string;
+  seq: number;
+  stream: AgentEventStream;
+  ts: number;
+  data: Record<string, unknown>;
+  sessionKey?: string;
+};
+
+// 动态导入，兼容 openclaw 未导出该函数的情况
+let _onAgentEvent: typeof OnAgentEventType | undefined;
+
+// SDK 加载完成的 Promise，确保只加载一次
+const sdkReady: Promise<typeof OnAgentEventType | undefined> = (async () => {
+  try {
+    const sdk = await import("openclaw/plugin-sdk");
+    if (typeof sdk.onAgentEvent === "function") {
+      _onAgentEvent = sdk.onAgentEvent;
+    }
+  } catch {
+    // ignore
+  }
+  return _onAgentEvent;
+})();
+
+/**
+ * 注册 Agent 事件监听器。
+ *
+ * 修复了原版的时序问题：原版使用 loadOnAgentEvent().then() 异步注册，
+ * 导致在 dispatchReplyWithBufferedBlockDispatcher 调用之前注册的监听器
+ * 实际上在 Agent 开始产生事件时还未真正挂载，造成事件全部丢失。
+ *
+ * 新版通过 await sdkReady 确保 SDK 加载完成后再注册监听器，
+ * 调用方需要 await 此函数返回的 Promise，再调用 dispatchReply。
+ */
+export const onAgentEvent = async (
+  listener: Parameters<typeof OnAgentEventType>[0]
+): Promise<() => boolean> => {
+  const fn = await sdkReady;
+  if (fn) {
+    const unsubscribe = fn(listener);
+    return unsubscribe;
+  }
+  return () => false;
+};

package/common/message-context.ts

@@ -0,0 +1,174 @@
+import type { FuwuhaoMessage } from "../http/types.js";
+import { getWecomRuntime } from "./runtime.js";
+
+// ============================================
+// 渠道来源标签
+// ============================================
+// 用于 ChannelSource，标识消息来自哪个微信渠道
+// UI 侧可通过此字段区分不同来源，做差异化展示或交互限制
+export const WECHAT_CHANNEL_LABELS = {
+  /** 微信服务号 */
+  serviceAccount: "serviceAccount",
+  /** 微信小程序 */
+  miniProgram: "miniProgram",
+} as const;
+
+// ============================================
+// 消息上下文构建
+// ============================================
+// 将微信服务号的原始消息转换为 OpenClaw 标准的消息上下文
+// 包括路由解析、会话管理、消息格式化等核心功能
+
+/**
+ * 消息上下文返回类型
+ * @property ctx - OpenClaw 标准的消息上下文对象，包含所有必要的消息元数据
+ * @property route - 路由信息，用于确定消息应该发送到哪个 Agent
+ * @property storePath - 会话存储路径，用于持久化会话数据
+ */
+export interface MessageContext {
+  ctx: Record<string, unknown>;
+  route: {
+    sessionKey: string;  // 会话唯一标识，用于关联同一用户的多轮对话
+    agentId: string;     // Agent ID，标识处理此消息的 Agent
+    accountId: string;   // 账号 ID，用于多账号场景
+  };
+  storePath: string;
+}
+
+/**
+ * 构建消息上下文
+ * @param message - 微信服务号的原始消息对象
+ * @returns MessageContext 包含上下文、路由和存储路径的完整消息上下文
+ * @description 
+ * 此函数是消息处理的核心，负责：
+ * 1. 提取和标准化消息字段（兼容多种格式）
+ * 2. 解析路由，确定消息应该发送到哪个 Agent
+ * 3. 获取会话存储路径，用于持久化对话历史
+ * 4. 格式化消息为 OpenClaw 标准格式
+ * 5. 构建完整的消息上下文对象
+ * 
+ * 内部流程：
+ * - 从 runtime 获取配置
+ * - 提取用户 ID、消息 ID、内容等关键信息
+ * - 调用 routing.resolveAgentRoute 解析路由
+ * - 调用 session.resolveStorePath 获取存储路径
+ * - 调用 reply.formatInboundEnvelope 格式化消息
+ * - 调用 reply.finalizeInboundContext 构建最终上下文
+ */
+export const buildMessageContext = (message: FuwuhaoMessage): MessageContext => {
+  // 获取 OpenClaw 运行时实例
+  const runtime = getWecomRuntime();
+  // 加载全局配置（包含 Agent 配置、路由规则等）
+  const cfg = runtime.config.loadConfig();
+  
+  // ============================================
+  // 1. 提取和标准化消息字段
+  // ============================================
+  // 兼容多种字段命名（FromUserName/userid）
+  const userId = message.FromUserName || message.userid || "unknown";
+  const toUser = message.ToUserName || "unknown";
+  // 确保消息 ID 唯一（用于去重和追踪）
+  const messageId = message.MsgId || message.msgid || `${Date.now()}`;
+  // TODO: 微信的 CreateTime 是秒级时间戳，需要转换为毫秒
+  // const timestamp = message.CreateTime ? message.CreateTime * 1000 : Date.now();
+  const timestamp = Date.now();
+  // 提取消息内容（兼容 Content 和 text.content 两种格式）
+  const content = message.Content || message.text?.content || "";
+  
+  // ============================================
+  // 2. 解析路由 - 确定消息应该发送到哪个 Agent
+  // ============================================
+  // runtime.channel.routing.resolveAgentRoute 是 OpenClaw 的核心路由方法
+  // 根据频道、账号、对话类型等信息，决定使用哪个 Agent 处理消息
+  const frameworkRoute = runtime.channel.routing.resolveAgentRoute({
+    cfg,                    // 全局配置
+    channel: "wechat-access",     // 频道标识
+    accountId: "default",   // 账号 ID（支持多账号场景）
+    peer: {
+      kind: "dm",           // 对话类型：dm=私聊，group=群聊
+      id: userId,           // 对话对象 ID（用户 ID）
+    },
+  });
+  // 框架返回的 sessionKey 通常是 agent:main:main，与 PC 端默认 session 相同。
+  // 为了让 UI 能区分外部渠道消息，使用独立的 sessionKey 格式：
+  //   agent:{agentId}:wechat-access:direct:{userId}
+  const channelSessionKey = `agent:${frameworkRoute.agentId}:wechat-access:direct:${userId}`;
+  const route = {
+    ...frameworkRoute,
+    sessionKey: channelSessionKey,
+  };
+  
+  // ============================================
+  // 3. 获取消息格式化选项
+  // ============================================
+  // runtime.channel.reply.resolveEnvelopeFormatOptions 获取消息格式化配置
+  // 包括时间格式、前缀、后缀等显示选项
+  const envelopeOptions = runtime.channel.reply.resolveEnvelopeFormatOptions(cfg);
+  
+  // ============================================
+  // 4. 获取会话存储路径
+  // ============================================
+  // runtime.channel.session.resolveStorePath 计算会话数据的存储路径
+  // 用于持久化对话历史、上下文等信息
+  const storePath = runtime.channel.session.resolveStorePath(cfg.session?.store, {
+    agentId: route.agentId,
+  });
+  // 存储路径通常类似：/data/sessions/{agentId}/{sessionKey}.json
+  
+  // ============================================
+  // 5. 读取上次会话时间
+  // ============================================
+  // runtime.channel.session.readSessionUpdatedAt 读取上次会话的更新时间
+  // 用于判断会话是否过期，是否需要重置上下文
+  const previousTimestamp = runtime.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+  // 如果距离上次会话时间过长，可能会清空历史上下文
+  
+  // ============================================
+  // 6. 格式化入站消息
+  // ============================================
+  // runtime.channel.reply.formatInboundEnvelope 将原始消息格式化为标准格式
+  // 添加时间戳、发送者信息、格式化选项等
+  const body = runtime.channel.reply.formatInboundEnvelope({
+    channel: "wechat-access",         // 频道标识
+    from: userId,               // 发送者 ID
+    timestamp,                  // 消息时间戳
+    body: content,              // 消息内容
+    chatType: "direct",         // 对话类型（direct=私聊）
+    sender: {
+      id: userId,               // 发送者 ID
+    },
+    previousTimestamp,          // 上次会话时间（用于判断是否需要添加时间分隔符）
+    envelope: envelopeOptions,  // 格式化选项
+  });
+  // 返回格式化后的消息体，可能包含时间前缀、发送者名称等
+  
+  // ============================================
+  // 7. 构建完整的消息上下文
+  // ============================================
+  // runtime.channel.reply.finalizeInboundContext 构建 OpenClaw 标准的消息上下文
+  // 这是 Agent 处理消息时使用的核心数据结构
+  const ctx = runtime.channel.reply.finalizeInboundContext({
+    Body: body,                                 // 格式化后的消息体
+    RawBody: content,                           // 原始消息内容
+    CommandBody: content,                       // 命令体（用于解析命令）
+    From: `wechat-access:${userId}`,                  // 发送者标识（带频道前缀）
+    To: `wechat-access:${toUser}`,                    // 接收者标识
+    SessionKey: route.sessionKey,               // 会话键
+    AccountId: route.accountId,                 // 账号 ID
+    ChatType: "direct" as const,                // 对话类型
+    ChannelSource: WECHAT_CHANNEL_LABELS.serviceAccount,  // 渠道来源标识（用于 UI 侧区分消息来源）
+    SenderId: userId,                           // 发送者 ID
+    Provider: "wechat-access",                        // 提供商标识
+    Surface: "wechat-access",                         // 界面标识
+    MessageSid: messageId,                      // 消息唯一标识
+    Timestamp: timestamp,                       // 时间戳
+    OriginatingChannel: "wechat-access" as const,     // 原始频道
+    OriginatingTo: `wechat-access:${userId}`,         // 原始接收者
+  });
+  // ctx 包含了 Agent 处理消息所需的所有信息
+  
+  return { ctx, route, storePath };
+};

package/common/runtime.ts

@@ -0,0 +1,35 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+// ============================================
+// Runtime 管理
+// ============================================
+// 用于存储和获取 OpenClaw 的运行时实例
+// Runtime 提供了访问配置、会话、路由、事件等核心功能的接口
+
+/**
+ * 全局运行时实例
+ * 在插件初始化时由 OpenClaw 框架注入
+ */
+let runtime: PluginRuntime | null = null;
+
+/**
+ * 设置微信企业号运行时实例
+ * @param next - OpenClaw 提供的运行时实例
+ * @description 此方法应在插件初始化时调用一次，用于注入运行时依赖
+ */
+export const setWecomRuntime = (next: PluginRuntime): void => {
+  runtime = next;
+};
+
+/**
+ * 获取微信企业号运行时实例
+ * @returns OpenClaw 运行时实例
+ * @throws 如果运行时未初始化则抛出错误
+ * @description 在需要访问 OpenClaw 核心功能时调用此方法
+ */
+export const getWecomRuntime = (): PluginRuntime => {
+  if (!runtime) {
+    throw new Error("WeCom runtime not initialized");
+  }
+  return runtime;
+};

package/http/README.md

@@ -0,0 +1,138 @@
+# Fuwuhao (微信服务号) 模块
+
+## 📁 文件结构
+
+```
+src/
+├── types.ts              # 类型定义
+├── crypto-utils.ts       # 加密解密工具
+├── http-utils.ts         # HTTP 请求处理工具
+├── callback-service.ts   # 后置回调服务
+├── message-context.ts    # 消息上下文构建
+├── message-handler.ts    # 消息处理器（核心业务逻辑）
+├── webhook.ts            # Webhook 处理器（主入口）
+├── runtime.ts            # Runtime 配置
+└── index.ts              # 模块导出索引
+```
+
+## 📦 模块说明
+
+### 1. `types.ts` - 类型定义
+定义所有 TypeScript 类型和接口：
+- `AgentEventPayload` - Agent 事件载荷
+- `FuwuhaoMessage` - 服务号消息格式
+- `SimpleAccount` - 账号配置
+- `CallbackPayload` - 回调数据格式
+- `StreamChunk` - 流式消息块
+- `StreamCallback` - 流式回调函数类型
+
+### 2. `crypto-utils.ts` - 加密解密工具
+处理微信服务号的签名验证和消息加密解密：
+- `verifySignature()` - 验证签名
+- `decryptMessage()` - 解密消息
+
+### 3. `http-utils.ts` - HTTP 工具
+处理 HTTP 请求相关的工具方法：
+- `parseQuery()` - 解析查询参数
+- `readBody()` - 读取请求体
+- `isFuwuhaoWebhookPath()` - 检查是否是服务号 webhook 路径
+
+### 4. `callback-service.ts` - 后置回调服务
+将处理结果发送到外部回调服务：
+- `sendToCallbackService()` - 发送回调数据
+
+### 5. `message-context.ts` - 消息上下文构建
+构建消息处理所需的上下文信息：
+- `buildMessageContext()` - 构建消息上下文（路由、会话、格式化等）
+
+### 6. `message-handler.ts` - 消息处理器
+核心业务逻辑，处理消息并调用 Agent：
+- `handleMessage()` - 同步处理消息
+- `handleMessageStream()` - 流式处理消息（SSE）
+
+### 7. `webhook.ts` - Webhook 处理器
+主入口，处理微信服务号的 webhook 请求：
+- `handleSimpleWecomWebhook()` - 处理 GET/POST 请求，支持同步和流式返回
+
+### 8. `runtime.ts` - Runtime 配置
+获取 OpenClaw 运行时实例
+
+### 9. `index.ts` - 模块导出
+统一导出所有公共 API
+
+## 🔄 数据流
+
+```
+微信服务号
+    ↓
+webhook.ts (入口)
+    ↓
+http-utils.ts (解析请求)
+    ↓
+crypto-utils.ts (验证签名/解密)
+    ↓
+message-context.ts (构建上下文)
+    ↓
+message-handler.ts (处理消息)
+    ↓
+OpenClaw Agent (AI 处理)
+    ↓
+callback-service.ts (后置回调)
+    ↓
+返回响应
+```
+
+## 🚀 使用示例
+
+### 基本使用
+```typescript
+import { handleSimpleWecomWebhook } from "./src/webhook.js";
+
+// 在 HTTP 服务器中使用
+server.on("request", async (req, res) => {
+  const handled = await handleSimpleWecomWebhook(req, res);
+  if (!handled) {
+    // 处理其他路由
+  }
+});
+```
+
+### 流式返回（SSE）
+```typescript
+// 客户端请求时添加 stream 参数
+fetch("/fuwuhao?stream=true", {
+  headers: {
+    "Accept": "text/event-stream"
+  }
+});
+```
+
+## 🔧 配置
+
+### 环境变量
+- `FUWUHAO_CALLBACK_URL` - 后置回调服务 URL（默认：`http://localhost:3001/api/fuwuhao/callback`）
+
+### 账号配置
+在 `webhook.ts` 中修改 `mockAccount` 对象：
+```typescript
+const mockAccount: SimpleAccount = {
+  token: "your_token_here",
+  encodingAESKey: "your_encoding_aes_key_here", 
+  receiveId: "your_receive_id_here"
+};
+```
+
+## 📝 注意事项
+
+1. **加密解密**：当前 `crypto-utils.ts` 中的加密解密方法是简化版，生产环境需要实现真实的加密逻辑
+2. **签名验证**：同样需要在生产环境中实现真实的签名验证算法
+3. **错误处理**：所有模块都包含完善的错误处理和日志记录
+4. **类型安全**：所有模块都使用 TypeScript 严格类型检查
+
+## 🎯 设计原则
+
+- **单一职责**：每个文件只负责一个特定功能
+- **低耦合**：模块之间通过明确的接口通信
+- **高内聚**：相关功能集中在同一模块
+- **可测试**：每个模块都可以独立测试
+- **可扩展**：易于添加新功能或修改现有功能

package/http/callback-service.ts

@@ -0,0 +1,73 @@
+import type { CallbackPayload } from "./types.js";
+
+// ============================================
+// 后置回调服务
+// ============================================
+// 用于将消息处理结果发送到外部服务进行后续处理
+// 例如：数据统计、日志记录、业务逻辑触发等
+
+/**
+ * 后置回调服务的 URL 地址
+ * @description 
+ * 可通过环境变量 WECHAT_ACCESS_CALLBACK_URL 配置
+ * 默认值：http://localhost:3001/api/wechat-access/callback
+ */
+const CALLBACK_SERVICE_URL = process.env.WECHAT_ACCESS_CALLBACK_URL || "http://localhost:3001/api/wechat-access/callback";
+
+/**
+ * 发送消息处理结果到后置回调服务
+ * @param payload - 回调数据载荷，包含用户消息、AI 回复、会话信息等
+ * @returns Promise<void> 异步执行，不阻塞主流程
+ * @description 
+ * 后置回调的作用：
+ * 1. 记录消息处理日志
+ * 2. 统计用户交互数据
+ * 3. 触发业务逻辑（如积分、通知等）
+ * 4. 数据分析和监控
+ * 
+ * 特点：
+ * - 异步执行，失败不影响主流程
+ * - 支持自定义认证（通过 Authorization header）
+ * - 自动处理错误，只记录日志
+ * @example
+ * await sendToCallbackService({
+ *   userId: 'user123',
+ *   messageId: 'msg456',
+ *   userMessage: '你好',
+ *   aiReply: '您好！有什么可以帮您？',
+ *   success: true
+ * });
+ */
+export const sendToCallbackService = async (payload: CallbackPayload): Promise<void> => {
+  try {
+    console.log("[wechat-access] 发送后置回调:", {
+      url: CALLBACK_SERVICE_URL,
+      userId: payload.userId,
+      hasReply: !!payload.aiReply,
+    });
+
+    const response = await fetch(CALLBACK_SERVICE_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        // 可以添加认证头
+        // "Authorization": `Bearer ${process.env.CALLBACK_AUTH_TOKEN}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      console.error("[wechat-access] 后置回调服务返回错误:", {
+        status: response.status,
+        statusText: response.statusText,
+      });
+      return;
+    }
+
+    const result = await response.json().catch(() => ({}));
+    console.log("[wechat-access] 后置回调成功:", result);
+  } catch (err) {
+    // 后置回调失败不影响主流程，只记录日志
+    console.error("[wechat-access] 后置回调失败:", err);
+  }
+};

package/http/crypto-utils.ts

@@ -0,0 +1,96 @@
+// ============================================
+// 加密解密工具
+// ============================================
+// 处理微信服务号的消息加密、解密和签名验证
+// 微信使用 AES-256-CBC 加密算法和 SHA-1 签名算法
+
+/**
+ * 验证签名参数接口
+ * @property token - 微信服务号配置的 Token
+ * @property timestamp - 时间戳
+ * @property nonce - 随机数
+ * @property encrypt - 加密的消息内容
+ * @property signature - 微信生成的签名，用于验证消息来源
+ */
+export interface VerifySignatureParams {
+  token: string;
+  timestamp: string;
+  nonce: string;
+  encrypt: string;
+  signature: string;
+}
+
+/**
+ * 解密消息参数接口
+ * @property encodingAESKey - 微信服务号配置的 EncodingAESKey（43位字符）
+ * @property receiveId - 接收方 ID（通常是服务号的原始 ID）
+ * @property encrypt - 加密的消息内容（Base64 编码）
+ */
+export interface DecryptMessageParams {
+  encodingAESKey: string;
+  receiveId: string;
+  encrypt: string;
+}
+
+/**
+ * 验证微信消息签名
+ * @param params - 签名验证参数
+ * @returns 签名是否有效
+ * @description 
+ * 验证流程：
+ * 1. 将 token、timestamp、nonce、encrypt 按字典序排序
+ * 2. 拼接成字符串
+ * 3. 进行 SHA-1 哈希
+ * 4. 与微信提供的 signature 比对
+ * 
+ * **注意：当前为简化实现，生产环境需要实现真实的 SHA-1 签名验证**
+ */
+export const verifySignature = (params: VerifySignatureParams): boolean => {
+  // TODO: 实现真实的签名验证逻辑
+  // 参考算法：
+  // const arr = [params.token, params.timestamp, params.nonce, params.encrypt].sort();
+  // const str = arr.join('');
+  // const hash = crypto.createHash('sha1').update(str).digest('hex');
+  // return hash === params.signature;
+  
+  console.log("[wechat-access] 验证签名参数:", params);
+  return true; // 简化实现，直接返回 true
+};
+
+/**
+ * 解密微信消息
+ * @param params - 解密参数
+ * @returns 解密后的明文消息（JSON 字符串）
+ * @description 
+ * 解密流程：
+ * 1. 将 Base64 编码的 encrypt 解码为二进制
+ * 2. 使用 AES-256-CBC 算法解密（密钥由 encodingAESKey 派生）
+ * 3. 去除填充（PKCS7）
+ * 4. 提取消息内容（格式：随机16字节 + 4字节消息长度 + 消息内容 + receiveId）
+ * 5. 验证 receiveId 是否匹配
+ * 
+ * **注意：当前为简化实现，返回模拟数据，生产环境需要实现真实的 AES 解密**
+ */
+export const decryptMessage = (params: DecryptMessageParams): string => {
+  // TODO: 实现真实的解密逻辑
+  // 参考算法：
+  // const key = Buffer.from(params.encodingAESKey + '=', 'base64');
+  // const iv = key.slice(0, 16);
+  // const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
+  // decipher.setAutoPadding(false);
+  // let decrypted = Buffer.concat([decipher.update(params.encrypt, 'base64'), decipher.final()]);
+  // // 去除 PKCS7 填充
+  // const pad = decrypted[decrypted.length - 1];
+  // decrypted = decrypted.slice(0, decrypted.length - pad);
+  // // 提取消息内容
+  // const content = decrypted.slice(16);
+  // const msgLen = content.readUInt32BE(0);
+  // const message = content.slice(4, 4 + msgLen).toString('utf8');
+  // const receiveId = content.slice(4 + msgLen).toString('utf8');
+  // if (receiveId !== params.receiveId) throw new Error('receiveId mismatch');
+  // return message;
+  
+  console.log("[wechat-access] 解密参数:", params);
+  // 返回模拟的解密结果（标准微信消息格式）
+  return '{"msgtype":"text","Content":"Hello from 服务号","MsgId":"123456","FromUserName":"user001","ToUserName":"gh_test","CreateTime":1234567890}';
+};

package/http/http-utils.ts

@@ -0,0 +1,81 @@
+import type { IncomingMessage } from "node:http";
+
+// ============================================
+// HTTP 工具方法
+// ============================================
+// 提供 HTTP 请求处理的通用工具函数
+
+/**
+ * 解析 URL 查询参数
+ * @param req - Node.js HTTP 请求对象
+ * @returns URLSearchParams 对象，可通过 get() 方法获取参数值
+ * @description 
+ * 从请求 URL 中提取查询参数，例如：
+ * - /wechat-access?timestamp=123&nonce=abc
+ * - 可通过 params.get('timestamp') 获取值
+ * @example
+ * const query = parseQuery(req);
+ * const timestamp = query.get('timestamp');
+ */
+export const parseQuery = (req: IncomingMessage): URLSearchParams => {
+  const url = new URL(req.url || "", `http://${req.headers.host}`);
+  return url.searchParams;
+};
+
+/**
+ * 读取 HTTP 请求体内容
+ * @param req - Node.js HTTP 请求对象
+ * @returns Promise<string> 请求体的完整内容（字符串格式）
+ * @description 
+ * 异步读取请求体的所有数据块，适用于：
+ * - POST 请求的 JSON 数据
+ * - XML 格式的微信消息
+ * - 表单数据
+ * 
+ * 内部实现：
+ * 1. 监听 'data' 事件，累积数据块
+ * 2. 监听 'end' 事件，返回完整内容
+ * 3. 监听 'error' 事件，处理读取错误
+ * @example
+ * const body = await readBody(req);
+ * const data = JSON.parse(body);
+ */
+export const readBody = async (req: IncomingMessage): Promise<string> => {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    // 监听数据块事件，累积内容
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+    // 监听结束事件，返回完整内容
+    req.on("end", () => {
+      resolve(body);
+    });
+    // 监听错误事件
+    req.on("error", reject);
+  });
+};
+
+/**
+ * 检查请求路径是否是服务号 webhook 路径
+ * @param url - 请求的完整 URL 或路径
+ * @returns 是否匹配服务号 webhook 路径
+ * @description 
+ * 支持多种路径格式：
+ * - /wechat-access - 基础路径
+ * - /wechat-access/webhook - 标准 webhook 路径
+ * - /wechat-access/* - 任何以 /wechat-access/ 开头的路径
+ * 
+ * 用于路由判断，确保只处理服务号相关的请求
+ * @example
+ * if (isFuwuhaoWebhookPath(req.url)) {
+ *   // 处理服务号消息
+ * }
+ */
+export const isFuwuhaoWebhookPath = (url: string): boolean => {
+  const pathname = new URL(url, "http://localhost").pathname;
+  // 支持多种路径格式
+  return pathname === "/wechat-access" || 
+         pathname === "/wechat-access/webhook" ||
+         pathname.startsWith("/wechat-access/");
+};