foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/cli.py

@@ -0,0 +1,183 @@
+"""命令行入口 `foxclaw`。
+
+与 PyPI 上 `foxclaw` 0.1.0 占位包发布的入口保持一致：包名 `foxclaw`,
+命令名 `foxclaw`。
+
+    foxclaw                # 打印版本与提示
+    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 进程
+自己先把整个应用栈加载一遍(含 HKC/HMR 与模型);`--reload` 时 uvicorn 也需要
+字符串目标才能重建子进程。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from foxclaw import __version__
+
+APP_TARGET = "foxclaw.api:app"
+
+
+def _repo_root() -> Path:
+    """仓库根目录(可编辑安装时即包含 foxclaw/ 的那一层)。"""
+    return Path(__file__).resolve().parents[1]
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    from foxclaw.core import settings
+
+    issues = settings.check()
+    fatal = settings.fatal_issues(issues)
+    if fatal:
+        print(settings.format_issues(issues), file=sys.stderr)
+        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
+
+    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
+
+
+def _cmd_config_check(args: argparse.Namespace) -> int:
+    from foxclaw.core import settings
+
+    issues = settings.check()
+    if args.json:
+        import json as _json
+        print(_json.dumps(
+            [{"level": i.level, "code": i.code, "name": i.name,
+              "message": i.message, "hint": i.hint} for i in issues],
+            ensure_ascii=False, indent=2))
+    else:
+        print(settings.format_issues(issues))
+    return 1 if any(i.level == "error" for i in issues) else 0
+
+
+def _cmd_config_show(args: argparse.Namespace) -> int:
+    from foxclaw.core import settings
+
+    current = ""
+    for opt in settings.SPECS:
+        if opt.group != current:
+            current = opt.group
+            print(f"[{current}]")
+        raw = os.environ.get(opt.name)
+        if raw is None or raw.strip() == "":
+            shown = f"{settings.mask(opt.default) if opt.secret else opt.default}" \
+                if opt.default not in ("", None) else "(未设置)"
+            suffix = "  默认"
+        else:
+            shown = settings.mask(raw) if (opt.secret and not args.reveal) else raw
+            suffix = "  已设置"
+        print(f"  {opt.name} = {shown}{suffix}")
+    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",
+        description="Foxclaw —— 认知 Agent 操作系统",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"foxclaw {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+
+    serve = subparsers.add_parser("serve", help="启动 API 服务")
+    serve.add_argument("--host", default="127.0.0.1", help="监听地址,默认仅本机回环")
+    serve.add_argument("--port", type=int, default=8000, help="监听端口,默认 8000")
+    serve.add_argument("--reload", action="store_true", help="改代码自动重启(开发用)")
+    serve.add_argument("--log-level", default="info", help="uvicorn 日志级别")
+    serve.set_defaults(handler=_cmd_serve)
+
+    config = subparsers.add_parser("config", help="查看/检查配置(.env 与环境变量)")
+    config_sub = config.add_subparsers(dest="config_action", metavar="<action>")
+
+    c_check = config_sub.add_parser(
+        "check", help="检查配置:类型、取值范围、拼错的键、互相矛盾的组合")
+    c_check.add_argument("--json", action="store_true", help="输出 JSON(便于脚本/前端消费)")
+    c_check.set_defaults(handler=_cmd_config_check)
+
+    c_show = config_sub.add_parser("show", help="打印当前生效配置")
+    c_show.add_argument("--reveal", action="store_true",
+                        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
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        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` 查看全部子命令。")
+        return 0
+    return int(handler(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/python/foxclaw/cognitive/__init__.py

@@ -0,0 +1,4 @@
+"""Foxclaw 认知层:认知状态快照等。"""
+from .state import CognitiveState, CognitiveStateTracker
+
+__all__ = ["CognitiveState", "CognitiveStateTracker"]

package/python/foxclaw/cognitive/reasoner.py

@@ -0,0 +1,81 @@
+"""
+DomainReasoner —— 领域认知化的推理骨架(v2 ③)。
+
+把领域裁决从"规则引擎"升级为显式的认知管线:
+    观察(observe) → 假设(hypothesize) → 收集证据(gather_evidence) → 裁决(arbitrate)
+
+**双层保留(铁律)**:规则永远是明确/硬约束情形的权威 + LLM/推理只增强模糊情形;
+每个裁决都带**证据链**(可审计);LLM 出错一律 **fail-safe**(转确认,呼应 P3 教训)。
+Step1 只做形式化:用现有规则实现本接口,裁决逐字不变、显式产出证据链。
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Evidence:
+    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}
+
+
+@dataclass
+class ReasonedVerdict:
+    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,
+                "source": self.source, "hypotheses": list(self.hypotheses),
+                "evidence": [e.to_dict() for e in self.evidence]}
+
+
+class DomainReasoner:
+    """领域推理器基座:reason() 串起四步。子类覆盖各步(默认空/放行)。"""
+
+    def observe(self, subject) -> dict:
+        return {}
+
+    def hypothesize(self, observation: dict) -> list:
+        return []
+
+    def gather_evidence(self, subject, observation: dict) -> list:
+        return []
+
+    def arbitrate(self, subject, observation: dict,
+                  hypotheses: list, evidence: list) -> ReasonedVerdict:
+        return ReasonedVerdict("approve", "无特殊裁决", evidence, hypotheses, "rules")
+
+    def reason(self, subject) -> ReasonedVerdict:
+        """观察 → 假设 → 收集证据 → 裁决。返回带证据链的 ReasonedVerdict。"""
+        obs = self.observe(subject)
+        hyps = self.hypothesize(obs)
+        ev = self.gather_evidence(subject, obs)
+        return self.arbitrate(subject, obs, hyps, ev)
+
+    @staticmethod
+    def llm_available(llm, enabled: bool) -> bool:
+        """LLM 是否真正可用:启用 + 非空 + 非 stub(无真实模型时视为不可用)。"""
+        return bool(enabled) and llm is not None and not getattr(llm, "is_stub", True)
+
+    @staticmethod
+    def llm_should_escalate(llm, system: str, user: str) -> bool:
+        """让 LLM 就"规则未发现硬问题、但情形微妙"的情况投票是否升级为人工确认。
+        **结构上只增强、不推翻**:只返回 True(建议 confirm)/False(维持规则裁决),
+        无从产生"推翻规则"的结果。出错/超时/响应不明 → False(维持规则裁决;
+        顾问域无治理闸口,不因 LLM 抖动制造确认噪声——与守门域 finance 的
+        error→confirm 区别正在于此)。"""
+        try:
+            resp = (llm.complete(system, [{"role": "user", "content": user}],
+                                 max_tokens=16) or "").upper()
+        except Exception:
+            return False
+        return "CONFIRM" in resp or "ESCALATE" in resp

