foxclaw 0.1.0 → 0.1.2

package/python/vendor/hkc/hkc_kep/event_bus.py

@@ -0,0 +1,205 @@
+"""
+hkc-kep / event_bus.py
+Knowledge Event Protocol — 事件总线。
+
+v1：进程内同步执行，零依赖。
+v2：可替换为 Redis Pub/Sub，接口不变。
+
+所有事件统一格式：
+{
+    "event_id":  "EVT_00000001",
+    "event":     "knowledge.created",
+    "version":   "1.0",
+    "timestamp": "2025-01-01T00:00:00Z",
+    "source":    "KDE",
+    "payload":   { ... }
+}
+"""
+import json
+import logging
+import sqlite3
+import threading
+
+logger = logging.getLogger(__name__)
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable
+
+
+# ── 事件类型常量 ─────────────────────────────────────────────
+
+class KEPEvents:
+    # KDE 产出
+    KNOWLEDGE_CREATED  = "knowledge.created"
+    KNOWLEDGE_UPDATED  = "knowledge.updated"
+    KNOWLEDGE_MERGED   = "knowledge.merged"
+    KNOWLEDGE_DELETED  = "knowledge.deleted"
+
+    # KEE 产出
+    CONFLICT_DETECTED  = "conflict.detected"
+    CONFLICT_RESOLVED  = "conflict.resolved"
+    CLAIM_STATUS_CHANGED = "claim.status_changed"
+
+    # ACE 产出
+    ABILITY_CREATED    = "ability.created"
+    ABILITY_UPDATED    = "ability.updated"
+
+    # HMR 来源
+    MEMORY_CREATED     = "memory.created"
+    MEMORY_UPDATED     = "memory.updated"
+    MEMORY_DELETED     = "memory.deleted"
+
+    # HAR 来源
+    AGENT_USED_ABILITY = "agent.used_ability"   # Feedback Loop 入口
+
+
+# ── EventBus ─────────────────────────────────────────────────
+
+class EventBus:
+    """
+    线程安全的进程内事件总线。
+    事件审计日志写入 SQLite，方便调试和回放。
+    """
+
+    def __init__(self, db_path: str = ":memory:"):
+        self._lock      = threading.RLock()
+        self._handlers: dict[str, list[Callable]] = defaultdict(list)
+        self._counter   = 0
+
+        # 审计日志
+        log_path = Path(db_path)
+        if db_path != ":memory:":
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+        self._log_db = sqlite3.connect(str(db_path), check_same_thread=False)
+        self._init_log_table()
+
+    def _init_log_table(self):
+        self._log_db.execute("""
+            CREATE TABLE IF NOT EXISTS event_log (
+                event_id   TEXT PRIMARY KEY,
+                event      TEXT NOT NULL,
+                source     TEXT,
+                payload    TEXT,
+                created_at TEXT
+            )
+        """)
+        self._log_db.commit()
+
+    def _gen_id(self) -> str:
+        with self._lock:
+            self._counter += 1
+            return f"EVT_{self._counter:08d}"
+
+    # ── 订阅 ─────────────────────────────────────────────────
+
+    def subscribe(self, event: str, handler: Callable) -> None:
+        """
+        注册事件处理器。
+        同一事件可注册多个处理器，按注册顺序执行。
+        """
+        with self._lock:
+            self._handlers[event].append(handler)
+
+    def unsubscribe(self, event: str, handler: Callable) -> None:
+        with self._lock:
+            handlers = self._handlers.get(event, [])
+            if handler in handlers:
+                handlers.remove(handler)
+
+    # ── 发布 ─────────────────────────────────────────────────
+
+    def publish(self, event_dict: dict) -> str:
+        """
+        发布事件，同步调用所有已注册处理器。
+        返回 event_id。
+        处理器异常不阻断后续处理器执行。
+        """
+        event_id = self._gen_id()
+        event_dict = {
+            "event_id":  event_id,
+            "version":   "1.0",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            **event_dict,
+        }
+
+        event_type = event_dict.get("event", "")
+        with self._lock:
+            handlers = list(self._handlers.get(event_type, []))
+
+        # 写审计日志(处理器不在锁内执行,避免长时间持锁/重入死锁)
+        self._write_log(event_dict)
+
+        # 调用处理器
+        for handler in handlers:
+            try:
+                handler(event_dict)
+            except Exception:
+                # 记录错误但不中断其他处理器
+                logger.error("Handler error for %s", event_type, exc_info=True)
+
+        return event_id
+
+    def _write_log(self, event_dict: dict):
+        try:
+            # 加锁:并发 publish(两个摄入任务)会从多个线程共用这一个连接,
+            # 不加锁 sqlite3 会 "recursive use of cursors"/损坏。与 GraphStore 一致。
+            with self._lock:
+                self._log_db.execute(
+                    "INSERT OR IGNORE INTO event_log "
+                    "(event_id,event,source,payload,created_at) VALUES (?,?,?,?,?)",
+                    (
+                        event_dict.get("event_id"),
+                        event_dict.get("event"),
+                        event_dict.get("source"),
+                        json.dumps(event_dict.get("payload", {})),
+                        event_dict.get("timestamp"),
+                    )
+                )
+                self._log_db.commit()
+        except Exception:
+            pass  # 日志失败不影响主流程
+
+    # ── 查询日志 ─────────────────────────────────────────────
+
+    def recent_events(self, limit: int = 50) -> list[dict]:
+        with self._lock:
+            rows = self._log_db.execute(
+                "SELECT * FROM event_log ORDER BY created_at DESC LIMIT ?",
+                (limit,)
+            ).fetchall()
+        return [
+            {
+                "event_id":  r[0],
+                "event":     r[1],
+                "source":    r[2],
+                "payload":   json.loads(r[3] or "{}"),
+                "created_at": r[4],
+            }
+            for r in rows
+        ]
+
+    def events_by_type(self, event_type: str, limit: int = 20) -> list[dict]:
+        with self._lock:
+            rows = self._log_db.execute(
+                "SELECT * FROM event_log WHERE event=? "
+                "ORDER BY created_at DESC LIMIT ?",
+                (event_type, limit)
+            ).fetchall()
+        return [
+            {
+                "event_id":  r[0],
+                "event":     r[1],
+                "source":    r[2],
+                "payload":   json.loads(r[3] or "{}"),
+                "created_at": r[4],
+            }
+            for r in rows
+        ]
+
+    def close(self) -> None:
+        """显式关闭事件日志的 SQLite 连接。容器 close/reset 时必须调,
+        否则 events.db 句柄泄漏——Windows 下导致数据目录删不掉(WinError 32)、
+        长期运行累积文件描述符泄漏。与 GraphStore.close 一致,带锁关闭。"""
+        with self._lock:
+            self._log_db.close()

