foxclaw 0.1.0 → 0.1.2

package/python/bench/load_test.py

@@ -0,0 +1,196 @@
+"""
+本地大并发压测（真实 uvicorn 服务）
+
+起一个真实的 uvicorn（Foxclaw，stub LLM / 离线），用 httpx 异步客户端打高并发
+`POST /api/task`，量:
+  · 吞吐(req/s)、延迟分位(p50/p90/p95/p99/max)、错误率;
+  · **负载下正确性**:每个请求拿到独立 session_id(无串味)、无 database is locked、无 5xx。
+
+这把 M2 加锁 + 顶层 contextvars 的并发修复放到**真实 HTTP 服务**下验证。
+纯本地、离线、零基建。用法:HF_HUB_OFFLINE=1 python bench/load_test.py [总请求数] [并发数]
+"""
+import asyncio
+import os
+import statistics
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+PORT = int(os.environ.get("FOXCLAW_BENCH_PORT", "8231"))
+BASE = f"http://127.0.0.1:{PORT}"
+
+# 一批覆盖不同分诊路径的任务模板（每个请求附唯一编号,便于校验会话唯一性）
+TEMPLATES = [
+    "分析本月理财预算与收支",       # finance
+    "总结这篇论文的核心要点",       # office
+    "安排明天上午的会议日程",       # admin
+    "整理并汇总这批资料",           # assistant
+    "你能做什么",                   # supervisor 自答(meta)
+]
+
+
+def _pct(xs, p):
+    if not xs:
+        return 0.0
+    xs = sorted(xs)
+    k = max(0, min(len(xs) - 1, int(round((p / 100) * (len(xs) - 1)))))
+    return xs[k]
+
+
+def _start_server():
+    """在后台线程起真实 uvicorn。返回 (server, thread)。"""
+    import uvicorn
+    os.environ.setdefault("FOXCLAW_DATA_DIR", tempfile.mkdtemp())
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "50"
+    # 不配任何 LLM key → Router 自动降级 stub(不联网、瞬时返回)
+    for k in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "DEEPSEEK_API_KEY",
+              "GOOGLE_API_KEY", "DASHSCOPE_API_KEY"):
+        os.environ.pop(k, None)
+    config = uvicorn.Config("foxclaw.api:app", host="127.0.0.1", port=PORT,
+                            log_level="warning", access_log=False)
+    server = uvicorn.Server(config)
+    th = threading.Thread(target=server.run, daemon=True)
+    th.start()
+    return server, th
+
+
+async def _wait_ready(timeout=120):
+    import httpx
+    t0 = time.time()
+    async with httpx.AsyncClient() as c:
+        while time.time() - t0 < timeout:
+            try:
+                r = await c.get(f"{BASE}/api/status", timeout=2)
+                if r.status_code == 200:
+                    return True
+            except Exception:
+                pass
+            await asyncio.sleep(0.3)
+    return False
+
+
+async def _run_load(total: int, concurrency: int):
+    import httpx
+    sem = asyncio.Semaphore(concurrency)
+    latencies, statuses, sessions, errors = [], [], [], []
+    lock = asyncio.Lock()
+
+    async def one(i: int):
+        task = f"{TEMPLATES[i % len(TEMPLATES)]}（REQ{i:05d}）"
+        async with sem:
+            t0 = time.perf_counter()
+            try:
+                async with httpx.AsyncClient(timeout=60) as c:
+                    r = await c.post(f"{BASE}/api/task",
+                                     json={"task": task, "agent_id": "supervisor"})
+                dt = (time.perf_counter() - t0) * 1000
+                async with lock:
+                    latencies.append(dt)
+                    statuses.append(r.status_code)
+                    if r.status_code == 200:
+                        body = r.json()
+                        sid = body.get("session_id")
+                        if sid:
+                            sessions.append(sid)
+                        if isinstance(body, dict) and body.get("error") == "主管处理失败":
+                            errors.append(body)
+            except Exception as e:
+                async with lock:
+                    errors.append(repr(e))
+
+    t0 = time.perf_counter()
+    await asyncio.gather(*[one(i) for i in range(total)])
+    wall = time.perf_counter() - t0
+    return {
+        "wall_s": wall, "throughput": total / wall if wall else 0,
+        "latencies": latencies, "statuses": statuses,
+        "sessions": sessions, "errors": errors,
+    }
+
+
+async def _server_log_has_locked():
+    """负载后查一次 /api/status 确认服务仍活;database is locked 会体现在 errors/5xx。"""
+    import httpx
+    try:
+        async with httpx.AsyncClient() as c:
+            r = await c.get(f"{BASE}/api/status", timeout=5)
+            return r.status_code == 200
+    except Exception:
+        return False
+
+
+async def main_async(total, concurrency):
+    print("=" * 62)
+    print(f"Foxclaw · 本地大并发压测  (总请求={total} 并发={concurrency})")
+    print("=" * 62)
+    ok = await _wait_ready()
+    if not ok:
+        print("✗ 服务未就绪"); return 1
+    print("服务就绪。先测单请求基线(concurrency=1)...")
+
+    # 基线:串行 10 个请求,量"单请求真实成本"(无并发争用),用于解释并发下的延迟来源
+    base = await _run_load(10, 1)
+    base_lat = base["latencies"]
+    base_p50 = _pct(base_lat, 50)
+    base_tps = base["throughput"]
+    print(f"  单请求 p50={base_p50:.0f}ms  串行吞吐={base_tps:.1f} req/s\n")
+
+    print(f"开始并发加载(concurrency={concurrency})...\n")
+    res = await _run_load(total, concurrency)
+    lat, st = res["latencies"], res["statuses"]
+    n2xx = sum(1 for s in st if 200 <= s < 300)
+    n5xx = sum(1 for s in st if s >= 500)
+    healthy = await _server_log_has_locked()
+
+    print("【吞吐 / 延迟】")
+    print(f"  墙钟         : {res['wall_s']:.2f} s")
+    print(f"  吞吐         : {res['throughput']:.1f} req/s")
+    print(f"  延迟 p50/p90 : {_pct(lat,50):.0f} / {_pct(lat,90):.0f} ms")
+    print(f"  延迟 p95/p99 : {_pct(lat,95):.0f} / {_pct(lat,99):.0f} ms")
+    print(f"  延迟 max     : {max(lat):.0f} ms" if lat else "  无延迟样本")
+    ratio = _pct(lat, 50) / base_p50 if base_p50 else 0
+    speedup = base_tps and res["throughput"] / base_tps
+    print("\n【规模化分析】")
+    print(f"  单请求成本(串行 p50)   : {base_p50:.0f} ms")
+    print(f"  并发吞吐 / 串行吞吐     : {speedup:.2f}×  "
+          f"（>1 = 请求已部分并行;offload 到线程后嵌入计算并行）")
+    print(f"  并发下 p50 / 串行 p50   : {ratio:.1f}×  "
+          f"(< 并发数 {concurrency} 越多 → 并行度越高;=并发数则完全串行)")
+    print(f"  现状: /api/task 已 offload 到线程,harness 语义嵌入在锁外并行(torch 释放 GIL);")
+    print(f"        非线性加速的余量卡在 GIL(Python 侧串行)+ 本机核数。")
+    print(f"  进一步提速: ① uvicorn --workers N 多进程(需先做状态外置) ② 更轻的 embedding。")
+    print("\n【正确性 · 负载下】")
+    print(f"  2xx / 总数   : {n2xx}/{total}   5xx: {n5xx}   异常: {len(res['errors'])}")
+    uniq = len(set(res["sessions"]))
+    print(f"  session 唯一 : {uniq}/{len(res['sessions'])}  "
+          f"→ {'✓ 无串味(顶层并发隔离成立)' if uniq == len(res['sessions']) and uniq > 0 else '✗ 有会话碰撞'}")
+    print(f"  服务负载后仍健康: {'✓' if healthy else '✗'}")
+    if res["errors"]:
+        print(f"  异常样例: {res['errors'][:2]}")
+
+    passed = (n5xx == 0 and not res["errors"] and healthy
+              and uniq == len(res["sessions"]) and uniq > 0)
+    print("\n" + "=" * 62)
+    print("结论:", "✓ 高并发下吞吐可测、零错误、审计无串味" if passed else "✗ 存在问题(见上)")
+    print("=" * 62)
+    return 0 if passed else 1
+
+
+def main():
+    total = int(sys.argv[1]) if len(sys.argv) > 1 else 200
+    concurrency = int(sys.argv[2]) if len(sys.argv) > 2 else 32
+    server, th = _start_server()
+    try:
+        rc = asyncio.run(main_async(total, concurrency))
+    finally:
+        server.should_exit = True
+        th.join(timeout=10)
+    sys.exit(rc)
+
+
+if __name__ == "__main__":
+    main()

