foxclaw 0.1.0 → 0.1.2

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,82 @@
+"""
+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                 # 证据因子(如规则 id / 历史频率 / 预算余量)
+    detail: str = ""            # 具体说明
+    weight: float = 1.0         # 权重(0~1)
+    raw: Any = None             # 原始证据对象(如 PolicyVerdict),供裁决内部使用
+
+    def to_dict(self) -> dict:
+        return {"factor": self.factor, "detail": self.detail, "weight": self.weight}
+
+
+@dataclass
+class ReasonedVerdict:
+    decision: str               # approve | confirm | reject
+    rationale: str              # 裁决说明(人类可读)
+    evidence: list = field(default_factory=list)      # [Evidence]
+    hypotheses: list = field(default_factory=list)    # [str]
+    source: str = "rules"       # rules | llm(哪层做出的裁决)
+
+    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)
+
+    # ── 双层增强的通用工具(v2 ③ Step4:itinerary/learning 复用)────────────
+    @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,147 @@
+"""
+认知状态 (CognitiveState)
+
+把"系统此刻在想什么"显式建模成一个可快照的认知状态。
+借鉴 Codex 版 Foxclaw 的 CognitiveState,适配本项目:不新存一份数据,而是
+作为聚合器 + 事件订阅者,把散落在调度器/进程/记忆/路由里的信号,聚成一张
+"系统当前心智状态"快照。
+
+对齐"认知操作系统"定位:OS 有 system state,认知 OS 该有 cognitive state。
+可驱动前端"系统在想什么"实时面板,也用于调试与回放。
+"""
+from __future__ import annotations
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CognitiveState:
+    """系统当前认知状态快照。随事件总线上的活动自动更新。"""
+
+    active_goal: str = None                          # 当前活跃目标(最近任务)
+    active_agent: str = None                         # 当前处理的 Agent
+    semantic_focus: str = None                       # 语义焦点(调度意图类别)
+    attention_scope: list = field(default_factory=list)   # 注意力范围(关键词)
+    reasoning_depth: float = 0.0                     # 当前推理深度
+    confidence_map: dict = field(default_factory=dict)    # 置信度图(意图/优先级)
+    activated_memories: list = field(default_factory=list)  # 激活的记忆(最近召回/沉淀)
+    last_route: str = None                           # 最近路由倾向
+    active_processes: int = 0                         # 活跃进程数
+    temporal_window: str = "current_turn"            # 时间窗口
+    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]
+            # 去重:已存在则先移除旧的,再插到最前(LRU 式)
+            existing = [m for m in self.activated_memories if m != snippet]
+            self.activated_memories = [snippet] + existing[:4]
+            self.temporal_window = "memory_augmented"
+        self.updated_at = time.time()
+
+    def on_process_change(self, payload: dict, active_count: int = None):
+        """进程状态变更 → 更新活跃进程数。"""
+        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
+        # 先按标点/空格切;若切出的片段仍很长(中文无空格),按 2-4 字滑窗取要点
+        rough = [w for w in re.split(r"[\s,，、。!?:;]", text or "") if len(w) >= 2]
+        out = []
+        for seg in rough:
+            if len(seg) <= 4:
+                out.append(seg)
+            else:
+                # 长片段取首尾 + 中部双字,作为注意力要点
+                out.append(seg[:3])
+                if len(seg) > 6:
+                    out.append(seg[len(seg)//2:len(seg)//2+2])
+                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:
+            # 【P4-1】前两个是精确 channel 名 → exact=True;task.lifecycle 是刻意的前缀
+            # 订阅(收 created/queued/running/... 一族),保持默认前缀匹配。
+            bus.subscribe("execution.completed", self._on_exec, exact=True)
+            bus.subscribe("memory.updated", self._on_mem, exact=True)
+            bus.subscribe("task.lifecycle", self._on_proc)   # Step3:统一生命周期词汇(前缀匹配)
+
+    def _on_exec(self, msg):
+        if msg is None:
+            return
+        with self._lock:
+            self.state.on_execution(getattr(msg, "payload", None))
+
+    def _on_mem(self, msg):
+        if msg is None:
+            return
+        with self._lock:
+            self.state.on_memory_updated(getattr(msg, "payload", None))
+
+    def _on_proc(self, msg):
+        if msg is None:
+            return
+        active = None
+        pm = self.process_manager
+        if pm is not None:
+            # 【深审优化】用 pm 的 O(1) active_count(),免去每次 lifecycle 事件 stats() 遍历
+            # 全部进程(O(n))。旧 pm 无此方法则回退到 stats()(scheduled+running)。
+            if hasattr(pm, "active_count"):
+                active = pm.active_count()
+            else:
+                st = pm.stats().get("by_state", {})
+                active = st.get("scheduled", 0) + st.get("running", 0)
+        with self._lock:
+            self.state.on_process_change(getattr(msg, "payload", None), active)
+
+    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,133 @@
+"""审计 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
+
+#: 首条记录的 prev_hash。用 64 个 0 而不是空串:一眼能看出「这是链头」。
+GENESIS = "0" * 64
+
+#: 从文件尾部回读的字节数:找 tail hash 只需最后一行,64KB 足够容下超长记录。
+_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                      # legacy 段:无链可验,跳过
+                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):  # EventSpine.subscribe 的 handler 形态:handler(event)
+        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