foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/channels/discord.py

@@ -18,20 +18,18 @@ Foxclaw Channels — Discord 适配器
 """
 from __future__ import annotations
 import json
-from typing import Optional
+from typing import Any, Optional
 from . import ChannelAdapter, InboundMessage, OutboundMessage, SendResult
 
 DISCORD_API_BASE = "https://discord.com/api/v10"
 DISCORD_GATEWAY = "wss://gateway.discord.gg/?v=10&encoding=json"
 
-# Gateway opcodes
 OP_DISPATCH = 0
 OP_HEARTBEAT = 1
 OP_IDENTIFY = 2
 OP_HELLO = 10
 OP_HEARTBEAT_ACK = 11
 
-# Intents(收消息内容需要 GUILD_MESSAGES + MESSAGE_CONTENT)
 INTENT_GUILD_MESSAGES = 1 << 9
 INTENT_DIRECT_MESSAGES = 1 << 12
 INTENT_MESSAGE_CONTENT = 1 << 15
@@ -47,20 +45,18 @@ class DiscordAdapter(ChannelAdapter):
         self.bot_token = bot_token
         self.intents = intents
         self.timeout = timeout
-        self._bot_user_id = ""     # 自己的 bot user id(用于忽略自己的消息)
+        self._bot_user_id = ""
 
     def _headers(self) -> dict:
         return {"Authorization": f"Bot {self.bot_token}",
                 "Content-Type": "application/json",
                 "User-Agent": "Foxclaw (https://github.com, 1.0)"}
 
-    # ── 入站:标准化 Gateway MESSAGE_CREATE 事件 ───────────
     def normalize(self, raw: dict) -> Optional[InboundMessage]:
         """Discord Gateway 事件 → 标准 InboundMessage。
 
         raw 可以是完整 Gateway 帧({op,t,d})或直接是 MESSAGE_CREATE 的 data。
         """
-        # 取出 data 部分
         if "op" in raw:
             if raw.get("op") != OP_DISPATCH or raw.get("t") != "MESSAGE_CREATE":
                 return None
@@ -70,15 +66,13 @@ class DiscordAdapter(ChannelAdapter):
         if not data:
             return None
         author = data.get("author", {})
-        # 忽略机器人消息(含自己),避免自循环
         if author.get("bot"):
             return None
         if self._bot_user_id and str(author.get("id")) == self._bot_user_id:
             return None
         text = data.get("content", "")
         if not text:
-            return None       # 非文本(纯附件/嵌入)暂忽略
-        # 有 guild_id = 服务器频道(群),无 = 私信
+            return None
         is_group = bool(data.get("guild_id"))
         return InboundMessage(
             channel=self.CHANNEL,
@@ -90,7 +84,6 @@ class DiscordAdapter(ChannelAdapter):
             is_group=is_group,
             raw=data)
 
-    # ── 出站:REST 发送 ────────────────────────────────────
     def send(self, msg: OutboundMessage) -> SendResult:
         """POST /channels/{channel_id}/messages 发文本。"""
         try:
@@ -99,7 +92,7 @@ class DiscordAdapter(ChannelAdapter):
             return SendResult(False, error="缺少 httpx 依赖")
         if not self.bot_token:
             return SendResult(False, error="未配置 Discord bot token")
-        payload = {"content": msg.text}
+        payload: dict[str, Any] = {"content": msg.text}
         if msg.reply_to:
             payload["message_reference"] = {"message_id": msg.reply_to}
         url = f"{DISCORD_API_BASE}/channels/{msg.conversation_id}/messages"
@@ -156,10 +149,8 @@ class DiscordAdapter(ChannelAdapter):
             raise RuntimeError("需要 websockets 库:pip install websockets")
         import asyncio
         async with websockets.connect(DISCORD_GATEWAY, max_size=None) as ws:
-            # 1. HELLO:拿心跳间隔
             hello = json.loads(await ws.recv())
             heartbeat_ms = hello["d"]["heartbeat_interval"]
-            # 2. IDENTIFY
             await ws.send(json.dumps(self.build_identify()))
             self._running = True
 

package/python/foxclaw/channels/dispatcher.py

@@ -18,7 +18,7 @@ from . import InboundMessage, ChannelRegistry, ChannelAdapter
 class ChannelDispatcher:
     """渠道闭环:把入站消息路由到主管,回复发回原渠道。"""
 
-    def __init__(self, supervisor, registry: ChannelRegistry = None,
+    def __init__(self, supervisor, registry: ChannelRegistry | None = None,
                  idempotency=None):
         """
         supervisor: 主管 Agent(有 async run_task 方法)
