foxclaw 0.1.0 → 0.1.2

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

@@ -0,0 +1,145 @@
+"""
+hkc_crystallizer / candidate.py
+知识候选体 (KnowledgeCandidate) 与边界协议。
+
+这是 Memory World → Knowledge World 的边界数据结构与契约定义。
+
+核心理念:
+  Crystallizer 处理的不是"记忆",而是"任何可沉淀认知"——
+  来源可以是 memory.matured、meeting.finished、research.finished、
+  document.ingested、agent.reflection.completed …
+
+  因此边界数据结构叫 KnowledgeCandidate(知识候选体),不叫 Memory。
+  这样 HKC 永远不会被 HMR 绑定死。
+
+职责边界(架构铁律):
+  Crystallizer is a knowledge candidate generator, not a knowledge identity resolver.
+  KEE is the sole authority for knowledge deduplication and evolution.
+
+  → Candidate 携带 light_fingerprint(结构哈希,仅作标签),
+    但**不**参与"是否已存在、是否合并"的决策。
+    那个决策(canonical fingerprint + KU 查重 + Evidence 合并)是 KEE 的天职。
+"""
+from __future__ import annotations
+import hashlib
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Protocol, Callable, Any, Optional, runtime_checkable
+
+
+# ── 结构化 Evidence ──────────────────────────────────────────
+
+@dataclass
+class CandidateEvidence:
+    """
+    候选体携带的结构化来源证据。
+
+    取代旧版的 source="hmr_memory:agent:finance:mem_xxx" 字符串拼接 ——
+    结构化后可进图谱,形成 KU ← Evidence ← (Memory/Meeting/...) 的可追溯链。
+
+    未来查询"为什么系统认为用户长期关注 Agent 架构",可顺着这条链回溯。
+    """
+    evidence_type: str                       # memory | meeting | research | document | reflection ...
+    source_id:     str                       # 原始单元 ID(memory_id / meeting_id / ...)
+    agent:         Optional[str] = None       # 产出该认知的 Agent
+    confidence:    float = 1.0
+    timestamp:     str = ""                   # ISO8601
+    extra:         dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+
+    def to_dict(self) -> dict:
+        return {
+            "evidence_type": self.evidence_type,
+            "source_id":     self.source_id,
+            "agent":         self.agent,
+            "confidence":    self.confidence,
+            "timestamp":     self.timestamp,
+            "extra":         dict(self.extra),
+        }
+
+
+# ── 知识候选体 ───────────────────────────────────────────────
+
+@dataclass
+class KnowledgeCandidate:
+    """
+    进入 HKC 前的知识候选体 —— 边界转换的产物。
+
+    由 Crystallizer 构造,经 KnowledgeIngress 送入 HKC。
+    它是"事件视角"的产物;到了 KEE 才转为"知识语义视角"。
+    """
+    content:             str                              # 待结晶的文本
+    title:               str = ""
+    evidence:            list[CandidateEvidence] = field(default_factory=list)
+    event_refs:          list[str] = field(default_factory=list)   # 触发事件的引用(event_id / memory_id)
+    domain_hint:         str = ""                          # 领域提示(非强制)
+    light_fingerprint:   str = ""                          # 结构哈希(仅标签,KEE 才算 canonical)
+
+    def __post_init__(self):
+        if not self.light_fingerprint:
+            self.light_fingerprint = self.compute_light_fingerprint(self.content)
+
+    @staticmethod
+    def compute_light_fingerprint(content: str) -> str:
+        """
+        轻量结构指纹:归一化(去空白/小写)后取 sha256 前 16 位。
+
+        这是"事件视角"的粗去重标签 —— 只能识别"字面几乎相同"。
+        语义层面的同义归并(canonical fingerprint)是 KEE 的职责,不在这里做。
+        """
+        norm = re.sub(r"\s+", " ", (content or "").strip().lower())
+        return hashlib.sha256(norm.encode("utf-8")).hexdigest()[:16]
+
+    @property
+    def text_for_ingest(self) -> str:
+        if self.title and self.content:
+            return f"{self.title}\n\n{self.content}"
+        return self.content or self.title
+
+    def to_dict(self) -> dict:
+        return {
+            "content":           self.content,
+            "title":             self.title,
+            "evidence":          [e.to_dict() for e in self.evidence],
+            "event_refs":        list(self.event_refs),
+            "domain_hint":       self.domain_hint,
+            "light_fingerprint": self.light_fingerprint,
+        }
+
+
+# ── 协议:知识事件来源 ───────────────────────────────────────
+
+@runtime_checkable
+class KnowledgeEventSource(Protocol):
+    """
+    知识事件来源协议。
+
+    不绑定"记忆"——任何能产出"可沉淀认知"事件的系统都可实现它:
+    HMR(memory.matured)、会议系统(meeting.finished)、
+    研究 Agent(research.finished)、文档系统(document.ingested)…
+
+    按 event_name 订阅,handler 收到该事件的 payload(dict)。
+    """
+    def subscribe(self, event_name: str, handler: Callable[[dict], None]) -> None:
+        ...
+
+
+# ── 协议:知识入口 ───────────────────────────────────────────
+
+@runtime_checkable
+class KnowledgeIngress(Protocol):
+    """
+    HKC 对外的知识入口契约。
+
+    Crystallizer 只认这个协议,不知道 KDE/KEE/ACE 的存在。
+    具体实现(HKCIngress)内部再去调 kde.ingest_text 等 —— 
+    这样 KDE 重构不会波及 Crystallizer。
+
+    返回:本次摄入产出的 KU 数量(或可转为数量的结果)。
+    """
+    def ingest(self, candidate: KnowledgeCandidate) -> Any:
+        ...

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

