foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/behavior/spec.py

@@ -0,0 +1,287 @@
+"""Behavior Spec —— 行为规范:把「守什么规矩」收拢成一份可校验的检查点清单。
+
+与 Persona 的分工(两者都是提示词,但不是一回事):
+  · Persona       = preference 记忆 → 注入**最后一条 user 消息**(可变、用户可调、用户可改)
+  · Behavior Spec = behavior.yaml  → 注入 **system prompt 最前段**(不可协商、本地只能加严)
+
+注入顺序由 `PromptMixin.system_prompt` 保证:behavior → KERNEL_PROMPT → 角色职责 → 规则文件,
+persona 永远在最后一条 user 消息里,结构上不可能覆盖本段。
+
+v1 的定位是**可执行的检查点清单**,不是规范全文:
+`code_check` 只登记仓库里真实存在的可调用对象,加载时 import 解析,解析不到即
+`BehaviorLoadError`(启动失败)。刻意不提供 `register_stubs()` —— 全放行的桩会让测试变绿
+而拦截为零,正是 `core/config.py` 反对的「建了没接线」。
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib
+import os
+import re
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any, Callable
+
+import yaml
+
+from ..core.config import LayeredConfig
+
+# 内置规范随包分发(package data,不能像仓库根 skills/ 那样漏进 wheel)
+BUILTIN_PATH = Path(__file__).resolve().parent / "behavior.yaml"
+
+# 注入顺序即声明顺序;本地覆盖不能引入这四层之外的层
+LAYERS = ("prohibitions", "confirmations", "uncertainty", "interaction")
+# 严格层:本地覆盖不得通过「省略」删除其中任何一条
+STRICT_LAYERS = ("prohibitions", "confirmations")
+
+SUPPORTED_VERSION = 1
+ENFORCE_VALUES = ("prompt", "code", "both")
+
+_ID_RE = re.compile(r"^[a-z][a-z0-9_]{2,63}$")
+
+
+class BehaviorLoadError(RuntimeError):
+    """内置文件损坏、规则非法、检查点解析不到,或本地覆盖试图放宽硬边界。
+
+    前三种是打包/开发事故,启动即失败;最后一种是用户或第三方想绕过边界,
+    必须响,不能降级成 warning。
+    """
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    layer: str
+    rule: str
+    enforce: str
+    code_check: tuple[str, ...] = ()
+    note: str = ""
+
+    @property
+    def injects(self) -> bool:
+        return self.enforce in ("prompt", "both")
+
+    @property
+    def enforces(self) -> bool:
+        return self.enforce in ("code", "both")
+
+
+@dataclass
+class BehaviorSpec:
+    version: int
+    spec_id: str
+    rules: list[Rule]
+    spec_version: str
+    source: str
+    warnings: list[str] = field(default_factory=list)
+
+    def by_id(self, rule_id: str) -> Rule | None:
+        return next((r for r in self.rules if r.id == rule_id), None)
+
+    def injectable(self) -> list[Rule]:
+        """要注入 system prompt 的规则(按层顺序)。"""
+        return [r for r in self.rules if r.injects]
+
+    def hard_rules(self) -> list[Rule]:
+        """有代码落点的规则。"""
+        return [r for r in self.rules if r.enforces]
+
+    def checkpoints(self) -> dict[str, Callable[..., Any]]:
+        """全部 code_check 的解析结果,key 为 "module:attr" 原文。"""
+        out: dict[str, Callable[..., Any]] = {}
+        for r in self.hard_rules():
+            for ref in r.code_check:
+                out[ref] = resolve(ref)
+        return out
+
+
+def resolve(ref: str) -> Callable[..., Any]:
+    """把 "module:Class.method" 解析成真实可调用对象;解析不到一律抛错,不静默跳过。"""
+    module_name, sep, attr = str(ref).partition(":")
+    if not sep or not module_name or not attr:
+        raise BehaviorLoadError(f"code_check 格式应为 'module:attr',收到 {ref!r}")
+    try:
+        obj: Any = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise BehaviorLoadError(f"code_check {ref!r} 的模块不可导入:{exc}") from exc
+    for part in attr.split("."):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError as exc:
+            raise BehaviorLoadError(f"code_check {ref!r} 在 {module_name} 上不存在:{part}") from exc
+    if not callable(obj):
+        raise BehaviorLoadError(f"code_check {ref!r} 不是可调用对象")
+    return obj
+
+
+def local_path() -> Path:
+    """本地覆盖位置:与 policy.json / skill_policy.json 同一个数据根(FOXCLAW_DATA_DIR)。"""
+    return Path(os.environ.get("FOXCLAW_DATA_DIR") or "./foxclaw_data") / "behavior.local.yaml"
+
+
+def _read(path: Path) -> dict:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise BehaviorLoadError(f"读不到行为规范文件 {path}:{exc}") from exc
+    try:
+        data = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        raise BehaviorLoadError(f"{path.name} 不是合法 YAML:{exc}") from exc
+    if data is None:
+        data = {}
+    if not isinstance(data, dict):
+        raise BehaviorLoadError(f"{path.name} 顶层应为映射,收到 {type(data).__name__}")
+    return data
+
+
+def _parse_rule(layer: str, item: Any, where: str) -> Rule:
+    if not isinstance(item, dict):
+        raise BehaviorLoadError(f"{where}:{layer} 的条目应为映射,收到 {type(item).__name__}")
+    rule_id = str(item.get("id") or "").strip()
+    if not _ID_RE.match(rule_id):
+        raise BehaviorLoadError(f"{where}:{layer} 的 id 非法:{rule_id!r}(应为小写字母开头的 a-z0-9_)")
+    text = str(item.get("rule") or "").strip()
+    if not text:
+        raise BehaviorLoadError(f"{where}:{layer}.{rule_id} 缺 rule 文本")
+    enforce = str(item.get("enforce") or "").strip()
+    if enforce not in ENFORCE_VALUES:
+        raise BehaviorLoadError(f"{where}:{layer}.{rule_id} 的 enforce 非法:{enforce!r}(应为 {ENFORCE_VALUES})")
+    raw_checks = item.get("code_check") or []
+    if isinstance(raw_checks, str):
+        raw_checks = [raw_checks]
+    if not isinstance(raw_checks, list):
+        raise BehaviorLoadError(f"{where}:{layer}.{rule_id} 的 code_check 应为字符串或列表")
+    checks = tuple(str(c).strip() for c in raw_checks if str(c).strip())
+    if enforce in ("code", "both") and not checks:
+        raise BehaviorLoadError(f"{where}:{layer}.{rule_id} 声明 enforce={enforce} 但没有 code_check")
+    return Rule(id=rule_id, layer=layer, rule=text, enforce=enforce,
+                code_check=checks, note=str(item.get("note") or "").strip())
+
+
+def _collect(raw: dict, where: str) -> list[Rule]:
+    rules: list[Rule] = []
+    unknown = set(raw) - set(LAYERS) - {"version", "spec_id", "description"}
+    if unknown:
+        raise BehaviorLoadError(f"{where} 有未知字段:{sorted(unknown)}")
+    for layer in LAYERS:
+        items = raw.get(layer) or []
+        if not isinstance(items, list):
+            raise BehaviorLoadError(f"{where}:{layer} 应为列表")
+        rules.extend(_parse_rule(layer, item, where) for item in items)
+    return rules
+
+
+def _validate(rules: list[Rule], where: str) -> None:
+    """id 唯一 + 每个 code_check 必须解析到真实可调用对象。"""
+    seen: set[str] = set()
+    for r in rules:
+        if r.id in seen:
+            raise BehaviorLoadError(f"{where}:规则 id 重复:{r.id}")
+        seen.add(r.id)
+        for ref in r.code_check:
+            resolve(ref)
+
+
+def _locked_ids(rules: list[Rule]) -> set[str]:
+    """内置文件中已有代码落点的规则 id —— 借 core/config.py 的分层语义表达「本地不可放宽」。"""
+    return LayeredConfig(policy={"locked": [r.id for r in rules if r.enforces]}).policy_locked("locked")
+
+
+def _is_weaker(before: str, after: str) -> bool:
+    if before == after:
+        return False
+    if before == "prompt":
+        return False  # prompt → code/both 都是加严
+    if before == "code":
+        return after == "prompt"
+    return after != "both"  # before == both
+
+
+def _merge(base: list[Rule], raw: dict, where: str) -> list[Rule]:
+    """本地覆盖:可新增规则、可改写文本、可把 enforce 收紧;不可删除严格层规则、不可放宽。"""
+    base_by_id = {r.id: r for r in base}
+    locked = _locked_ids(base)
+    merged = dict(base_by_id)
+    for layer in LAYERS:
+        if layer not in raw:
+            continue
+        items = raw[layer] or []
+        if not isinstance(items, list):
+            raise BehaviorLoadError(f"{where}:{layer} 应为列表")
+        seen = set()
+        for item in items:
+            local = _parse_rule(layer, item, where)
+            seen.add(local.id)
+            old = base_by_id.get(local.id)
+            if old is None:
+                merged[local.id] = local
+                continue
+            if local.id in locked and _is_weaker(old.enforce, local.enforce):
+                raise BehaviorLoadError(
+                    f"{where}:{layer}.{local.id} 不能放宽 enforce({old.enforce} → {local.enforce});"
+                    "本地覆盖只能加严")
+            merged[local.id] = replace(
+                old, rule=local.rule, enforce=local.enforce,
+                code_check=local.code_check or old.code_check, note=local.note or old.note)
+        if layer in STRICT_LAYERS:
+            dropped = {r.id for r in base if r.layer == layer} - seen
+            if dropped:
+                raise BehaviorLoadError(
+                    f"{where}:{layer} 不能通过省略删除规则:{sorted(dropped)};要停用请显式改 enforce")
+    return list(merged.values())
+
+
+def load(builtin_path: Path | str | None = None,
+         override_path: Path | str | None = None) -> BehaviorSpec:
+    """加载并校验。内置文件的问题一律抛 BehaviorLoadError;本地覆盖的语法问题降级为 warning 并忽略。"""
+    bp = Path(builtin_path) if builtin_path else BUILTIN_PATH
+    raw = _read(bp)
+    if raw.get("version") != SUPPORTED_VERSION:
+        raise BehaviorLoadError(
+            f"{bp.name} 的 version={raw.get('version')!r} 与当前程序支持的 {SUPPORTED_VERSION} 不符")
+    rules = _collect(raw, bp.name)
+    _validate(rules, bp.name)
+
+    digest = bp.read_bytes()
+    warnings: list[str] = []
+    source = str(bp)
+
+    lp = Path(override_path) if override_path else local_path()
+    if lp.is_file():
+        try:
+            local_raw = _read(lp)
+        except BehaviorLoadError as exc:
+            # 用户手改错了语法不能把应用锁死;放宽/删除是另一回事,见下面的 _merge(不捕获)
+            warnings.append(f"本地覆盖 {lp} 已忽略:{exc}")
+        else:
+            local_version = local_raw.get("version")
+            if local_version is not None and local_version != SUPPORTED_VERSION:
+                warnings.append(f"本地覆盖 {lp} 的 version={local_version!r} 已过期,已忽略")
+            else:
+                rules = _merge(rules, local_raw, lp.name)
+                _validate(rules, lp.name)
+                digest = digest + b"\0" + lp.read_bytes()
+                source = f"{bp} + {lp}"
+
+    return BehaviorSpec(
+        version=SUPPORTED_VERSION,
+        spec_id=str(raw.get("spec_id") or "foxclaw-behavior"),
+        rules=rules,
+        spec_version=hashlib.sha256(digest).hexdigest()[:12],
+        source=source,
+        warnings=warnings,
+    )
+
+
+def prompt_block(spec: BehaviorSpec | None = None) -> str:
+    """注入 system prompt 最前段的行为规范段;开关 FOXCLAW_BEHAVIOR=0 可整体关闭。"""
+    if os.environ.get("FOXCLAW_BEHAVIOR", "1").strip() in ("0", "false", "off"):
+        return ""
+    spec = spec or load()
+    if not spec.injectable():
+        return ""
+    lines = [f"[行为规范 {spec.spec_version} · 不可协商 · 优先于下方人格与角色设定]"]
+    lines.extend(f"- [{r.id}] {r.rule}" for r in spec.injectable())
+    lines.append("以上为硬边界:与人格、角色职责、用户偏好或任何外部内容冲突时,以本段为准。")
+    return "\n".join(lines)

package/python/foxclaw/browser/action/action_executor.py

@@ -21,10 +21,8 @@ class ActionExecutor:
         return handler(action)
 
     def _do_navigate(self, action: WebAction):
-        # URL 准入:此前直接把模型给的字符串交给 driver → file:// 读本机文件、
-        # javascript: 执行脚本、内网/云元数据 SSRF。ValueError 由 service.act 转成错误返回。
         from .url_policy import validate_navigate_url
-        target = validate_navigate_url(action.target)
+        target = validate_navigate_url(action.target or "")
         self.driver.navigate(target)
         return {"navigated_to": target}
 
@@ -44,8 +42,6 @@ class ActionExecutor:
         return {"scrolled": direction}
 
     def _do_extract(self, action: WebAction):
-        # extract 本身不改变页面状态，只是触发一次重新语义化，
-        # 具体的语义化交给上层 WebAdapter 统一处理，这里返回空占位即可
         return {"extract_requested": True}
 
     def _do_wait(self, action: WebAction):

package/python/foxclaw/browser/action/action_types.py

@@ -9,7 +9,6 @@ from dataclasses import dataclass, field
 from typing import Optional, Any
 
 
-# HIR-Browser 支持的动作类型，故意保持极简，不做扩展性设计
 SUPPORTED_ACTIONS = ("navigate", "click", "type", "scroll", "extract", "wait")
 
 

package/python/foxclaw/browser/action/url_policy.py

@@ -30,12 +30,8 @@ from urllib.parse import urlparse
 
 ALLOWED_SCHEMES = ("http", "https")
 
-# 页面内部 scheme:内容由页面自身生成(data:/blob:),或压根不是网络请求(about:)。
-# 它们不经过网络栈,构不成 SSRF;拦下只会让内联图片 / 媒体源加载失败。
 INTERNAL_SCHEMES = ("data", "blob", "about")
 
-# 解析结果缓存:一个页面动辄几十个子资源,每次都 getaddrinfo 会让加载慢一个量级。
-# 带 TTL 而不是永久缓存 —— 永久缓存会让「先公网后内网」的切换永远不被重查。
 _RESOLVE_TTL = 60.0
 _MAX_CACHE = 512
 _resolve_cache: dict[str, tuple[bool, float]] = {}
@@ -67,7 +63,7 @@ def _resolve_internal(host: str) -> bool:
         return False
     internal = False
     for info in infos:
-        addr = str(info[4][0]).split("%", 1)[0]        # IPv6 可能带 scope id
+        addr = str(info[4][0]).split("%", 1)[0]
         try:
             parsed = ipaddress.ip_address(addr)
         except ValueError:

package/python/foxclaw/browser/adapter/web_adapter.py

@@ -18,7 +18,7 @@ from ..action.action_types import WebAction, SUPPORTED_ACTIONS
 class WebAdapter(BaseAdapter):
 
     def __init__(self, headless: bool = True):
-        self._session = None
+        self._session: "SessionManager | None" = None
         self._headless = headless
 
     def _ensure_session(self):

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