@@ -27,7 +27,7 @@ class ChannelDispatcher:
         """
         self.supervisor = supervisor
         self.registry = registry or ChannelRegistry()
-        self._pending: set = set()    # 持有运行中的 task 引用,防止被 GC 回收
+        self._pending: set = set()
         if idempotency is None:
             from ..core.idempotency import IdempotencyGuard
             idempotency = IdempotencyGuard(ttl_seconds=3600)
@@ -61,23 +61,18 @@ class ChannelDispatcher:
             running = None
 
         if running is not None:
-            # 在异步环境:发任务 + 持有引用(防止无引用 task 被 GC 静默回收)
             task = running.create_task(self.handle(msg))
             self._pending.add(task)
             task.add_done_callback(self._pending.discard)
         else:
-            # 同步环境(轮询渠道):跑到完成,调用方得到完整处理结果
             asyncio.run(self.handle(msg))
 
     async def handle(self, msg: InboundMessage) -> dict:
         """处理一条入站消息:主管思考 → 回复原渠道。返回处理结果。"""
-        # 幂等检查:同一渠道+消息ID只处理一次(防平台重发/轮询游标边界导致重复回复)
         from ..core.idempotency import make_key
         if msg.message_id:
             idem_key = make_key("message", msg.channel, msg.message_id, msg.sender_id)
         else:
-            # 无稳定 message_id 的渠道/消息:用 渠道+发送者+内容+时间窗(10秒)
-            # 算 fallback key——退化但仍能挡住短时间内的重发,不留盲区。
             import time as _t
             window = int(_t.time() // 10)
             idem_key = make_key("message_fallback", msg.channel, msg.sender_id,
@@ -86,7 +81,6 @@ class ChannelDispatcher:
             return {"handled": True, "replied": False, "reason": "重复消息,已跳过",
                     "idempotent_skip": True}
 
-        # 交给主管处理,带上渠道上下文(便于主管知道来源)
         context = {
             "channel": msg.channel,
             "session_id": self._session_key(msg),
@@ -94,14 +88,7 @@ class ChannelDispatcher:
             "sender_name": msg.sender_name,
             "is_group": msg.is_group,
         }
-        # 渠道入站文本来自外部(Telegram/Discord/…),默认按**不可信数据**处理:
-        # 此前 msg.text 原样当任务喂主管,等于把任意外部聊天用户当指令源(无发送者
-        # 白名单、无 <untrusted> 包裹)。可信发送者用 FOXCLAW_CHANNEL_TRUSTED_SENDERS
-        # 显式声明,逗号分隔,支持 `sender_id` 或 `channel:sender_id`,`*` 为该渠道全信任。
         context["sender_trusted"] = self._sender_trusted(msg)
-        # 下传给权限判定:不可信来源驱动的任务里,写/发送/外发动作一律按「已接触敏感数据」
-        # 处理(见 agents/_context._untrusted_get → tool_exec._guard_tool / skillbox)。
-        # 只影响带此键的入口(渠道),本地 HTTP 对话不带 → 行为不变。
         context["untrusted_source"] = not context["sender_trusted"]
         text = msg.text
         if not context["sender_trusted"]:
@@ -114,12 +101,10 @@ class ChannelDispatcher:
         except Exception as e:
             result = {"error": f"主管处理失败: {e}"}
 
-        # 提取回复文本
         reply_text = self._extract_reply(result)
         if not reply_text:
             return {"handled": True, "replied": False, "reason": "无回复内容"}
 
-        # 通过原渠道回复
         adapter = self.registry.get(msg.channel)
         if adapter is None:
             return {"handled": True, "replied": False, "reason": f"渠道 {msg.channel} 未注册"}
@@ -141,9 +126,6 @@ class ChannelDispatcher:
             return False
         sid = str(getattr(msg, "sender_id", "") or "")
         chan = str(getattr(msg, "channel", "") or "")
-        # 裸 `*` 曾等于「所有渠道的所有发送者都可信」——一次手滑就把任意外部聊天用户提成
-        # 指令源,而列表里看不出它比 channel:sender_id 宽多少。现在必须二选一:
-        # 写 `channel:*`(限定渠道,推荐),或用 FOXCLAW_CHANNEL_TRUST_ALL=1 显式确认全局信任。
         trust_all = _os.environ.get("FOXCLAW_CHANNEL_TRUST_ALL", "").strip() in ("1", "true", "True")
         for item in (x.strip() for x in raw.split(",")):
             if not item:
@@ -169,16 +151,12 @@ class ChannelDispatcher:
             return str(result) if result else ""
 
         inner = result.get("result")
-        # 情况1:result 直接是字符串
         if isinstance(inner, str) and inner.strip():
             return inner
-        # 情况2:result 是嵌套字典(主管分诊结果)
         if isinstance(inner, dict):
-            # 单 Agent:sub_result
             sub = inner.get("sub_result")
             if isinstance(sub, str) and sub.strip():
                 return sub
-            # 多 Agent:拼接每步输出
             steps = inner.get("multi_steps")
             if isinstance(steps, list) and steps:
                 parts = []
@@ -188,17 +166,14 @@ class ChannelDispatcher:
                         parts.append(str(out))
                 if parts:
                     return "\n\n".join(parts)
-            # 元问题自答等:answer / summary
             for k in ("answer", "summary", "response"):
                 v = inner.get(k)
                 if isinstance(v, str) and v.strip():
                     return v
-        # 情况3:顶层的 summary/response/output
         for key in ("summary", "response", "output"):
             val = result.get(key)
             if isinstance(val, str) and val.strip():
                 return val
-        # 出错兜底
         if result.get("error"):
             return f"抱歉,处理时遇到问题:{result['error']}"
         return ""

package/python/foxclaw/channels/feishu.py

@@ -30,15 +30,14 @@ class FeishuAdapter(ChannelAdapter):
         super().__init__(on_message=on_message)
         self.app_id = app_id
         self.app_secret = app_secret
-        self.verification_token = verification_token   # webhook 模式校验
-        self.encrypt_key = encrypt_key                 # 若开启加密
+        self.verification_token = verification_token
+        self.encrypt_key = encrypt_key
         self.base = FEISHU_BASE if domain == "feishu" else LARK_BASE
         self.timeout = timeout
-        self._token = ""           # 缓存的 tenant_access_token
-        self._token_exp = 0.0      # 过期时间戳
-        self._last_error = ""      # 最近一次解密/处理错误(便于排查)
+        self._token = ""
+        self._token_exp = 0.0
+        self._last_error = ""
 
-    # ── 入站:事件订阅 ──────────────────────────────────────
     def decrypt_event(self, encrypt: str) -> Optional[dict]:
         """解密飞书加密事件(AES-256-CBC,key=sha256(encrypt_key))。
 