package/python/bench/vector_ivf_upgrade.py

@@ -0,0 +1,134 @@
+"""vector 索引升级 + 性能对比:Flat vs IVF(1500 mock KU, stub backend)
+
+目的:验证 HKC_VECTOR_IVF_THRESHOLD 触发的 Flat → IVF 自动升级,
+     并对比两种索引在 500 / 1500 mock KU 下的检索延迟。
+
+用法:
+    python bench/vector_ivf_upgrade.py
+
+可调参数:
+    HKC_VECTOR_IVF_THRESHOLD  默认 500(本脚本覆盖)
+    IVF_NLIST                 自定义 nlist(可选)
+    TOTAL_KUS                 总 mock KU 数,默认 1500
+"""
+from __future__ import annotations
+
+import os
+import statistics
+import sys
+import tempfile
+import time
+from pathlib import Path
+from types import SimpleNamespace
+
+# 必须在 import VectorIndex 之前设,否则模块级常量已固化
+os.environ["HKC_VECTOR_IVF_THRESHOLD"] = "500"
+
+# 让 vendor.hkc.* 可导入(脚本放在 bench/,不在 vendor 树内)
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from vendor.hkc.hkc_search.vector_search import VectorIndex
+from vendor.hkc.hkc_search.embedding_backends import StubBackend
+
+
+def make_ku(i: int) -> SimpleNamespace:
+    """构造 mock KU,字段匹配 vector_search._ku_text() 期望的 4 项: name/summary/tags/statement。"""
+    return SimpleNamespace(
+        ku_id     = f"ku_{i:06d}",
+        name      = f"entity_{i}",
+        summary   = f"summary of entity {i} about topic {i % 50}",
+        tags      = [f"tag_{i % 10}", f"category_{i % 5}"],
+        statement = f"fact {i}: something interesting about subject {i}",
+    )
+
+
+def bench_search(idx, query: str, n: int = 100, top_k: int = 10) -> tuple[float, float, float]:
+    """跑 n 次 search,返 (median_ms, min_ms, max_ms)。"""
+    times = []
+    for _ in range(n):
+        t0 = time.perf_counter()
+        idx.search(query, top_k=top_k)
+        times.append((time.perf_counter() - t0) * 1000)
+    return statistics.median(times), min(times), max(times)
+
+
+def main() -> None:
+    backend = StubBackend(dim=384)
+    threshold = int(os.environ["HKC_VECTOR_IVF_THRESHOLD"])
+
+    print("=" * 70)
+    print(f"backend       : {backend.name}")
+    print(f"threshold     : HKC_VECTOR_IVF_THRESHOLD = {threshold}")
+    print(f"upgrade to    : IndexIVFFlat(nlist≈√N, nprobe=16)")
+    print("=" * 70)
+
+    N = 5000
+    print(f"\n构造 {N} 条 mock KU...")
+    kus = [make_ku(i) for i in range(N)]
+
+    idx = VectorIndex(backend=backend)
+    print(f"index type 初始: {type(idx._index).__name__}")
+
+    # ── Phase 1: append < threshold,保持 Flat ──────────────────
+    phase1_n = threshold - 1
+    print(f"\n[Phase 1] append {phase1_n} 条(< {threshold},应保持 Flat)...")
+    for ku in kus[:phase1_n]:
+        idx.append_ku(ku)
+    print(f"  index type: {type(idx._index).__name__}, ntotal={idx._index.ntotal}")
+    med, mn, mx = bench_search(idx, "find something about topic 7")
+    print(f"  search ×100: median={med:.2f}ms  min={mn:.2f}ms  max={mx:.2f}ms")
+
+    # ── Phase 2: append 触发升级 Flat → IVF ──────────────────
+    print(f"\n[Phase 2] append 第 {threshold} 条(应触发升级)...")
+    t0 = time.perf_counter()
+    idx.append_ku(kus[phase1_n])
+    upgrade_ms = (time.perf_counter() - t0) * 1000
+    print(f"  append(含升级)耗时: {upgrade_ms:.1f}ms")
+    print(f"  index type: {type(idx._index).__name__}, ntotal={idx._index.ntotal}")
+    if hasattr(idx._index, "nlist"):
+        print(f"  IVF nlist={idx._index.nlist}, nprobe={idx._index.nprobe}")
+    med, mn, mx = bench_search(idx, "find something about topic 7")
+    print(f"  search ×100: median={med:.2f}ms  min={mn:.2f}ms  max={mx:.2f}ms")
+
+    # ── Phase 3: append 1000 条,验证 IVF 追加正常 ──────────────────
+    rest = N - threshold
+    print(f"\n[Phase 3] append {rest} 条(应直接 add 到 IVF)...")
+    t0 = time.perf_counter()
+    for ku in kus[threshold:]:
+        idx.append_ku(ku)
+    bulk_ms = (time.perf_counter() - t0) * 1000
+    print(f"  {rest} 条 append 耗时: {bulk_ms:.1f}ms(平均 {bulk_ms/rest:.2f}ms/条)")
+    print(f"  index type: {type(idx._index).__name__}, ntotal={idx._index.ntotal}")
+    med, mn, mx = bench_search(idx, "find something about topic 7")
+    print(f"  search ×100: median={med:.2f}ms  min={mn:.2f}ms  max={mx:.2f}ms")
+
+    # ── Phase 4: save/load roundtrip(IVF 必须正确持久化) ──────────────────
+    print(f"\n[Phase 4] save/load roundtrip(IVF 持久化)...")
+    with tempfile.TemporaryDirectory() as td:
+        p = str(Path(td) / "vec")
+        t0 = time.perf_counter()
+        idx.save(p)
+        save_ms = (time.perf_counter() - t0) * 1000
+        idx2 = VectorIndex(backend=backend)
+        t0 = time.perf_counter()
+        ok = idx2.load(p)
+        load_ms = (time.perf_counter() - t0) * 1000
+        n_loaded = idx2._index.ntotal if idx2._index else 0
+        type_loaded = type(idx2._index).__name__ if idx2._index else "None"
+        print(f"  save: {save_ms:.1f}ms  load: {load_ms:.1f}ms  ok={ok}")
+        print(f"  loaded ntotal={n_loaded}, type={type_loaded}")
+        if n_loaded != N:
+            print(f"  [FAIL] 数据丢失! 期望 {N} 实际 {n_loaded}")
+        elif "FlatIP" in type_loaded:   # 严格判:IndexFlatIP 才算 Flat(IndexIVFFlat 含 "Flat" 字符串,要排除)
+            print(f"  [FAIL] IVF 没保存,降回 FlatIP")
+        else:
+            print(f"  [OK] IVF 完整保存/加载(ntotal={n_loaded}, type={type_loaded})")
+
+    print("\n" + "=" * 70)
+    print("[OK] benchmark 完成")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