package/python/vendor/hkc/hkc_sdk/__init__.py

@@ -0,0 +1,63 @@
+"""
+hkc_sdk
+Foxclaw Knowledge Core — Python SDK
+
+统一入口 connect()，两种后端无感切换：
+
+    from hkc_sdk import connect
+
+    # 远程 HTTP（HKC 独立部署）
+    hkc = connect("http://localhost:8000")
+
+    # 进程内直连（HAR 与 HKC 同进程）
+    from hkc_api.container import HKCContainer
+    hkc = connect(container=HKCContainer(data_dir="./data"))
+
+    # 用法完全一样
+    hkc.ingest_text("巴菲特认为价值投资长期跑赢市场", domain="Investment")
+    hits = hkc.search("价值投资")
+    ability = hkc.ensure_ability("quant_analyst")
+"""
+from .base import BaseClient
+from .http_client import HTTPClient
+from .direct_client import DirectClient
+from .models import (
+    KU, SearchHit, Ability, Skill, CoverageReport, Conflict, IngestResult,
+)
+from .exceptions import (
+    HKCError, HKCNotFoundError, HKCInsufficientCoverage,
+    HKCBadRequest, HKCServerError,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "connect",
+    "BaseClient", "HTTPClient", "DirectClient",
+    "KU", "SearchHit", "Ability", "Skill",
+    "CoverageReport", "Conflict", "IngestResult",
+    "HKCError", "HKCNotFoundError", "HKCInsufficientCoverage",
+    "HKCBadRequest", "HKCServerError",
+]
+
+
+def connect(
+    base_url: str = None,
+    *,
+    container=None,
+    timeout: int = 60,
+) -> BaseClient:
+    """
+    创建 HKC 客户端。
+
+    二选一：
+      connect("http://localhost:8000")   → HTTPClient
+      connect(container=my_container)     → DirectClient
+
+    两者都返回 BaseClient，方法签名一致。
+    """
+    if container is not None:
+        return DirectClient(container)
+    if base_url is not None:
+        return HTTPClient(base_url, timeout=timeout)
+    raise ValueError("必须提供 base_url（HTTP）或 container（直连）之一")

