foxclaw 0.1.0 → 0.1.3

package/python/vendor/hkc/hkc_core/models/enums.py

@@ -0,0 +1,65 @@
+"""
+hkc-core / models / enums.py
+所有枚举类型集中定义，整个 HKC 统一使用这里的常量。
+"""
+from enum import Enum
+
+
+class KUType(str, Enum):
+    ENTITY   = "Entity"
+    CONCEPT  = "Concept"
+    FACT     = "Fact"
+    CLAIM    = "Claim"
+    EVIDENCE = "Evidence"
+    ABILITY  = "Ability"
+
+
+class EntityType(str, Enum):
+    PERSON       = "Person"
+    ORGANIZATION = "Organization"
+    PRODUCT      = "Product"
+    EVENT        = "Event"
+    PLACE        = "Place"
+
+
+class ClaimStatus(str, Enum):
+    PENDING    = "pending"     # 证据不足，暂不结论
+    ACTIVE     = "active"      # 置信度 > 0.7，无冲突
+    DISPUTED   = "disputed"    # 存在对立 Claim，置信度相近
+    SUPERSEDED = "superseded"  # 被新研究推翻，历史归档
+    REJECTED   = "rejected"    # 置信度 < 0.3，明确反驳
+
+
+class RelationType(str, Enum):
+    CREATED_BY   = "CREATED_BY"    # Entity → Concept
+    SUPPORTS     = "SUPPORTS"      # Evidence → Claim
+    CONTRADICTS  = "CONTRADICTS"   # Evidence → Claim
+    MENTIONS     = "MENTIONS"      # Evidence → Entity
+    BELONGS_TO   = "BELONGS_TO"    # Concept → Domain
+    DERIVED_FROM = "DERIVED_FROM"  # Concept → Concept
+    IMPLEMENTS   = "IMPLEMENTS"    # Ability → Skill
+    USES         = "USES"          # Ability → Concept
+    SUPERSEDES   = "SUPERSEDES"    # Claim → Claim
+    INTERESTED_IN = "INTERESTED_IN" # UserProfile → KU (HMR bridge)
+
+
+class ConflictStatus(str, Enum):
+    OPEN     = "open"      # 等待裁决
+    RESOLVED = "resolved"  # 已裁决
+    DEFERRED = "deferred"  # 人工延后
+
+
+class ResolutionStrategy(str, Enum):
+    EVIDENCE_WEIGHT = "evidence_weight"  # 按 Evidence 数量和质量加权（默认）
+    RECENCY         = "recency"          # 越新的研究权重越高
+    AUTHORITY       = "authority"        # 按来源权威度
+    MANUAL          = "manual"           # 人工标注裁决
+
+
+class SourceType(str, Enum):
+    BOOK    = "Book"
+    PAPER   = "Paper"
+    ARTICLE = "Article"
+    SPEECH  = "Speech"
+    DATASET = "Dataset"
+    WEB     = "Web"

package/python/vendor/hkc/hkc_core/models/ku.py