@@ -60,7 +59,6 @@ class FeishuAdapter(ChannelAdapter):
         plain = self._aes_cbc_decrypt(key, iv, ciphertext)
         if plain is None:
             return None
-        # PKCS7 去 padding(带校验,防损坏数据)
         if not plain:
             return None
         pad = plain[-1]
@@ -76,7 +74,6 @@ class FeishuAdapter(ChannelAdapter):
 
     def _aes_cbc_decrypt(self, key: bytes, iv: bytes, ciphertext: bytes) -> Optional[bytes]:
         """AES-256-CBC 解密。优先用 cryptography,回退 pycryptodome。"""
-        # 优先 cryptography(更常见)
         try:
             from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
             cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
@@ -85,7 +82,7 @@ class FeishuAdapter(ChannelAdapter):
         except ImportError:
             pass
         try:
-            from Crypto.Cipher import AES   # pycryptodome
+            from Crypto.Cipher import AES
             return AES.new(key, AES.MODE_CBC, iv).decrypt(ciphertext)
         except ImportError:
             self._last_error = ("缺少 AES 库,无法解密飞书加密事件。"
@@ -99,12 +96,12 @@ class FeishuAdapter(ChannelAdapter):
                          signature: str) -> bool:
         """验签:sha256(timestamp + nonce + encrypt_key + body)。"""
         if not self.encrypt_key:
