foxclaw 0.1.0 → 0.1.2

package/python/vendor/hkc/hkc_api/routes/search.py

@@ -0,0 +1,88 @@
+"""
+hkc-api / routes / search.py
+搜索路由：关键词 / 向量 / 图谱 / 混合检索。
+"""
+from fastapi import APIRouter, HTTPException, Depends
+
+from ..container import HKCContainer, get_container
+from ..schemas import (
+    SearchRequest, SearchResponse, SearchHit, NeighborsRequest,
+)
+
+router = APIRouter(prefix="/search", tags=["search"])
+
+
+@router.post("", response_model=SearchResponse)
+def search(
+    req: SearchRequest,
+    c: HKCContainer = Depends(get_container),
+):
+    """
+    统一搜索接口。
+    mode: bm25 | vector | graph | hybrid（默认）
+    """
+    if req.mode not in ("bm25", "vector", "graph", "hybrid"):
+        raise HTTPException(
+            status_code=400,
+            detail=f"无效 mode: {req.mode}，支持 bm25/vector/graph/hybrid"
+        )
+
+    results = c.search.search(
+        query    = req.query,
+        mode     = req.mode,
+        top_k    = req.top_k,
+        domain   = req.domain,
+        ku_types = req.ku_types,
+    )
+    return SearchResponse(
+        query = req.query,
+        mode  = req.mode,
+        hits  = [
+            SearchHit(
+                ku_id=r.ku_id, score=r.score, mode=r.mode,
+                name=r.name, summary=r.summary, ku_type=r.ku_type,
+            )
+            for r in results
+        ],
+    )
+
+
+@router.post("/neighbors")
+def search_neighbors(
+    req: NeighborsRequest,
+    c: HKCContainer = Depends(get_container),
+):
+    """从指定 KU 出发做图谱邻居展开。"""
+    ku = c.graph_store.get(req.ku_id)
+    if not ku:
+        raise HTTPException(status_code=404, detail=f"KU 不存在: {req.ku_id}")
+
+    results = c.search.search_neighbors(
+        req.ku_id, max_depth=req.max_depth,
+        top_k=req.top_k, rel_types=req.rel_types,
+    )
+    return {
+        "ku_id": req.ku_id,
+        "hits": [
+            {"ku_id": r.ku_id, "score": r.score,
+             "name": r.name, "summary": r.summary}
+            for r in results
+        ],
+    }
+
+
+@router.get("/path")
+def find_path(
+    from_id: str,
+    to_id:   str,
+    c: HKCContainer = Depends(get_container),
+):
+    """查找两个 KU 之间的最短路径。"""
+    path = c.search.find_path(from_id, to_id)
+    return {
+        "from":      from_id,
+        "to":        to_id,
+        "path":      path,
+        "reachable": len(path) > 0,
+        "hops":      max(0, len(path) - 1),
+    }

package/python/vendor/hkc/hkc_api/schemas.py

