foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/core/steering_queue.py

@@ -0,0 +1,153 @@
+"""
+Foxclaw Core — 运行中干预队列 (Steering Queue)
+
+借鉴 OpenClaw 的"租约队列"原理,适配 Foxclaw。解决的问题:
+  子任务完成的结果,如何安全地回收给主任务——
+  · 不丢:主任务崩了/没及时取,结果不能消失(租约过期 → 重新入队)
+  · 不重复:已被某个消费者租走的结果,不会被另一个消费者再拿一次
+
+当前用途:多 Agent 顺序执行其实用不上(直接收集即可)。
+设计目标:为**未来并行子 Agent**预留——主管并行派发多个子任务,
+各自完成时间不定,本队列负责"完成一个安全回收一个,不丢不重"。
+
+租约(Lease)机制:
+  · publish:子任务完成 → 结果入队(pending)
+  · lease:消费者租走一批结果(标记 leased + 租约到期时间),拿去注入主任务
+  · ack:消费者确认处理完 → 结果移除
+  · 过期未 ack 的 leased 项 → 自动回到 pending(主任务崩溃/超时的兜底)
+"""
+from __future__ import annotations
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SteeringItem:
+    item_id: str
+    requester: str                 # 谁在等这个结果(主任务/会话标识)
+    source_agent: str              # 哪个子 Agent 产出的
+    payload: dict                  # 结果内容
+    created: float = field(default_factory=time.time)
+    leased_until: float = 0.0      # 0 = 未租出;>0 = 租约到期时间戳
+    lease_id: str = ""             # 当前租约持有者标识
+
+    @property
+    def is_leased(self) -> bool:
+        return self.leased_until > time.time()
+
+    def to_dict(self) -> dict:
+        return {"item_id": self.item_id, "requester": self.requester,
+                "source_agent": self.source_agent, "payload": self.payload,
+                "created": self.created, "leased": self.is_leased}
+
+
+class SteeringQueue:
+    """租约队列。线程安全,支持多消费者并发租取不重复。"""
+
+    def __init__(self, lease_seconds: float = 30.0):
+        self.lease_seconds = lease_seconds
+        self._items: dict[str, SteeringItem] = {}
+        self._lock = threading.RLock()
+
+    def publish(self, requester: str, source_agent: str, payload: dict) -> str:
+        """子任务完成 → 结果入队。返回 item_id。"""
+        with self._lock:
+            item_id = uuid.uuid4().hex[:16]
+            self._items[item_id] = SteeringItem(
+                item_id=item_id, requester=requester,
+                source_agent=source_agent, payload=payload)
+            return item_id
+
+    def lease(self, requester: str = None, max_items: int = 10) -> list[SteeringItem]:
+        """租走一批待处理结果(可按 requester 过滤)。
+
+        原子地:挑出未被租用(或租约已过期)的项,标记为 leased,返回。
+        同一项不会被两个消费者同时租到(锁内完成挑选+标记)。
+        """
+        with self._lock:
+            self._reclaim_expired()
+            now = time.time()
+            leased = []
+            lease_id = uuid.uuid4().hex[:12]
+            for item in self._items.values():
+                if len(leased) >= max_items:
+                    break
+                if item.is_leased:
+                    continue
+                if requester is not None and item.requester != requester:
+                    continue
+                item.leased_until = now + self.lease_seconds
+                item.lease_id = lease_id
+                leased.append(item)
+            return leased
+
+    def ack(self, item_id: str, lease_id: str = None) -> bool:
+        """消费者确认处理完 → 移除该项。
+
+        校验 lease_id:只有持有当前租约的消费者能 ack(防止过期租约误删
+        已被别人重新租走的项)。lease_id=None 时跳过校验(兼容简单场景)。
+        """
+        with self._lock:
+            item = self._items.get(item_id)
+            if item is None:
+                return False
+            if lease_id is not None and item.lease_id != lease_id:
+                return False        # 租约不匹配(可能已过期被别人租走)
+            del self._items[item_id]
+            return True
+
+    def nack(self, item_id: str):
+        """消费者放弃处理 → 立即释放租约,回到 pending(可被重新租取)。"""
+        with self._lock:
+            item = self._items.get(item_id)
+            if item:
+                item.leased_until = 0.0
+                item.lease_id = ""
+
+    def _reclaim_expired(self):
+        """过期未 ack 的 leased 项 → 回到 pending(主任务崩溃/超时的兜底)。"""
+        now = time.time()
+        for item in self._items.values():
+            if 0 < item.leased_until <= now:
+                item.leased_until = 0.0
+                item.lease_id = ""
+
+    def pending_count(self, requester: str = None) -> int:
+        """待处理(未被有效租用)的项数。"""
+        with self._lock:
+            self._reclaim_expired()
+            return sum(1 for it in self._items.values()
+                       if not it.is_leased
+                       and (requester is None or it.requester == requester))
+
+    def stats(self) -> dict:
+        with self._lock:
+            self._reclaim_expired()
+            total = len(self._items)
+            leased = sum(1 for it in self._items.values() if it.is_leased)
+            return {"total": total, "leased": leased, "pending": total - leased,
+                    "lease_seconds": self.lease_seconds}
+
+    def drain(self, requester: str) -> list[dict]:
+        """便捷方法(顺序场景用):取出某 requester 的待处理结果并清空。
+
+        适合"主任务等所有子任务完成后一次性收集"的顺序模式。
+        尊重租约:**跳过正被 lease 租用的项**,避免与 lease/ack 混用时
+        同一结果被处理两次(drain 拿一次 + 租约消费者再拿一次)。
+        """
+        with self._lock:
+            self._reclaim_expired()
+            out = []
+            to_del = []
+            for item_id, item in self._items.items():
+                if item.requester != requester:
+                    continue
+                if item.is_leased:
+                    continue        # 正被租用 → 留给租约消费者,drain 不碰
+                out.append(item.payload)
+                to_del.append(item_id)
+            for item_id in to_del:
+                del self._items[item_id]
+            return out