-            return True       # 未开启加密则不验签(飞书此时也不发签名)
+            return True
         content = (timestamp + nonce + self.encrypt_key).encode() + body
         digest = hashlib.sha256(content).hexdigest()
         return digest == signature
 
-    def handle_event(self, payload: dict, headers: dict = None,
+    def handle_event(self, payload: dict, headers: dict | None = None,
                      raw_body: bytes = b"") -> dict:
         """处理飞书事件回调入口。返回应答给飞书的 dict。
 
@@ -114,23 +111,19 @@ class FeishuAdapter(ChannelAdapter):
         - 验签 → normalize → on_message
         """
         headers = headers or {}
-        # 1. 加密:先解密外层
         if "encrypt" in payload:
             dec = self.decrypt_event(payload["encrypt"])
             if dec is None:
                 return {"error": "decrypt_failed"}
             payload = dec
-        # 2. URL 验证(首次配置回调地址时)
         if payload.get("type") == "url_verification":
             return {"challenge": payload.get("challenge", "")}
-        # 3. 验签(若有签名头)
         sig = headers.get("X-Lark-Signature") or headers.get("x-lark-signature")
         if sig:
             ts = headers.get("X-Lark-Request-Timestamp", "")
             nonce = headers.get("X-Lark-Request-Nonce", "")
             if not self.verify_signature(ts, nonce, raw_body, sig):
                 return {"error": "invalid_signature"}
-        # 4. 消息事件 → normalize → 回调
         inbound = self.normalize(payload)
         if inbound and self.on_message:
             self.on_message(inbound)
@@ -145,7 +138,6 @@ class FeishuAdapter(ChannelAdapter):
         message = event.get("message", {})
         sender = event.get("sender", {})
         sender_sid = sender.get("sender_id", {})
-        # 飞书消息内容是 JSON 字符串,文本在 {"text": "..."}
         text = ""
         try:
             import json
@@ -155,19 +147,18 @@ class FeishuAdapter(ChannelAdapter):
             pass
         if not text:
             return None
-        chat_type = message.get("chat_type", "p2p")   # p2p=私聊, group=群
+        chat_type = message.get("chat_type", "p2p")
         return InboundMessage(
             channel=self.CHANNEL,
             message_id=message.get("message_id", ""),
             text=text,
             sender_id=sender_sid.get("open_id", ""),
-            sender_name="",            # 飞书需额外调 API 取名,默认留空(可选 resolveSenderNames)
+            sender_name="",
             conversation_id=message.get("chat_id", ""),
             is_group=(chat_type == "group"),
             timestamp=float(message.get("create_time", 0)) / 1000 or time.time(),
             raw=raw)
 
-    # ── 出站:tenant_access_token + 发消息 ──────────────────
     def _get_token(self) -> str:
         """取 tenant_access_token,带缓存与自动刷新(过期前 5 分钟刷新)。"""
         if self._token and time.time() < self._token_exp - 300:
@@ -197,7 +188,6 @@ class FeishuAdapter(ChannelAdapter):
         token = self._get_token()
         if not token:
             return SendResult(False, error="获取 tenant_access_token 失败")
-        # receive_id_type 用 chat_id(群和私聊的会话 ID 都用 chat_id 发)
         payload = {
             "receive_id": msg.conversation_id,
             "msg_type": "text",

package/python/foxclaw/channels/openclaw_bridge.py

@@ -47,13 +47,12 @@ class OpenClawBridgeAdapter(ChannelAdapter):
         关键:保留 OpenClaw 侧的 channel(真实渠道,如 wechat)和 conversation 引用,
         以便回复时让 OpenClaw 发回正确的原渠道。
         """
-        # OpenClaw 消息常见结构:{channel, message:{id,text}, sender:{id,name}, conversation:{id,isGroup}}
         msg = raw.get("message") or raw
         if not isinstance(msg, dict):
             return None
         text = msg.get("text") or msg.get("content") or ""
         if not text:
-            return None       # 非文本事件忽略
+            return None
         sender = raw.get("sender") or msg.get("sender") or {}
         conv = raw.get("conversation") or msg.get("conversation") or {}
         return InboundMessage(
@@ -64,7 +63,7 @@ class OpenClawBridgeAdapter(ChannelAdapter):
             sender_name=str(sender.get("name") or sender.get("username") or ""),
             conversation_id=str(conv.get("id") or conv.get("conversation_id") or ""),
             is_group=bool(conv.get("isGroup") or conv.get("is_group") or False),
-            raw=raw)       # 原始 payload 留底(含 upstream channel 等回发所需信息)
+            raw=raw)
 
     def _upstream_channel(self, inbound_raw: dict) -> str:
         return (inbound_raw.get("channel")
@@ -86,21 +85,17 @@ class OpenClawBridgeAdapter(ChannelAdapter):
         }
         if msg.reply_to:
             payload["reply_to"] = msg.reply_to
-        # 若上层指明了真实渠道(从入站 raw 透传),带上,确保发回正确渠道
         if msg.extra.get("upstream_channel"):
             payload["channel"] = msg.extra["upstream_channel"]
         headers = {}
         if self.api_token:
             headers["Authorization"] = f"Bearer {self.api_token}"
-        # 先序列化成 bytes 再发:签名必须覆盖**实际发出去的字节**,否则网关侧
-        # 重新序列化(键序/转义差异)会导致验签失败。content= 而非 json=,
-        # 就是为了保证"签的就是发的"。
         try:
             body = json.dumps(payload, ensure_ascii=False,
                               sort_keys=True).encode("utf-8")
         except Exception as e:
             return SendResult(False, error=f"出站 payload 序列化失败: {e}")
-        headers["Content-Type"] = "application/json"   # content= 不走 httpx 的 json= 推断
+        headers["Content-Type"] = "application/json"
         if self.signer is not None and self.signer.enabled:
             try:
                 headers.update(self.signer.headers(body))
@@ -130,7 +125,7 @@ class OpenClawBridgeAdapter(ChannelAdapter):
 
     def verify_webhook(self, headers, body: bytes,
                        tolerance: float = _signing.DEFAULT_TOLERANCE,
-                       replay: "_signing.ReplayGuard" = None):
+                       replay: "_signing.ReplayGuard | None" = None):
         """验 OpenClaw 转发来的 webhook 签名,返回 (是否通过, 原因码)。
 
         与出站签名同一套 canonical 结构、同一个共享密钥(`signing.verify`)。

package/python/foxclaw/channels/signing.py

@@ -41,7 +41,7 @@ KEY_ID_HEADER = "X-Foxclaw-Key-Id"
 ENV_SECRET = "FOXCLAW_CHANNEL_SIGNING_SECRET"
 ENV_KEY_ID = "FOXCLAW_CHANNEL_SIGNING_KEY_ID"
 
-DEFAULT_TOLERANCE = 300.0     # 秒;超过即判过期(时钟漂移容忍)
+DEFAULT_TOLERANCE = 300.0
 
 
 def body_digest(body: bytes) -> str:
@@ -70,10 +70,10 @@ class ReplayGuard:
     def __init__(self, ttl: float = DEFAULT_TOLERANCE, max_entries: int = 4096):
         self.ttl = float(ttl)
         self.max_entries = max(16, int(max_entries))
-        self._seen: dict[str, float] = {}      # nonce -> 首次见到的时间
+        self._seen: dict[str, float] = {}
         self._lock = threading.Lock()
 
-    def purge(self, now: float = None) -> int:
+    def purge(self, now: float | None = None) -> int:
         """清掉过期 nonce,返回清理条数。"""
         cut = (now if now is not None else time.time()) - self.ttl
         with self._lock:
@@ -82,10 +82,10 @@ class ReplayGuard:
                 self._seen.pop(k, None)
         return len(dead)
 
-    def seen(self, nonce: str, now: float = None) -> bool:
+    def seen(self, nonce: str, now: float | None = None) -> bool:
         """见过 → True(**这是重放**);没见过则登记并返回 False。"""
         if not nonce:
-            return True                        # 空 nonce 一律当重放/fail-closed
+            return True
         now = now if now is not None else time.time()
         with self._lock:
             cut = now - self.ttl
@@ -115,7 +115,7 @@ class OutboundSigner:
     def enabled(self) -> bool:
         return bool(self.secret)
 
-    def headers(self, body: bytes, nonce: str = "", now: float = None) -> dict:
+    def headers(self, body: bytes, nonce: str = "", now: float | None = None) -> dict:
         """生成签名头。未配置密钥直接抛错(fail-closed:调用方必须先判 `enabled`)。"""
         if not self.enabled:
             raise ValueError("未配置渠道签名密钥(FOXCLAW_CHANNEL_SIGNING_SECRET)")
@@ -145,8 +145,8 @@ def _header(headers: Mapping, name: str) -> str:
 
 
 def verify(headers: Mapping, body: bytes, secret: str,
-           tolerance: float = DEFAULT_TOLERANCE, replay: ReplayGuard = None,
-           now: float = None) -> Tuple[bool, str]:
+           tolerance: float = DEFAULT_TOLERANCE, replay: ReplayGuard | None = None,
+           now: float | None = None) -> Tuple[bool, str]:
     """验签。返回 (是否通过, 原因码)。
 
     原因码:``ok`` / ``missing_secret`` / ``missing_header`` / ``bad_version`` /
@@ -178,7 +178,7 @@ def verify(headers: Mapping, body: bytes, secret: str,
     return True, "ok"
 
 
-def from_env(env: Mapping = None) -> Optional[OutboundSigner]:
+def from_env(env: Mapping | None = None) -> Optional[OutboundSigner]:
     """按环境变量构造签名器;未配置密钥 → None(不签,opt-in)。"""
     env = env if env is not None else os.environ
     secret = (env.get(ENV_SECRET) or "").strip()

package/python/foxclaw/channels/telegram.py

@@ -22,7 +22,7 @@ class TelegramAdapter(ChannelAdapter):
         super().__init__(on_message=on_message)
         self.bot_token = bot_token
         self.timeout = timeout
-        self._offset = 0          # getUpdates 增量游标(避免重复拉取)
+        self._offset = 0
 
     @property
     def _base(self) -> str:
@@ -32,7 +32,7 @@ class TelegramAdapter(ChannelAdapter):
         """Telegram update → 标准 InboundMessage。非文本消息返回 None。"""
         msg = raw.get("message") or raw.get("edited_message")
         if not msg or "text" not in msg:
-            return None       # 非文本消息(贴纸/图片/已读等)暂忽略
+            return None
         chat = msg.get("chat", {})
         sender = msg.get("from", {})
         chat_type = chat.get("type", "private")
@@ -97,11 +97,10 @@ class TelegramAdapter(ChannelAdapter):
             return []
         out = []
         for update in data.get("result", []):
-            # 推进游标:下次从最大 update_id + 1 开始,避免重复
             uid = update.get("update_id", 0)
             if uid >= self._offset:
                 self._offset = uid + 1
-            inbound = self.handle_raw(update)   # normalize + 触发 on_message
+            inbound = self.handle_raw(update)
             if inbound:
                 out.append(inbound)
         return out

package/python/foxclaw/channels/weixin.py

@@ -22,20 +22,17 @@ import secrets
 from typing import Optional
 from . import ChannelAdapter, InboundMessage, OutboundMessage, SendResult
 
-# 官方网关与端点(来自 Tencent/openclaw-weixin 源码 src/auth/accounts.ts)
 WEIXIN_BASE_URL = "https://ilinkai.weixin.qq.com"
 EP_GET_UPDATES = "ilink/bot/getupdates"
 EP_SEND_MESSAGE = "ilink/bot/sendmessage"
 EP_GET_CONFIG = "ilink/bot/getconfig"
 EP_SEND_TYPING = "ilink/bot/sendtyping"
 
-# 消息 item 类型(来自 README MessageItem 表)
 ITEM_TEXT = 1
 ITEM_IMAGE = 2
 ITEM_VOICE = 3
 ITEM_FILE = 4
 ITEM_VIDEO = 5
-# message_type
 MSG_FROM_USER = 1
 MSG_FROM_BOT = 2
 
@@ -55,8 +52,7 @@ class WeixinAdapter(ChannelAdapter):
         self.ilink_app_id = ilink_app_id
         self.long_poll_timeout_ms = long_poll_timeout_ms
         self.timeout = timeout
-        self._cursor = ""        # get_updates_buf 同步游标
-        # 记录每个用户最近的 context_token(回复时必须带回)
+        self._cursor = ""
         self._context_tokens: dict[str, str] = {}
 
     @staticmethod
@@ -69,7 +65,6 @@ class WeixinAdapter(ChannelAdapter):
             major = minor = patch = 0
         return ((major & 0xFF) << 16) | ((minor & 0xFF) << 8) | (patch & 0xFF)
 
-    # ── 鉴权头(照官方 buildHeaders)──────────────────────
     @staticmethod
     def _random_wechat_uin() -> str:
         """X-WECHAT-UIN: 随机 uint32 → 十进制字符串 → base64。"""
@@ -91,7 +86,7 @@ class WeixinAdapter(ChannelAdapter):
     def _base_info(self) -> dict:
         return {"channel_version": self.channel_version, "bot_agent": self.bot_agent}
 
-    def _post(self, endpoint: str, body: dict, timeout: float = None):
+    def _post(self, endpoint: str, body: dict, timeout: float | None = None):
         import httpx
         url = f"{self.base_url}/{endpoint}"
         payload = {**body, "base_info": self._base_info()}
@@ -100,7 +95,6 @@ class WeixinAdapter(ChannelAdapter):
                                timeout=timeout or self.timeout)
         return resp
 
-    # ── 入站:getUpdates 长轮询 ────────────────────────────
     def poll_once(self) -> list[InboundMessage]:
         """长轮询拉一批新消息。宿主在循环里反复调用即可持续接收。"""
         try:
@@ -114,7 +108,7 @@ class WeixinAdapter(ChannelAdapter):
                               {"get_updates_buf": self._cursor},
                               timeout=self.long_poll_timeout_ms / 1000 + 5)
         except Exception:
-            return []        # 长轮询超时/中断 → 空,下次重试
+            return []
         if resp.status_code != 200:
             return []
         try:
@@ -122,8 +116,7 @@ class WeixinAdapter(ChannelAdapter):
         except Exception:
             return []
         if data.get("ret") != 0:
-            return []        # errcode -14 = 会话超时,需重新登录
-        # 推进游标
+            return []
         new_buf = data.get("get_updates_buf")
         if new_buf is not None:
             self._cursor = new_buf
@@ -141,20 +134,18 @@ class WeixinAdapter(ChannelAdapter):
         return self._normalize_msg(raw)
 
     def _normalize_msg(self, msg: dict) -> Optional[InboundMessage]:
-        # 只处理用户发来的消息(message_type=1),忽略 bot 自己的回显
         if msg.get("message_type") not in (None, MSG_FROM_USER):
             return None
-        # 从 item_list 提取文本
         text = ""
         for item in msg.get("item_list", []) or []:
             if item.get("type") == ITEM_TEXT and item.get("text_item"):
                 text += item["text_item"].get("text", "")
         if not text:
-            return None       # 非文本(图片/语音等)暂忽略
+            return None
         from_user = str(msg.get("from_user_id", ""))
         ctx = msg.get("context_token", "")
         if from_user and ctx:
-            self._context_tokens[from_user] = ctx   # 记住,回复时带回
+            self._context_tokens[from_user] = ctx
         return InboundMessage(
             channel=self.CHANNEL,
             message_id=str(msg.get("message_id", "")),
@@ -162,11 +153,10 @@ class WeixinAdapter(ChannelAdapter):
             sender_id=from_user,
             sender_name="",
             conversation_id=str(msg.get("session_id", "") or from_user),
-            is_group=False,    # 个人号 DM;群聊当前插件能力未公开
+            is_group=False,
             timestamp=float(msg.get("create_time_ms", 0)) / 1000 or 0.0,
             raw=msg)
 
-    # ── 出站:sendMessage ──────────────────────────────────
     def send(self, msg: OutboundMessage) -> SendResult:
         """发文本消息。conversation_id 作为 to_user_id;context_token 从记录里取或由 extra 传入。"""
         try: