foxclaw 0.1.2 → 0.1.3

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:

package/python/foxclaw/cli.py

@@ -7,6 +7,8 @@
     foxclaw serve          # 启动 API 服务(默认 http://127.0.0.1:8000)
     foxclaw config check   # 检查 .env / 环境变量:类型写错、拼错的键、互相矛盾的组合
     foxclaw config show     # 打印当前生效配置(密钥默认脱敏)
+    foxclaw skills install @owner/slug   # 装 SKILL.md 技能(ClawHub/GitHub/URL/本地包)
+    foxclaw skills list                  # 列出已装技能
     foxclaw --version      # 打印版本
 
 `serve` 用字符串目标 `foxclaw.api:app` 交给 uvicorn 导入,避免 CLI 进程
@@ -34,8 +36,6 @@ def _repo_root() -> Path:
 def _cmd_serve(args: argparse.Namespace) -> int:
     from foxclaw.core import settings
 
-    # 启动前先查配置:类型写错的值今天会崩在很远的地方(uvicorn 40 行 traceback 中间的
-    # `int()`),用户看不出是自己 .env 写错了。这里提前拦下并说清怎么改。
     issues = settings.check()
     fatal = settings.fatal_issues(issues)
     if fatal:
@@ -43,22 +43,19 @@ def _cmd_serve(args: argparse.Namespace) -> int:
         print("\n以上配置会让启动直接失败,已中止。改好后重试。", file=sys.stderr)
         return 2
     if issues:
-        # 不影响启动的问题(可疑但能跑)只提醒一次,不拦
         print(settings.format_issues(issues, limit=8), file=sys.stderr)
         print("(以上不阻断启动;`foxclaw config check` 看完整诊断)", file=sys.stderr)
 
     import uvicorn
 
-    kwargs: dict[str, object] = {
-        "host": args.host,
-        "port": args.port,
-        "log_level": args.log_level,
-    }
-    if args.reload:
-        # 只监听源码目录,避免 vendor/ 与测试临时文件触发重启
-        kwargs["reload"] = True
-        kwargs["reload_dirs"] = [str(_repo_root() / "foxclaw")]
-    uvicorn.run(APP_TARGET, **kwargs)
+    uvicorn.run(
+        APP_TARGET,
+        host=args.host,
+        port=args.port,
+        log_level=args.log_level,
+        reload=bool(args.reload),
+        reload_dirs=[str(_repo_root() / "foxclaw")] if args.reload else None,
+    )
     return 0
 
 
@@ -97,6 +94,12 @@ def _cmd_config_show(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_skills(args: argparse.Namespace) -> int:
+    from foxclaw.skills.install_cmd import run
+
+    return run(args)
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="foxclaw",
@@ -131,6 +134,28 @@ def build_parser() -> argparse.ArgumentParser:
                         help="显示密钥原文(默认脱敏;别在截图/日志里用)")
     c_show.set_defaults(handler=_cmd_config_show)
 
+    skills = subparsers.add_parser("skills", help="安装/查看/卸载指令技能(SKILL.md)")
+    skills_sub = skills.add_subparsers(dest="skills_action", metavar="<action>")
+
+    s_install = skills_sub.add_parser("install", help="从 ClawHub/GitHub/URL/本地包装一个技能")
+    s_install.add_argument(
+        "ref",
+        help="@owner/slug(ClawHub) | github:owner/repo[/子路径][@ref] | "
+             "http(s)://包地址 | 本地 .zip/.tar.gz/SKILL.md/目录")
+    s_install.add_argument("--yes", action="store_true",
+                           help="跳过确认(脚本/CI 必填;非终端环境没有它一定失败)")
+    s_install.add_argument("--id", default="", help="覆盖技能 id(默认取 SKILL.md 里的 name)")
+    s_install.add_argument("--json", action="store_true", help="输出 JSON")
+    s_install.set_defaults(handler=_cmd_skills)
+
+    s_list = skills_sub.add_parser("list", help="列出已安装的指令技能")
+    s_list.add_argument("--json", action="store_true", help="输出 JSON")
+    s_list.set_defaults(handler=_cmd_skills)
+
+    s_remove = skills_sub.add_parser("remove", help="卸载一个指令技能")
+    s_remove.add_argument("id", help="技能 id(`foxclaw skills list` 第一列)")
+    s_remove.set_defaults(handler=_cmd_skills)
+
     return parser
 
 
@@ -143,6 +168,10 @@ def main(argv: list[str] | None = None) -> int:
         if getattr(args, "command", None) == "config":
             print("用法:`foxclaw config check` 或 `foxclaw config show`")
             return 2