package/python/vendor/hkc/hkc_sdk/base.py

@@ -0,0 +1,151 @@
+"""
+hkc_sdk / base.py
+SDK 客户端抽象接口。
+
+两种实现共享这套方法签名：
+  HTTPClient    通过 REST 调用 hkc-api（远程/跨进程）
+  DirectClient  直接调 HKCContainer 的引擎（进程内）
+
+用户代码只依赖 BaseClient，底层随时可换：
+  from hkc_sdk import connect
+  hkc = connect("http://localhost:8000")   # HTTP
+  hkc = connect(container=my_container)     # 直连
+  hits = hkc.search("价值投资")             # 两种写法完全一样
+"""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+
+from .models import (
+    KU, SearchHit, Ability, CoverageReport, Conflict, IngestResult,
+)
+
+
+class BaseClient(ABC):
+
+    # ── 知识摄入 ─────────────────────────────────────────────
+
+    @abstractmethod
+    def ingest_text(
+        self,
+        text: str,
+        source_title: str = "",
+        domain: str = "",
+        source: str = "inline",
+        source_year: int = 0,
+    ) -> IngestResult:
+        """摄入文本，返回写入的 KU 信息。"""
+        ...
+
+    @abstractmethod
+    def ingest_url(
+        self,
+        url: str,
+        source_title: str = "",
+        domain: str = "",
+        source_year: int = 0,
+    ) -> IngestResult:
+        """摄入网页 URL。"""
+        ...
+
+    # ── KU 查询 ──────────────────────────────────────────────
+
+    @abstractmethod
+    def get_ku(self, ku_id: str) -> KU:
+        """按 ID 获取 KU，不存在抛 HKCNotFoundError。"""
+        ...
+
+    @abstractmethod
+    def list_by_domain(self, domain: str, limit: int = 50) -> list[KU]:
+        """列出某领域的所有 KU。"""
+        ...
+
+    @abstractmethod
+    def neighbors(self, ku_id: str, max_depth: int = 2, top_k: int = 20) -> list[SearchHit]:
+        """获取 KU 的图谱邻居。"""
+        ...
+
+    # ── 搜索 ─────────────────────────────────────────────────
+
+    @abstractmethod
+    def search(
+        self,
+        query: str,
+        mode: str = "hybrid",
+        top_k: int = 10,
+        domain: str = "",
+        ku_types: list[str] | None = None,
+    ) -> list[SearchHit]:
+        """统一搜索。mode: bm25 | vector | graph | hybrid。"""
+        ...
+
+    @abstractmethod
+    def find_path(self, from_id: str, to_id: str) -> list[str]:
+        """两 KU 间最短路径。"""
+        ...
+
+    # ── 能力（ACE）───────────────────────────────────────────
+
+    @abstractmethod
+    def list_abilities(self) -> list[str]:
+        """列出所有可编译的 Ability key。"""
+        ...
+
+    @abstractmethod
+    def coverage_report(self, ability_key: str) -> CoverageReport:
+        """查看某 Ability 的知识覆盖情况（不编译）。"""
+        ...
+
+    @abstractmethod
+    def compile_ability(self, ability_key: str) -> Ability:
+        """
+        编译能力包。覆盖度不足时抛 HKCInsufficientCoverage。
+        """
+        ...
+
+    @abstractmethod
+    def get_ability(self, ability_key: str) -> Ability:
+        """加载已编译的能力包，未编译抛 HKCNotFoundError。"""
+        ...
+
+    # ── 冲突（KEE）───────────────────────────────────────────
+
+    @abstractmethod
+    def list_conflicts(self, status: str = "open", domain: str = "") -> list[Conflict]:
+        """列出冲突卡。"""
+        ...
+
+    @abstractmethod
+    def resolve_conflict(
+        self,
+        conflict_id: str,
+        winner_id: str,
+        note: str = "",
+        resolved_by: str = "sdk",
+    ) -> bool:
+        """人工裁决冲突。"""
+        ...
+
+    # ── 系统 ─────────────────────────────────────────────────
+
+    @abstractmethod
+    def stats(self) -> dict:
+        """系统统计。"""
+        ...
+
+    @abstractmethod
+    def health(self) -> bool:
+        """检查 HKC 是否可用。"""
+        ...
+
+    # ── 便捷方法（默认实现，子类无需重写）────────────────────
+
+    def ensure_ability(self, ability_key: str) -> Ability:
+        """
+        获取能力包，若未编译则尝试编译。
+        覆盖度足够时返回 Ability，不足时抛 HKCInsufficientCoverage。
+        """
+        from .exceptions import HKCNotFoundError
+        try:
+            return self.get_ability(ability_key)
+        except HKCNotFoundError:
+            return self.compile_ability(ability_key)