package/python/foxclaw/core/system_bus.py

@@ -0,0 +1,84 @@
+"""
+系统事件总线 (SystemBus)
+
+进程内发布订阅总线,用于系统级事件流转(执行→审计→记忆)。
+借鉴 Codex 版 Foxclaw 的 SystemBus,提升为本项目的全局事件中枢。
+
+与 HarnessEventBus 的区别:HarnessEventBus 局限于单个 Agent 的 Harness 内部;
+SystemBus 是系统级的,跨 Agent / 跨模块,且保留事件历史供审计回放。
+"""
+from __future__ import annotations
+import time
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class BusMessage:
+    channel: str
+    payload: dict
+    ts: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        return {"channel": self.channel, "payload": self.payload, "ts": self.ts}
+
+
+class SystemBus:
+    """系统级发布订阅总线。
+
+    【P0·统一事件脊柱】SystemBus 现已退化为 EventSpine 的**薄门面**:系统级事件
+    与 harness 事件汇入同一条脊柱,被同一个 WS 投影统一观测(修复"truth/process
+    到不了前端")。对既有消费者(TruthPipeline/ProcessManager/CognitiveState/主管分发)
+    零改动:publish/subscribe/history 签名不变;handler 收到的 Event 与旧 BusMessage
+    同形(都有 .channel/.payload/.to_dict())。
+
+    【P3-6/P4-1】subscribe/history 加 exact 参数,语义显式化:
+      · exact=False(默认):前缀匹配(EventSpine 原生行为)。订阅 "execution.completed"
+        会同时收到 "execution.completed" 和 "execution.completed.extra"(如果有)。
+        旧版独立 SystemBus 是精确匹配,门面化后语义悄悄变了——精确 channel 名的
+        订阅点应显式传 exact=True,前缀意图保持默认。
+      · exact=True:包一层过滤,只放行 topic 完全相等的事件(与旧版语义一致)。
+
+    【P4-1】调用点审查结论(grep `.subscribe(` 全仓):
+      ✓ truth_pipeline.py ×3(execution.completed/trace.recorded/truth.appended)→ exact=True
+      ✓ foxclaw/__init__.py(truth.appended → TruthCrystallizer)→ exact=True
+      ✓ cognitive/state.py ×2(execution.completed/memory.updated)→ exact=True
+      · cognitive/state.py(task.lifecycle)→ 前缀意图(注释明示),保持 exact=False
+      · core/audit_sink.py(memory.shared.write)→ 直接持 spine 引用,不经本门面,不在范围
+      · knowledge/__init__.py → HKC 自有 event bus,非本总线,不在范围
+    """
+
+    def __init__(self, history_limit: int = 500, spine=None):
+        if spine is None:
+            from ..kernel.spine import EventSpine
+            spine = EventSpine(history_limit=history_limit)
+        self.spine = spine
+
+    def subscribe(self, channel: str, handler: Callable, exact: bool = False):
+        """订阅 channel。
+
+        exact=False(默认):前缀匹配。subscribe("execution") 收到
+            execution.completed / execution.failed 等。
+        exact=True:精确匹配。subscribe("execution.completed", exact=True)
+            只收到 topic 完全等于 "execution.completed" 的事件。
+        """
+        if exact:
+            def _exact_handler(msg):
+                if getattr(msg, "topic", None) == channel:
+                    handler(msg)
+            self.spine.subscribe(channel, _exact_handler)
+        else:
+            self.spine.subscribe(channel, handler)
+
+    def publish(self, channel: str, payload: dict):
+        return self.spine.publish(channel, payload, source="system_bus")
+
+    def history(self, channel: str = None, limit: int = 50,
+                exact: bool = False) -> list:
+        """历史事件(dict 列表)。exact=True 时只返回 topic 完全匹配的事件
+        (默认前缀匹配,与 EventSpine 原生一致)。"""
+        events = self.spine.history(channel, limit)
+        if exact and channel:
+            events = [e for e in events
+                      if (e.get("topic") or e.get("channel")) == channel]
+        return events