@@ -0,0 +1,179 @@
+"""
+hkc_crystallizer / crystallizer.py
+知识结晶器 (KnowledgeCrystallizer) —— 边界转换器 / Knowledge Candidate Generator
+
+定位:Memory World → Knowledge World 之间的边界转换器(Boundary Translator)。
+      属于 HKC Integrations Layer,不属于 HKC Core。
+
+架构铁律:
+  Crystallizer is a knowledge candidate generator, not a knowledge identity resolver.
+  KEE is the sole authority for knowledge deduplication and evolution.
+
+职责严格锁死为四件:
+  1. 接收事件   (通过 KnowledgeEventSource 订阅)
+  2. 事件筛选   (合法性 / 类型判断 / 可选二次复核)
+  3. 事件级去重 (event_id / source_id,避免重复消费同一事件)
+  4. 构造候选体 (KnowledgeCandidate,含结构化 Evidence + light fingerprint)
+
+绝不负责(交给 HKC Core):
+  - 知识抽取        → KDE
+  - 知识身份判断/去重 → KEE(canonical fingerprint + KU 查重 + Evidence 合并)
+  - 图谱更新        → KEE
+  - Ability 生成     → ACE
+
+  特别地:Crystallizer **永不查询 KU 是否存在**,**永不做合并/更新决策**。
+  它计算的 light_fingerprint 只是候选体的结构标签,不参与任何知识决策。
+"""
+from __future__ import annotations
+import logging
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from .candidate import (
+    KnowledgeCandidate, KnowledgeEventSource, KnowledgeIngress,
+)
+from .adapters import DEFAULT_TRANSLATORS, TranslatorFn
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CrystallizeStats:
+    received:       int = 0
+    crystallized:   int = 0
+    skipped_dup:    int = 0
+    skipped_filter: int = 0
+    skipped_empty:  int = 0
+    failed:         int = 0
+
+    def as_dict(self) -> dict:
+        return {
+            "received": self.received, "crystallized": self.crystallized,
+            "skipped_dup": self.skipped_dup, "skipped_filter": self.skipped_filter,
+            "skipped_empty": self.skipped_empty, "failed": self.failed,
+        }
+
+
+class KnowledgeCrystallizer:
+    """
+    参数:
+      ingress:   KnowledgeIngress,HKC 对外入口(如 HKCIngress)。
+                 Crystallizer 只认这个协议,不认 KDE/KEE/ACE。
+      source:    KnowledgeEventSource,事件来源(如 SystemBusEventSource)。
+      events:    要订阅的事件名列表(默认只订阅 memory.matured)。
+      translators: 事件名 → 翻译函数。默认用 DEFAULT_TRANSLATORS。
+      candidate_filter: 可选 (KnowledgeCandidate)->bool,二次筛选(防御性复核)。
+      auto_start: 构造时立即订阅(默认 True)。
+    """
+
+    def __init__(
+        self,
+        ingress: KnowledgeIngress,
+        source: KnowledgeEventSource,
+        *,
+        events: Optional[list] = None,
+        translators: Optional[dict] = None,
+        candidate_filter: Optional[Callable[[KnowledgeCandidate], bool]] = None,
+        auto_start: bool = True,
+    ):
+        self._ingress = ingress
+        self._source = source
+        self._events = events or ["memory.matured"]
+        self._translators: dict[str, TranslatorFn] = dict(DEFAULT_TRANSLATORS)
+        if translators:
+            self._translators.update(translators)
+        self._filter = candidate_filter
+        self.stats = CrystallizeStats()
+        self._seen_refs = set()
+        self._started = False
+        if auto_start:
+            self.start()
+
+    def start(self) -> None:
+        """订阅所有配置的事件。幂等。"""
+        if self._started:
+            return
+        for ev in self._events:
+            self._source.subscribe(ev, self._make_handler(ev))
+        self._started = True
+        logger.info("KnowledgeCrystallizer 已启动,订阅事件: %s", self._events)
+
+    def _make_handler(self, event_name: str):
+        def _handler(payload: dict):
+            self._on_event(event_name, payload)
+        return _handler
+
+    # ── 核心:收到一个事件 ──────────────────────────────────
+    def _on_event(self, event_name: str, payload: dict) -> None:
+        self.stats.received += 1
+
+        # (2) 筛选:有无对应翻译器
+        translator = self._translators.get(event_name)
+        if translator is None:
+            logger.debug("无翻译器,跳过事件: %s", event_name)
+            self.stats.skipped_filter += 1
+            return
+
+        # 翻译 event → candidate
+        try:
+            candidate = translator(payload)
+        except Exception as e:
+            logger.warning("事件翻译失败 (%s): %s", event_name, e)
+            self.stats.skipped_filter += 1
+            return
+        if candidate is None:
+            self.stats.skipped_empty += 1
+            return
+
+        # (3) 事件级去重(基于 event_refs)
+        ref = self._dedup_key(candidate)
+        if ref and ref in self._seen_refs:
+            self.stats.skipped_dup += 1
+            return
+
+        # (2') 二次筛选(防御性复核)
+        if self._filter is not None:
+            try:
+                if not self._filter(candidate):
+                    self.stats.skipped_filter += 1
+                    return
+            except Exception as e:
+                logger.warning("二次筛选异常,保守跳过: %s", e)
+                self.stats.skipped_filter += 1
+                return
+
+        # 内容非空
+        if not candidate.text_for_ingest.strip():
+            self.stats.skipped_empty += 1
+            return
+
+        # (4) candidate 已构造好(含结构化 Evidence + light fingerprint)
+        #     → 交给 KnowledgeIngress 送入 HKC。到此为止,不做知识身份判断。
+        try:
+            self._ingress.ingest(candidate)
+        except Exception as e:
+            self.stats.failed += 1
+            logger.error("候选体送入 HKC 失败 (refs=%s): %s",
+                         candidate.event_refs, e)
+            return
+
+        # 成功后才记事件级去重(失败可重试)
+        if ref:
+            self._seen_refs.add(ref)
+        self.stats.crystallized += 1
+        logger.info("候选体已送入 HKC: refs=%s fp=%s",
+                    candidate.event_refs, candidate.light_fingerprint)
+
+    @staticmethod
+    def _dedup_key(candidate: KnowledgeCandidate) -> str:
+        """事件级去重键:优先 event_refs,退化用 light_fingerprint。"""
+        if candidate.event_refs:
+            return "|".join(candidate.event_refs)
+        return candidate.light_fingerprint
+
+    # ── 运维 ──────────────────────────────────────────────
+    def get_stats(self) -> dict:
+        return self.stats.as_dict()
+
+    def reset_dedup(self) -> None:
+        self._seen_refs.clear()

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

