foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/browser/driver/playwright_driver.py

@@ -24,11 +24,9 @@ from typing import List, Any
 from .base_driver import BaseDriver
 
 
-# 被拦请求只留最近这些条:诊断/测试用,不落盘
 _MAX_BLOCKED = 50
 
 
-# role -> 对应的 CSS selector，v1 用简单选择器覆盖大多数场景
 ROLE_SELECTOR_MAP = {
     "button": "button, [role=button], input[type=button], input[type=submit]",
     "link": "a[href]",
@@ -44,8 +42,6 @@ ROLE_SELECTOR_MAP = {
 class PlaywrightDriver(BaseDriver):
 
     def __init__(self, headless: bool = True, guard_requests: bool | None = None):
-        # A1：惰性导入——缺 playwright 时这里才抛 ImportError，由上层能力探测拦截，
-        # 不会污染 `import foxclaw.browser`。
         from playwright.sync_api import sync_playwright
 
         self._pw = None
@@ -60,12 +56,8 @@ class PlaywrightDriver(BaseDriver):
                 guard_requests = os.environ.get(
                     "FOXCLAW_BROWSER_GUARD_REQUESTS", "1").strip() not in ("0", "false", "no")
             if guard_requests:
-                # `**/*` 覆盖主文档、3xx 跳转后的新地址、iframe 与全部子资源。
-                # 原先只校验 navigate 的目标:公网页面跳一次转,或塞一个
-                # `<img src="http://169.254.169.254/...">` 就能越过准入。
                 self._page.route("**/*", self._on_route)
         except Exception:
-            # A4：构造中途失败（如 chromium 内核未 install）也不能泄漏原生资源
             self._safe_teardown()
             raise
 
@@ -95,7 +87,6 @@ class PlaywrightDriver(BaseDriver):
         try:
             route.continue_()
         except Exception:
-            # 会话已在拆卸中(回调与 close 竞争):请求已无意义,静默丢弃
             pass
 
     def _safe_teardown(self):
@@ -112,14 +103,27 @@ class PlaywrightDriver(BaseDriver):
         self._browser = None
         self._pw = None
 
+    def _require_page(self):
+        """取当前页面；未打开或已拆卸时立刻报错，而不是等 None 属性访问炸。
+
+        `_page` 的静态类型是 `Page | None`（初始化与拆卸都会置 None）。下面几个
+        方法原先直接 `self._page.xxx`：正常流程里 close() 之后没人再调，所以一直
+        没出事；一旦有人在拆卸后调用，得到的是 `'NoneType' object has no attribute
+        'goto'`，看不出「会话已关闭」这层意思。集中在这里判一次，报错即意图。
+        """
+        if self._page is None:
+            raise RuntimeError(
+                "browser session is not open: driver was closed or failed to launch"
+            )
+        return self._page
+
     def navigate(self, url: str) -> None:
-        self._page.goto(url, wait_until="domcontentloaded")
+        self._require_page().goto(url, wait_until="domcontentloaded")
 
     def query_interactive_elements(self, roles: tuple) -> List[Any]:
         selectors = [ROLE_SELECTOR_MAP[r] for r in roles if r in ROLE_SELECTOR_MAP]
         combined = ", ".join(selectors)
-        elements = self._page.query_selector_all(combined)
-        # 只保留当前可见的元素，避免 LLM 尝试操作看不见的东西
+        elements = self._require_page().query_selector_all(combined)
         return [el for el in elements if el.is_visible()]
 
     def describe_element(self, handle) -> dict:
@@ -148,19 +152,19 @@ class PlaywrightDriver(BaseDriver):
 
     def scroll(self, direction: str) -> None:
         delta = 600 if direction == "down" else -600
-        self._page.mouse.wheel(0, delta)
+        self._require_page().mouse.wheel(0, delta)
 
     def wait(self, seconds: float) -> None:
         time.sleep(seconds)
 
     def get_visible_text(self) -> str:
-        return self._page.inner_text("body")
+        return self._require_page().inner_text("body")
 
     def current_url(self) -> str:
-        return self._page.url
+        return self._require_page().url
 
     def current_title(self) -> str:
-        return self._page.title()
+        return self._require_page().title()
 
     def close(self) -> None:
         self._safe_teardown()

package/python/foxclaw/browser/perception/dom_extractor.py

@@ -7,7 +7,6 @@ DOM 提取器。
 （比如以后换成 CDP driver，只需要改这一层）。
 """
 
-# 只关心这些角色的元素，减少噪音；按需扩展
 INTERACTIVE_ROLES = ("button", "link", "textbox", "checkbox", "radio", "combobox", "menuitem")
 
 

package/python/foxclaw/browser/perception/element_indexer.py

@@ -16,7 +16,6 @@ from typing import List, Dict, Any
 class ElementIndexer:
 
     def __init__(self):
-        # id(str) -> 底层 driver 元素句柄
         self._registry: Dict[str, Any] = {}
         self._counter = 0
 
@@ -42,7 +41,7 @@ class ElementIndexer:
             indexed.append({
                 "id": eid,
                 "role": desc.get("role", "unknown"),
-                "text": desc.get("text", "")[:80],  # 截断，控制 token 成本
+                "text": desc.get("text", "")[:80],
                 "attrs": desc.get("attrs", {}),
             })
 

package/python/foxclaw/browser/service.py

@@ -23,21 +23,22 @@ import asyncio
 import importlib.util
 import threading
 from concurrent.futures import ThreadPoolExecutor
-from typing import Optional
+from typing import Optional, TYPE_CHECKING
 
 
+if TYPE_CHECKING:
+    from .session.session_manager import SessionManager
+
 class BrowserService:
 
     def __init__(self, headless: bool = True):
         self._headless = headless
-        self._session = None
+        self._session: "SessionManager | None" = None
         self._executor: Optional[ThreadPoolExecutor] = None
         self._closed = False
         self._launch_error: Optional[str] = None
-        # 保护 executor/session 的创建与关闭（仅协调，不进浏览器调用）
         self._guard = threading.Lock()
 
-    # ── 能力探测 ────────────────────────────────────────────────
     @staticmethod
     def available() -> bool:
         """playwright 包是否可导入。注意：这不保证 chromium 内核已 install，
@@ -53,7 +54,6 @@ class BrowserService:
             "launch_error": self._launch_error,
         }
 
-    # ── 工作线程上运行的同步实现 ──────────────────────────────────
     def _get_executor(self) -> ThreadPoolExecutor:
         with self._guard:
             if self._closed:
@@ -89,7 +89,6 @@ class BrowserService:
         loop = asyncio.get_running_loop()
         return await loop.run_in_executor(self._get_executor(), fn, *args)
 
-    # ── 对外 async API ─────────────────────────────────────────
     async def perceive(self) -> dict:
         """只感知当前页面语义结构，不改变页面状态。"""
         if not self.available():
@@ -107,9 +106,9 @@ class BrowserService:
             return {"ok": False, "error": "非法动作：需 {type, target?, value?}"}
         try:
             return {"ok": True, **await self._run(self._act_sync, action)}
-        except ValueError as e:  # 不支持的动作类型 / 非法编号
+        except ValueError as e:
             return {"ok": False, "error": str(e)}
-        except KeyError as e:    # 元素编号过期
+        except KeyError as e:
             return {"ok": False, "error": str(e).strip('"')}
         except Exception as e:
             return self._handle_error(e)
@@ -123,13 +122,11 @@ class BrowserService:
             executor = self._executor
         if executor is not None:
             try:
-                # 会话的 close 必须回到工作线程执行（Playwright 对象线程亲和）
                 loop = asyncio.get_running_loop()
                 await loop.run_in_executor(executor, self._close_sync)
             finally:
                 executor.shutdown(wait=True)
 
-    # ── 错误/降级处理 ──────────────────────────────────────────
     def _unavailable(self) -> dict:
         return {
             "ok": False,
@@ -140,7 +137,6 @@ class BrowserService:
 
     def _handle_error(self, e: Exception) -> dict:
         msg = str(e)
-        # chromium 内核未安装是最常见的 launch 失败，给出可操作提示
         if "playwright install" in msg or "Executable doesn't exist" in msg:
             self._launch_error = msg
             return {"ok": False, "available": False,

package/python/foxclaw/capability/embedding_service.py

@@ -22,8 +22,8 @@ import os
 import threading
 
 _lock = threading.Lock()
-_cache: dict[str, object] = {}     # model_name -> model 实例 或 None(加载失败/缺库)
-_load_attempts = 0                  # 实际发起过多少次"加载尝试"(缓存命中不计),用于验证收敛
+_cache: dict[str, object] = {}
+_load_attempts = 0
 
 
 def get_text_embedder(model_name: str | None = None):
@@ -42,17 +42,15 @@ def get_text_embedder(model_name: str | None = None):
             or os.environ.get("FOXCLAW_EMBEDDING_MODEL")
             or "all-MiniLM-L6-v2").strip()
     with _lock:
-        if name in _cache:                 # 本服务缓存命中(不重复走 HKC):绝不重复加载
+        if name in _cache:
             return _cache[name]
         _load_attempts += 1
         model = None
         try:
-            # 【P2·share-bge-m3】走 HKC 共享进程缓存 —— 同名 model 全 Foxclaw 只 load 1 次
-            # (HKC 检索 / HMR VectorStore / Harness SemanticDrift 共用同一份 instance)
             from hkc_search.embedding_backends import get_st_model as _hk_get
             model = _hk_get(name)
         except Exception:
-            model = None                   # HKC 不可用 / 缺库 / 离线 → 降级哈希嵌入
+            model = None
         _cache[name] = model
         return model
 

package/python/foxclaw/channels/__init__.py

@@ -20,15 +20,15 @@ import time
 @dataclass
 class InboundMessage:
     """标准化的入站消息(各平台 normalize 后的统一格式)。"""
-    channel: str                       # 来源渠道(telegram/slack/...)
+    channel: str
     message_id: str
     text: str
-    sender_id: str                     # 发送者唯一 ID(平台内)
+    sender_id: str
     sender_name: str = ""
-    conversation_id: str = ""          # 会话 ID(群=群ID,私聊=对方ID)
+    conversation_id: str = ""
     is_group: bool = False
     timestamp: float = field(default_factory=time.time)
-    raw: dict = field(default_factory=dict)   # 平台原始数据(留底,便于调试)
+    raw: dict = field(default_factory=dict)
 
     def to_dict(self) -> dict:
         return {"channel": self.channel, "message_id": self.message_id,
@@ -41,9 +41,9 @@ class InboundMessage:
 @dataclass
 class OutboundMessage:
     """标准化的出站消息(上层产出,各适配器转成平台格式发送)。"""
-    conversation_id: str               # 发往哪个会话
+    conversation_id: str
     text: str
-    reply_to: str = ""                 # 可选:回复某条消息
+    reply_to: str = ""
     extra: dict = field(default_factory=dict)
 
 
@@ -63,13 +63,12 @@ class ChannelAdapter(ABC):
     - 入站统一回调 on_message,上层无需关心平台差异
     """
 
-    # 子类覆盖:渠道名
     CHANNEL = "base"
 
-    def __init__(self, on_message: Callable[[InboundMessage], None] = None):
+    def __init__(self, on_message: Callable[[InboundMessage], None] | None = None):
         self.on_message = on_message
         self._running = False
-        self.last_error = ""       # 最近一次处理错误(便于排查,不抛断轮询)
+        self.last_error = ""
 
     @abstractmethod
     def normalize(self, raw: dict) -> Optional[InboundMessage]:
@@ -93,12 +92,11 @@ class ChannelAdapter(ABC):
             self.last_error = f"normalize 失败: {e}"
             return None
         if inbound is None:
-            return None       # 非消息事件(如已读回执),忽略
+            return None
         if self.on_message:
             try:
                 self.on_message(inbound)
             except Exception as e:
-                # on_message(主管处理)失败:记录但不抛,保证整批轮询不中断
                 self.last_error = f"on_message 失败: {e}"
         return inbound
 

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",