@@ -0,0 +1,307 @@
+"""
+hkc-core / models / ku.py
+Knowledge Unit 数据结构定义。
+六种类型共用 BaseKU，各自扩展专属字段。
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Optional
+from .enums import (
+    KUType, EntityType, ClaimStatus,
+    SourceType, ResolutionStrategy, ConflictStatus
+)
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# ─────────────────────────────────────────
+# Base
+# ─────────────────────────────────────────
+
+@dataclass
+class BaseKU:
+    """所有 KU 类型共用的基础字段。"""
+    ku_id:      str
+    ku_type:    KUType
+    name:       str
+    summary:    str                  = ""
+    tags:       list[str]            = field(default_factory=list)
+    sources:    list[str]            = field(default_factory=list)   # EVD_xxx
+    relations:  list[str]            = field(default_factory=list)   # REL_xxx
+    confidence: float                = 1.0
+    status:     str                  = "active"
+    domain:     str                  = ""
+    version:    int                  = 1
+    created_at: str                  = field(default_factory=_now)
+    updated_at: str                  = field(default_factory=_now)
+    extra:      dict[str, Any]       = field(default_factory=dict)   # 扩展字段
+
+    def to_dict(self) -> dict:
+        return {
+            "ku_id":      self.ku_id,
+            "ku_type":    self.ku_type.value,
+            "name":       self.name,
+            "summary":    self.summary,
+            "tags":       self.tags,
+            "sources":    self.sources,
+            "relations":  self.relations,
+            "confidence": self.confidence,
+            "status":     self.status,
+            "domain":     self.domain,
+            "version":    self.version,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "extra":      self.extra,
+        }
+
+
+# ─────────────────────────────────────────
+# Entity
+# ─────────────────────────────────────────
+
+@dataclass
+class EntityKU(BaseKU):
+    """
+    真实存在的人 / 机构 / 产品 / 事件 / 地点。
+    Fact 和 Claim 的锚点。
+    """
+    ku_type:     KUType      = field(default=KUType.ENTITY, init=False)
+    entity_type: EntityType  = EntityType.PERSON
+    aliases:     list[str]   = field(default_factory=list)
+    birth:       str         = ""    # ISO date，仅 Person
+    active:      bool        = True
+    source_text: str         = ""    # 提炼自的原文段落(供前端"看原文")
+
+    def to_dict(self) -> dict:
+        d = super().to_dict()
+        d["extra"].update({
+            "entity_type": self.entity_type.value,
+            "aliases":     self.aliases,
+            "birth":       self.birth,
+            "active":      self.active,
+            "source_text": self.source_text,
+        })
+        return d
+
+
+# ─────────────────────────────────────────
+# Concept
+# ─────────────────────────────────────────
+
+@dataclass
+class ConceptKU(BaseKU):
+    """
+    抽象知识单元：理论、模型、方法论。
+    不可辩驳，但可被 DERIVED_FROM 细化。
+    """
+    ku_type:    KUType     = field(default=KUType.CONCEPT, init=False)
+    aka:        list[str]  = field(default_factory=list)   # 别名
+    definition: str        = ""
+    source_text: str       = ""   # 提炼自的原文段落(供前端"看原文")
+
+    def to_dict(self) -> dict:
+        d = super().to_dict()
+        d["extra"].update({
+            "aka":         self.aka,
+            "definition":  self.definition,
+            "source_text": self.source_text,
+        })
+        return d
+
+
+# ─────────────────────────────────────────
+# Fact   ← 关键：与 Claim 分开
+# ─────────────────────────────────────────
+
+@dataclass
+class FactKU(BaseKU):
+    """
+    不可辩驳的客观陈述。
+    confidence 固定 1.0，不参与 KEE 冲突检测。
+    """
+    ku_type:    KUType  = field(default=KUType.FACT, init=False)
+    statement:  str     = ""
+    verifiable: bool    = True
+    source_ref: str     = ""    # 直接指向 EVD_xxx
+    source_text: str    = ""    # 提炼自的原文段落(供前端"看原文")
+
+    def __post_init__(self):
+        # Fact 的置信度永远是 1.0
+        self.confidence = 1.0
+
+    def to_dict(self) -> dict:
+        d = super().to_dict()
+        d["extra"].update({
+            "statement":   self.statement,
+            "verifiable":  self.verifiable,
+            "source_ref":  self.source_ref,
+            "source_text": self.source_text,
+        })
+        return d
+
+
+# ─────────────────────────────────────────
+# Claim  ← KEE 的核心处理对象
+# ─────────────────────────────────────────
+
+@dataclass
+class ClaimKU(BaseKU):
+    """
+    有置信度的观点 / 理论。
+    可被质疑，参与 KEE 冲突检测和状态机流转。
+    """
+    ku_type:       KUType       = field(default=KUType.CLAIM, init=False)
+    statement:     str          = ""
+    claim_status:  ClaimStatus  = ClaimStatus.PENDING
+    supports:      list[str]    = field(default_factory=list)    # EVD_xxx 支持
+    contradicts:   list[str]    = field(default_factory=list)    # EVD_xxx 反对
+    conflict_refs: list[str]    = field(default_factory=list)    # CFT_xxx
+    source_text:   str          = ""   # 提炼自的原文段落(供前端"看原文")
+
+    def to_dict(self) -> dict:
+        d = super().to_dict()
+        d["extra"].update({
+            "statement":     self.statement,
+            "claim_status":  self.claim_status.value,
+            "supports":      self.supports,
+            "contradicts":   self.contradicts,
+            "conflict_refs": self.conflict_refs,
+            "source_text":   self.source_text,
+        })
+        return d
+
+
+# ─────────────────────────────────────────
+# Evidence
+# ─────────────────────────────────────────
+
+@dataclass
+class EvidenceKU(BaseKU):
+    """
+    支持或反对 Claim 的来源。
+    是 Claim 置信度计算的基础材料。
+    """
+    ku_type:      KUType      = field(default=KUType.EVIDENCE, init=False)
+    source:       str         = ""        # 书名 / 论文标题 / URL
+    source_type:  SourceType  = SourceType.BOOK
+    author:       str         = ""
+    year:         int         = 0
+    page:         int         = 0
+    quote:        str         = ""        # 严格限制 < 200 字
+    supports:     list[str]   = field(default_factory=list)   # CLM_xxx
+    contradicts:          list[str] = field(default_factory=list)  # CLM_xxx
+
+    def to_dict(self) -> dict:
+        d = super().to_dict()
+        d["extra"].update({
+            "source":       self.source,
+            "source_type":  self.source_type.value,
+            "author":       self.author,
+            "year":         self.year,
+            "page":         self.page,
+            "quote":        self.quote,
+            "supports":     self.supports,
+            "contradicts":          self.contradicts,
+        })
+        return d
+
+
+# ─────────────────────────────────────────
+# Ability  ← ACE 的最终产物
+# ─────────────────────────────────────────
+
+@dataclass
+class AbilityKU(BaseKU):
+    """
+    ACE 编译产出的能力包。
+    Agent 直接加载，无需读原始书籍。
+    """
+    ku_type:       KUType          = field(default=KUType.ABILITY, init=False)
+    ability_key:   str             = ""        # "quant_analyst"
+    skills:        list[str]       = field(default_factory=list)    # SKL_xxx
+    workflows:     list[str]       = field(default_factory=list)    # WFL_xxx
+    coverage:      dict[str, float] = field(default_factory=dict)   # skill → 覆盖率
+    knowledge_refs: list[str]      = field(default_factory=list)    # KU_xxx
+    package_path:  str             = ""        # abilities/xxx.hkap
+    pkg_version:   str             = "1.0.0"
+
+    def to_dict(self) -> dict:
+        d = super().to_dict()
+        d["extra"].update({
+            "ability_key":   self.ability_key,
+            "skills":        self.skills,
+            "workflows":     self.workflows,
+            "coverage":      self.coverage,
+            "knowledge_refs": self.knowledge_refs,
+            "package_path":  self.package_path,
+            "pkg_version":   self.pkg_version,
+        })
+        return d
+
+
+# ─────────────────────────────────────────
+# Relation
+# ─────────────────────────────────────────
+
+@dataclass
+class Relation:
+    rel_id:   str
+    from_ku:  str
+    to_ku:    str
+    rel_type: str          # RelationType value
+    weight:   float        = 1.0
+    source:   str          = ""    # EVD_xxx（可选，记录关系来源）
+    created_at: str        = field(default_factory=_now)
+
+    def to_dict(self) -> dict:
+        return {
+            "rel_id":     self.rel_id,
+            "from_ku":    self.from_ku,
+            "to_ku":      self.to_ku,
+            "rel_type":   self.rel_type,
+            "weight":     self.weight,
+            "source":     self.source,
+            "created_at": self.created_at,
+        }
+
+
+# ─────────────────────────────────────────
+# Conflict Card  ← KEE 产出
+# ─────────────────────────────────────────
+
+@dataclass
+class ConflictCard:
+    conflict_id:         str
+    claim_a_id:          str
+    claim_b_id:          str
+    domain:              str                = ""
+    status:              ConflictStatus     = ConflictStatus.OPEN
+    resolution_strategy: ResolutionStrategy = ResolutionStrategy.EVIDENCE_WEIGHT
+    resolution_note:     str                = ""
+    resolved_by:         Optional[str]      = None
+    resolved_at:         Optional[str]      = None
+    created_at:          str                = field(default_factory=_now)
+
+    def to_dict(self) -> dict:
+        return {
+            "conflict_id":         self.conflict_id,
+            "claim_a_id":          self.claim_a_id,
+            "claim_b_id":          self.claim_b_id,
+            "domain":              self.domain,
+            "status":              self.status.value,
+            "resolution_strategy": self.resolution_strategy.value,
+            "resolution_note":     self.resolution_note,
+            "resolved_by":         self.resolved_by,
+            "resolved_at":         self.resolved_at,
+            "created_at":          self.created_at,
+        }
+
+
+# ─────────────────────────────────────────
+# Union type helper
+# ─────────────────────────────────────────
+
+KU = EntityKU | ConceptKU | FactKU | ClaimKU | EvidenceKU | AbilityKU

package/python/vendor/hkc/hkc_core/utils/id_gen.py

@@ -0,0 +1,113 @@
+"""
+hkc-core / utils / id_gen.py
+统一 ID 生成器。
+每种类型有固定前缀，ID 格式：PREFIX_XXXXXXXX（8位补零）。
+"""
+import sqlite3
+import threading
+
+
+# 前缀映射
+_PREFIX = {
+    "Entity":   "ENT",
+    "Concept":  "CON",
+    "Fact":     "FCT",
+    "Claim":    "CLM",
+    "Evidence": "EVD",
+    "Ability":  "ABL",
+    "Relation": "REL",
+    "Conflict": "CFT",
+    "Event":    "EVT",
+    "Skill":    "SKL",
+    "Workflow": "WFL",
+}
+
+
+class IDGenerator:
+    """
+    线程安全的自增 ID 生成器。
+    计数器持久化到 SQLite，重启后不重置。
+    """
+
+    def __init__(self, db_path: str):
+        self._lock = threading.Lock()
+        self._db   = sqlite3.connect(db_path, check_same_thread=False)
+        self._init_table()
+
+    def _init_table(self):
+        self._db.execute("""
+            CREATE TABLE IF NOT EXISTS id_counters (
+                prefix TEXT PRIMARY KEY,
+                counter INTEGER DEFAULT 0
+            )
+        """)
+        self._db.commit()
+
+    def next(self, ku_type: str) -> str:
+        prefix = _PREFIX.get(ku_type, "UNK")
+        with self._lock:
+            row = self._db.execute(
+                "SELECT counter FROM id_counters WHERE prefix = ?",
+                (prefix,)
+            ).fetchone()
+
+            if row:
+                counter = row[0] + 1
+                self._db.execute(
+                    "UPDATE id_counters SET counter = ? WHERE prefix = ?",
+                    (counter, prefix)
+                )
+            else:
+                counter = 1
+                self._db.execute(
+                    "INSERT INTO id_counters (prefix, counter) VALUES (?, ?)",
+                    (prefix, counter)
+                )
+            self._db.commit()
+
+        return f"{prefix}_{counter:08d}"
+
+    def next_batch(self, ku_type: str, count: int) -> list[str]:
+        """一次性预留 count 个连续 ID（单事务、单 commit）。
+
+        用于批量写关系等场景：逐个 next() 每次都 SELECT+UPDATE+commit(一次 fsync)，
+        大文档关系发现产出上千条关系时会造成 fsync 风暴导致摄入长时间卡住。
+        """
+        if count <= 0:
+            return []
+        prefix = _PREFIX.get(ku_type, "UNK")
+        with self._lock:
+            row = self._db.execute(
+                "SELECT counter FROM id_counters WHERE prefix = ?",
+                (prefix,)
+            ).fetchone()
+            start = (row[0] if row else 0) + 1
+            end   = start + count - 1
+            if row:
+                self._db.execute(
+                    "UPDATE id_counters SET counter = ? WHERE prefix = ?",
+                    (end, prefix)
+                )
+            else:
+                self._db.execute(
+                    "INSERT INTO id_counters (prefix, counter) VALUES (?, ?)",
+                    (prefix, end)
+                )
+            self._db.commit()
+        return [f"{prefix}_{c:08d}" for c in range(start, end + 1)]
+
+    def peek(self, ku_type: str) -> int:
+        """查看当前计数器，不自增。"""
+        prefix = _PREFIX.get(ku_type, "UNK")
+        with self._lock:      # 与 next() 共用同一连接,并发下读也要加锁
+            row = self._db.execute(
+                "SELECT counter FROM id_counters WHERE prefix = ?",
+                (prefix,)
+            ).fetchone()
+        return row[0] if row else 0
+
+    def close(self) -> None:
+        """显式关闭 id_counters.db 连接。容器 close/reset 时必须调,
+        否则句柄泄漏——Windows 下导致数据目录删不掉(WinError 32)。带锁关闭。"""
+        with self._lock:
+            self._db.close()

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

@@ -0,0 +1,44 @@
+"""
+hkc_crystallizer — 知识结晶器(HKC Integrations Layer)
+
+Memory World → Knowledge World 的边界转换器。
+把任何"可沉淀认知"事件(memory.matured / meeting.finished / research.finished …)
+转化为 HKC 可接收的知识候选体。
+
+架构铁律:
+  Crystallizer is a knowledge candidate generator, not a knowledge identity resolver.
+  KEE is the sole authority for knowledge deduplication and evolution.
+
+用法:
+    from hkc_crystallizer import (
+        KnowledgeCrystallizer, HKCIngress, SystemBusEventSource,
+    )
+    from hkc_sdk import connect
+
+    hkc = connect(container=hkc_container)
+
+    crystallizer = KnowledgeCrystallizer(
+        ingress = HKCIngress(hkc),                  # 只认 KnowledgeIngress 协议
+        source  = SystemBusEventSource(system_bus), # 只认 KnowledgeEventSource 协议
+        events  = ["memory.matured"],               # 未来可加 meeting.finished 等
+    )
+"""
+from .crystallizer import KnowledgeCrystallizer, CrystallizeStats
+from .candidate import (
+    KnowledgeCandidate, CandidateEvidence,
+    KnowledgeEventSource, KnowledgeIngress,
+)
+from .ingress import HKCIngress
+from .adapters import (
+    SystemBusEventSource, DEFAULT_TRANSLATORS, translate_memory_matured,
+)
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "KnowledgeCrystallizer", "CrystallizeStats",
+    "KnowledgeCandidate", "CandidateEvidence",
+    "KnowledgeEventSource", "KnowledgeIngress",
+    "HKCIngress",
+    "SystemBusEventSource", "DEFAULT_TRANSLATORS", "translate_memory_matured",
+]

package/python/vendor/hkc/hkc_crystallizer/adapters.py

@@ -0,0 +1,94 @@
+"""
+hkc_crystallizer / adapters.py
+事件适配器:把各类"可沉淀认知"事件转为 KnowledgeCandidate。
+
+KnowledgeEventSource 协议本身在 candidate.py 定义。
+这里提供:
+  - SystemBusEventSource: 基于 Foxclaw SystemBus 的事件来源(实现 KnowledgeEventSource)
+  - EventToCandidate:    把事件 payload 翻译成 KnowledgeCandidate 的可插拔翻译器
+
+为什么要 EventToCandidate 这一层:
+  不同事件的 payload 结构不同(memory.matured 有 memory_id/confidence,
+  meeting.finished 可能有 meeting_id/participants)。翻译逻辑按事件类型可插拔,
+  新增事件类型只需注册一个翻译函数,不改 Crystallizer 主体。
+"""
+from __future__ import annotations
+import logging
+from typing import Callable, Any, Optional
+
+from .candidate import (
+    KnowledgeCandidate, CandidateEvidence, KnowledgeEventSource,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ── 事件 → 候选体 翻译器 ─────────────────────────────────────
+
+# 翻译函数签名: (payload: dict) -> Optional[KnowledgeCandidate]
+TranslatorFn = Callable[[dict], Optional[KnowledgeCandidate]]
+
+
+def translate_memory_matured(payload: dict) -> Optional[KnowledgeCandidate]:
+    """memory.matured 事件 → KnowledgeCandidate。"""
+    content = (payload.get("content") or "").strip()
+    title = (payload.get("title") or "").strip()
+    if not content and not title:
+        return None
+
+    ev = CandidateEvidence(
+        evidence_type = "memory",
+        source_id     = payload.get("memory_id", ""),
+        agent         = payload.get("agent_id"),
+        confidence    = payload.get("confidence", 1.0),
+        extra         = {
+            "memory_type":     payload.get("memory_type", ""),
+            "temporal_weight": payload.get("temporal_weight", 0.0),
+            "matured_reason":  payload.get("reason", ""),
+            "shared":          payload.get("shared", False),
+        },
+    )
+    return KnowledgeCandidate(
+        content     = content or title,
+        title       = title,
+        evidence    = [ev],
+        event_refs  = [payload.get("memory_id", "")] if payload.get("memory_id") else [],
+        domain_hint = payload.get("domain_hint", ""),
+    )
+
+
+# 默认翻译器注册表:事件名 → 翻译函数
+DEFAULT_TRANSLATORS: dict[str, TranslatorFn] = {
+    "memory.matured": translate_memory_matured,
+    # 未来扩展(只需加翻译函数,不改 Crystallizer):
+    #   "meeting.finished":  translate_meeting_finished,
+    #   "research.finished": translate_research_finished,
+    #   "document.ingested": translate_document_ingested,
+}
+
+
+# ── SystemBus 事件来源 ───────────────────────────────────────
+
+class SystemBusEventSource:
+    """
+    基于 Foxclaw SystemBus 的知识事件来源,实现 KnowledgeEventSource 协议。
+
+    bus: 任何提供 subscribe(channel, handler) 的对象(Foxclaw SystemBus)。
+    """
+
+    def __init__(self, bus):
+        self._bus = bus
+
+    def subscribe(self, event_name: str, handler: Callable[[dict], None]) -> None:
+        def _bus_handler(msg: Any):
+            # SystemBus handler 收到 BusMessage(有 .payload);也兼容直接 dict
+            payload = getattr(msg, "payload", None)
+            if payload is None and isinstance(msg, dict):
+                payload = msg
+            if payload is not None:
+                handler(payload)
+        self._bus.subscribe(event_name, _bus_handler)
+
+
+# 协议一致性断言(显式声明 SystemBusEventSource 实现 KnowledgeEventSource)
+_: KnowledgeEventSource = SystemBusEventSource.__new__(SystemBusEventSource)