package/python/foxclaw/core/thought_chain.py

@@ -0,0 +1,318 @@
+"""
+ThoughtChain — 带 Harness 标注的推理图
+每个节点是一个推理步骤，边是因果依赖
+Harness 校验结果作为节点属性附着其上
+"""
+
+import os
+import sqlite3
+import json
+import uuid
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from dataclasses import dataclass, asdict
+from typing import Literal, Optional
+from pathlib import Path
+
+
+NodeType = Literal[
+    "goal",        # 目标基线节点（根）
+    "reasoning",   # 推理步骤
+    "memory_retrieval",  # 记忆检索
+    "tool_intent", # 工具意图
+    "tool_use",    # 工具实际调用（augment.py 已在用；此前漏登记，类型面是欠账）
+    "plan",        # 显式计划（steps/flow 落在 metadata，供回显与审计）
+    "decision",    # 行动决策
+    "policy_update",  # Policy 候选更新
+    "consolidation",  # 记忆巩固写回
+    "reflection",  # 执行后反思
+]
+
+HarnessStatus = Literal["BASELINE", "PASS", "WARN", "BLOCK", "PENDING", "REGRESSION"]
+
+
+@dataclass
+class ThoughtNode:
+    """ThoughtChain 的基本单元"""
+    id: str
+    session_id: str
+    agent_id: str
+    type: NodeType
+    content: str
+    conf: float                        # 置信度 0.0-1.0
+    mem_refs: list[str]               # 引用的 HMR 记忆 ID
+    parent_ids: list[str]             # 父节点 ID（因果依赖）
+    harness_status: HarnessStatus
+    harness_reason: Optional[str]     # BLOCK/WARN 时的原因
+    harness_delta: Optional[float]    # 目标漂移量
+    dominant_dim: Optional[str]       # 主导漂移维度
+    tool_name: Optional[str]          # 如果是 tool_intent 节点
+    entities: list[str]              # 涉及的实体集合
+    timestamp: str
+    metadata: dict
+
+    @classmethod
+    def create(
+        cls,
+        session_id: str,
+        agent_id: str,
+        type: NodeType,
+        content: str,
+        conf: float = 1.0,
+        mem_refs: list[str] = None,
+        parent_ids: list[str] = None,
+        tool_name: str = None,
+        entities: list[str] = None,
+        metadata: dict = None,
+    ) -> "ThoughtNode":
+        return cls(
+            id=f"tn_{uuid.uuid4().hex[:12]}",
+            session_id=session_id,
+            agent_id=agent_id,
+            type=type,
+            content=content,
+            conf=conf,
+            mem_refs=mem_refs or [],
+            parent_ids=parent_ids or [],
+            harness_status="PENDING",
+            harness_reason=None,
+            harness_delta=None,
+            dominant_dim=None,
+            tool_name=tool_name,
+            entities=entities or [],
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            metadata=metadata or {},
+        )
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ThoughtNode":
+        return cls(**d)
+
+
+class ThoughtChain:
+    """
+    ThoughtChain 存储与查询引擎
+    底层使用 SQLite，接口设计为对外标准化可替换
+    """
+
+    def __init__(self, db_path: str = "./foxclaw_data/thoughtchain.db"):
+        self.db_path = Path(db_path).resolve()
+        os.makedirs(self.db_path.parent, exist_ok=True)
+        self._init_db()
+
+    def _init_db(self):
+        with self._conn() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS thought_nodes (
+                    id TEXT PRIMARY KEY,
+                    session_id TEXT NOT NULL,
+                    agent_id TEXT NOT NULL,
+                    type TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    conf REAL NOT NULL,
+                    mem_refs TEXT NOT NULL,
+                    parent_ids TEXT NOT NULL,
+                    harness_status TEXT NOT NULL,
+                    harness_reason TEXT,
+                    harness_delta REAL,
+                    dominant_dim TEXT,
+                    tool_name TEXT,
+                    entities TEXT NOT NULL,
+                    timestamp TEXT NOT NULL,
+                    metadata TEXT NOT NULL
+                )
+            """)
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_session ON thought_nodes(session_id)")
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_agent ON thought_nodes(agent_id)")
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_harness ON thought_nodes(harness_status)")
+
+    @contextmanager
+    def _conn(self):
+        """新建一条 SQLite 连接(每次调用即建即弃,不跨线程复用连接对象)。
+
+        并发加固:ThoughtChain 是**五个 Agent 共享**的审计存储,而写入发生在
+        `_call_llm` 的 `asyncio.to_thread` 工作线程 + FastAPI 请求线程里,必然跨线程并发写。
+        SQLite 默认 busy_timeout=0,锁竞争时会立刻抛 `OperationalError: database is locked`。
+          · timeout=5.0    —— 即 busy_timeout,写者遇锁最多等 5s 而非立刻报错;
+          · journal_mode=WAL —— 单写多读、读写不互斥,大幅降低锁竞争(审计读多写多)。
+        WAL 是数据库级持久设置,重复设置幂等无害。
+
+        生命周期语义:`with self._conn() as conn:` 退出时——正常则 commit,异常则
+        rollback,并**无论正常/异常都 close**。不能依赖 sqlite3.Connection 自带的
+        `with`(它退出只 commit/rollback 不 close,WAL 的 -wal/-shm 句柄会残留,
+        Windows 上删库会 WinError 32);也不能只用 closing()(它只 close 不 commit,
+        会把 INSERT/UPDATE 回滚导致并发写全丢)。
+        """
+        conn = sqlite3.connect(self.db_path, timeout=5.0)
+        try:
+            conn.execute("PRAGMA journal_mode=WAL")
+        except sqlite3.OperationalError:
+            pass  # 个别文件系统不支持 WAL(如网络盘)→ 退回默认日志模式,timeout 仍生效
+        try:
+            yield conn
+            conn.commit()
+        except BaseException:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def add_node(self, node: ThoughtNode) -> ThoughtNode:
+        """写入节点，返回写入后的节点（Harness 标注前状态）"""
+        with self._conn() as conn:
+            conn.execute("""
+                INSERT INTO thought_nodes VALUES (
+                    :id, :session_id, :agent_id, :type, :content, :conf,
+                    :mem_refs, :parent_ids, :harness_status, :harness_reason,
+                    :harness_delta, :dominant_dim, :tool_name, :entities,
+                    :timestamp, :metadata
+                )
+            """, {
+                **node.to_dict(),
+                "mem_refs": json.dumps(node.mem_refs),
+                "parent_ids": json.dumps(node.parent_ids),
+                "entities": json.dumps(node.entities),
+                "metadata": json.dumps(node.metadata),
+            })
+        return node
+
+    def update_harness(
+        self,
+        node_id: str,
+        status: HarnessStatus,
+        reason: str = None,
+        delta: float = None,
+        dominant_dim: str = None,
+    ):
+        """Harness 校验完成后更新节点标注"""
+        with self._conn() as conn:
+            conn.execute("""
+                UPDATE thought_nodes
+                SET harness_status=?, harness_reason=?, harness_delta=?, dominant_dim=?
+                WHERE id=?
+            """, (status, reason, delta, dominant_dim, node_id))
+
+    def get_node(self, node_id: str) -> Optional[ThoughtNode]:
+        with self._conn() as conn:
+            row = conn.execute(
+                "SELECT * FROM thought_nodes WHERE id=?", (node_id,)
+            ).fetchone()
+        return self._row_to_node(row) if row else None
+
+    def get_chain(self, session_id: str, agent_id: str = None) -> list[ThoughtNode]:
+        """获取一个会话的完整推理链，按时间排序"""
+        with self._conn() as conn:
+            if agent_id:
+                rows = conn.execute(
+                    "SELECT * FROM thought_nodes WHERE session_id=? AND agent_id=? ORDER BY timestamp",
+                    (session_id, agent_id)
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM thought_nodes WHERE session_id=? ORDER BY timestamp",
+                    (session_id,)
+                ).fetchall()
+        return [self._row_to_node(r) for r in rows]
+
+    def get_blocked_nodes(self, agent_id: str = None, limit: int = 50) -> list[ThoughtNode]:
+        """获取被 Harness 截断的节点，用于审计"""
+        with self._conn() as conn:
+            if agent_id:
+                rows = conn.execute(
+                    "SELECT * FROM thought_nodes WHERE harness_status='BLOCK' AND agent_id=? ORDER BY timestamp DESC LIMIT ?",
+                    (agent_id, limit)
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM thought_nodes WHERE harness_status='BLOCK' ORDER BY timestamp DESC LIMIT ?",
+                    (limit,)
+                ).fetchall()
+        return [self._row_to_node(r) for r in rows]
+
+    def search_nodes(self, keyword: str, agent_id: str = None,
+                     limit: int = 20) -> list[ThoughtNode]:
+        """按关键词在推理节点内容里检索(LIKE 子串匹配)。供 HSR 的 AgentSourcePort
+        把「各 Agent 想过/判过什么」连通进内部搜索。只读。"""
+        kw = (keyword or "").strip()
+        if not kw:
+            return []
+        like = f"%{kw}%"
+        with self._conn() as conn:
+            if agent_id:
+                rows = conn.execute(
+                    "SELECT * FROM thought_nodes WHERE content LIKE ? AND agent_id=? "
+                    "ORDER BY timestamp DESC LIMIT ?", (like, agent_id, limit)
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM thought_nodes WHERE content LIKE ? "
+                    "ORDER BY timestamp DESC LIMIT ?", (like, limit)
+                ).fetchall()
+        return [self._row_to_node(r) for r in rows]
+
+    def get_delta_trend(self, agent_id: str, limit: int = 100) -> list[dict]:
+        """获取漂移趋势数据，用于前端可视化"""
+        with self._conn() as conn:
+            rows = conn.execute("""
+                SELECT timestamp, harness_delta, harness_status, dominant_dim
+                FROM thought_nodes
+                WHERE agent_id=? AND harness_delta IS NOT NULL
+                ORDER BY timestamp DESC LIMIT ?
+            """, (agent_id, limit)).fetchall()
+        return [
+            {"timestamp": r[0], "delta": r[1], "status": r[2], "dim": r[3]}
+            for r in rows
+        ]
+
+    def get_summary(self, agent_id: str) -> dict:
+        """获取 Agent 的 ThoughtChain 健康摘要"""
+        with self._conn() as conn:
+            total = conn.execute(
+                "SELECT COUNT(*) FROM thought_nodes WHERE agent_id=?", (agent_id,)
+            ).fetchone()[0]
+            blocked = conn.execute(
+                "SELECT COUNT(*) FROM thought_nodes WHERE agent_id=? AND harness_status='BLOCK'",
+                (agent_id,)
+            ).fetchone()[0]
+            warned = conn.execute(
+                "SELECT COUNT(*) FROM thought_nodes WHERE agent_id=? AND harness_status='WARN'",
+                (agent_id,)
+            ).fetchone()[0]
+            avg_conf = conn.execute(
+                "SELECT AVG(conf) FROM thought_nodes WHERE agent_id=? AND harness_status='PASS'",
+                (agent_id,)
+            ).fetchone()[0] or 0.0
+            avg_delta = conn.execute(
+                "SELECT AVG(harness_delta) FROM thought_nodes WHERE agent_id=? AND harness_delta IS NOT NULL",
+                (agent_id,)
+            ).fetchone()[0] or 0.0
+        return {
+            "agent_id": agent_id,
+            "total_nodes": total,
+            "blocked_nodes": blocked,
+            "warned_nodes": warned,
+            "block_rate": blocked / total if total > 0 else 0.0,
+            "avg_confidence": round(avg_conf, 3),
+            "avg_delta": round(avg_delta, 3),
+        }
+
+    def _row_to_node(self, row) -> ThoughtNode:
+        cols = [
+            "id", "session_id", "agent_id", "type", "content", "conf",
+            "mem_refs", "parent_ids", "harness_status", "harness_reason",
+            "harness_delta", "dominant_dim", "tool_name", "entities",
+            "timestamp", "metadata"
+        ]
+        d = dict(zip(cols, row))
+        # JSON 字段容错:单行某字段损坏时降级为默认值,而非让整个审计链读取崩溃。
+        # 审计系统的可靠性要求"一条坏数据不拖垮全部"。
+        for field, default in (("mem_refs", []), ("parent_ids", []),
+                               ("entities", []), ("metadata", {})):
+            try:
+                d[field] = json.loads(d[field])
+            except (json.JSONDecodeError, TypeError):
+                d[field] = default
+        return ThoughtNode(**d)