@@ -0,0 +1,153 @@
+"""
+hkc-api / schemas.py
+API 请求 / 响应模型（Pydantic）。
+"""
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import Optional, Any
+
+
+# ── Ingest ───────────────────────────────────────────────────
+
+class IngestTextRequest(BaseModel):
+    text:         str
+    source:       str = "inline"
+    source_title: str = ""
+    source_year:  int = 0
+    domain:       str = ""
+
+
+class IngestURLRequest(BaseModel):
+    url:          str
+    source_title: str = ""
+    source_year:  int = 0
+    domain:       str = ""
+
+
+class CrystallizeRequest(BaseModel):
+    """外部系统经 Crystallizer 集成层推送的知识候选(边界转换入口)。"""
+    content:       str
+    title:         str = ""
+    domain:        str = ""
+    evidence_type: str = "document"   # memory | meeting | research | document | reflection ...
+    source_id:     str = ""
+    agent:         str = ""
+    event_refs:    list[str] = []
+
+
+class IngestResponse(BaseModel):
+    ku_count:  int
+    ku_ids:    list[str]
+    counts:    dict[str, int] = Field(default_factory=dict)
+
+
+# ── KU ───────────────────────────────────────────────────────
+
+class KUResponse(BaseModel):
+    ku_id:      str
+    ku_type:    str
+    name:       str
+    summary:    str
+    domain:     str
+    confidence: float
+    status:     str
+    tags:       list[str]      = Field(default_factory=list)
+    extra:      dict[str, Any] = Field(default_factory=dict)
+
+
+class GraphResponse(BaseModel):
+    """全量知识图谱：所有 KU + 所有关系 + 统计。前端星球一次拉取用。"""
+    kus:       list[KUResponse]
+    relations: list[dict[str, Any]] = Field(default_factory=list)
+    stats:     dict[str, Any]       = Field(default_factory=dict)
+
+
+# ── Search ───────────────────────────────────────────────────
+
+class SearchRequest(BaseModel):
+    query:    str
+    mode:     str = "hybrid"          # bm25 | vector | graph | hybrid
+    top_k:    int = 10
+    domain:   str = ""
+    ku_types: Optional[list[str]] = None
+
+
+class SearchHit(BaseModel):
+    ku_id:   str
+    score:   float
+    mode:    str
+    name:    str
+    summary: str
+    ku_type: str = ""
+
+
+class SearchResponse(BaseModel):
+    query:   str
+    mode:    str
+    hits:    list[SearchHit]
+
+
+class NeighborsRequest(BaseModel):
+    ku_id:     str
+    max_depth: int = 2
+    top_k:     int = 20
+    rel_types: Optional[list[str]] = None
+
+
+# ── Ability ──────────────────────────────────────────────────
+
+class AbilityCompileRequest(BaseModel):
+    ability_key: str
+
+
+class CoverageReportResponse(BaseModel):
+    ability_key:    str
+    display_name:   str = ""            # 能力显示名(可中文),供前端列表展示
+    domains:        list[str] = []      # 该能力参与覆盖匹配的领域列表
+    can_compile:    bool
+    coverage:       dict[str, float]
+    missing_skills: list[str]
+    ku_count:       int
+
+
+class AbilityResponse(BaseModel):
+    ability_key:  str
+    display_name: str
+    domain:       str
+    coverage:     dict[str, float]
+    skills:       list[dict]
+    workflows:    list[dict]
+    version:      str
+
+
+# ── Conflict ─────────────────────────────────────────────────
+
+class ConflictResponse(BaseModel):
+    conflict_id:         str
+    claim_a_id:          str
+    claim_b_id:          str
+    domain:              str
+    status:              str
+    resolution_strategy: str
+    resolution_note:     str
+
+
+class ConflictResolveRequest(BaseModel):
+    winner_id:   str
+    note:        str = ""
+    resolved_by: str = "human"
+
+
+# ── Stats ────────────────────────────────────────────────────
+
+class StatsResponse(BaseModel):
+    assembled:       bool
+    data_dir:        str = ""          # 后端实际使用的数据目录(绝对路径),供前端显示/排查"连错目录"
+    embedding:       str = ""          # 生效的向量后端名(Stub 无语义 / Local / TEI)
+    total_kus:       int = 0
+    ku_counts:       dict[str, int] = Field(default_factory=dict)
+    total_relations: int = 0
+    open_conflicts:  int = 0
+    bm25_size:       int = 0
+    vector_size:     int = 0
+    abilities:       list[str] = Field(default_factory=list)

package/python/vendor/hkc/hkc_api/synthesis.py