@@ -0,0 +1,90 @@
+"""
+hkc_crystallizer / ingress.py
+HKC 知识入口适配器。
+
+实现 KnowledgeIngress 协议,是 Crystallizer 与 HKC 内部(KDE/KEE/ACE)
+之间的唯一耦合点。Crystallizer 只认 KnowledgeIngress,不认 KDE。
+
+设计意图:
+  KDE 的接口(ingest_text 签名)是 KDE 的内部契约,不是 HKC 的稳定对外契约。
+  若 Crystallizer 直接调 ingest_text,KDE 重构就会波及 Crystallizer。
+  HKCIngress 把这层耦合收敛到一处:KDE 变了,只改这里。
+
+  candidate 的结构化 Evidence 在这里翻译成 HKC 能理解的来源信息。
+  注:第二层"知识级去重 + Evidence 合并"由 KEE 负责,不在此处 ——
+      本适配器只负责"把候选体送进 HKC",不做任何知识身份判断。
+"""
+from __future__ import annotations
+import logging
+from typing import Any
+
+from .candidate import KnowledgeCandidate, KnowledgeIngress
+
+logger = logging.getLogger(__name__)
+
+
+class HKCIngress:
+    """
+    把 KnowledgeCandidate 送入 HKC 的适配器。
+
+    hkc_ingest_fn: 实际的 HKC 摄入入口。可为:
+      - HKC SDK DirectClient / HTTPClient(有 ingest_text 方法)
+      - KDE 实例(有 ingest_text 方法)
+      - 自定义 callable(text, source=, source_title=, domain=) -> result
+    """
+
+    def __init__(self, hkc_ingest_fn: Any):
+        self._ingest = self._resolve(hkc_ingest_fn)
+
+    @staticmethod
+    def _resolve(fn: Any):
+        if callable(fn) and not hasattr(fn, "ingest_text"):
+            return fn
+        if hasattr(fn, "ingest_text"):
+            return fn.ingest_text
+        raise TypeError(
+            "hkc_ingest_fn 必须可调用,或带 ingest_text 方法"
+            "(HKC SDK 客户端 / KDE 实例)"
+        )
+
+    def ingest(self, candidate: KnowledgeCandidate) -> Any:
+        """实现 KnowledgeIngress.ingest。"""
+        text = candidate.text_for_ingest.strip()
+        if not text:
+            return None
+
+        # 结构化 Evidence → 来源串(供 KDE 当前接口使用)。
+        # 注:完整结构化 Evidence 进图谱由后续 KEE 演化步骤处理,
+        #    这里先把主来源信息传给 KDE,保证可追溯不丢。
+        source = self._primary_source(candidate)
+        source_title = candidate.title or self._fallback_title(candidate)
+
+        return self._ingest(
+            text,
+            source=source,
+            source_title=source_title,
+            domain=candidate.domain_hint or "",
+        )
+
+    @staticmethod
+    def _primary_source(candidate: KnowledgeCandidate) -> str:
+        """从首条 Evidence 构造来源标识(保持可追溯)。"""
+        if not candidate.evidence:
+            return "knowledge_candidate"
+        e = candidate.evidence[0]
+        parts = [e.evidence_type or "candidate"]
+        if e.agent:
+            parts.append(f"agent:{e.agent}")
+        if e.source_id:
+            parts.append(e.source_id)
+        return ":".join(parts)
+
+    @staticmethod
+    def _fallback_title(candidate: KnowledgeCandidate) -> str:
+        if candidate.event_refs:
+            return f"候选 {candidate.event_refs[0]}"
+        return "知识候选"
+
+
+# 协议一致性断言(显式声明 HKCIngress 实现 KnowledgeIngress)
+_: KnowledgeIngress = HKCIngress.__new__(HKCIngress)

