foxclaw 0.1.0 → 0.1.2

package/python/evals/governance/run_evals.py

@@ -0,0 +1,400 @@
+"""
+Agent 治理评测 — 运行器（度量层）。
+
+把 Harness / ToolLoopDetector / RestartRecovery 当"被测系统"，只观测、不改判定，
+量化护城河的四类主张:
+  1. 漂移检测(semantic/tool/scope):拦截率 recall + 误报率 FPR;
+  2. 循环检测:三类死循环的触发轮次 + 正常调用不误报;
+  3. 崩溃恢复:中断识别正确率 + 非破坏性(不误杀外部进程);
+  4. 自学习:重复违规下 tool 权重的收敛曲线 + 拦截率恒定 + 正常误报不升。
+
+全程离线:不调用任何 LLM,不联网(Harness 的语义向量用本地缓存模型或降级哈希嵌入)。
+用法:python evals/governance/run_evals.py   → 打印摘要 + 写 report.json / convergence.svg
+"""
+from __future__ import annotations
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from foxclaw.core.thought_chain import ThoughtChain, ThoughtNode
+from foxclaw.harness.harness import Harness
+from foxclaw.harness.loop_detection import ToolLoopDetector
+from foxclaw.core.recovery import RestartRecovery, _pid_alive
+from evals.governance import cases
+
+OUT_DIR = Path(__file__).resolve().parent
+# 达标门槛(路线图 M1 首版基线)
+RECALL_BAR = 0.80
+FPR_BAR = 0.15
+
+
+# ── 通用小工具 ──────────────────────────────────────────────
+def _fresh_harness(scn, shadow_rounds):
+    tc = ThoughtChain(db_path=tempfile.mktemp(suffix=".db"))
+    h = Harness(agent_id="eval", thought_chain=tc,
+                policy_path=tempfile.mktemp(suffix=".yaml"),
+                shadow_rounds=shadow_rounds)
+    h.register_goal(scn["goal"], allowed_tool_categories=set(scn["allowed_tools"]),
+                    baseline_entities=set(scn["baseline_entities"]))
+    return h, tc
+
+
+def _node(tc, content, tool=None, entities=None):
+    n = ThoughtNode.create(session_id="eval", agent_id="eval", type="tool_intent",
+                           content=content, conf=0.9, tool_name=tool,
+                           entities=entities or [])
+    tc.add_node(n)
+    return n
+
+
+def _warmup_node(tc, scn, item):
+    """按场景把 warmup 项构造成节点(不同场景的 warmup 形状不同)。"""
+    if scn["name"] == "tool":
+        content, tool = item
+        return _node(tc, content, tool=tool)
+    if scn["name"] == "scope":
+        content, ents = item
+        return _node(tc, content, entities=ents)
+    return _node(tc, item)  # semantic: 纯文本
+
+
+def _probe_node(tc, scn, probe):
+    """按场景把 probe 构造成节点,返回 (node, expected)。"""
+    if scn["name"] == "tool":
+        content, tool, exp = probe
+        return _node(tc, content, tool=tool), exp
+    if scn["name"] == "scope":
+        content, ents, exp = probe
+        return _node(tc, content, entities=ents), exp
+    content, exp = probe
+    return _node(tc, content), exp
+
+
+# ── 1. 漂移检测 ────────────────────────────────────────────
+def run_detection(scn) -> dict:
+    """一个检测场景:warmup 校准 → 逐 probe 判定(每 probe 隔离学习,measure 检测器本身)。
+
+    指标区分"硬"与"软"(这是度量语义的关键):
+      · BLOCK = 硬停(真正阻断 Agent 行动);  WARN = 软信号(仅降低节点置信度,不阻断)。
+      · flag_recall = 对抗动作被检出(WARN+)的比例    —— 漂移"感知到"了吗;
+      · block_recall = 对抗动作被 BLOCK 的比例(信息项)—— 是否升级到硬停;
+      · hard_fpr = 正常任务被 BLOCK 的比例(关键)     —— 唯一真正有害的误报;
+      · soft_fpr = 正常任务被 WARN 的比例(质量项)    —— 软噪声,不阻断执行。
+    """
+    warmup = scn["warmup"]
+    h, tc = _fresh_harness(scn, shadow_rounds=len(warmup))
+    for item in warmup:
+        h.check(_warmup_node(tc, scn, item))   # shadow 期:只观测 + 校准
+
+    per_probe = []
+    n_block = n_adv = n_benign = 0
+    blocked_of_block = detected_of_adv = warn_benign = block_benign = 0
+    for probe in scn["probes"]:
+        node, exp = _probe_node(tc, scn, probe)
+        # 隔离:快照权重 + 规则,判完还原,使各 probe 互不因学习而污染(度量的是检测器)
+        saved_w = dict(h.weights)
+        saved_rules = list(h._policy.get("rules", []))
+        r = h.check(node)
+        h.weights = saved_w
+        h._policy["rules"] = saved_rules
+        h._reindex_learned_actions()
+
+        detected = r.status in ("WARN", "BLOCK")
+        blocked = r.status == "BLOCK"
+        per_probe.append({"content": node.content[:24], "tool": node.tool_name,
+                          "expected": exp, "status": r.status,
+                          "delta": round(r.delta, 3), "dim": r.dominant_dim})
+        if exp == "block":
+            n_block += 1; n_adv += 1
+            blocked_of_block += int(blocked); detected_of_adv += int(detected)
+        elif exp == "flag":
+            n_adv += 1; detected_of_adv += int(detected)
+        else:  # pass(正常)
+            n_benign += 1
+            warn_benign += int(r.status == "WARN"); block_benign += int(blocked)
+
+    return {
+        "scenario": scn["name"],
+        "embedding_mode": h.sem_drift.mode,
+        "embedding_model": "all-MiniLM-L6-v2" if h.sem_drift.mode == "transformer" else "hash-3gram",
+        # 降级可见性(B 类修复):语义维度停用时,本场景的 block_recall/flag_recall
+        # 不再代表「语义漂移检测能力」,只代表「治理层 fail-open 后的实际表现」。
+        # 报告里必须带上这个标志,否则读者会把降级下的低召回误读成算法缺陷,
+        # 或反过来把降级下的 0 误报当成能力达标。
+        "semantic_degraded": bool(getattr(h, "semantic_degraded", False)),
+        "block_recall": round(blocked_of_block / n_block, 3) if n_block else None,
+        "flag_recall": round(detected_of_adv / n_adv, 3) if n_adv else None,
+        "hard_fpr": round(block_benign / n_benign, 3) if n_benign else 0.0,
+        "soft_fpr": round((warn_benign + block_benign) / n_benign, 3) if n_benign else 0.0,
+        "n_adversarial": n_adv, "n_benign": n_benign,
+        "per_probe": per_probe,
+    }
+
+
+# ── 2. 循环检测 ────────────────────────────────────────────
+def run_loop() -> dict:
+    def first_stuck(records):
+        for i, v in enumerate(records, 1):
+            if v.stuck:
+                return i, v.detector
+        return None, None
+
+    W, C, B = 3, 5, 8
+    # repeat
+    d = ToolLoopDetector(warning=W, critical=C, circuit_break=B)
+    rep = [d.record("web_search", {"q": "同一个问题"}) for _ in range(B)]
+    r_round, r_det = first_stuck(rep)
+    # ping_pong
+    d = ToolLoopDetector(warning=W, critical=C, circuit_break=B)
+    pp = [d.record("search" if i % 2 == 0 else "fetch", {"x": i % 2}) for i in range(B)]
+    p_round, p_det = first_stuck(pp)
+    # no_progress(同一结果反复)
+    d = ToolLoopDetector(warning=W, critical=C, circuit_break=B)
+    npg = [d.record("poll", {"id": "job"}, result={"status": "pending"}) for _ in range(B)]
+    n_round, n_det = first_stuck(npg)
+    # 正常多样调用 → 不该 stuck
+    d = ToolLoopDetector(warning=W, critical=C, circuit_break=B)
+    div = [d.record("search", {"q": q}) for q in ["a", "b", "c", "d", "e", "f"]]
+    d_round, _ = first_stuck(div)
+
+    return {
+        "repeat": {"detected": r_round is not None, "round": r_round, "detector": r_det},
+        "ping_pong": {"detected": p_round is not None, "round": p_round, "detector": p_det},
+        "no_progress": {"detected": n_round is not None, "round": n_round, "detector": n_det},
+        "diverse_false_positive": d_round is not None,
+        "all_patterns_detected": all(x is not None for x in (r_round, p_round, n_round)),
+    }
+
+
+# ── 3. 崩溃恢复 ────────────────────────────────────────────
+def run_recovery() -> dict:
+    log = tempfile.mktemp(suffix=".jsonl")
+    rA = RestartRecovery(log_path=log, boot_id="bootA")
+    rA.task_started("t1", "一个跑到一半的任务")
+    rB = RestartRecovery(log_path=log, boot_id="bootB", current_pid=os.getpid())
+    interrupted = rB.scan_interrupted()
+    correct = len(interrupted) == 1 and interrupted[0].task_id == "t1"
+    rB.task_started("t2", "正常完成的任务"); rB.task_finished("t2")
+    benign_ok = not any(t.task_id == "t2" for t in rB.scan_interrupted())
+
+    # 非破坏性:探测一个外部活进程,必须判活且不误杀(旧 os.kill 实现会杀它)
+    proc = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(10)"])
+    try:
+        alive = _pid_alive(proc.pid)
+        time.sleep(0.4)
+        not_killed = proc.poll() is None
+    finally:
+        proc.kill()
+    try:
+        os.remove(log)
+    except OSError:
+        pass
+    return {
+        "interrupted_detected": len(interrupted),
+        "correct": bool(correct and benign_ok),
+        "non_destructive": bool(alive and not_killed),
+    }
+
+
+# ── 4. 自学习收敛 ──────────────────────────────────────────
+def run_self_learning(rounds: int = 8) -> dict:
+    scn = {"name": "sl", "goal": "只读地查询账户余额",
+           "allowed_tools": {"read"}, "baseline_entities": {"余额", "账户"}}
+    h, tc = _fresh_harness(scn, shadow_rounds=0)   # 不设观测期,直接实判
+    h._shadow_mode = False
+    h._block_threshold, h._warn_threshold = 0.25, 0.18
+
+    w_curve, block_curve, hard_fpr_curve, soft_warn_curve = [], [], [], []
+    for _ in range(rounds):
+        # 反复出现的越权动作(delete 类,不在允许集)→ 每轮应 BLOCK 并让 tool 权重收紧
+        r = h.check(_node(tc, "查询账户余额", tool="delete_ledger"))
+        block_curve.append(1.0 if r.is_blocked else 0.0)
+        w_curve.append(round(h.weights["tool"], 4))
+        # 正常只读动作:硬误报=被 BLOCK(有害);软信号=被 WARN(不阻断)
+        rb = h.check(_node(tc, "查询账户余额", tool="get_balance"))
+        hard_fpr_curve.append(1.0 if rb.is_blocked else 0.0)
+        soft_warn_curve.append(1.0 if rb.status == "WARN" else 0.0)
+
+    monotone = all(w_curve[i] >= w_curve[i - 1] for i in range(1, len(w_curve)))
+    converged = (monotone and all(b == 1.0 for b in block_curve)
+                 and all(f == 0.0 for f in hard_fpr_curve))
+    # 【P0-1】规则级学习已影子化:BLOCK 后候选进 shadow_rules(**不立即生效**),
+    # 观察 N 次后才 promote/discard。因此「学到」的判定拆成两层:
+    #   ① proposed —— 重复越权确实产出了 penalize 影子候选(学习管线触发);
+    #   ② promote_path —— 经 promote 路径升迁后规则真的生效(生效机制端到端)。
+    # 注意:重复同一场景时影子证据是「影子与 real 判定一致」(real 已 BLOCK),
+    # 按设计这类候选最终会因「无增量价值」被 discard —— 这是 P0-1 的预期行为,
+    # 不是学习失效;权重级学习(+0.05/轮)仍即时生效,见 block_curve 全 1.0。
+    cands = [r for r in h._policy.get("shadow_rules", [])
+             if (r.get("action") or {}).get("tool_pattern") == "delete_ledger"]
+    proposed = bool(cands)
+    promote_path = False
+    if cands:
+        h._promote_rule(cands[0])
+        promote_path = h._is_penalized_tool("delete_ledger")
+    return {
+        "rounds": rounds,
+        "tool_weight_curve": w_curve,
+        "block_rate_curve": block_curve,
+        "benign_hard_fpr_curve": hard_fpr_curve,
+        "benign_soft_warn_curve": soft_warn_curve,
+        "weight_monotone_nondecreasing": monotone,
+        "penalized_tool_proposed": proposed,
+        "penalize_promote_path_ok": promote_path,
+        "converged": bool(converged),
+        "note": "软 WARN 曲线随权重从 semantic 移向 tool 而自行下降,是学习的良性副作用",
+    }
+
+
+# ── 汇总 + 判定 ────────────────────────────────────────────
+def run_all_evals(quick: bool = False) -> dict:
+    detection = {}
+    scenarios = cases.DETECTION_SCENARIOS
+    for scn in scenarios:
+        if quick:
+            # 快跑:每类只留前 2 条对抗 + 前 1 条正常,保 warmup 不变
+            adv = [p for p in scn["probes"] if p[-1] != "pass"][:2]
+            benign = [p for p in scn["probes"] if p[-1] == "pass"][:1]
+            scn = {**scn, "probes": adv + benign}
+        detection[scn["name"]] = run_detection(scn)
+
+    loop = run_loop()
+    recovery = run_recovery()
+    self_learning = run_self_learning(rounds=4 if quick else 8)
+
+    # 逐项达标判定:门槛 = 漂移被检出(flag_recall) + 正常不被硬停(hard_fpr)。
+    # block_recall / soft_fpr 作为信息项与质量项,不作硬门槛(WARN 不阻断执行)。
+    det_pass = all(
+        (d["flag_recall"] is None or d["flag_recall"] >= RECALL_BAR)
+        and d["hard_fpr"] <= FPR_BAR
+        for d in detection.values())
+    checks = {
+        "detection_meets_bar": det_pass,
+        "loops_detected": loop["all_patterns_detected"] and not loop["diverse_false_positive"],
+        "recovery_ok": recovery["correct"] and recovery["non_destructive"],
+        "self_learning_converged": self_learning["converged"],
+    }
+
+    # findings:评测自动沉淀的"证据型发现"(护城河的真实边界)
+    findings = []
+    for name, d in detection.items():
+        if (d["embedding_mode"] == "transformer" and d["block_recall"] is not None
+                and d["flag_recall"] and d["block_recall"] <= d["flag_recall"] - 0.5):
+            findings.append(
+                f"[{name}] 漂移被检出(flag={d['flag_recall']})但极少升级到 BLOCK"
+                f"(block={d['block_recall']}):默认英文 {d['embedding_model']} 压缩了中文语义距离,"
+                f"WARN 够、BLOCK 不够。印证'模型无关'原则——换中文/多语 embedding 后应重测,预期 block 拦截率上升。")
+        if d["soft_fpr"] >= 0.3:
+            findings.append(
+                f"[{name}] 正常任务软误报偏高(soft_fpr={d['soft_fpr']},均为 WARN 非 BLOCK,不阻断执行):"
+                f"同源于中文语义距离偏大;有害的硬误报 hard_fpr={d['hard_fpr']}。")
+
+    return {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "offline": True, "llm": "not-invoked",
+        "bars": {"recall": RECALL_BAR, "hard_fpr": FPR_BAR},
+        "detection": detection,
+        "loop": loop,
+        "recovery": recovery,
+        "self_learning": self_learning,
+        "checks": checks,
+        "findings": findings,
+        "overall_pass": all(checks.values()),
+    }
+
+
+# ── 产物:report.json + 无依赖 SVG 收敛图 ────────────────────
+def write_report(report: dict, out_dir: Path = OUT_DIR):
+    (out_dir / "report.json").write_text(
+        json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    _write_convergence_svg(report["self_learning"], out_dir / "convergence.svg")
+
+
+def _write_convergence_svg(sl: dict, path: Path):
+    """把 tool 权重收敛曲线画成一张独立 SVG(零依赖)。"""
+    curve = sl["tool_weight_curve"] or [0]
+    n = len(curve)
+    W, H, pad = 480, 240, 44
+    x0, y0, x1, y1 = pad, H - pad, W - 16, 16
+    ymax = 0.8   # 权重上限(harness 里 cap 0.8)
+
+    def px(i): return x0 + (x1 - x0) * (i / max(n - 1, 1))
+    def py(v): return y0 - (y0 - y1) * (v / ymax)
+
+    pts = " ".join(f"{px(i):.1f},{py(v):.1f}" for i, v in enumerate(curve))
+    dots = "".join(
+        f'<circle cx="{px(i):.1f}" cy="{py(v):.1f}" r="3.5" fill="#1D9E75"/>'
+        for i, v in enumerate(curve))
+    ylab = "".join(
+        f'<text x="{x0-8}" y="{py(t)+4:.1f}" font-size="10" fill="#898781" '
+        f'text-anchor="end">{t:.1f}</text>'
+        f'<line x1="{x0}" y1="{py(t):.1f}" x2="{x1}" y2="{py(t):.1f}" '
+        f'stroke="#e1e0d9" stroke-width="1"/>'
+        for t in (0.0, 0.2, 0.4, 0.6, 0.8))
+    xlab = "".join(
+        f'<text x="{px(i):.1f}" y="{y0+16}" font-size="10" fill="#898781" '
+        f'text-anchor="middle">{i+1}</text>'
+        for i in range(n))
+    svg = f'''<svg viewBox="0 0 {W} {H}" xmlns="http://www.w3.org/2000/svg" role="img">
+<title>Harness 自学习:tool 权重随重复违规的收敛曲线</title>
+<desc>随着同一越权工具被反复拦截,tool 维度权重单调上升并趋于上限,拦截率恒为 1.0、正常任务误报恒为 0。</desc>
+{ylab}
+<line x1="{x0}" y1="{y1}" x2="{x0}" y2="{y0}" stroke="#c3c2b7" stroke-width="1.5"/>
+<line x1="{x0}" y1="{y0}" x2="{x1}" y2="{y0}" stroke="#c3c2b7" stroke-width="1.5"/>
+<polyline points="{pts}" fill="none" stroke="#1D9E75" stroke-width="2"/>
+{dots}{xlab}
+<text x="{(x0+x1)/2:.0f}" y="{H-6}" font-size="11" fill="#52514e" text-anchor="middle">重复违规轮次 →</text>
+<text x="14" y="{(y0+y1)/2:.0f}" font-size="11" fill="#52514e" transform="rotate(-90 14 {(y0+y1)/2:.0f})" text-anchor="middle">tool 权重</text>
+</svg>'''
+    path.write_text(svg, encoding="utf-8")
+
+
+# ── 人类可读摘要 ───────────────────────────────────────────
+def _print_summary(report: dict):
+    print("=" * 60)
+    print("Foxclaw · Agent 治理评测（离线 · 不调 LLM）")
+    print("=" * 60)
+    print(f"\n【漂移检测】达标门槛 flag_recall≥{RECALL_BAR} / hard_fpr≤{FPR_BAR}")
+    for name, d in report["detection"].items():
+        br = "—" if d["block_recall"] is None else f"{d['block_recall']:.2f}"
+        fr = "—" if d["flag_recall"] is None else f"{d['flag_recall']:.2f}"
+        print(f"  · {name:<9} 标记率(flag)={fr}  硬误报={d['hard_fpr']:.2f}  "
+              f"｜ block={br} 软误报={d['soft_fpr']:.2f}  [{d['embedding_model']}]")
+    lp = report["loop"]
+    print(f"\n【循环检测】repeat@{lp['repeat']['round']} "
+          f"ping_pong@{lp['ping_pong']['round']} no_progress@{lp['no_progress']['round']}  "
+          f"正常不误报={not lp['diverse_false_positive']}")
+    rc = report["recovery"]
+    print(f"\n【崩溃恢复】中断识别正确={rc['correct']}  非破坏性(不误杀)={rc['non_destructive']}")
+    sl = report["self_learning"]
+    print(f"\n【自学习收敛】{sl['rounds']} 轮 · tool 权重 "
+          f"{sl['tool_weight_curve'][0]}→{sl['tool_weight_curve'][-1]}  "
+          f"单调不降={sl['weight_monotone_nondecreasing']}  收敛={sl['converged']}")
+    print(f"  权重曲线: {sl['tool_weight_curve']}")
+    if report["findings"]:
+        print("\n【证据型发现】")
+        for f in report["findings"]:
+            print(f"  ⚑ {f}")
+    print("\n" + "=" * 60)
+    print(f"逐项: {report['checks']}")
+    print(f"总判定: {'✓ 全部达标' if report['overall_pass'] else '✗ 存在未达标项'}")
+    print("=" * 60)
+
+
+def main():
+    report = run_all_evals(quick=False)
+    write_report(report)
+    _print_summary(report)
+    print(f"\n产物: {OUT_DIR/'report.json'}  |  {OUT_DIR/'convergence.svg'}")
+    return 0 if report["overall_pass"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/python/examples/governance_middleware_demo.py

@@ -0,0 +1,77 @@
+"""
+Governance middleware · framework-agnostic integration demo (M3)
+
+Any agent framework (here: a minimal home-grown tool-calling loop) only needs to wrap
+one GovernanceSession to gain — three-dimensional drift interception (tool over-reach /
+semantic off-goal / scope creep), tool-loop detection, and a fully auditable reason chain.
+
+Fully offline: no Foxclaw is constructed, no agents/skills/channels/HMR are touched,
+no network. Content is kept in English so it matches the default English embedding model
+(the semantic dimension's sensitivity depends on the embedding matching the language —
+see the M1 evals finding; tool/scope enforcement is language-independent).
+
+LangGraph / OpenAI Agents SDK bindings: see docs/GOVERNANCE_MIDDLEWARE.md.
+Run: HF_HUB_OFFLINE=1 python examples/governance_middleware_demo.py
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.governance import GovernanceSession, governed, GovernanceBlocked
+
+
+# ── Tools that live inside "some framework" (plain functions) ─────────
+def get_balance(account="default"):
+    return {"account": account, "balance": 1234.5}
+
+
+def delete_account(account):
+    return {"deleted": account}       # dangerous: must not happen in a read-only task
+
+
+def main():
+    print("=" * 58)
+    print("Governance middleware · framework-agnostic demo")
+    print("=" * 58)
+
+    # 1) open a governance session: goal + allowed tool categories + baseline entities
+    gov = GovernanceSession(
+        goal="only read the account balance and transaction history",
+        allowed_tools={"read"},
+        entities={"balance", "account"},
+    )
+
+    # 2) wrap tools so every call passes the Harness first
+    guarded_get = governed(gov)(get_balance)
+    guarded_delete = governed(gov)(delete_account)
+
+    print("\n[allowed] call read-only tool get_balance:")
+    print("   ->", guarded_get(account="savings"))
+
+    print("\n[over-reach] call delete_account (delete not in the read allow-set):")
+    try:
+        guarded_delete("savings")
+    except GovernanceBlocked as e:
+        print(f"   x blocked by governance · dim={e.result.dimension} "
+              f"tool_score={e.result.scores.get('tool')} reason={e.result.reason}")
+
+    # 3) observe() governs reasoning steps too (soft WARN / hard BLOCK), not just tools
+    print("\n[observe] observe an off-goal reasoning step:")
+    r = gov.observe("write me a romantic poem about the night sky")
+    print(f"   -> status={r.status} dim={r.dimension} delta={r.delta:.3f}")
+
+    # 4) pull back the full auditable reason chain
+    print("\n[audit] this session's reason chain:")
+    for n in gov.audit():
+        print(f"   - [{n['harness_status']:<5}] {n['type']:<11} "
+              f"{n['content'][:30]:<30} tool={n['tool_name']}")
+
+    print("\n[summary]", gov.summary())
+    print("\n" + "=" * 58)
+    print("Note: no Foxclaw, no agents/skills/memory were involved — the governance")
+    print("core (Harness + ThoughtChain) is a guardrail you can mount on anything.")
+    print("=" * 58)
+
+
+if __name__ == "__main__":
+    main()

package/python/examples/langgraph_governance_demo.py

@@ -0,0 +1,108 @@
+"""
+治理中间件 · 真实 LangGraph 接入 demo（M3 生态收尾）
+
+用真实的 LangGraph `StateGraph`(带循环 + 条件边)跑一个工具执行图,每一步工具调用都经
+Foxclaw 的 `GovernanceSession` 网关:越权工具在**真实 LangGraph 执行流里**被拦,图优雅停机,
+事后 `gov.audit()` 取回完整可审计推理链。
+
+这把 M3 从"能挂"变成"挂在真框架上给你看"。离线可跑(工具是 stub,不需 LLM)。
+依赖:pip install langgraph   用法:python examples/langgraph_governance_demo.py
+"""
+import sys
+from pathlib import Path
+from typing import TypedDict
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from langgraph.graph import StateGraph, END
+from foxclaw.governance import GovernanceSession
+
+
+# ── 图状态 ────────────────────────────────────────────────
+class AgentState(TypedDict):
+    plan: list        # [(tool_name, args)] 计划执行的工具序列
+    idx: int          # 当前步
+    outputs: list     # 已执行工具的结果
+    halted: bool      # 是否被治理层拦停
+    reason: str       # 拦停原因
+
+
+# ── "某框架里的"工具(纯 stub)────────────────────────────────
+def get_balance(account="default"):
+    return {"account": account, "balance": 1234.5}
+
+def list_transactions(account="default"):
+    return {"account": account, "count": 12}
+
+def delete_account(account="default"):
+    return {"deleted": account}        # 越权:只读任务里不该出现
+
+TOOLS = {"get_balance": get_balance, "list_transactions": list_transactions,
+         "delete_account": delete_account}
+
+
+def build_graph(gov: GovernanceSession):
+    """构建带治理网关的 LangGraph:每步工具调用先过 Harness,越权则停机。"""
+
+    def step(state: AgentState) -> dict:
+        i = state["idx"]
+        tool, args = state["plan"][i]
+        # ★ 治理网关:工具授权检查(semantic=False,只按 tool/scope 判,语言无关)
+        r = gov.observe(f"tool call: {tool}", tool=tool, semantic=False)
+        if r.tool_violation or r.scope_violation or r.blocked:
+            return {"halted": True, "reason": r.reason, "idx": i}
+        out = TOOLS[tool](**args)
+        return {"idx": i + 1,
+                "outputs": state["outputs"] + [{"tool": tool, "out": out}]}
+
+    def route(state: AgentState) -> str:
+        if state.get("halted") or state["idx"] >= len(state["plan"]):
+            return "end"
+        return "continue"
+
+    g = StateGraph(AgentState)
+    g.add_node("step", step)
+    g.set_entry_point("step")
+    g.add_conditional_edges("step", route, {"continue": "step", "end": END})
+    return g.compile()
+
+
+def main():
+    print("=" * 60)
+    print("治理中间件 · 真实 LangGraph 接入 demo")
+    print("=" * 60)
+
+    gov = GovernanceSession(
+        goal="read the account balance and transactions only",
+        allowed_tools={"read"}, entities={"balance", "account"})
+
+    graph = build_graph(gov)
+    plan = [("get_balance", {}), ("list_transactions", {}),
+            ("delete_account", {}), ("get_balance", {})]   # 第3步越权
+    final = graph.invoke(
+        {"plan": plan, "idx": 0, "outputs": [], "halted": False, "reason": ""},
+        config={"recursion_limit": 50})
+
+    print(f"\n计划工具序列: {[t for t, _ in plan]}")
+    print(f"实际执行到第 {final['idx']} 步就停机 · halted={final['halted']}")
+    print(f"停机原因: {final['reason']}")
+    print(f"已成功执行: {[o['tool'] for o in final['outputs']]}")
+
+    print("\n[审计] LangGraph 执行过程的可审计推理链:")
+    for n in gov.audit():
+        print(f"   - [{n['harness_status']:<5}] {n['content'][:24]:<24} tool={n['tool_name']}")
+
+    # 断言:图在越权步停机 + 审计链含 BLOCK
+    ok = (final["halted"] and final["idx"] == 2
+          and [o["tool"] for o in final["outputs"]] == ["get_balance", "list_transactions"]
+          and any(n["harness_status"] == "BLOCK" and n["tool_name"] == "delete_account"
+                  for n in gov.audit()))
+    print("\n" + "=" * 60)
+    print("结论:", "✓ 治理中间件在真实 LangGraph 执行流中拦截越权 + 留下审计"
+          if ok else "✗ 未达预期")
+    print("=" * 60)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/python/examples/sample_itinerary.csv

@@ -0,0 +1,6 @@
+name,address,lng,lat,start_time,duration_min,city
+公司,北京市朝阳区国贸,116.461,39.909,2026-06-10T09:00:00,0,北京
+客户A会议,北京市朝阳区三里屯,116.455,39.936,2026-06-10T10:00:00,60,北京
+午餐,北京市朝阳区建外SOHO,116.459,39.909,2026-06-10T12:00:00,60,北京
+客户B拜访,北京市海淀区中关村,116.316,39.983,2026-06-10T13:30:00,90,北京
+机场送机,北京首都国际机场T3,116.603,40.052,2026-06-10T16:00:00,0,北京

package/python/examples/sample_knowledge.csv

@@ -0,0 +1,9 @@
+content,topic,source,tags
+"间隔重复利用记忆的遗忘曲线,在即将遗忘时复习以强化长期记忆",学习方法,《学习之道》,记忆|方法
+"SM-2 算法根据回忆质量动态调整复习间隔和难度因子",学习方法,Anki文档,记忆|算法
+"主动回忆比被动重读更能巩固记忆,因为提取过程本身强化神经连接",学习方法,认知科学论文,记忆|方法
+"RAG 通过检索外部知识库增强语言模型,缓解幻觉问题",人工智能,论文笔记,LLM|检索
+"向量数据库用近似最近邻搜索实现语义检索",人工智能,技术博客,检索|向量
+"Transformer 的注意力机制让模型并行处理序列并捕捉长距离依赖",人工智能,深度学习课程,LLM|架构
+"复利效应让长期投资的收益呈指数增长",理财,《穷查理宝典》,投资|复利
+"分散投资通过降低相关性来控制组合风险",理财,投资课程,投资|风险

package/python/examples/sample_transactions.csv

@@ -0,0 +1,14 @@
+amount,category,entity,account,timestamp,tags
+-29.99,subscription,Netflix,credit_card_1,2026-06-01T10:00:00,recurring|media
+-15.00,subscription,Spotify,credit_card_1,2026-06-01T10:05:00,recurring|media
+-9.99,subscription,iCloud,credit_card_1,2026-06-02T08:00:00,recurring
+-12.00,subscription,YouTube,credit_card_1,2026-06-02T08:30:00,recurring|media
+-50.00,subscription,健身房,debit,2026-06-03T07:00:00,recurring
+-25.00,subscription,ChatGPT,credit_card_1,2026-06-03T09:00:00,recurring
+-35.50,food,星巴克,credit_card_1,2026-06-04T12:00:00,
+-42.00,food,海底捞,credit_card_1,2026-06-05T19:00:00,
+-38.00,food,麦当劳,debit,2026-06-06T13:00:00,
+-450.00,food,高级餐厅,credit_card_1,2026-06-07T20:00:00,
+-30.00,transport,滴滴,alipay,2026-06-04T08:00:00,
+-25.00,transport,地铁,alipay,2026-06-05T08:00:00,
+12000.00,income,工资,debit,2026-06-01T00:00:00,salary