+        if getattr(args, "command", None) == "skills":
+            print("用法:`foxclaw skills install <ref>` / `foxclaw skills list` / "
+                  "`foxclaw skills remove <id>`")
+            return 2
         print(f"foxclaw {__version__}")
         print("用 `foxclaw serve` 启动本地服务;`foxclaw config check` 检查配置;"
               "`foxclaw --help` 查看全部子命令。")

package/python/foxclaw/cognitive/reasoner.py

@@ -15,10 +15,10 @@ from typing import Any
 
 @dataclass
 class Evidence:
-    factor: str                 # 证据因子(如规则 id / 历史频率 / 预算余量)
-    detail: str = ""            # 具体说明
-    weight: float = 1.0         # 权重(0~1)
-    raw: Any = None             # 原始证据对象(如 PolicyVerdict),供裁决内部使用
+    factor: str
+    detail: str = ""
+    weight: float = 1.0
+    raw: Any = None
 
     def to_dict(self) -> dict:
         return {"factor": self.factor, "detail": self.detail, "weight": self.weight}
@@ -26,11 +26,11 @@ class Evidence:
 
 @dataclass
 class ReasonedVerdict:
-    decision: str               # approve | confirm | reject
-    rationale: str              # 裁决说明(人类可读)
-    evidence: list = field(default_factory=list)      # [Evidence]
-    hypotheses: list = field(default_factory=list)    # [str]
-    source: str = "rules"       # rules | llm(哪层做出的裁决)
+    decision: str
+    rationale: str
+    evidence: list = field(default_factory=list)
+    hypotheses: list = field(default_factory=list)
+    source: str = "rules"
 
     def to_dict(self) -> dict:
         return {"decision": self.decision, "rationale": self.rationale,
@@ -61,7 +61,6 @@ class DomainReasoner:
         ev = self.gather_evidence(subject, obs)
         return self.arbitrate(subject, obs, hyps, ev)
 
-    # ── 双层增强的通用工具(v2 ③ Step4:itinerary/learning 复用)────────────
     @staticmethod
     def llm_available(llm, enabled: bool) -> bool:
         """LLM 是否真正可用:启用 + 非空 + 非 stub(无真实模型时视为不可用)。"""

package/python/foxclaw/cognitive/state.py

@@ -10,6 +10,8 @@
 可驱动前端"系统在想什么"实时面板,也用于调试与回放。
 """
 from __future__ import annotations
+
+from typing import Optional
 import time
 from dataclasses import dataclass, field
 
@@ -18,19 +20,18 @@ from dataclasses import dataclass, field
 class CognitiveState:
     """系统当前认知状态快照。随事件总线上的活动自动更新。"""
 
-    active_goal: str = None                          # 当前活跃目标(最近任务)
-    active_agent: str = None                         # 当前处理的 Agent
-    semantic_focus: str = None                       # 语义焦点(调度意图类别)
-    attention_scope: list = field(default_factory=list)   # 注意力范围(关键词)
-    reasoning_depth: float = 0.0                     # 当前推理深度
-    confidence_map: dict = field(default_factory=dict)    # 置信度图(意图/优先级)
-    activated_memories: list = field(default_factory=list)  # 激活的记忆(最近召回/沉淀)
-    last_route: str = None                           # 最近路由倾向
-    active_processes: int = 0                         # 活跃进程数
-    temporal_window: str = "current_turn"            # 时间窗口
+    active_goal: Optional[str] = None
+    active_agent: Optional[str] = None
+    semantic_focus: Optional[str] = None
+    attention_scope: list = field(default_factory=list)
+    reasoning_depth: float = 0.0
+    confidence_map: dict = field(default_factory=dict)
+    activated_memories: list = field(default_factory=list)
+    last_route: Optional[str] = None
+    active_processes: int = 0
+    temporal_window: str = "current_turn"
     updated_at: float = field(default_factory=time.time)
 
-    # ── 信号摄入(由事件驱动)──
 
     def on_execution(self, payload: dict):
         """执行事件 → 更新目标/Agent/注意力。"""
@@ -54,13 +55,12 @@ class CognitiveState:
         content = mu.get("content")
         if content:
             snippet = content[:80]
-            # 去重:已存在则先移除旧的,再插到最前(LRU 式)
             existing = [m for m in self.activated_memories if m != snippet]
             self.activated_memories = [snippet] + existing[:4]
             self.temporal_window = "memory_augmented"
         self.updated_at = time.time()
 
-    def on_process_change(self, payload: dict, active_count: int = None):
+    def on_process_change(self, payload: dict, active_count: int | None = None):
         """进程状态变更 → 更新活跃进程数。"""
         if active_count is not None:
             self.active_processes = active_count
@@ -69,14 +69,12 @@ class CognitiveState:
     @staticmethod
     def _keywords(text: str, n: int = 6) -> list:
         import re
-        # 先按标点/空格切;若切出的片段仍很长(中文无空格),按 2-4 字滑窗取要点
         rough = [w for w in re.split(r"[\s,，、。!?:;]", text or "") if len(w) >= 2]
         out = []
         for seg in rough:
             if len(seg) <= 4:
                 out.append(seg)
             else:
-                # 长片段取首尾 + 中部双字,作为注意力要点
                 out.append(seg[:3])
                 if len(seg) > 6:
                     out.append(seg[len(seg)//2:len(seg)//2+2])
@@ -106,25 +104,23 @@ class CognitiveStateTracker:
         import threading
         self.state = CognitiveState()
         self.process_manager = process_manager
-        self._lock = threading.Lock()   # 事件可能跨线程触发,保护状态更新
+        self._lock = threading.Lock()
         if bus is not None:
-            # 【P4-1】前两个是精确 channel 名 → exact=True;task.lifecycle 是刻意的前缀
-            # 订阅(收 created/queued/running/... 一族),保持默认前缀匹配。
             bus.subscribe("execution.completed", self._on_exec, exact=True)
             bus.subscribe("memory.updated", self._on_mem, exact=True)
-            bus.subscribe("task.lifecycle", self._on_proc)   # Step3:统一生命周期词汇(前缀匹配)
+            bus.subscribe("task.lifecycle", self._on_proc)
 
     def _on_exec(self, msg):
         if msg is None:
             return
         with self._lock:
-            self.state.on_execution(getattr(msg, "payload", None))
+            self.state.on_execution(getattr(msg, "payload", None) or {})
 
     def _on_mem(self, msg):
         if msg is None:
             return
         with self._lock:
-            self.state.on_memory_updated(getattr(msg, "payload", None))
+            self.state.on_memory_updated(getattr(msg, "payload", None) or {})
 
     def _on_proc(self, msg):
         if msg is None:
@@ -132,15 +128,13 @@ class CognitiveStateTracker:
         active = None
         pm = self.process_manager
         if pm is not None:
-            # 【深审优化】用 pm 的 O(1) active_count(),免去每次 lifecycle 事件 stats() 遍历
-            # 全部进程(O(n))。旧 pm 无此方法则回退到 stats()(scheduled+running)。
             if hasattr(pm, "active_count"):
                 active = pm.active_count()
             else:
                 st = pm.stats().get("by_state", {})
                 active = st.get("scheduled", 0) + st.get("running", 0)
         with self._lock:
-            self.state.on_process_change(getattr(msg, "payload", None), active)
+            self.state.on_process_change(getattr(msg, "payload", None) or {}, active)
 
     def snapshot(self) -> dict:
         with self._lock:

package/python/foxclaw/core/audit_chain.py

@@ -28,10 +28,8 @@ import hashlib
 import json
 from pathlib import Path
 
-#: 首条记录的 prev_hash。用 64 个 0 而不是空串:一眼能看出「这是链头」。
 GENESIS = "0" * 64
 
-#: 从文件尾部回读的字节数:找 tail hash 只需最后一行,64KB 足够容下超长记录。
 _TAIL_WINDOW = 65536
 
 
@@ -100,7 +98,7 @@ def verify(path) -> tuple:
                     return False, n, f"第 {i} 行不是合法 JSON"
                 h = rec.get("hash")
                 if not h:
-                    continue                      # legacy 段:无链可验,跳过
+                    continue
                 if rec.get("prev_hash") != prev:
                     return False, n, (f"第 {i} 行链断:prev_hash 与上一条 hash 不符"
                                       "(中间记录被删或被挪动)")

package/python/foxclaw/core/audit_sink.py

@@ -50,10 +50,10 @@ class SharedWriteAuditSink:
     def __init__(self, path: Path):
         self.path = Path(path)
         self._lock = threading.Lock()
-        self._last_hash: str | None = None    # 链尾,首次写时从文件尾部补齐
+        self._last_hash: str | None = None
         self.path.parent.mkdir(parents=True, exist_ok=True)
 
-    def __call__(self, evt):  # EventSpine.subscribe 的 handler 形态:handler(event)
+    def __call__(self, evt):
         try:
             rec = {
                 "ts": datetime.now().isoformat(timespec="seconds"),
@@ -69,7 +69,7 @@ class SharedWriteAuditSink:
                     f.write(json.dumps(rec, ensure_ascii=False, default=str) + "\n")
                 self._last_hash = rec["hash"]
         except Exception:
-            pass  # 审计失败绝不影响写入主流程
+            pass
 
     def read(self, limit: int = 200) -> list:
         """读最近 limit 条(供诊断/工具用)。坏行跳过 —— 落盘绝不该反过来卡死读取。"""