package/python/vendor/hkc/hkc_sdk/direct_client.py

@@ -0,0 +1,153 @@
+"""
+hkc_sdk / direct_client.py
+直连客户端：直接调用 HKCContainer 的引擎，不走 HTTP。
+
+用于 HAR 和 HKC 跑在同一进程的场景，省掉网络序列化开销。
+方法签名与 HTTPClient 完全一致，上层代码无感切换。
+"""
+from __future__ import annotations
+import logging
+
+from .base import BaseClient
+from .models import (
+    KU, SearchHit, Ability, CoverageReport, Conflict, IngestResult,
+)
+from .exceptions import (
+    HKCNotFoundError, HKCInsufficientCoverage, HKCBadRequest,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class DirectClient(BaseClient):
+
+    def __init__(self, container):
+        """
+        container: 已 assemble 的 HKCContainer 实例。
+        """
+        if not getattr(container, "_assembled", False):
+            container.assemble()
+        self.c = container
+
+    # ── 知识摄入 ─────────────────────────────────────────────
+
+    def ingest_text(self, text, source_title="", domain="",
+                    source="inline", source_year=0) -> IngestResult:
+        kus = self.c.kde.ingest_text(
+            text=text, source=source, source_title=source_title,
+            source_year=source_year, domain=domain,
+        )
+        return self._ingest_result(kus)
+
+    def ingest_url(self, url, source_title="", domain="", source_year=0) -> IngestResult:
+        kus = self.c.kde.ingest_url(
+            url=url, source_title=source_title,
+            source_year=source_year, domain=domain,
+        )
+        return self._ingest_result(kus)
+
+    def _ingest_result(self, kus) -> IngestResult:
+        counts = {}
+        for ku in kus:
+            t = ku.ku_type.value
+            counts[t] = counts.get(t, 0) + 1
+        return IngestResult(
+            ku_count=len(kus),
+            ku_ids=[ku.ku_id for ku in kus],
+            counts=counts,
+        )
+
+    # ── KU 查询 ──────────────────────────────────────────────
+
+    def get_ku(self, ku_id) -> KU:
+        ku = self.c.graph_store.get(ku_id)
+        if not ku:
+            raise HKCNotFoundError(f"KU 不存在: {ku_id}")
+        return KU.from_dict(ku.to_dict())
+
+    def list_by_domain(self, domain, limit=50) -> list[KU]:
+        kus = self.c.graph_store.query_by_domain(domain, limit=limit)
+        return [KU.from_dict(ku.to_dict()) for ku in kus]
+
+    def neighbors(self, ku_id, max_depth=2, top_k=20) -> list[SearchHit]:
+        ku = self.c.graph_store.get(ku_id)
+        if not ku:
+            raise HKCNotFoundError(f"KU 不存在: {ku_id}")
+        hits = self.c.search.search_neighbors(ku_id, max_depth=max_depth, top_k=top_k)
+        return [
+            SearchHit(ku_id=h.ku_id, score=h.score, name=h.name,
+                      summary=h.summary, mode="graph")
+            for h in hits
+        ]
+
+    # ── 搜索 ─────────────────────────────────────────────────
+
+    def search(self, query, mode="hybrid", top_k=10, domain="",
+               ku_types=None) -> list[SearchHit]:
+        if mode not in ("bm25", "vector", "graph", "hybrid"):
+            raise HKCBadRequest(f"无效 mode: {mode}")
+        results = self.c.search.search(
+            query=query, mode=mode, top_k=top_k,
+            domain=domain, ku_types=ku_types,
+        )
+        return [
+            SearchHit(ku_id=r.ku_id, score=r.score, name=r.name,
+                      summary=r.summary, mode=r.mode, ku_type=r.ku_type)
+            for r in results
+        ]
+
+    def find_path(self, from_id, to_id) -> list[str]:
+        return self.c.search.find_path(from_id, to_id)
+
+    # ── 能力 ─────────────────────────────────────────────────
+
+    def list_abilities(self) -> list[str]:
+        return self.c.ace.list_available()
+
+    def coverage_report(self, ability_key) -> CoverageReport:
+        report = self.c.ace.coverage_report(ability_key)
+        if not report:
+            raise HKCNotFoundError(f"未知 Ability: {ability_key}")
+        return CoverageReport.from_dict(report)
+
+    def compile_ability(self, ability_key) -> Ability:
+        try:
+            pkg = self.c.ace.compile(ability_key)
+        except ValueError as e:
+            raise HKCNotFoundError(str(e))
+        if pkg is None:
+            report = self.c.ace.coverage_report(ability_key)
+            raise HKCInsufficientCoverage(
+                "知识覆盖度不足，无法编译此 Ability",
+                {"coverage": report.get("coverage", {}),
+                 "missing_skills": report.get("missing_skills", [])},
+            )
+        return Ability.from_dict(pkg.to_dict())
+
+    def get_ability(self, ability_key) -> Ability:
+        pkg = self.c.ace.load_ability(ability_key)
+        if not pkg:
+            raise HKCNotFoundError(f"Ability 尚未编译: {ability_key}")
+        return Ability.from_dict(pkg.to_dict())
+
+    # ── 冲突 ─────────────────────────────────────────────────
+
+    def list_conflicts(self, status="open", domain="") -> list[Conflict]:
+        cards = self.c.graph_store.list_conflicts(status=status, domain=domain)
+        return [Conflict.from_dict(card.to_dict()) for card in cards]
+
+    def resolve_conflict(self, conflict_id, winner_id, note="",
+                         resolved_by="sdk") -> bool:
+        return self.c.kee.manual_resolve(
+            conflict_id=conflict_id, winner_id=winner_id,
+            note=note, resolved_by=resolved_by,
+        )
+
+    # ── 系统 ─────────────────────────────────────────────────
+
+    def stats(self) -> dict:
+        return self.c.stats()
+
+    def health(self) -> bool:
+        """直连模式：容器已装配即健康。"""
+        return getattr(self.c, "_assembled", False)

package/python/vendor/hkc/hkc_sdk/exceptions.py

@@ -0,0 +1,39 @@
+"""
+hkc_sdk / exceptions.py
+SDK 异常体系。
+
+让用户能用一致的方式捕获错误，不管底层是 HTTP 还是直连：
+  HKCError                  基类
+  ├── HKCNotFoundError      资源不存在（404）
+  ├── HKCInsufficientCoverage  能力覆盖度不足（422）
+  ├── HKCBadRequest         请求参数错误（400 / 413）
+  └── HKCServerError        服务内部错误（500 / 连接失败）
+"""
+
+
+class HKCError(Exception):
+    """所有 SDK 异常的基类。"""
+    def __init__(self, message: str, detail=None):
+        super().__init__(message)
+        self.message = message
+        self.detail  = detail
+
+
+class HKCNotFoundError(HKCError):
+    """请求的资源不存在（KU / Ability / Conflict）。"""
+
+
+class HKCInsufficientCoverage(HKCError):
+    """编译能力时知识覆盖度不足。detail 含 missing_skills。"""
+    def __init__(self, message: str, detail=None):
+        super().__init__(message, detail)
+        self.missing_skills = (detail or {}).get("missing_skills", [])
+        self.coverage       = (detail or {}).get("coverage", {})
+
+
+class HKCBadRequest(HKCError):
+    """请求参数错误或请求体过大。"""
+
+
+class HKCServerError(HKCError):
+    """服务内部错误或连接失败。"""