package/python/docs/CHANNELS.md

@@ -0,0 +1,195 @@
+# Foxclaw 消息平台接入说明
+
+把 Foxclaw 接到消息平台,让用户在微信 / 飞书 / Telegram / Discord 里直接和你的认知系统对话。
+
+## 架构总览
+
+```
+用户在某渠道发消息
+   → 渠道适配器 normalize 成标准消息(InboundMessage)
+   → ChannelDispatcher 交给主管 Agent 处理
+   → 主管 run_task 思考、调度子 Agent
+   → 回复通过同一渠道发回
+```
+
+三个角色各司其职:**适配器**只管收发(翻译平台格式 ↔ 标准格式),**主管**只管思考,**调度器(ChannelDispatcher)**把两者接起来。
+
+所有适配器都遵循同一套接口(`normalize` / `send` / `reply`),但**内部各按平台官方规范实现**——微信是长轮询、飞书是事件订阅 webhook、Telegram 是 getUpdates、Discord 是 Gateway WebSocket,互不相同。
+
+## 通用启动方式
+
+```python
+from foxclaw import Foxclaw
+from foxclaw.channels.dispatcher import ChannelDispatcher
+
+os_ = Foxclaw(data_dir="./data")
+dispatcher = ChannelDispatcher(os_.supervisor)
+
+# 注册渠道(下面每个平台示例都用这个 dispatcher)
+dispatcher.register_channel(adapter)   # adapter 见下文各平台
+```
+
+`register_channel` 会自动把适配器的入站消息接到主管闭环——之后该渠道收到的每条消息都会经主管处理并自动回复。
+
+---
+
+## Telegram(最易跑通,建议先用它验证)
+
+**拿 token:** Telegram 里找 `@BotFather` → 发 `/newbot` → 按提示拿到 bot token。
+
+```python
+from foxclaw.channels.telegram import TelegramAdapter
+
+tg = TelegramAdapter(bot_token="123456:ABC-DEF...")
+dispatcher.register_channel(tg)
+
+# 验证 token
+print(tg.verify_token().ok)
+
+# 持续收消息(轮询):放进循环
+import time
+while True:
+    tg.poll_once()      # 拉一批新消息,自动经主管处理并回复
+    time.sleep(1)
+```
+
+收发模型:**getUpdates 长轮询**,无需公网回调地址,本地直接能跑。
+
+---
+
+## 微信(iLink Bot API)
+
+照 Tencent 官方开源插件 [`Tencent/openclaw-weixin`](https://github.com/Tencent/openclaw-weixin) 公开的 iLink Bot API 协议实现。
+
+**拿 token:** token 需用微信官方那套**扫码登录**获得(扫码登录在微信侧,Foxclaw 不复现登录,只复现登录后的消息收发)。可用 OpenClaw 官方 CLI 扫码:
+```bash
+openclaw channels login --channel openclaw-weixin   # 扫码后本地拿到 token
+```
+
+```python
+from foxclaw.channels.weixin import WeixinAdapter
+
+wx = WeixinAdapter(token="<扫码登录得到的 token>")
+dispatcher.register_channel(wx)
+
+# 持续收消息(长轮询)
+while True:
+    wx.poll_once()      # getUpdates 长轮询,自动处理并回复
+```
+
+收发模型:**getUpdates 长轮询**。回复时会自动带回 `context_token`(微信要求),已内部处理。`verify_token(ilink_user_id)` 需提供真实用户 ID 才能探测。
+
+---
+
+## 飞书 / Lark(事件订阅 webhook)
+
+**拿凭证:** 飞书开放平台 → 创建企业自建应用 → 拿 `App ID` + `App Secret`;在「事件订阅」里配置回调地址,记下 `Verification Token` 和 `Encrypt Key`(若开启加密)。事件订阅勾选 `im.message.receive_v1`。
+
+飞书是**平台主动推事件到你的回调地址**,所以需要一个公网可达的 webhook 端点(FastAPI 路由)。
+
+```python
+from foxclaw.channels.feishu import FeishuAdapter
+
+fs = FeishuAdapter(
+    app_id="cli_xxx",
+    app_secret="xxx",
+    verification_token="xxx",   # webhook 模式需要
+    encrypt_key="xxx",          # 若开启加密
+)
+dispatcher.register_channel(fs)
+
+# FastAPI 路由接飞书事件回调
+from fastapi import FastAPI, Request
+app = FastAPI()
+
+@app.post("/feishu/events")
+async def feishu_events(request: Request):
+    raw_body = await request.body()
+    payload = await request.json()
+    # handle_event 内部完成:URL验证 / 解密 / 验签 / 标准化 / 主管处理
+    return fs.handle_event(payload, headers=dict(request.headers), raw_body=raw_body)
+```
+
+收发模型:**事件订阅 webhook**。`handle_event` 自动处理 URL 验证(challenge)、AES 解密、签名验签。发消息用 `tenant_access_token`(自动缓存 + 过期前刷新)。
+
+> 注意:飞书加密事件解密需要 `cryptography` 库(或 pycryptodome)。环境一般已自带 cryptography。
+
+---
+
+## Discord(Gateway WebSocket)
+
+**拿 token:** Discord Developer Portal → 创建 Application → Bot → 拿 bot token。**务必在 Bot 设置里开启 `MESSAGE CONTENT INTENT`**(否则收不到消息文本)。把 Bot 邀请进你的服务器。
+
+```python
+from foxclaw.channels.discord import DiscordAdapter
+
+dc = DiscordAdapter(bot_token="...")
+dispatcher.register_channel(dc)
+
+# 验证 token(同时记录 bot 自身 ID,用于忽略自己的消息)
+print(dc.verify_token().ok)
+
+# 持续收消息(Gateway WebSocket,异步)
+import asyncio
+asyncio.run(dc.connect_gateway())   # 需要 websockets 库
+```
+
+收发模型:**Gateway WebSocket 长连接**(收) + **REST API**(发)。`connect_gateway` 实现了 HELLO→IDENTIFY→心跳→消息分发的最小闭环。生产环境也可换成成熟的 discord.py,再把消息喂给 `dc.normalize()`。
+
+> 需要 `websockets` 库:`pip install websockets`
+
+---
+
+## 备选:对接 OpenClaw 网关
+
+若你已在用 OpenClaw(它接了某些渠道),可让 Foxclaw 通过 OpenClaw 网关收发,而不必自己实现那些渠道。
+
+```python
+from foxclaw.channels.openclaw_bridge import OpenClawBridgeAdapter
+
+bridge = OpenClawBridgeAdapter(gateway_url="http://127.0.0.1:8080", api_token="...")
+dispatcher.register_channel(bridge)
+```
+
+OpenClaw 负责渠道接入,Foxclaw 负责认知处理,两者通过 HTTP 桥接。
+
+---
+
+## 多渠道同时运行
+
+一个 dispatcher 可注册多个渠道,各自独立收发,共用同一个主管:
+
+```python
+dispatcher.register_channel(tg)     # Telegram(轮询)
+dispatcher.register_channel(wx)     # 微信(轮询)
+dispatcher.register_channel(dc)     # Discord(WebSocket)
+# 飞书走 FastAPI webhook 路由
+
+# 轮询类渠道各起一个循环/线程;WebSocket/webhook 类按各自方式跑
+```
+
+**会话隔离:** 默认按 `渠道:会话:发送者` 隔离(不同渠道的对话互不串)。若想做"跨渠道同一记忆"(同一用户在飞书和微信共享上下文),可改 `dispatcher._session_key` 只用 `sender_id`。
+
+---
+
+## 依赖小结
+
+| 渠道 | 必需依赖 | 凭证 |
+|---|---|---|
+| Telegram | httpx | bot token(@BotFather) |
+| 微信 | httpx | 扫码登录 token |
+| 飞书 | httpx, cryptography | App ID/Secret + (加密时)Encrypt Key |
+| Discord | httpx, websockets | bot token + Message Content Intent |
+| OpenClaw 桥 | httpx | OpenClaw 网关地址 + token |
+
+```bash
+pip install httpx cryptography websockets
+```
+
+---
+
+## 安全提示
+
+- **凭证不要硬编码**:token / app_secret 用环境变量或配置文件注入,别写进代码或提交到 Git。
+- 飞书 webhook 建议保留**签名验签**(开启 Encrypt Key),适配器会自动验。
+- 各渠道的访问控制(谁能跟 bot 对话)目前在主管侧统一处理;如需更细的白名单,可在 `dispatcher.handle` 里按 `msg.sender_id` 加判断。

package/python/docs/GOVERNANCE.md

@@ -0,0 +1,164 @@
+# Foxclaw 运行时治理能力说明
+
+这组能力借鉴 OpenClaw 等成熟 Agent 系统的设计原理,用 Python 适配 Foxclaw 实现,目标是让系统在真实运行(消息重发、进程崩溃、长任务、死循环)中保持**可靠、可审计、不丢不重**。
+
+六项能力分两类:**已接入主路径、现在就生效**的(幂等、重启恢复、循环检测),和**基础设施、按需启用**的(上下文压缩、钩子标准化、干预队列)。
+
+---
+
+## 一、幂等守卫(Idempotency)— 已生效
+
+**解决:** 消息平台天生会重发(网络抖动、平台重试、轮询游标边界)。没有幂等,用户会收到重复回复、同一操作被记两次。
+
+**原理:** 给"只应发生一次"的操作算一个稳定 key,执行前**原子查重**——处理过就跳过,没处理才执行并记录。
+
+**核心接口**(`foxclaw/core/idempotency.py`):
+```python
+from foxclaw.core.idempotency import IdempotencyGuard, make_key
+
+guard = IdempotencyGuard(ttl_seconds=3600)        # 可选 persist_path 跨重启
+key = make_key("message", channel, message_id, sender_id)
+if guard.check_and_mark(key):     # 原子:首次返回 True(执行),重复返回 False(跳过)
+    do_the_work()
+```
+
+**已接入:** `ChannelDispatcher.handle` 自动按 `channel+message_id+sender` 去重;无 message_id 的消息退化为"渠道+发送者+内容+10秒时间窗"兜底。
+
+**设计要点:**
+- `check_and_mark` 在同一把锁里完成查重+标记(防并发重发都去执行,50线程压测验证恰好1个成功)
+- TTL 过期清理 + 容量上限 LRU 淘汰(防无限膨胀)
+- 可选落盘(原子替换写),跨进程重启仍识别"处理过了"
+
+---
+
+## 二、重启恢复(Restart Recovery)— 已生效
+
+**解决:** 长任务(多 Agent 链、财务分析)跑到一半进程崩了/重启,任务凭空消失,记忆可能留下半完成的脏数据。
+
+**原理:** 启动时主动识别"上次还在进行、但持有它的进程已不在"的任务,**诚实标记为中断**,而不是装无事。契合 Foxclaw"可审计、可信"的定位。
+
+**核心接口**(`foxclaw/core/recovery.py`):
+```python
+from foxclaw.core.recovery import RestartRecovery
+
+rec = RestartRecovery(log_path="data/task_log.jsonl")
+rec.task_started(task_id, description)    # 任务开始(落 in_progress)
+rec.task_finished(task_id, status="done")  # 结束(done/failed)
+interrupted = rec.scan_interrupted()       # 启动时扫描:返回被中断的任务列表
+```
+
+**已接入:** `Foxclaw` 启动时自动扫描,检测到中断任务会打印提示;主管任务经 base 模板的
+生命周期钩子(`_on_session_started`/`_on_task_settled`,P1-1)自动记录开始/结束
+(正常终态标 done、未兜底异常标 failed;`run_task` 与 `run_task_stream` 两条路径都记账)。
+
+**设计要点:**
+- **boot_id 防 pid 复用**:每次启动生成唯一 ID,判据是"非本次启动的 in_progress 任务=被中断"。比单纯靠 pid 可靠——pid 会被 OS 复用,旧任务的 pid 被新进程占用会导致漏判。
+- JSONL 追加写 + fsync(崩溃安全:单行 append 原子,损坏行自动跳过)
+- `compact_log` 防日志无限膨胀
+
+---
+
+## 三、工具循环检测(Loop Detection)— 已生效
+
+**解决:** 断路器管"失败",但管不了"无进展死循环"——Agent 不报错却陷入重复/横跳/轮询卡死,白烧 token。
+
+**原理:** 监控工具调用历史,检测三种循环模式,多级阈值预警→熔断。
+
+**核心接口**(`foxclaw/harness/loop_detection.py`):
+```python
+from foxclaw.harness.loop_detection import ToolLoopDetector
+
+det = ToolLoopDetector(warning=6, critical=12, circuit_break=20)
+verdict = det.record(tool_name, args, result)   # 每次工具调用后
+if verdict.stuck:
+    print(verdict.detector, verdict.message)     # repeat/ping_pong/no_progress
+if det.should_abort():
+    abort()                                       # 达熔断阈值
+```
+
+**已接入:** `SkillAdapter` 每次工具调用后自动检测,卡死时在结果上附 `loop_warning` 并触发 `on_loop` 钩子。
+
+**三种模式:** `repeat`(同调用连续重复)、`ping_pong`(两调用交替)、`no_progress`(轮询结果无变化,优先级最高,语义最精确)。
+
+---
+
+## 四、上下文压缩(Compaction)— 基础设施
+
+**解决:** 长对话撑爆上下文窗口。
+
+**原理:** 渐进降级压缩,绝不崩——LLM 完整摘要 → 排除超大消息的部分摘要 → 截断兜底。始终保留系统提示 + 最近 N 轮 + 关键标识符(ID/金额)。
+
+**核心接口**(`foxclaw/core/compaction.py`):
+```python
+from foxclaw.core.compaction import Compactor
+
+c = Compactor(router=model_router, max_tokens=6000, keep_recent=4)
+if c.needs_compaction(messages):
+    result = c.compact(messages)     # result.messages 是压缩后的列表
+```
+
+**设计要点:** 压缩后校验是否真变小(省不到 10% 就放弃,method=`skipped_ineffective`),避免系统消息过大时压缩反而变大。`router=None` 时直接走截断兜底。
+
+---
+
+## 五、生命周期钩子标准化(Hooks)— 基础设施
+
+**解决:** 钩子点命名零散、阻断权不清晰。
+
+**原理:** 标准生命周期钩子 + 明确的阻断权 + 向后兼容。
+
+**标准钩子点**(`foxclaw/skills/hooks_spec.py`):
+- 会话级:`session_start` → `agent_start` → `agent_end` → `session_end`
+  - `agent_start`(别名 **`pre_reasoning`**)/ `agent_end`(别名 **`task_complete`**)由**认知管线 `run_task`** 触发(E2);`agent_start` 可返回 `additional_context` 注入本次推理(非阻断)。`session_start/end` 由 AHS skill 编排链触发。
+- 工具级:`before_tool_call`(唯一可阻断)→ `after_tool_call` / `on_error` / `on_loop`
+- 消息级:`before_message_write`
+
+```python
+from foxclaw.skills.lifecycle import HookManager
+hm = HookManager()
+hm.register("before_tool_call", my_hook)    # 旧名 pre_skill 也兼容,自动规整
+```
+
+**设计要点:** 只有 `before_tool_call` 有阻断权(返回 `{block:True}` 生效);旧名(pre_skill/post_skill)自动规整为标准名且互通;非法钩子名会记警告(防拼错静默失效)。
+
+---
+
+## 六、干预队列(Steering Queue)— 基础设施(为并行预留)
+
+**解决:** 并行子 Agent 的结果如何安全回收——不丢、不重复。
+
+**原理:** 租约机制。当前多 Agent 顺序执行用不上(直接收集即可);这是为**未来并行子 Agent** 预留的基础设施。
+
+**核心接口**(`foxclaw/core/steering_queue.py`):
+```python
+from foxclaw.core.steering_queue import SteeringQueue
+
+q = SteeringQueue(lease_seconds=30)
+q.publish(requester, source_agent, payload)   # 子任务完成入队
+items = q.lease(requester)                      # 消费者租走(不会被重复租)
+q.ack(item.item_id, item.lease_id)             # 确认处理完移除
+# 过期未 ack 的项自动回到 pending(主任务崩溃兜底)
+# 顺序场景便捷:q.drain(requester) 一次性取走(尊重租约,跳过被租用项)
+```
+
+**设计要点:** 锁内挑选+标记(并发不重复租用);租约过期自动重入队(结果不丢);ack 校验 lease_id(防过期租约误删别人重新租走的项)。
+
+---
+
+## 测试
+
+全部纳入回归(`python tests/run_all.py`):
+- `test_governance.py` — 六项治理能力(幂等并发、boot_id 防复用、租约不重复等)
+- `test_channels.py` — 渠道适配器 + 闭环 + 幂等去重
+
+---
+
+## 设计原则小结
+
+这组能力反复体现几个原则,可供后续开发参考:
+
+- **操作要校验是否真达到目的**:压缩后检查真变小了吗、幂等并发下真只执行一次吗——不假设操作一定有效。
+- **静默失效最危险**:拼错钩子名、解密缺库、消息处理失败被吞——都要让问题可见(警告/last_error),而非默默不工作。
+- **崩溃后不装没事**:重启恢复主动交代中断的任务,契合"可信"定位。
+- **别只信 pid**:进程恢复要用 boot_id 这类不复用的标识,pid 会被 OS 复用。
+- **便捷接口别破坏核心保证**:drain 要尊重租约,否则破坏"不重复"。