foxclaw 0.1.3 → 0.1.4

package/python/tools/recheck_conflicts.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python
+"""复核存量冲突卡:用当前判定规则重算,把已经不成立的卡批量标记为误判。
+
+默认 dry-run,只打印统计与样本;加 --apply 才真正调 /conflicts/bulk-dismiss。
+写入必须走运行中的服务——只有它才持有 open 冲突集合与向量索引,直接改库会让
+服务内的缓存与库不一致(那些因冲突被置 disputed 的 claim 也不会回到检索)。
+
+用法:
+    python tools/recheck_conflicts.py                    # 只看统计
+    python tools/recheck_conflicts.py --apply            # 确认后批量关闭误判
+"""
+import argparse
+import json
+import sqlite3
+import sys
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "vendor" / "hkc"))
+
+from hkc_kee.kee import _SimpleEmbedder  # noqa: E402
+
+THRESHOLD = 0.30          # 与 KnowledgeEvolutionEngine.similarity_threshold 一致
+DEFAULT_DB = ROOT / "foxclaw_data" / "hkc" / "hkc.db"
+
+
+def load_open(conn):
+    cols = [r[1] for r in conn.execute("pragma table_info(conflict_cards)")]
+    idx = {c: i for i, c in enumerate(cols)}
+    rows = conn.execute(
+        "select * from conflict_cards where status='open' order by conflict_id"
+    ).fetchall()
+    return [
+        {
+            "conflict_id": r[idx["conflict_id"]],
+            "a": r[idx["claim_a_id"]],
+            "b": r[idx["claim_b_id"]],
+            "domain": r[idx["domain"]],
+        }
+        for r in rows
+    ]
+
+
+def load_claims(conn):
+    cols = [r[1] for r in conn.execute("pragma table_info(knowledge_units)")]
+    idx = {c: i for i, c in enumerate(cols)}
+    out = {}
+    for r in conn.execute("select * from knowledge_units"):
+        if r[idx["ku_type"]] != "Claim":
+            continue
+        try:
+            extra = json.loads(r[idx["extra"]] or "{}")
+        except Exception:
+            extra = {}
+        out[r[idx["ku_id"]]] = {
+            "text": (extra.get("statement") or r[idx["name"]] or "").strip(),
+            "claim_status": extra.get("claim_status", "active"),
+        }
+    return out
+
+
+def classify(cards, claims, emb):
+    buckets = {"claim_missing": [], "not_contradiction": [], "still_contradiction": []}
+    for card in cards:
+        ca, cb = claims.get(card["a"]), claims.get(card["b"])
+        if not ca or not cb or not ca["text"] or not cb["text"]:
+            buckets["claim_missing"].append(card)
+            continue
+        score = emb.score(ca["text"], cb["text"])
+        card["score"] = round(score, 3)
+        card["a_text"], card["b_text"] = ca["text"][:70], cb["text"][:70]
+        key = "still_contradiction" if score < -THRESHOLD else "not_contradiction"
+        buckets[key].append(card)
+    return buckets
+
+
+def post(base_url, path, payload, timeout=300):
+    req = urllib.request.Request(
+        base_url.rstrip("/") + path,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.load(resp)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="复核并批量关闭误判冲突卡")
+    ap.add_argument("--db", default=str(DEFAULT_DB), help="HKC sqlite 路径(只读)")
+    ap.add_argument("--base-url", default="http://127.0.0.1:8000",
+                    help="运行中的服务地址(--apply 时用)")
+    ap.add_argument("--apply", action="store_true", help="真正提交,默认只统计")
+    ap.add_argument("--chunk", type=int, default=200, help="每次批量提交的张数")
+    ap.add_argument("--sample", type=int, default=5, help="每类打印的样本数")
+    ap.add_argument("--json", action="store_true", help="输出 JSON 摘要")
+    args = ap.parse_args(argv)
+
+    db = Path(args.db)
+    if not db.exists():
+        print(f"找不到库文件:{db}", file=sys.stderr)
+        return 2
+
+    conn = sqlite3.connect(f"file:{db.as_posix()}?mode=ro", uri=True)
+    cards = load_open(conn)
+    claims = load_claims(conn)
+    if not cards:
+        print("没有 open 冲突卡,无需处理")
+        return 0
+
+    buckets = classify(cards, claims, _SimpleEmbedder())
+    closed = buckets["not_contradiction"] + buckets["claim_missing"]
+
+    summary = {
+        "open_total": len(cards),
+        "not_contradiction": len(buckets["not_contradiction"]),
+        "claim_missing": len(buckets["claim_missing"]),
+        "still_contradiction": len(buckets["still_contradiction"]),
+        "to_close": len(closed),
+    }
+    if args.json:
+        print(json.dumps(summary, ensure_ascii=False, indent=2))
+    else:
+        print(f"open 冲突卡          {summary['open_total']}")
+        print(f"  重算后不再矛盾     {summary['not_contradiction']}  ← 可关闭")
+        print(f"  claim 已不存在     {summary['claim_missing']}  ← 可关闭")
+        print(f"  仍然矛盾           {summary['still_contradiction']}  ← 留给人工裁决")
+
+    if args.sample:
+        print("\n仍然矛盾的样本(需人工看):")
+        for c in buckets["still_contradiction"][:args.sample]:
+            print(f"  {c['conflict_id']} score={c['score']}")
+            print(f"    A: {c['a_text']}")
+            print(f"    B: {c['b_text']}")
+
+    if not args.apply:
+        if closed:
+            print(f"\ndry-run,未提交。确认后加 --apply 关闭 {len(closed)} 张。")
+        return 0
+
+    ids = [c["conflict_id"] for c in closed]
+    done = 0
+    for i in range(0, len(ids), args.chunk):
+        batch = ids[i:i + args.chunk]
+        res = post(args.base_url, "/conflicts/bulk-dismiss",
+                   {"conflict_ids": batch, "resolved_by": "recheck",
+                    "note": "复核误判：两个观点并非同一命题的正反两面"})
+        done += int(res.get("dismissed", 0))
+        print(f"  已关闭 {done}/{len(ids)}")
+    print(f"完成:提交 {len(ids)} 张,实际关闭 {done} 张")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/python/tools/release_check.py