@@ -0,0 +1,179 @@
+"""
+hkc-api / synthesis.py
+综合页「第 2 档 · LLM 综述」——把一个节点在图里的邻域，用 LLM 组织成连贯的中文词条。
+
+★ Principle 07 边界（务必守住）：
+  综述是**派生只读视图**，不是新知识。它——
+    - 不建 KU、不写知识图、不走 KEE；
+    - 缓存存在**独立的 synthesis.db**（物理上与 hkc.db 知识库分开，表明"这不是知识"）；
+    - 只依据图里已有的知识材料重新组织表达，Prompt 明确禁止杜撰/引入外部知识。
+  它与 3D 星球一样，只是知识图的一种渲染视图。
+"""
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+import logging
+import threading
+from datetime import datetime, timezone
+
+logger = logging.getLogger(__name__)
+
+
+_SYS_PROMPT = """你是严谨的知识编辑。下面给你的是某个知识节点及其在知识库里的关联材料。
+请把它们组织成一篇连贯、准确、可读的中文 wiki 式词条。
+
+严格规则：
+- 只依据给定材料，绝不杜撰、绝不引入材料之外的知识；材料没提到的就不写。
+- 这是对**已有知识的重新组织表达**，不是创造新知识，也不要下与材料相悖的结论。
+- 用简短小标题 + 段落；开头一句话定义/概述该节点，然后展开关联事实、观点与背景。
+- 若材料稀少，就如实写简短几句，不要凑字数。
+- 直接输出词条正文，不要说"根据材料"之类的元话术。"""
+
+
+class SynthesisStore:
+    """综述缓存（独立 SQLite，与知识库物理隔离）。"""
+
+    def __init__(self, path: str):
+        self.path = path
+        # check_same_thread=False + 显式锁：FastAPI 同步路由跑在线程池里，
+        # 并发请求会从多个线程共用这一个连接；不加锁会 "recursive use of cursors"/
+        # "database is locked"。与 SQLiteGraphStore 的既有模式保持一致。
+        self._lock = threading.Lock()
+        self._db = sqlite3.connect(path, check_same_thread=False)
+        with self._lock:
+            self._db.execute("""
+                CREATE TABLE IF NOT EXISTS synthesis (
+                    ku_id        TEXT PRIMARY KEY,
+                    content      TEXT NOT NULL,
+                    model        TEXT,
+                    generated_at TEXT,
+                    context_hash TEXT
+                )
+            """)
+            self._db.commit()
+
+    def get(self, ku_id: str) -> dict | None:
+        with self._lock:
+            row = self._db.execute(
+                "SELECT ku_id, content, model, generated_at, context_hash "
+                "FROM synthesis WHERE ku_id=?", (ku_id,)
+            ).fetchone()
+        if not row:
+            return None
+        return {"ku_id": row[0], "content": row[1], "model": row[2],
+                "generated_at": row[3], "context_hash": row[4]}
+
+    def put(self, ku_id: str, content: str, model: str, context_hash: str):
+        with self._lock:
+            self._db.execute(
+                "INSERT INTO synthesis(ku_id, content, model, generated_at, context_hash) "
+                "VALUES(?,?,?,?,?) ON CONFLICT(ku_id) DO UPDATE SET "
+                "content=excluded.content, model=excluded.model, "
+                "generated_at=excluded.generated_at, context_hash=excluded.context_hash",
+                (ku_id, content, model,
+                 datetime.now(timezone.utc).isoformat(), context_hash),
+            )
+            self._db.commit()
+
+    def delete(self, ku_id: str):
+        with self._lock:
+            self._db.execute("DELETE FROM synthesis WHERE ku_id=?", (ku_id,))
+            self._db.commit()
+
+    def close(self):
+        with self._lock:
+            self._db.close()
+
+
+class SynthesisService:
+    """按需生成 + 缓存节点综述。生成走已配置的任意 LLM（模型无关）。"""
+
+    def __init__(self, graph_store, search, kde, cache_path: str):
+        self.store  = graph_store
+        self.search = search
+        self.kde    = kde          # 动态取 kde.extractor,尊重运行时换/重配 LLM
+        self.cache  = SynthesisStore(cache_path)
+
+    @property
+    def extractor(self):
+        return self.kde.extractor
+
+    # ── 邻域材料收集（复用图邻居 + 检索"提及"，均有界）──────────
+    def _gather_context(self, ku) -> tuple[str, str]:
+        """返回 (拼好的材料文本, 材料指纹)。材料只读，不改动任何知识。"""
+        ex = ku.to_dict().get("extra", {})
+        lines: list[str] = []
+        head = f"节点：{ku.name}（{ku.ku_type.value}）"
+        if ku.domain:
+            head += f"　领域：{ku.domain}"
+        lines.append(head)
+        stmt = ex.get("statement")
+        if stmt:
+            lines.append(f"陈述：{stmt}")
+        if ku.summary and ku.summary != stmt:
+            lines.append(f"概述：{ku.summary}")
+        src = (ex.get("source_text") or "").strip()
+        if src:
+            lines.append(f"原文片段：{src[:800]}")
+
+        seen = {ku.ku_id}
+        related: list[str] = []
+        # 1) 图谱邻居（有直接关系的节点）
+        try:
+            for h in self.search.search_neighbors(ku.ku_id, max_depth=2, top_k=15):
+                if h.ku_id in seen:
+                    continue
+                seen.add(h.ku_id)
+                related.append(f"- {h.name}：{(h.summary or '').strip()[:160]}")
+        except Exception as e:
+            logger.warning("综述邻居收集失败 %s: %s", ku.ku_id, e)
+        # 2) 检索"提及本节点名字"的事实/观点（图里常只连到书、不直接连实体）
+        try:
+            for h in self.search.search(ku.name, top_k=12):
+                if h.ku_id in seen:
+                    continue
+                seen.add(h.ku_id)
+                related.append(f"- {h.name}：{(h.summary or '').strip()[:160]}")
+        except Exception as e:
+            logger.warning("综述检索收集失败 %s: %s", ku.ku_id, e)
+
+        if related:
+            lines.append("\n关联材料：")
+            lines.extend(related[:24])          # 上界，控 prompt 体积
+
+        text = "\n".join(lines)
+        digest = hashlib.sha1(text.encode("utf-8")).hexdigest()
+        return text, digest
+
+    def get_cached(self, ku_id: str) -> dict | None:
+        return self.cache.get(ku_id)
+
+    def generate(self, ku_id: str, force: bool = False) -> dict:
+        """
+        返回 {ku_id, content, model, generated_at, cached, stale}。
+        - 有缓存且非 force：直接返回缓存（stale 标记材料是否已变，供前端提示"可重新生成"）。
+        - force 或无缓存：调 LLM 生成并写缓存。
+        LLM 未配置/调用失败会抛异常，由路由转成明确错误。
+        """
+        ku = self.store.get(ku_id)
+        if not ku:
+            raise KeyError(ku_id)
+
+        context, digest = self._gather_context(ku)
+        cached = self.cache.get(ku_id)
+        if cached and not force:
+            cached["cached"] = True
+            cached["stale"]  = (cached.get("context_hash") != digest)
+            return cached
+
+        content = self.extractor.complete(
+            system=_SYS_PROMPT,
+            user=context,
+            max_tokens=1500,
+        )
+        model = getattr(self.extractor, "model", "")
+        self.cache.put(ku_id, content, model, digest)
+        return {"ku_id": ku_id, "content": content, "model": model,
+                "generated_at": datetime.now(timezone.utc).isoformat(),
+                "context_hash": digest, "cached": False, "stale": False}