package/python/foxclaw/cognitive/state.py

@@ -0,0 +1,141 @@
+"""
+认知状态 (CognitiveState)
+
+把"系统此刻在想什么"显式建模成一个可快照的认知状态。
+借鉴 Codex 版 Foxclaw 的 CognitiveState,适配本项目:不新存一份数据,而是
+作为聚合器 + 事件订阅者,把散落在调度器/进程/记忆/路由里的信号,聚成一张
+"系统当前心智状态"快照。
+
+对齐"认知操作系统"定位:OS 有 system state,认知 OS 该有 cognitive state。
+可驱动前端"系统在想什么"实时面板,也用于调试与回放。
+"""
+from __future__ import annotations
+
+from typing import Optional
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CognitiveState:
+    """系统当前认知状态快照。随事件总线上的活动自动更新。"""
+
+    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/注意力。"""
+        payload = payload or {}
+        task = payload.get("task", "")
+        self.active_goal = task[:120] if task else self.active_goal
+        self.active_agent = payload.get("agent_id") or self.active_agent
+        self.attention_scope = self._keywords(task)
+        sched = payload.get("schedule") or {}
+        if sched:
+            self.semantic_focus = sched.get("intent")
+            self.last_route = sched.get("route_hint")
+            self.confidence_map["priority"] = sched.get("priority", 0.0)
+        self.temporal_window = "current_turn"
+        self.updated_at = time.time()
+
+    def on_memory_updated(self, payload: dict):
+        """记忆更新事件 → 记录激活的记忆(去重,保留最近 5 条)。"""
+        payload = payload or {}
+        mu = payload.get("memory_update") or {}
+        content = mu.get("content")
+        if content:
+            snippet = content[:80]
+            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 = None):
+        """进程状态变更 → 更新活跃进程数。"""
+        if active_count is not None:
+            self.active_processes = active_count
+        self.updated_at = time.time()
+
+    @staticmethod
+    def _keywords(text: str, n: int = 6) -> list:
+        import re
+        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])
+                out.append(seg[-2:])
+        return out[:n]
+
+    def snapshot(self) -> dict:
+        return {
+            "active_goal": self.active_goal,
+            "active_agent": self.active_agent,
+            "semantic_focus": self.semantic_focus,
+            "attention_scope": list(self.attention_scope),
+            "reasoning_depth": self.reasoning_depth,
+            "confidence_map": dict(self.confidence_map),
+            "activated_memories": list(self.activated_memories),
+            "last_route": self.last_route,
+            "active_processes": self.active_processes,
+            "temporal_window": self.temporal_window,
+            "updated_at": self.updated_at,
+        }
+
+
+class CognitiveStateTracker:
+    """把 CognitiveState 接到事件总线 + 进程管理器,自动维护快照。"""
+
+    def __init__(self, bus, process_manager=None):
+        import threading
+        self.state = CognitiveState()
+        self.process_manager = process_manager
+        self._lock = threading.Lock()
+        if bus is not None:
+            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)
+
+    def _on_exec(self, msg):
+        if msg is None:
+            return
+        with self._lock:
+            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) or {})
+
+    def _on_proc(self, msg):
+        if msg is None:
+            return
+        active = None
+        pm = self.process_manager
+        if pm is not None:
+            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) or {}, active)
+
+    def snapshot(self) -> dict:
+        with self._lock:
+            return self.state.snapshot()

package/python/foxclaw/core/__init__.py

@@ -0,0 +1,9 @@
+"""Foxclaw — Core: 认知运行时核心数据结构"""
+from .thought_chain import (
+    ThoughtChain,
+    ThoughtNode,
+    NodeType,
+    HarnessStatus,
+)
+
+__all__ = ["ThoughtChain", "ThoughtNode", "NodeType", "HarnessStatus"]

package/python/foxclaw/core/audit_chain.py

@@ -0,0 +1,131 @@
+"""审计 JSONL 的哈希链:让「改一笔、删一笔」这类事后篡改可被检测。
+
+为什么需要
+──────────
+`{data_dir}/audit/*.jsonl` 是纯 append 的明文文件:谁能写这个文件,谁就能改历史
+(把 `allowed=false` 改成 `true`、删掉某次 deny)。审计的价值建立在「事后还能信」上,
+所以每行补两个字段:
+
+    prev_hash = 上一条的 hash(首条为 GENESIS)
+    hash      = sha256(canonical(除 hash 外的整行))
+
+`verify()` 逐行重算,任何一行被改(hash 不匹配)或被删(后继 prev_hash 断)都会暴露。
+
+适用边界(别高估它)
+──────────────────
+· 防**零散篡改**,不防「整文件重算链」——攻击者若能连改 N 行并重算全部 hash,链自洽。
+  真要防这个,得把 tail hash 锚到外部(另一台机器 / 时间戳服务);本机单进程场景
+  收益不抵复杂度。
+· 删**最后一条**检测不到:没有后继记录指向它。删中间、改任意行都能发现。
+· 老文件(该行无 hash 字段)按 legacy 段跳过校验,不会因为历史数据报错;
+  一旦出现过 hash,后面的行就必须接上。
+· 链是**单进程假设**(与两个 sink 的锁一致)。多进程各自 append 会让 prev_hash 冲突,
+  表现为 verify 报链断——部署上应避免同目录多进程写审计。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+GENESIS = "0" * 64
+
+_TAIL_WINDOW = 65536
+
+
+def _canonical(rec: dict) -> bytes:
+    """稳定序列化:sort_keys + 紧凑分隔符,保证跨进程/跨版本重算一致。"""
+    return json.dumps(rec, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False, default=str).encode("utf-8")
+
+
+def link(rec: dict, prev_hash: str = GENESIS) -> dict:
+    """给一行记录接上链,返回**新** dict(不改入参,便于调用方继续用原始 rec)。"""
+    body = dict(rec)
+    body["prev_hash"] = prev_hash
+    body["hash"] = hashlib.sha256(_canonical(body)).hexdigest()
+    return body
+
+
+def tail_hash(path) -> str:
+    """读文件最后一条带 hash 的记录的 hash;不存在/空/无链 → GENESIS。
+
+    倒着找而不是顺着读:审计文件可能很长,重启续链只需要最后一行;
+    尾部若有写一半的残行(进程被杀),跳过继续往前找。
+    """
+    p = Path(path)
+    try:
+        with open(p, "rb") as f:
+            f.seek(0, 2)
+            size = f.tell()
+            f.seek(max(0, size - _TAIL_WINDOW))
+            chunk = f.read().decode("utf-8", "replace")
+    except OSError:
+        return GENESIS
+    for line in reversed(chunk.splitlines()):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except Exception:
+            continue
+        h = rec.get("hash")
+        if isinstance(h, str) and h:
+            return h
+    return GENESIS
+
+
+def verify(path) -> tuple:
+    """校验整条链 → (ok, 已校验条数, 问题描述)。
+
+    问题描述为空串表示通过;不通过时给出「第几行 + 断在哪」,便于人工定位。
+    """
+    p = Path(path)
+    if not p.exists():
+        return True, 0, ""
+    prev = GENESIS
+    n = 0
+    try:
+        with open(p, encoding="utf-8") as f:
+            for i, line in enumerate(f, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                except Exception:
+                    return False, n, f"第 {i} 行不是合法 JSON"
+                h = rec.get("hash")
+                if not h:
+                    continue
+                if rec.get("prev_hash") != prev:
+                    return False, n, (f"第 {i} 行链断:prev_hash 与上一条 hash 不符"
+                                      "(中间记录被删或被挪动)")
+                body = {k: v for k, v in rec.items() if k != "hash"}
+                if hashlib.sha256(_canonical(body)).hexdigest() != h:
+                    return False, n, f"第 {i} 行内容被改(hash 不匹配)"
+                prev = h
+                n += 1
+    except OSError as e:
+        return False, n, f"读取失败: {e}"
+    return True, n, ""
+
+
+def _main(argv: list) -> int:
+    if not argv:
+        print("用法: python -m foxclaw.core.audit_chain <audit.jsonl> [...]")
+        return 2
+    bad = 0
+    for p in argv:
+        ok, n, msg = verify(p)
+        print(f"{p}: {'OK' if ok else 'BROKEN'} ({n} 条)" + (f" - {msg}" if msg else ""))
+        if not ok:
+            bad = 1
+    return bad
+
+
+if __name__ == "__main__":
+    import sys
+
+    raise SystemExit(_main(sys.argv[1:]))

package/python/foxclaw/core/audit_sink.py

@@ -0,0 +1,100 @@
+"""
+共享层写入审计落盘 sink —— P0-3 配套
+
+为什么必须落盘
+──────────────
+EventSpine._history 是 deque(maxlen=1000) 的**进程内环形缓冲**,且全系统事件共享:
+高频事件(agent.cognition.* / knowledge.created)会很快把 memory.shared.write 冲掉,
+进程退出即全丢。而 P0-3 切 enforce 的判据恰恰是「真实流量中有没有**合法的**写入被拒」
+—— 没有落盘,这个样本永远积累不起来(总不能让人蹲守 /api/bus/history),策略表就
+只能停在「自洽的假设」上,灰度推进(audit→warn→enforce)没有事实依据。
+
+行为
+────
+订阅 EventSpine 的 memory.shared.write 主题,逐条 JSON 追加到:
+  {data_dir}/audit/shared_write.jsonl
+每行:{"ts": ISO 时间, "topic": ..., "correlation_id": ..., "payload": {原始审计字段}}
+payload 即 guard_shared_write 发布的全部字段(agent_id/type/tags/allowed/reason/mode/
+content_sha/content_preview)——正文只留 60 字符预览 + 16 位哈希,不落敏感全文。
+
+写入失败一律静默吞掉 —— **审计绝不影响写入主流程**(与 guard_shared_write 同一设计约束)。
+
+开关:FOXCLAW_SHARED_WRITE_AUDIT=0 关闭(默认开;每条 <300 字节,量级可忽略)。
+判读:用 read() 或直接看文件 —— allowed=false 的每一行都要逐条判读
+(是真越界,还是策略表误伤),全部为真越界且无一条误伤,方可切 enforce。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from datetime import datetime
+from pathlib import Path
+
+from . import audit_chain
+
+ENV_SWITCH = "FOXCLAW_SHARED_WRITE_AUDIT"
+AUDIT_DIR = "audit"
+AUDIT_FILE = "shared_write.jsonl"
+
+
+class SharedWriteAuditSink:
+    """把 memory.shared.write 审计事件追加落盘。
+
+    线程安全:EventSpine 的 handler 在发布线程、锁外被调用(脊柱只锁快照),
+    并发写入同一文件必须串行 —— 用进程内锁。多进程部署(FOXCLAW_ALLOW_INSECURE
+    反对但允许)各自 append 行,JSONL 每行自包含,不会互相破坏。
+    """
+
+    def __init__(self, path: Path):
+        self.path = Path(path)
+        self._lock = threading.Lock()
+        self._last_hash: str | None = None
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def __call__(self, evt):
+        try:
+            rec = {
+                "ts": datetime.now().isoformat(timespec="seconds"),
+                "topic": evt.topic,
+                "correlation_id": getattr(evt, "correlation_id", ""),
+                "payload": evt.payload,
+            }
+            with self._lock:
+                if self._last_hash is None:
+                    self._last_hash = audit_chain.tail_hash(self.path)
+                rec = audit_chain.link(rec, self._last_hash)
+                with open(self.path, "a", encoding="utf-8") as f:
+                    f.write(json.dumps(rec, ensure_ascii=False, default=str) + "\n")
+                self._last_hash = rec["hash"]
+        except Exception:
+            pass
+
+    def read(self, limit: int = 200) -> list:
+        """读最近 limit 条(供诊断/工具用)。坏行跳过 —— 落盘绝不该反过来卡死读取。"""
+        try:
+            with open(self.path, encoding="utf-8") as f:
+                lines = f.readlines()
+        except OSError:
+            return []
+        out = []
+        for ln in lines[-limit:]:
+            try:
+                out.append(json.loads(ln))
+            except Exception:
+                continue
+        return out
+
+    def verify(self) -> tuple:
+        """校验落盘链 → (ok, 条数, 问题)。"""
+        return audit_chain.verify(self.path)
+
+
+def attach(spine, data_dir):
+    """把 sink 挂到脊柱,返回 sink 实例;FOXCLAW_SHARED_WRITE_AUDIT=0 时不挂(返回 None)。"""
+    if str(os.environ.get(ENV_SWITCH, "")).strip() == "0":
+        return None
+    sink = SharedWriteAuditSink(Path(data_dir) / AUDIT_DIR / AUDIT_FILE)
+    spine.subscribe("memory.shared.write", sink)
+    return sink