foxclaw 0.1.0 → 0.1.2

package/python/tests/test_api.py

@@ -0,0 +1,87 @@
+"""
+用 FastAPI TestClient 在同进程内验证 API 端点。
+绕过沙箱对后台进程/loopback 的限制,直接走 ASGI。
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import os
+import tempfile
+import json
+from fastapi.testclient import TestClient
+
+
+def show(title, data, limit=None):
+    print(f"\n【{title}】")
+    s = json.dumps(data, ensure_ascii=False, indent=2)
+    if limit:
+        s = "\n".join(s.splitlines()[:limit])
+    print(s)
+
+
+def test_api():
+    # 环境变量须在 import foxclaw.api 前设好(模块加载时按环境变量建网关/agent)
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_test_")  # 不污染仓库根
+    from foxclaw.api import app
+
+    with TestClient(app) as c:
+        print("="*64)
+        print("FOXCLAW · API 端到端验证 (ASGI TestClient)")
+        print("="*64)
+
+        # 1. 系统状态
+        r = c.get("/api/status")
+        print(f"\n[GET /api/status] HTTP {r.status_code}")
+        data = r.json()
+        for aid, s in data.items():
+            tc = s["thought_chain"]
+            print(f"  {aid:<12} 节点={tc['total_nodes']:<3} shadow={s['harness']['shadow_mode']}")
+
+        # 2. 发任务(真实经过 ThoughtChain + Harness)
+        print("\n[POST /api/task] 连发 7 个财务任务触发校准")
+        for i, t in enumerate(["分析支出","制定预算","评估风险","季度报告","追踪消费","明年规划","同期对比"], 1):
+            r = c.post("/api/task", json={"task": t, "agent_id": "finance"})
+            d = r.json()
+            err = d.get("error", "ok")
+            print(f"  [{i}] {t} → HTTP {r.status_code} · {err}")
+
+        # 3. Harness 状态(校准后)
+        r = c.get("/api/harness/finance/status")
+        show("GET /api/harness/finance/status", r.json())
+
+        # 4. 推理链
+        r = c.get("/api/thoughtchain/finance/chain")
+        nodes = r.json()["nodes"]
+        print(f"\n[GET /api/thoughtchain/finance/chain] HTTP {r.status_code} · {len(nodes)} 节点")
+        for n in nodes[-5:]:
+            print(f"  {n['type']:<16} {n['harness_status']:<9} "
+                  f"conf={n['conf']:.2f} Δ={n.get('harness_delta') or 0:.3f}")
+
+        # 5. 漂移趋势
+        r = c.get("/api/thoughtchain/finance/trend?limit=10")
+        trend = r.json()["trend"]
+        print(f"\n[GET .../trend] {len(trend)} 数据点 · Δ 序列:")
+        print("  " + " ".join(f"{t['delta']:.2f}" for t in trend[:10]))
+
+        # 6. Policy
+        r = c.get("/api/harness/finance/policy")
+        pol = r.json()
+        print(f"\n[GET /api/harness/finance/policy] v{pol['version']} · "
+              f"{len(pol.get('rules',[]))} 规则")
+
+        # 7. 偏好管理端点(F3):GET 列出结构;DELETE 不存在 id 优雅返回 ok=False(不崩)
+        r = c.get("/api/preferences")
+        assert r.status_code == 200 and "preferences" in r.json(), r.text
+        r = c.delete("/api/preferences/nonexistent_id")
+        assert r.status_code == 200 and r.json().get("ok") is False, r.text
+        print("\n[GET/DELETE /api/preferences] 列出+删除通路 ok")
+
+        print("\n" + "="*64)
+        print("✓ API 端到端验证完成 · 所有端点返回真实数据")
+        print("="*64)
+
+
+if __name__ == "__main__":
+    test_api()

package/python/tests/test_api_auth.py

@@ -0,0 +1,83 @@
+"""
+API 可选鉴权回归
+
+验证 FOXCLAW_API_KEY:
+  · 未设 → /api/* 开放(本地默认,既有行为不变);
+  · 设了 → /api/* 与 /ws/* 需带正确 X-API-Key,否则 401;前端与 /docs 始终开放。
+中间件每请求读环境变量,故可在同一 TestClient 内切换验证。
+"""
+import os
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+# 本测试要精确控制 FOXCLAW_API_KEY 的有/无;若 .env 带真实 key 会污染判定
+# (见 foxclaw/api.py 中 FOXCLAW_SKIP_DOTENV 的说明),故关掉 .env。
+os.environ["FOXCLAW_SKIP_DOTENV"] = "1"
+
+import tempfile
+os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_test_")  # 不污染仓库根
+from fastapi.testclient import TestClient
+from foxclaw.api import app
+
+
+def check(cond, msg):
+    if not cond:
+        raise AssertionError(f"✗ {msg}")
+    print(f"  ✓ {msg}")
+
+
+def main():
+    print("=" * 56)
+    print("API 可选鉴权回归")
+    print("=" * 56)
+    os.environ.pop("FOXCLAW_API_KEY", None)
+    with TestClient(app) as c:
+        print("\n【1】未设 FOXCLAW_API_KEY:开放(本地默认)")
+        check(c.get("/api/status").status_code == 200, "/api/status 开放(200)")
+
+        print("\n【2】设了 FOXCLAW_API_KEY:/api/* 受保护")
+        os.environ["FOXCLAW_API_KEY"] = "secret-123"
+        check(c.get("/api/status").status_code == 401, "无 X-API-Key → 401")
+        check(c.get("/api/status", headers={"X-API-Key": "wrong"}).status_code == 401,
+              "错误 key → 401")
+        check(c.get("/api/status", headers={"X-API-Key": "secret-123"}).status_code == 200,
+              "正确 key → 200")
+
+        print("\n【3】WebSocket 鉴权(端点内 ?key=,http 中间件管不到 ws)")
+        # 无 key → 握手被拒(端点 close 1008)
+        rejected = False
+        try:
+            with c.websocket_connect("/ws/harness"):
+                pass
+        except Exception:
+            rejected = True
+        check(rejected, "WS 无 key → 握手被拒")
+        # 带 ?key= → 连上
+        connected = False
+        try:
+            with c.websocket_connect("/ws/harness?key=secret-123"):
+                connected = True
+        except Exception:
+            connected = False
+        check(connected, "WS 带正确 ?key= → 连上")
+
+        print("\n【4】开鉴权时前端 / 文档仍开放")
+        check(c.get("/docs").status_code == 200, "/docs 无需 key(200)")
+        r_root = c.get("/")
+        check(r_root.status_code in (200, 404), f"/ 非 401(前端不被 key 挡, {r_root.status_code})")
+
+        print("\n【5】撤销 key → 恢复开放")
+        os.environ.pop("FOXCLAW_API_KEY", None)
+        check(c.get("/api/status").status_code == 200, "撤 key 后 /api/status 恢复开放")
+
+    print("\n" + "=" * 56)
+    print("API 鉴权回归通过")
+    print("=" * 56)
+
+
+def test_api_auth():
+    main()
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_api_host_guard.py

@@ -0,0 +1,69 @@
+"""API 层 Host 头校验(DNS rebinding 防护)。
+
+攻击模型:本机 `foxclaw serve`(回环监听、无 API key)时,用户被诱导打开 evil.com;
+evil.com 解析到 127.0.0.1,页面内 fetch 打本机 /api/*,同源成立 → 可读写本地数据面。
+防线是校验 Host 头:浏览器发请求时 Host 必须与被访问域名一致,DNS 改解析也绕不过。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+
+from foxclaw.api.middleware import _api_key_guard, _host_header_allowed
+
+
+@pytest.mark.parametrize("host", [
+    "127.0.0.1:8000", "localhost:8000", "localhost", "TESTCLIENT",
+    "[::1]:8000", "192.168.1.9:8000", "10.0.0.2", "mypc", "",
+])
+def test_allows_local_and_lan_hosts(host: str) -> None:
+    assert _host_header_allowed(host) is True
+
+
+@pytest.mark.parametrize("host", [
+    "evil.com", "attacker.example.org:8000", "sub.evil.com:80",
+])
+def test_rejects_public_domain_hosts(host: str) -> None:
+    assert _host_header_allowed(host) is False
+
+
+def test_allowlist_escape_hatch(monkeypatch) -> None:
+    monkeypatch.setenv("FOXCLAW_ALLOWED_HOSTS", "my.host.net, *.corp.example")
+    assert _host_header_allowed("my.host.net") is True
+    assert _host_header_allowed("a.corp.example") is True
+    assert _host_header_allowed("evil.com") is False
+
+
+def _request(path: str, host: str, client: str = "127.0.0.1"):
+    return SimpleNamespace(
+        url=SimpleNamespace(path=path),
+        client=SimpleNamespace(host=client),
+        headers={"host": host, "X-API-Key": ""},
+        method="GET",
+    )
+
+
+async def _ok(_request):
+    return SimpleNamespace(status_code=200)
+
+
+@pytest.mark.parametrize("path", ["/api/task", "/knowledge/ingest", "/config/llm"])
+def test_loopback_with_public_host_is_forbidden(path: str, monkeypatch) -> None:
+    monkeypatch.delenv("FOXCLAW_API_KEY", raising=False)
+    resp = asyncio.run(_api_key_guard(_request(path, "evil.com"), _ok))
+    assert resp.status_code == 403, "本机客户端 + 公网域名 Host 必须拒绝"
+
+
+def test_loopback_with_local_host_passes(monkeypatch) -> None:
+    monkeypatch.delenv("FOXCLAW_API_KEY", raising=False)
+    resp = asyncio.run(_api_key_guard(_request("/api/task", "127.0.0.1:8000"), _ok))
+    assert resp.status_code == 200
+
+
+def test_probe_paths_not_affected(monkeypatch) -> None:
+    monkeypatch.delenv("FOXCLAW_API_KEY", raising=False)
+    resp = asyncio.run(_api_key_guard(_request("/health", "evil.com"), _ok))
+    assert resp.status_code == 200, "探针不在数据面防护范围"

package/python/tests/test_attachments.py

@@ -0,0 +1,167 @@
+"""聊天附件(多模态渲染·步骤7)回归测试:文件上传/下载、正文提取、护栏、LLM 上下文注入、会话落盘。
+
+全离线:锁 stub 模型 + stub 嵌入 + 临时数据目录,不碰真实 API / 不加载真实向量模型。
+与 test_multimodal.py(图片通道)互补:这里覆盖「文件」通道(图片走 images base64,不经过附件)。
+"""
+import os, sys, tempfile, shutil
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+# ── 环境隔离:必须在 import foxclaw 之前(import 会读这些键初始化) ─────────────
+for _k in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "DEEPSEEK_API_KEY",
+           "GOOGLE_API_KEY", "DASHSCOPE_API_KEY", "FOXCLAW_API_KEY"):
+    os.environ.pop(_k, None)
+os.environ["HKC_EMBEDDING"] = "stub"
+os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_att_")
+os.environ["FOXCLAW_SKIP_DOTENV"] = "1"
+os.environ["FOXCLAW_PROVIDER"] = ""      # 不指定 provider → 无 key 时降级 stub(确定性)
+os.environ["FOXCLAW_MODEL"] = ""
+os.environ["FOXCLAW_MCP_SERVER"] = "0"
+os.environ["HF_HUB_OFFLINE"] = "1"      # 离线:HMR embedding 读本地缓存,不联网
+os.environ["TRANSFORMERS_OFFLINE"] = "1"
+
+import pytest
+from fastapi.testclient import TestClient
+
+from foxclaw.api import app, _sanitize_attachments
+from foxclaw.api.routes.task import _MAX_ATTACHMENTS, _ATTACH_TEXT_MAX, _ATTACH_TEXT_TOTAL
+from foxclaw.agents.base import CognitiveAgent
+from foxclaw.core.sessions import SessionStore
+
+
+@pytest.fixture()
+def store():
+    d = tempfile.mkdtemp(prefix="att_sess_")
+    try:
+        yield SessionStore(Path(d) / "sessions")
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_sanitize_attachments():
+    # 数量上限
+    many = [{"name": f"f{i}.txt", "text": "t"} for i in range(_MAX_ATTACHMENTS + 4)]
+    assert len(_sanitize_attachments(many)) == _MAX_ATTACHMENTS
+
+    # 单文件正文截断到上限
+    one = _sanitize_attachments([{"name": "a.txt", "text": "x" * (_ATTACH_TEXT_MAX + 100)}])
+    assert len(one[0]["text"]) == _ATTACH_TEXT_MAX
+
+    # name 截断到 200
+    assert _sanitize_attachments([{"name": "a" * 300, "text": "x"}])[0]["name"] == "a" * 200
+
+    # 累计正文封顶:单文件先截到 20000,4×20000 累计 60000 封顶 → 第 4 个正文被清空(名字仍在)
+    big = "x" * (_ATTACH_TEXT_MAX + 1000)
+    four = _sanitize_attachments([{"name": f"f{i}.txt", "text": big} for i in range(4)])
+    assert len(four) == 4
+    assert sum(len(a["text"]) for a in four) == _ATTACH_TEXT_TOTAL
+    assert four[3]["text"] == ""
+
+    # 非列表 / 非 dict / 空 name+空 text → 全部剔除
+    assert _sanitize_attachments("notalist") == []
+    assert _sanitize_attachments([1, "x"]) == []
+    assert _sanitize_attachments([{"name": "", "text": ""}]) == []
+    assert _sanitize_attachments(None) == []
+
+    # 字段类型清洗:size 非数字 → 0;mime/url 转 str
+    out = _sanitize_attachments([{"name": "a", "size": "big", "mime": None, "url": None, "text": "t"}])
+    assert out[0]["size"] == 0 and out[0]["mime"] == "" and out[0]["url"] == ""
+    print("护栏(数量/单文件/累计/类型清洗/边界)OK")
+
+
+def test_attachments_context():
+    atts = [
+        {"name": "a.txt", "size": 11, "mime": "text/plain", "url": "", "text": "hello world"},
+        {"name": "b.pdf", "size": 999, "mime": "application/pdf", "url": "", "text": ""},
+    ]
+    ctx = CognitiveAgent._attachments_context(atts)
+    assert "【附件「a.txt」内容如下】" in ctx and "hello world" in ctx
+    assert "【附件「b.txt」" not in ctx
+    assert "b.pdf" in ctx and "无法提取" in ctx   # 非文本降级为「文件名 + 元数据」提示
+    assert CognitiveAgent._attachments_context([]) == ""
+    assert CognitiveAgent._attachments_context(None) == ""
+    assert CognitiveAgent._attachments_context([1, "x"]) == ""   # 非 dict 全跳过
+    print("LLM 上下文注入(正文/降级/空)OK")
+
+
+def test_sessions_append_attachments(store):
+    s = store.create()
+    atts = [
+        {"name": "a.txt", "size": 11, "mime": "text/plain", "url": "/api/attachments/abc", "text": "正文不落盘"},
+        {"name": "b.pdf", "size": 999, "mime": "application/pdf", "url": "/api/attachments/def", "text": ""},
+    ]
+    assert store.append(s["id"], "user", "读一下这两个文件", attachments=atts)
+    d = store.get(s["id"])
+    m = d["messages"][0]
+    assert m["role"] == "user" and m["content"] == "读一下这两个文件"
+    assert len(m["attachments"]) == 2
+    assert m["attachments"][0] == {"name": "a.txt", "size": 11, "mime": "text/plain", "url": "/api/attachments/abc"}
+    assert "text" not in m["attachments"][0], "text 不得落盘(会话文件不膨胀)"
+    # 不带附件 → 无 attachments 字段(向后兼容)
+    assert store.append(s["id"], "assistant", "好")
+    assert "attachments" not in store.get(s["id"])["messages"][1]
+    print("会话落盘(轻字段/不存 text/向后兼容)OK")
+
+
+def test_upload_and_download():
+    with TestClient(app) as c:
+        # 上传文本文件 → 提取正文
+        r = c.post("/api/upload", files={"file": ("笔记.txt", "今天学了三件事".encode(), "text/plain")})
+        assert r.status_code == 200, r.text
+        a = r.json()
+        assert a["name"] == "笔记.txt" and a["text"] == "今天学了三件事"
+        assert a["url"].startswith("/api/attachments/") and a["id"] and a["size"] > 0
+
+        # 下载 → 同一内容
+        r2 = c.get(a["url"])
+        assert r2.status_code == 200
+        assert r2.content.decode("utf-8") == "今天学了三件事"
+
+        # 二进制(不可提取)→ text 为空,降级
+        r3 = c.post("/api/upload", files={"file": ("img.bin", b"\x00\x01\x02", "application/octet-stream")})
+        assert r3.status_code == 200 and r3.json()["text"] == ""
+
+        # 空文件 → 400;超大 → 413
+        assert c.post("/api/upload", files={"file": ("e.txt", b"", "text/plain")}).status_code == 400
+        big = b"x" * (21 * 1024 * 1024)
+        assert c.post("/api/upload", files={"file": ("big.txt", big, "text/plain")}).status_code == 413
+
+        # 路径穿越:HTTP 层规范化后到不了附件路由(404);非法 id 字符 → 400;合法但不存在 → 404
+        assert c.get("/api/attachments/../../etc/passwd").status_code == 404  # .. 被 URL 规范化,不匹配路由
+        assert c.get("/api/attachments/a.b").status_code == 400               # . 不在 id 白名单 [_A-Za-z0-9_-]
+        assert c.get("/api/attachments/deadbeef0000").status_code == 404      # 合法 id 但文件不存在
+    print("上传/下载(正文提取/二进制降级/空/超大/穿越/404)OK")
+
+
+def test_chat_stream_with_attachments():
+    import foxclaw.api as _api
+    with TestClient(app) as c:
+        # 先上传一个带正文的附件,拿到引用
+        up = c.post("/api/upload", files={"file": ("要点.txt", "预算 100 万".encode(), "text/plain")})
+        att = up.json()
+        # 会话须先存在,append 才会落盘(前端 ensureSession 同款:POST /api/sessions → 拿 id)
+        sid = _api._os_instance.sessions.create()["id"]
+        payload = {
+            "task": "帮我总结要点",
+            "agent_id": "supervisor",
+            "session_id": sid,
+            "attachments": [{"name": att["name"], "size": att["size"], "mime": att["mime"],
+                             "url": att["url"], "text": att["text"]}],
+        }
+        r = c.post("/api/chat/stream", json=payload)
+        assert r.status_code == 200, r.text[:200]
+        assert "data:" in r.text and '"error"' not in r.text, r.text[:300]
+
+        # 会话已落盘用户消息 + 附件元数据(不含 text)
+        d = _api._os_instance.sessions.get(sid)
+        assert d is not None, "会话未落盘"
+        um = d["messages"][0]
+        assert um["role"] == "user" and um["content"] == "帮我总结要点"
+        assert um["attachments"][0]["name"] == "要点.txt"
+        assert "text" not in um["attachments"][0]
+    print("/chat/stream 带附件端到端(SSE + 会话落盘)OK")
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

package/python/tests/test_audit_chain.py

@@ -0,0 +1,121 @@
+"""审计落盘的哈希链 + recovery 日志脱敏的回归。
+
+审计文件是纯 append 明文,谁能写谁就能改历史;哈希链不改可见性,只让「改一笔 / 删中间
+一笔」在 verify 里暴露。recovery 日志则是被回放读回、长期留在磁盘上的工具调用记录,
+工具参数里带 token 的情况很常见。
+"""
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+def _write_chain(path: Path, records) -> None:
+    from foxclaw.core import audit_chain
+
+    prev = audit_chain.GENESIS
+    lines = []
+    for r in records:
+        rec = audit_chain.link(r, prev)
+        prev = rec["hash"]
+        lines.append(json.dumps(rec, ensure_ascii=False))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+# ── 链 ─────────────────────────────────────────────────────────────
+
+def test_chain_passes(tmp_path):
+    from foxclaw.core import audit_chain
+
+    p = tmp_path / "a.jsonl"
+    _write_chain(p, [{"verdict": "deny"}, {"verdict": "allow"}, {"verdict": "success"}])
+    ok, n, msg = audit_chain.verify(p)
+    assert ok and n == 3, msg
+
+
+def test_tampered_line_detected(tmp_path):
+    from foxclaw.core import audit_chain
+
+    p = tmp_path / "a.jsonl"
+    _write_chain(p, [{"verdict": "deny"}, {"verdict": "allow"}])
+    lines = p.read_text(encoding="utf-8").splitlines()
+    rec = json.loads(lines[0])
+    rec["verdict"] = "allow"                     # 把一次拒绝抹成放行
+    lines[0] = json.dumps(rec, ensure_ascii=False)
+    p.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    ok, _, msg = audit_chain.verify(p)
+    assert not ok and "被改" in msg, msg
+
+
+def test_deleted_middle_line_detected(tmp_path):
+    from foxclaw.core import audit_chain
+
+    p = tmp_path / "a.jsonl"
+    _write_chain(p, [{"i": 0}, {"i": 1}, {"i": 2}])
+    lines = p.read_text(encoding="utf-8").splitlines()
+    p.write_text("\n".join([lines[0], lines[2]]) + "\n", encoding="utf-8")
+
+    ok, _, msg = audit_chain.verify(p)
+    assert not ok and "链断" in msg, msg
+
+
+def test_resume_after_restart(tmp_path):
+    """进程重启后内存链尾丢失,新 auditor 应从文件尾部续链,而不是重开 GENESIS。"""
+    from foxclaw.core.governance_audit import GovernanceAuditor
+
+    p = tmp_path / "governance.jsonl"
+    GovernanceAuditor(sink_path=p).record(
+        layer="skill", actor="office", action="write_note", verdict="success")
+    aud = GovernanceAuditor(sink_path=p)          # 模拟重启
+    aud.record(layer="skill", actor="office", action="write_note", verdict="success")
+
+    ok, n, msg = aud.verify()
+    assert ok and n == 2, msg
+    recs = aud.read()
+    assert recs[1]["hash"] != recs[0]["hash"]
+
+
+def test_legacy_lines_skipped(tmp_path):
+    """老文件(无 hash)不能因为「没链」就报错;新记录从 GENESIS 起头。"""
+    from foxclaw.core import audit_chain
+
+    p = tmp_path / "a.jsonl"
+    p.write_text('{"legacy": true}\n', encoding="utf-8")
+    assert audit_chain.verify(p)[0] is True
+    assert audit_chain.tail_hash(p) == audit_chain.GENESIS
+
+
+def test_tail_hash_ignores_torn_line(tmp_path):
+    from foxclaw.core import audit_chain
+
+    p = tmp_path / "a.jsonl"
+    p.write_text('{"a": 1, "hash": "h1"}\n{"half', encoding="utf-8")
+    assert audit_chain.tail_hash(p) == "h1"
+
+
+# ── recovery 脱敏 ──────────────────────────────────────────────────
+
+def test_recovery_step_args_and_result_redacted():
+    from types import SimpleNamespace
+
+    from foxclaw.agents.mixins.tool_exec import _record_step, _step_key
+
+    key = "sk-" + "a" * 24
+    got = {}
+
+    class _Rec:
+        @staticmethod
+        def record_step(tid, rec):
+            got.update(rec)
+
+    agent = SimpleNamespace(_recovery=_Rec(), _session_id="s1")
+    _record_step(agent, {"name": "http", "args": {"api_key": key}},
+                 f"ok token=sk-{'b' * 24}")
+
+    assert "sk-" not in json.dumps(got["args"]), got["args"]
+    assert "[已脱敏]" in got["result"], got["result"]
+    # key 必须用未脱敏的 args 算,否则同一步骤前后 key 不一致(缓存/回放对不上)
+    assert got["key"] == _step_key("http", {"api_key": key})

package/python/tests/test_audit_sink.py

@@ -0,0 +1,136 @@
+"""审计落盘 sink(audit_sink)测试 —— P0-3 配套
+
+覆盖:
+  1. 单元层:EventSpine + sink 直连 —— JSONL 格式、字段齐全、追加语义、开关、坏行容错
+  2. 端到端层:真实 Foxclaw 装配 → 共享写入 → 文件里出现完整记录(接线正确性)
+"""
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+_FAILS = []
+_N = 0
+
+
+def check(cond, msg):
+    global _N
+    _N += 1
+    print(f"  {'✓' if cond else '✗'} {msg}")
+    if not cond:
+        _FAILS.append(msg)
+
+
+def test_unit():
+    print("\n【1】单元层:EventSpine + sink 直连")
+    from foxclaw.kernel.spine import EventSpine
+    from foxclaw.core.audit_sink import SharedWriteAuditSink, attach, ENV_SWITCH
+
+    tmp = tempfile.mkdtemp(prefix="foxclaw_asink_")
+    try:
+        path = Path(tmp) / "audit" / "shared_write.jsonl"
+        spine = EventSpine()
+        sink = SharedWriteAuditSink(path)
+        spine.subscribe("memory.shared.write", sink)
+
+        spine.publish("memory.shared.write", {
+            "agent_id": "office", "type": "decision",
+            "tags": ["finance.transfer"], "allowed": False,
+            "reason": "office 的职责域不含 ['type:decision','finance.transfer']",
+            "mode": "audit", "content_sha": "0123456789abcdef",
+            "content_preview": "财务应给办公转账1000元"}, source="office")
+        # 非本主题的事件不应落盘(subscribe 前缀精确命中)
+        spine.publish("memory.updated", {"x": 1})
+
+        check(path.exists(), "审计文件已创建(含 audit/ 目录)")
+        recs = sink.read()
+        check(len(recs) == 1, f"只落了本主题 1 条(非本主题被过滤):实际 {len(recs)}")
+        r = recs[0]
+        check(r["topic"] == "memory.shared.write", "topic 正确")
+        check(r["payload"]["allowed"] is False, "payload 原样保留(allowed=False 可判读)")
+        check(len(r["payload"]["content_sha"]) == 16, "content_sha 为 16 位哈希")
+        check("ts" in r and "T" in r["ts"], "ts 为 ISO 时间(人类可读)")
+        check(bool(r["correlation_id"]), "correlation_id 已记录(可与脊柱 history 对账)")
+
+        # 追加语义:第二条接在后面,顺序保持
+        spine.publish("memory.shared.write", {"agent_id": "system", "type": "execution",
+                                              "tags": ["truth_pipeline"], "allowed": True,
+                                              "reason": "命中全局允许 facet", "mode": "audit",
+                                              "content_sha": "ffffffffffffffff",
+                                              "content_preview": "真值"})
+        recs = sink.read()
+        check(len(recs) == 2 and recs[1]["payload"]["agent_id"] == "system",
+              "追加写不覆盖旧行,顺序保持")
+
+        # 坏行容错:夹一行垃圾,read() 跳过而不是崩
+        with open(path, "a", encoding="utf-8") as f:
+            f.write("{这不是JSON}\n")
+        check(len(sink.read()) == 2, "坏行被跳过,读取不崩")
+
+        # 开关:环境变量置 0 时 attach 不挂
+        old = os.environ.get(ENV_SWITCH)
+        os.environ[ENV_SWITCH] = "0"
+        try:
+            check(attach(EventSpine(), tmp) is None, "FOXCLAW_SHARED_WRITE_AUDIT=0 → 不挂")
+            os.environ[ENV_SWITCH] = "1"
+            s2 = attach(EventSpine(), tmp)
+            check(s2 is not None and s2.path == Path(tmp) / "audit" / "shared_write.jsonl",
+                  "开启时挂载且路径跟随 data_dir")
+        finally:
+            if old is None:
+                os.environ.pop(ENV_SWITCH, None)
+            else:
+                os.environ[ENV_SWITCH] = old
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def test_end_to_end():
+    print("\n【2】端到端:真实 Foxclaw 装配 → 共享写入 → 落盘")
+    tmp = tempfile.mkdtemp(prefix="foxclaw_asink_e2e_")
+    try:
+        from foxclaw import Foxclaw
+        osi = Foxclaw(data_dir=tmp, shadow_rounds=5)
+
+        check(osi.shared_write_audit is not None, "sink 已随装配挂上(默认开启)")
+        audit_path = Path(tmp) / "audit" / "shared_write.jsonl"
+        check(audit_path.parent.exists(), "audit/ 目录已建在 data_dir 下")
+
+        # 一条合法 + 一条越界(audit 模式不拦截,只记录)——真实闸门口径
+        osi.hmr.ingest("用户偏好:喜欢表格", type="concept", agent_id="finance",
+                       tags=["preference"], shared=True)
+        osi.hmr.ingest("财务应给办公转账1000元", type="decision", agent_id="office",
+                       tags=["finance.transfer"], shared=True)
+
+        recs = osi.shared_write_audit.read()
+        check(len(recs) == 2, f"两笔共享写入都落盘:实际 {len(recs)}")
+        by_allowed = {r["payload"]["allowed"] for r in recs}
+        check(by_allowed == {True, False}, "allowed 的 True/False 都被原样记录(判读依据完整)")
+        denied = [r for r in recs if not r["payload"]["allowed"]]
+        check(bool(denied) and "office" in denied[0]["payload"]["reason"] or bool(denied),
+              "越界那条可从文件直接判读")
+        # 与脊柱 history 口径一致:文件条数 == 脊柱里该主题条数
+        spine_n = len(osi.event_spine.history("memory.shared.write", 100))
+        check(spine_n == len(recs), f"文件条数与脊柱 history 一致({len(recs)}=={spine_n})")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def main():
+    print("=" * 60)
+    print("审计落盘 sink(P0-3 配套)")
+    print("=" * 60)
+    test_unit()
+    test_end_to_end()
+    print("\n" + "=" * 60)
+    if _FAILS:
+        print(f"✗ {len(_FAILS)}/{_N} 项失败"); return 1
+    print(f"✓ 全部通过({_N} 项)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())