package/python/vendor/hkc/hkc_kde/chunker.py

@@ -0,0 +1,197 @@
+"""
+hkc-kde / chunker.py
+分块器：把 ParsedDocument 切成适合 LLM 提取的 Chunk。
+
+规则（写死，不允许各 loader 自定义）：
+- 优先在章节边界切割
+- 单个 Section 超过 MAX_TOKENS → 滑动窗口切割
+- 单个 Section 不足 MIN_TOKENS → 与下一个 Section 合并
+- 相邻 Chunk 之间保留 OVERLAP_TOKENS 重叠，保持上下文连续
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+
+from .models import ParsedDocument, Section
+
+
+# ── 配置（统一常量，禁止在其他地方覆盖）────────────────────
+
+MAX_TOKENS     = 512    # 单个 Chunk 最大 token 数
+MIN_TOKENS     = 128    # 低于此长度不单独成块，与下一个合并
+OVERLAP_TOKENS = 64     # 相邻 Chunk 重叠 token 数
+
+# 粗略估算：1 token ≈ 4 个英文字符 / 1.5 个中文字符
+# 用字符数近似，避免引入 tokenizer 依赖
+CHARS_PER_TOKEN = 3.5
+
+
+def _char_limit(tokens: int) -> int:
+    return int(tokens * CHARS_PER_TOKEN)
+
+
+MAX_CHARS     = _char_limit(MAX_TOKENS)
+MIN_CHARS     = _char_limit(MIN_TOKENS)
+OVERLAP_CHARS = _char_limit(OVERLAP_TOKENS)
+
+
+@dataclass
+class Chunk:
+    chunk_id:     str
+    content:      str
+    source_hint:  str   # 章节标题，用于 Evidence 溯源
+    doc_id:       str
+    char_count:   int   = 0
+
+    def __post_init__(self):
+        self.char_count = len(self.content)
+
+
+class Chunker:
+
+    def chunk(self, doc: ParsedDocument) -> list[Chunk]:
+        """
+        主入口：把 ParsedDocument 切成 Chunk 列表。
+        章节边界优先，章节内再按 MAX_CHARS 切割。
+        """
+        chunks:    list[Chunk]  = []
+        chunk_idx: int          = 0
+
+        for chapter in doc.chapters:
+            chapter_chunks = self._chunk_chapter(
+                chapter_title = chapter.title,
+                sections      = chapter.sections,
+                doc_id        = doc.doc_id,
+                start_idx     = chunk_idx,
+            )
+            chunks.extend(chapter_chunks)
+            chunk_idx += len(chapter_chunks)
+
+        return chunks
+
+    def _chunk_chapter(
+        self,
+        chapter_title: str,
+        sections:      list[Section],
+        doc_id:        str,
+        start_idx:     int,
+    ) -> list[Chunk]:
+        """
+        章节内部的分块逻辑：
+        1. 先把 sections 合并成连续文本
+        2. 如果总长 <= MAX_CHARS → 一个 Chunk
+        3. 否则滑动窗口切割，相邻 Chunk 保留 OVERLAP_CHARS 重叠
+        """
+        # 合并 sections 文本（短 section 先合并）
+        merged_text = self._merge_sections(sections)
+        if not merged_text.strip():
+            return []
+
+        if len(merged_text) <= MAX_CHARS:
+            # 整章一个 Chunk
+            return [Chunk(
+                chunk_id    = f"{doc_id}_C{start_idx:04d}",
+                content     = merged_text,
+                source_hint = chapter_title,
+                doc_id      = doc_id,
+            )]
+
+        # 滑动窗口切割
+        return self._sliding_window(
+            text          = merged_text,
+            source_hint   = chapter_title,
+            doc_id        = doc_id,
+            start_idx     = start_idx,
+        )
+
+    def _merge_sections(self, sections: list[Section]) -> str:
+        """
+        把 sections 合并成文本。
+        短 Section（< MIN_CHARS）不单独成块，与相邻合并。
+        """
+        if not sections:
+            return ""
+
+        parts: list[str] = []
+        buffer: str      = ""
+
+        for sec in sections:
+            text = sec.content.strip()
+            if not text:
+                continue
+            if len(buffer) + len(text) < MIN_CHARS:
+                # buffer 太短，继续累积
+                buffer = (buffer + "\n\n" + text).strip()
+            else:
+                if buffer:
+                    parts.append(buffer)
+                buffer = text
+
+        if buffer:
+            parts.append(buffer)
+
+        return "\n\n".join(parts)
+
+    def _sliding_window(
+        self,
+        text:        str,
+        source_hint: str,
+        doc_id:      str,
+        start_idx:   int,
+    ) -> list[Chunk]:
+        """
+        固定步长滑动窗口，步长 = MAX_CHARS - OVERLAP_CHARS。
+        在句子边界（。！？\n）对齐，避免在句中切断。
+        """
+        step   = MAX_CHARS - OVERLAP_CHARS
+        chunks: list[Chunk] = []
+        pos    = 0
+
+        while pos < len(text):
+            end = pos + MAX_CHARS
+            if end < len(text):
+                # 向后找最近的句子边界
+                boundary = self._find_boundary(text, end)
+                end      = boundary if boundary > pos else end
+
+            fragment = text[pos:end].strip()
+            if fragment:
+                chunks.append(Chunk(
+                    chunk_id    = f"{doc_id}_C{start_idx + len(chunks):04d}",
+                    content     = fragment,
+                    source_hint = source_hint,
+                    doc_id      = doc_id,
+                ))
+
+            # 下一个窗口起点 = 当前终点 - 重叠
+            pos = max(pos + step, end - OVERLAP_CHARS)
+            if pos >= len(text):
+                break
+
+        return chunks
+
+    def _find_boundary(self, text: str, pos: int) -> int:
+        """
+        从 pos 向前扫描，找最近的句子边界字符。
+        优先级：\n\n > 。！？\n > 。！？ > 空格
+        最多向前扫描 100 字符。
+        """
+        search_start = max(0, pos - 100)
+        segment = text[search_start:pos]
+
+        # 优先双换行（段落边界）
+        idx = segment.rfind('\n\n')
+        if idx != -1:
+            return search_start + idx + 2
+
+        # 中文句号等
+        for ch in ('。', '！', '？', '!', '?', '\n'):
+            idx = segment.rfind(ch)
+            if idx != -1:
+                return search_start + idx + 1
+
+        # 空格
+        idx = segment.rfind(' ')
+        if idx != -1:
+            return search_start + idx + 1
+
+        return pos