package/python/vendor/hkc/hkc_core/graph/base.py

@@ -0,0 +1,188 @@
+"""
+hkc-core / graph / base.py
+GraphStore 抽象接口。
+v1 实现：SQLiteGraphStore
+v2 可替换：Neo4jGraphStore
+上层代码只依赖这个接口，底层实现随时可换。
+"""
+from abc import ABC, abstractmethod
+from typing import Optional
+from ..models.ku import KU, Relation, ConflictCard, ClaimKU
+from ..models.enums import KUType, ClaimStatus
+
+
+class GraphStore(ABC):
+
+    # ── 单个 KU ──────────────────────────────
+
+    @abstractmethod
+    def get(self, ku_id: str) -> Optional[KU]:
+        """按 ID 获取 KU，不存在返回 None。"""
+        ...
+
+    @abstractmethod
+    def put(self, ku: KU) -> None:
+        """写入或更新单个 KU。"""
+        ...
+
+    @abstractmethod
+    def delete(self, ku_id: str) -> None:
+        """软删除：把 status 改为 'deleted'。"""
+        ...
+
+    # ── 局部写入（默认实现退化为整行 put）─────────
+    #
+    # put() 是整行写。当两个子系统各自只关心 KU 的不同部分时(复习状态在
+    # extra["review"],KEE 演化改 sources / confidence / supports),整行读改写会
+    # 互相覆盖 —— 谁后写谁赢,前一个的改动静默丢失。存储实现应覆盖这两个方法,
+    # 只写属于自己的那几列/那几个键。
+
+    def patch_ku(
+        self,
+        ku_id:   str,
+        columns: Optional[dict] = None,
+        extra:   Optional[dict] = None,
+    ) -> int:
+        """只写指定列 + 合并 extra 的指定键。返回受影响行数(0 = KU 不存在)。
+        默认实现:get → 改 → put(等价的整行写,不解决覆盖问题,仅保证接口可用)。"""
+        ku = self.get(ku_id)
+        if ku is None:
+            return 0
+        for k, v in (columns or {}).items():
+            setattr(ku, k, v)
+        if extra:
+            ku.extra = {**(ku.extra or {}), **extra}
+        self.put(ku)
+        return 1
+
+    def update_extra(self, ku_id: str, fn) -> Optional[dict]:
+        """锁内「读 extra → fn(extra) → 写回」。返回写后的 extra;None = KU 不存在。
+        默认实现不加锁,仅保证接口可用。"""
+        ku = self.get(ku_id)
+        if ku is None:
+            return None
+        new_extra = fn({**(ku.extra or {})})
+        if new_extra is None:
+            return ku.extra
+        ku.extra = new_extra
+        self.put(ku)
+        return new_extra
+
+    # ── 批量操作 ─────────────────────────────
+
+    @abstractmethod
+    def batch_write(self, kus: list[KU]) -> None:
+        """批量写入，原子操作。"""
+        ...
+
+    # ── 查询 ─────────────────────────────────
+
+    @abstractmethod
+    def query_by_type(
+        self,
+        ku_type: KUType,
+        domain: str = "",
+        status: str = "active",
+        limit: int = 100,
+    ) -> list[KU]:
+        ...
+
+    @abstractmethod
+    def query_by_domain(self, domain: str, limit: int = 200) -> list[KU]:
+        ...
+
+    @abstractmethod
+    def search_by_name(self, name: str, fuzzy: bool = True) -> list[KU]:
+        ...
+
+    # ── 关系 ─────────────────────────────────
+
+    @abstractmethod
+    def add_relation(self, rel: Relation) -> None:
+        ...
+
+    @abstractmethod
+    def delete_relation(self, rel_id: str) -> None:
+        """删除一条关系(SQLite 表 + 图结构同步移除)。"""
+        ...
+
+    @abstractmethod
+    def redirect_relations(self, from_ku_id: str, to_ku_id: str) -> int:
+        """
+        把所有指向/来自 from_ku_id 的关系,重定向到 to_ku_id。
+        用于知识级去重:重复 KU 被合并入 canonical KU 后,
+        其关系不应悬空,而应转移到 canonical KU 上。
+        返回重定向的关系数。自环(重定向后 from==to)会被丢弃。
+        """
+        ...
+
+    @abstractmethod
+    def get_relations(
+        self,
+        ku_id: str,
+        rel_type: str = "",
+        direction: str = "both",   # "out" | "in" | "both"
+    ) -> list[Relation]:
+        ...
+
+    @abstractmethod
+    def get_all_relations(self, limit: int = 5000) -> list[Relation]:
+        """全量拉取所有关系（用于一次性构建全图，如前端星球）。"""
+        ...
+
+    @abstractmethod
+    def neighbors(
+        self,
+        ku_id: str,
+        rel_type: str = "",
+        depth: int = 1,
+    ) -> list[KU]:
+        ...
+
+    @abstractmethod
+    def shortest_path(self, from_id: str, to_id: str) -> list[str]:
+        """返回 KU ID 路径列表，不可达返回空列表。"""
+        ...
+
+    # ── Conflict Cards ────────────────────────
+
+    @abstractmethod
+    def save_conflict(self, card: ConflictCard) -> None:
+        ...
+
+    @abstractmethod
+    def get_conflict(self, conflict_id: str) -> Optional[ConflictCard]:
+        ...
+
+    @abstractmethod
+    def list_conflicts(
+        self,
+        status: str = "open",
+        domain: str = "",
+    ) -> list[ConflictCard]:
+        ...
+
+    # ── Claim 专用 ────────────────────────────
+
+    def query_all(self, limit: int = 2000) -> list[KU]:
+        """全量查询所有非删除 KU，默认实现：遍历所有类型。"""
+        from ..models.enums import KUType
+        result = []
+        for ku_type in KUType:
+            result.extend(self.query_by_type(ku_type, status='active', limit=limit))
+        return result
+
+    @abstractmethod
+    def find_claims_by_domain(
+        self,
+        domain: str,
+        status: ClaimStatus = None,
+    ) -> list[ClaimKU]:
+        ...
+
+    # ── 统计 ─────────────────────────────────
+
+    @abstractmethod
+    def stats(self) -> dict:
+        """返回各类型 KU 数量、关系数量等基础统计。"""
+        ...