@@ -10,10 +10,11 @@ PyPI / npm 的版本号不可撤回:上传后只能 yank(仍占号、仍可被 p
 
 两侧产物性质不同(别把"发布成功"当"装完能用")
 ------------------------------------------
-HKC / HMR 内嵌在 vendor/、运行期按 `Path(__file__)/../../vendor` 找;而 setuptools
-只收 `foxclaw*`,故 **wheel/sdist 不含 vendor/**:装上是能 import、但知识/记忆
-子系统降级为 None 的**占位包**(与 npm/index.js 占位同一性质)。本脚本对"缺 vendor"
-只 warn 不 error —— 既定事实不是事故,但发布说明必须写明。
+后端是同一份代码:`hmr` 与 `hkc_*` 经 `packages.find` 的 `where=vendor` 被提升成
+顶层包,已经真的在 wheel 里(0.1.2 起就是),pip 装完知识/记忆子系统完好。
+**真正缺的是前端 UI** —— `frontend/` 在仓库根、不属于任何包,构建前必须先跑
+`tools/bundle_web.py` 把它复制成 `foxclaw/web/`。漏跑则 wheel 里没有任何
+html/js,`foxclaw serve` 首页 404,所以这里对"缺 foxclaw/web"判 **error**。
 
 用法
 ----
@@ -278,10 +279,18 @@ def check_dist(dist: Path, name: str, version: str) -> list:
         issues.append(Issue("error", "missing_entry", f"{sdist.name} 里没有 foxclaw/cli.py"))
 
     issues += _scan_forbidden(whl) + _scan_forbidden(sdist)
-    if not any("/vendor/" in e for e in entries):
-        issues.append(Issue("warn", "no_vendor",
-                            f"{whl.name} 不含 vendor/(hkc/hmr)→ 装上是占位包,"
-                            f"知识/记忆子系统降级;发布说明需写明"))
+    # HMR/HKC 在 wheel 里被"提升"成顶层包(hmr/、hkc_ace/…),没有 vendor/ 目录;
+    # 判据看顶层包,不看 vendor/ 路径,否则会把完好的 wheel 误判成占位包。
+    if not any(e.startswith("hmr/") for e in entries):
+        issues.append(Issue("error", "missing_hmr",
+                            f"{whl.name} 里没有 hmr/ → 记忆子系统会降级;检查 packages.find"))
+    if not any(e.startswith("hkc_") for e in entries):
+        issues.append(Issue("error", "missing_hkc",
+                            f"{whl.name} 里没有 hkc_* → 知识子系统会降级;检查 packages.find"))
+    if "foxclaw/web/v3/index.html" not in entries:
+        issues.append(Issue("error", "missing_web_ui",
+                            f"{whl.name} 缺 foxclaw/web/v3/index.html → pip 装完首页 404;"
+                            f"构建前先跑 python tools/bundle_web.py"))
     return issues
 
 

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

@@ -8,6 +8,7 @@ from ..container import HKCContainer, get_container
 from ..schemas import (
     AbilityResponse, CoverageReportResponse,
     ConflictResponse, ConflictResolveRequest,
+    ConflictDismissRequest, ConflictBulkDismissRequest,
 )
 
 router = APIRouter(tags=["ability"])
@@ -149,3 +150,33 @@ def resolve_conflict(
             detail=f"裁决失败：冲突 {conflict_id} 不存在、已解决，或 winner_id 无效"
         )
     return {"conflict_id": conflict_id, "resolved": True, "winner": req.winner_id}
+
+
+@router.post("/conflicts/bulk-dismiss")
+def bulk_dismiss_conflicts(
+    req: ConflictBulkDismissRequest,
+    c: HKCContainer = Depends(get_container),
+):
+    """批量把误判冲突关闭（不判胜负、不废弃任何一方观点）。"""
+    n = c.kee.dismiss_conflicts(
+        req.conflict_ids, note=req.note, resolved_by=req.resolved_by
+    )
+    return {"requested": len(req.conflict_ids), "dismissed": n}
+
+
+@router.post("/conflicts/{conflict_id}/dismiss")
+def dismiss_conflict(
+    conflict_id: str,
+    req: ConflictDismissRequest,
+    c: HKCContainer = Depends(get_container),
+):
+    """把一张误判冲突标记为已解决（双方观点都保留）。"""
+    ok = c.kee.dismiss_conflict(
+        conflict_id, note=req.note, resolved_by=req.resolved_by
+    )
+    if not ok:
+        raise HTTPException(
+            status_code=400,
+            detail=f"关闭失败：冲突 {conflict_id} 不存在或已解决"
+        )
+    return {"conflict_id": conflict_id, "dismissed": True}

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

@@ -138,6 +138,17 @@ class ConflictResolveRequest(BaseModel):
     resolved_by: str = "human"
 
 
+class ConflictDismissRequest(BaseModel):
+    note:        str = ""
+    resolved_by: str = "human"
+
+
+class ConflictBulkDismissRequest(BaseModel):
+    conflict_ids: list[str]
+    note:         str = ""
+    resolved_by:  str = "human"
+
+
 # ── Stats ────────────────────────────────────────────────────
 
 class StatsResponse(BaseModel):

package/python/vendor/hkc/hkc_kee/kee.py

@@ -37,6 +37,10 @@ _NEG_CJK_FALSE = (
     "非常", "非凡",
     "不过", "不仅", "不但", "不断", "不只", "不妨", "不禁", "不由", "不时", "不外乎", "不失为",
     "差不多", "差点",
+    # 描述性「不/无」:修饰名词或状态而非否定命题(不变/不可观测/不同/不管…),
+    # 是最主要的假阳性来源——技术文档几乎每句都带,却与立场无关。
+    "不变", "不同", "不论", "不管", "不再", "不需", "无需", "无须",
+    "不可观测", "不可见", "不可控", "不可用", "不可变", "不可能",
 )
 _NEG_ASCII_RE = _re.compile(r"\b(" + "|".join(sorted(_NEG_ASCII, key=len, reverse=True)) + r")\b")
 _NEGATION = _NEG_ASCII | _NEG_CJK   # 供 _score_keyword 的词集匹配(word-set,ASCII 本就安全)
@@ -57,6 +61,31 @@ class _SimpleEmbedder:
     无 ST/加载失败 → 回退 v1 关键词重叠 + 否定词。接口不变。
     """
     _MODEL_NAME = "paraphrase-multilingual-MiniLM-L12-v2"   # 与 HKC LocalSTBackend 默认同名 → 共享一份
+    # 否定翻转的两个门槛,缺一不可:
+    #   NEG_FLIP_MIN_COS     —— 主题相关性(同领域才算得上对立);
+    #   NEG_FLIP_MIN_OVERLAP —— 字面同命题(二元组 Jaccard)。
+    # 只用余弦时,"同领域不同命题"也会被判反向(实测 1063 张伪冲突的主因);而只用字面
+    # 重合又认不出换了说法的对立。两条一起过 = 讲同一件事且一方否定,才是真矛盾。
+    NEG_FLIP_MIN_COS = 0.35
+    NEG_FLIP_MIN_OVERLAP = 0.40
+
+    def __init__(self, neg_flip_min_cos: float | None = None,
+                 neg_flip_min_overlap: float | None = None):
+        if neg_flip_min_cos is not None:
+            self.NEG_FLIP_MIN_COS = float(neg_flip_min_cos)
+        if neg_flip_min_overlap is not None:
+            self.NEG_FLIP_MIN_OVERLAP = float(neg_flip_min_overlap)
+
+    @staticmethod
+    def _bigrams(text: str) -> set:
+        t = "".join(ch for ch in (text or "").lower() if not ch.isspace())
+        return {t[i:i + 2] for i in range(len(t) - 1)}
+
+    def _same_proposition(self, text_a: str, text_b: str) -> bool:
+        ga, gb = self._bigrams(text_a), self._bigrams(text_b)
+        if not ga or not gb:
+            return False
+        return len(ga & gb) / len(ga | gb) >= self.NEG_FLIP_MIN_OVERLAP
 
     @staticmethod
     def _has_neg(text: str) -> bool:
@@ -81,8 +110,10 @@ class _SimpleEmbedder:
                 va = _encode_one(model, self._MODEL_NAME, text_a)   # 缓存,不重复编码
                 vb = _encode_one(model, self._MODEL_NAME, text_b)
                 cos = float(np.dot(va, vb))   # 归一化后点积=余弦 ∈ [-1,1]
-                # 否定方向:主题高度相似但一方否定另一方不否定 → 立场相反 → 反号(矛盾)
-                if self._has_neg(text_a) != self._has_neg(text_b) and cos > 0.35:
+                # 否定方向:同一命题一方否定 → 立场相反 → 反号(矛盾)
+                if (self._has_neg(text_a) != self._has_neg(text_b)
+                        and cos >= self.NEG_FLIP_MIN_COS
+                        and self._same_proposition(text_a, text_b)):
                     return -abs(cos)
                 return max(-1.0, min(1.0, cos))
             except Exception:
@@ -161,16 +192,23 @@ class KnowledgeEvolutionEngine:
         id_gen:      IDGenerator,
         similarity_threshold: float = 0.30,
         auto_resolve_gap:     float = 0.20,
+        neg_flip_min_cos:     float | None = None,
+        neg_flip_min_overlap: float | None = None,
     ):
         self.store   = graph_store
         self.bus     = event_bus
         self.id_gen  = id_gen
-        self.embedder = _SimpleEmbedder()
+        self.embedder = _SimpleEmbedder(
+            neg_flip_min_cos=neg_flip_min_cos,
+            neg_flip_min_overlap=neg_flip_min_overlap,
+        )
         self.state_machine = ClaimStateMachine()
         # 语义方向阈值(score∈[-1,1]):|score|>threshold 判同向(合并)/反向(冲突)。
         # 默认 0.30 与既有硬编码一致(behavior-preserving);可经构造参数调严/调宽。
         self.similarity_threshold = similarity_threshold
         self.auto_resolve_gap     = auto_resolve_gap
+        self.neg_flip_min_cos     = self.embedder.NEG_FLIP_MIN_COS
+        self.neg_flip_min_overlap = self.embedder.NEG_FLIP_MIN_OVERLAP
 
         # open 冲突卡的 (claim_a, claim_b) 对索引:替代 _handle_conflict 里每次
         # list_conflicts 全扫去重(冲突多时 O(冲突²))。并发摄入会跨线程碰它 → 加锁。
@@ -539,3 +577,86 @@ class KnowledgeEvolutionEngine:
             }
         })
         return True
+
+    def dismiss_conflict(
+        self,
+        conflict_id: str,
+        note:        str = "",
+        resolved_by: str = "human",
+    ) -> bool:
+        """按「误判」关闭一张冲突卡:不判胜负,双方 claim_status 保持原样。"""
+        return self.dismiss_conflicts(
+            [conflict_id], note=note, resolved_by=resolved_by
+        ) == 1
+
+    def dismiss_conflicts(
+        self,
+        conflict_ids,
+        note:        str = "",
+        resolved_by: str = "human",
+    ) -> int:
+        """批量关闭误判冲突卡,返回真正关闭的张数。
+
+        与 manual_resolve 的差别:没有 winner,也不把任何一方标成 superseded。
+        唯一例外是因冲突被置为 disputed 的 claim——disputed 会被检索层剔除
+        (_sync_ku 分支 3),若它已不牵涉任何 open 冲突,这里恢复成 active;
+        否则关掉卡片等于让这条知识永久隐身。
+        """
+        cards = []
+        for cid in dict.fromkeys(conflict_ids or []):
+            card = self.store.get_conflict(cid)
+            if card and card.status == ConflictStatus.OPEN:
+                cards.append(card)
+        if not cards:
+            return 0
+
+        note = note or "误判：双方观点并存，不构成对立"
+        ts   = datetime.now(timezone.utc).isoformat()
+        touched = set()
+        for card in cards:
+            card.status          = ConflictStatus.RESOLVED
+            card.resolved_by     = resolved_by
+            card.resolved_at     = ts
+            card.resolution_note = note
+            self.store.save_conflict(card)
+            self._forget_open_pair(card.claim_a_id, card.claim_b_id)
+            touched.update((card.claim_a_id, card.claim_b_id))
+            self.bus.publish({
+                "event":   KEPEvents.CONFLICT_RESOLVED,
+                "source":  "KEE",
+                "payload": {
+                    "conflict_id": card.conflict_id,
+                    "reason":      "dismissed",
+                    "by":          resolved_by,
+                }
+            })
+
+        with self._conflict_lock:
+            self._ensure_open_pairs()
+            still_open = set(self._open_pairs or ())
+
+        restored = []
+        for ku_id in touched:
+            if any(ku_id in pair for pair in still_open):
+                continue
+            ku = self.store.get(ku_id)
+            if ku is None or getattr(ku, "claim_status", None) != ClaimStatus.DISPUTED:
+                continue
+            ku.claim_status = ClaimStatus.ACTIVE
+            if self.store.patch_ku(
+                ku_id, extra={"claim_status": ClaimStatus.ACTIVE.value}
+            ) == 0:
+                self.store.put(ku)
+            restored.append(ku_id)
+
+        if restored:
+            self.bus.publish({
+                "event":   KEPEvents.KNOWLEDGE_UPDATED,
+                "source":  "KEE",
+                "payload": {
+                    "ku_ids": restored,
+                    "reason": "conflict_dismissed_restored",
+                }
+            })
+        return len(cards)
+

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

@@ -125,6 +125,28 @@ class BaseClient(ABC):
         """人工裁决冲突。"""
         ...
 
+    @abstractmethod
+    def dismiss_conflict(
+        self,
+        conflict_id: str,
+        note: str = "",
+        resolved_by: str = "sdk",
+    ) -> bool:
+        """把误判冲突关闭：不判胜负，双方观点都保留。"""
+        ...
+
+    def dismiss_conflicts(
+        self,
+        conflict_ids: list[str],
+        note: str = "",
+        resolved_by: str = "sdk",
+    ) -> int:
+        """批量关闭误判冲突，返回真正关闭的张数。默认逐条调用。"""
+        return sum(
+            1 for cid in conflict_ids
+            if self.dismiss_conflict(cid, note=note, resolved_by=resolved_by)
+        )
+
     # ── 系统 ─────────────────────────────────────────────────
 
     @abstractmethod

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

@@ -143,6 +143,16 @@ class DirectClient(BaseClient):
             note=note, resolved_by=resolved_by,
         )
 
+    def dismiss_conflict(self, conflict_id, note="", resolved_by="sdk") -> bool:
+        return self.c.kee.dismiss_conflict(
+            conflict_id=conflict_id, note=note, resolved_by=resolved_by,
+        )
+
+    def dismiss_conflicts(self, conflict_ids, note="", resolved_by="sdk") -> int:
+        return self.c.kee.dismiss_conflicts(
+            list(conflict_ids or []), note=note, resolved_by=resolved_by,
+        )
+
     # ── 系统 ─────────────────────────────────────────────────
 
     def stats(self) -> dict:

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

@@ -152,6 +152,25 @@ class HTTPClient(BaseClient):
         except HKCBadRequest:
             return False
 
+    def dismiss_conflict(self, conflict_id, note="", resolved_by="sdk") -> bool:
+        from .exceptions import HKCBadRequest
+        try:
+            data = self._request("POST", f"/conflicts/{conflict_id}/dismiss", json={
+                "note": note, "resolved_by": resolved_by,
+            })
+            return data.get("dismissed", False)
+        except HKCBadRequest:
+            return False
+
+    def dismiss_conflicts(self, conflict_ids, note="", resolved_by="sdk") -> int:
+        conflict_ids = list(conflict_ids or [])
+        if not conflict_ids:
+            return 0
+        data = self._request("POST", "/conflicts/bulk-dismiss", json={
+            "conflict_ids": conflict_ids, "note": note, "resolved_by": resolved_by,
+        })
+        return int(data.get("dismissed", 0))
+
     # ── 系统 ─────────────────────────────────────────────────
 
     def stats(self) -> dict: