foxclaw 0.1.2 → 0.1.4

package/python/tools/strip_comments.py

@@ -0,0 +1,228 @@
+"""剥离代码里的解释性注释。
+
+用法:
+    python tools/strip_comments.py --dry          只统计,不改文件
+    python tools/strip_comments.py                真正改写
+    python tools/strip_comments.py a.py b.js      只处理指定文件
+
+不能一刀切:下面这些注释被删会改变 lint / 类型检查 / 解释器行为,必须原样保留。
+    #!...                shebang
+    # -*- coding -*-     编码声明
+    # noqa ...           ruff 抑制
+    # type: ...          mypy 注解(含 `x = []  # type: list[int]`)
+    # pragma / fmt: / isort: / pyright: / pylint: / nosec / coverage:
+docstring 不动 —— 它是运行时对象,不是注释。
+
+vendor/ 是内嵌第三方,不改;frontend/v3 是构建产物,由 vite 重新生成。
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import sys
+import tokenize
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+SKIP_PARTS = {".git", "node_modules", "__pycache__", ".venv", "venv", "vendor",
+              "foxclaw_data", "test_data", ".pytest_cache", ".ruff_cache", ".mypy_cache",
+              "build", "dist", "htmlcov"}
+# 生成副本:npm/python 由 npm/build.cjs 从仓库根复制,frontend/v3 由 vite 构建
+SKIP_PREFIX = {"frontend/v3/", "npm/python/"}
+EXTS = {".py", ".js", ".vue", ".ps1"}
+
+DIRECTIVE = re.compile(
+    r"^#\s*(?:!|-\*-|noqa|type:|pragma|fmt:|isort:|pyright:|pylint:|ruff:|nosec|"
+    r"coverage:|mypy:|noinspection|coding[:=])",
+    re.I,
+)
+
+MAX_BLANK = 2
+
+
+def targets() -> list[Path]:
+    out = []
+    for p in ROOT.rglob("*"):
+        if p.suffix not in EXTS or not p.is_file():
+            continue
+        rel = p.relative_to(ROOT).as_posix()
+        if SKIP_PARTS & set(p.relative_to(ROOT).parts):
+            continue
+        if any(rel.startswith(x) for x in SKIP_PREFIX):
+            continue
+        if rel == "tools/strip_comments.py":
+            continue
+        out.append(p)
+    return sorted(out)
+
+
+def collapse_blank(lines: list[str], limit: int = MAX_BLANK) -> list[str]:
+    out: list[str] = []
+    run = 0
+    for ln in lines:
+        if ln.strip() == "":
+            run += 1
+            if run > limit:
+                continue
+        else:
+            run = 0
+        out.append(ln)
+    return out
+
+
+def strip_py(text: str) -> tuple[str, int]:
+    try:
+        toks = list(tokenize.generate_tokens(io.StringIO(text).readline))
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        return text, 0
+
+    lines = text.splitlines(keepends=True)
+    drops: dict[int, int | None] = {}
+    for t in toks:
+        if t.type != tokenize.COMMENT:
+            continue
+        row, col = t.start
+        if DIRECTIVE.match(t.string):
+            continue
+        line = lines[row - 1] if row - 1 < len(lines) else ""
+        head = line[:col]
+        drops[row] = None if head.strip() == "" else col
+
+    if not drops:
+        return text, 0
+
+    out: list[str] = []
+    for idx, line in enumerate(lines, 1):
+        if idx not in drops:
+            out.append(line)
+            continue
+        col = drops[idx]
+        if col is None:
+            continue
+        body = line[:col].rstrip()
+        eol = line[len(line.rstrip("\r\n")):]
+        out.append(body + eol)
+    out = collapse_blank(out)
+    return "".join(out), len(drops)
+
+
+def _tpl_open(s: str) -> bool:
+    n = 0
+    i = 0
+    while i < len(s):
+        if s[i] == "\\":
+            i += 2
+            continue
+        if s[i] == "`":
+            n += 1
+        i += 1
+    return n % 2 == 1
+
+
+def strip_js(text: str) -> tuple[str, int]:
+    """只删独占整行的注释,行尾注释一律不动。
+
+    按位置切不行:正则字面量里的 \/\/ 和字符串里的 // 都会被当成注释起点 ——
+    markdown.js 的 /^https?:\/\//i 就被切掉半个函数。整行判定是安全的:
+    行首出现 // 或 /* 时,它只能是注释。
+    """
+    lines = text.splitlines(keepends=True)
+    out: list[str] = []
+    removed = 0
+    in_block = ""
+    in_tpl = False
+    for line in lines:
+        body = line.rstrip("\r\n")
+        s = body.strip()
+        if in_block:
+            removed += 1
+            if (in_block == "<!--" and "-->" in s) or (in_block == "/*" and "*/" in s):
+                in_block = ""
+            continue
+        if in_tpl:
+            if _tpl_open(s):
+                in_tpl = False
+            out.append(line)
+            continue
+        if s.startswith("<!--"):
+            removed += 1
+            if "-->" not in s[4:]:
+                in_block = "<!--"
+            continue
+        if s.startswith("/*"):
+            removed += 1
+            if "*/" not in s[2:]:
+                in_block = "/*"
+            continue
+        if s.startswith("//"):
+            removed += 1
+            continue
+        if _tpl_open(body):
+            in_tpl = True
+        out.append(line)
+    return "".join(collapse_blank(out, 1)), removed
+
+
+def strip_ps(text: str) -> tuple[str, int]:
+    """PowerShell 的注释符是 # 和 <# #>。只删独占行的,行尾的不碰 —— 拆字符串不值当。"""
+    out: list[str] = []
+    removed = 0
+    in_block = False
+    for line in text.splitlines(keepends=True):
+        stripped = line.strip()
+        if in_block:
+            removed += 1
+            if "#>" in stripped:
+                in_block = False
+            continue
+        if stripped.startswith("<#"):
+            removed += 1
+            if "#>" not in stripped[2:]:
+                in_block = True
+            continue
+        if stripped.startswith("#") and not re.match(r"#\s*requires\b", stripped, re.I):
+            removed += 1
+            continue
+        out.append(line)
+    return "".join(collapse_blank(out, 1)), removed
+
+
+def main(argv: list[str]) -> int:
+    dry = "--dry" in argv
+    picked = [Path(a) for a in argv if not a.startswith("-")]
+    files = picked or targets()
+    total_files = 0
+    total_lines = 0
+    for p in files:
+        if not p.is_absolute():
+            p = ROOT / p
+        raw = p.read_bytes()
+        text = raw.decode("utf-8")
+        if p.suffix == ".py":
+            new, n = strip_py(text)
+        elif p.suffix == ".ps1":
+            new, n = strip_ps(text)
+        else:
+            new, n = strip_js(text)
+        if n == 0 or new == text:
+            continue
+        if p.suffix == ".py":
+            try:
+                compile(new, str(p), "exec")
+            except SyntaxError as e:
+                print(f"SKIP {p.relative_to(ROOT)}: 删后语法错误 {e}")
+                continue
+        total_files += 1
+        total_lines += n
+        if dry:
+            print(f"{n:5d}  {p.relative_to(ROOT).as_posix()}")
+        else:
+            p.write_bytes(new.encode("utf-8"))
+    print(f"\n{'[dry] ' if dry else ''}files={total_files} comment_lines={total_lines}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

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:

package/python/foxclaw/api/app.py

@@ -1,123 +0,0 @@
-"""app 配置与挂载:CORS、HKC 星球数据面、前端静态文件。
-
-从 `foxclaw/api/__init__.py` 搬移出来的「挂载类」逻辑,均为接收 `app` 参数的纯函数,
-在 `__init__.py` 创建 `app` 之后按原顺序调用,保持行为不变。
-"""
-import os
-from pathlib import Path
-
-from fastapi import HTTPException
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.staticfiles import StaticFiles
-from fastapi.responses import FileResponse
-
-import foxclaw.api as _api
-
-
-def _configure_cors(app):
-    # ── 可选鉴权 + CORS 收紧（部署安全）──────────────────────────
-    # FOXCLAW_API_KEY 未设 → 开放(本地默认,保持现状,既有测试/前端不受影响)。
-    # 设了 → 所有 /api/* 请求必须带正确的 X-API-Key,否则 401。
-    # 注意:http 中间件**看不到 websocket scope**,故 /ws 的鉴权在 WS 端点内单独做
-    # (见 harness_websocket,用 ?key= 查询参数)。前端(静态)与 /docs 始终开放。
-    # 默认只放行回环来源(本地开发足够:前端与 API 是同源挂载,同源请求本就不经 CORS)。
-    # 需要跨源时设 FOXCLAW_CORS_ORIGINS=来源1,来源2(逗号分隔);显式设 "*" 才会全开(不推荐,
-    # 与未鉴权叠加等于把 API 交给任意网页)。收紧默认值属于「默认安全」:不再默认 allow_origins=["*"]。
-    _cors_env = os.environ.get("FOXCLAW_CORS_ORIGINS", "").strip()
-    if _cors_env == "*":
-        _CORS_ORIGINS = ["*"]
-        _CORS_ORIGIN_REGEX = None
-    elif _cors_env:
-        _CORS_ORIGINS = [o.strip() for o in _cors_env.split(",") if o.strip()]
-        _CORS_ORIGIN_REGEX = None
-    else:
-        _CORS_ORIGINS = []
-        _CORS_ORIGIN_REGEX = r"^https?://(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$"
-
-    app.add_middleware(
-        CORSMiddleware,
-        allow_origins=_CORS_ORIGINS,
-        allow_origin_regex=_CORS_ORIGIN_REGEX,
-        allow_methods=["*"],
-        allow_headers=["*"],
-    )
-
-
-def _mount_hkc(app):
-    # ── HKC 星球数据面:挂载 HKC 自带的 /knowledge REST 路由 ──────────────────
-    # 星球 UI(frontend/planet)需要 /knowledge/graph、/ku/{id}、/ku/{id}/neighbors、
-    # /ingest/*、/reset 等。HKC 在本进程装配,这里把它自带的 knowledge 路由挂上,并用
-    # dependency_overrides 把 get_container 指向 **Foxclaw 已装配的同一个容器**(依赖倒置,
-    # 不另开一套;保持惰性:首个 /knowledge 请求才触发 HKC 装配)。鉴权由上面中间件覆盖 /knowledge。
-    # 缺 vendor/hkc 或导入失败 → 静默跳过(星球无数据但不影响主应用)。
-    try:
-        from foxclaw.knowledge import _ensure_hkc_importable as _ensure_hkc
-        _ensure_hkc()
-        from hkc_api.routes.knowledge import router as _hkc_knowledge_router
-        from hkc_api.container import get_container as _hkc_get_container
-
-        def _resolve_hkc_container():
-            svc = _api._os_instance.hkc if _api._os_instance is not None else None
-            if svc is None or not getattr(svc, "available", False):
-                raise HTTPException(503, "HKC 未启用(未 vendor 或缺依赖)")
-            return svc.container
-
-        app.dependency_overrides[_hkc_get_container] = _resolve_hkc_container
-        app.include_router(_hkc_knowledge_router)
-        # /stats 系统统计:独立 hkc-api 在 main.py 顶层 @app.get("/stats") 定义,不在任何
-        # router 里,嵌入式挂载时会漏掉 → 星球 UI 的 updateDataInfo 调 /stats 404,
-        # 「数据目录 / 全库知识总数」提示失效。这里补挂,复用同一容器 override(惰性装配)。
-        @app.get("/stats", tags=["system"])
-        def _hkc_stats():
-            return _resolve_hkc_container().stats()
-        # 连接设置(星球 UI 左下的「连接设置」面板)POST /config/llm 做运行时 LLM 配置,
-        # 覆盖 .env 的 HKC_LLM_*。独立 hkc-api 有这个路由,嵌入式 foxclaw 之前没挂 → 前端
-        # 报「模型配置失败:404」且改配置无效。这里补挂 config 路由(同一容器 override 已覆盖),
-        # 让「连接设置」的「知识抽取模型」段在 foxclaw 下真正生效。
-        from hkc_api.routes.config import router as _hkc_config_router
-        app.include_router(_hkc_config_router)   # /config/llm(GET 读配置 / POST 改配置)
-        # 星球副面板(冲突裁决/能力编译/最短路径)用的 HKC 路由。不挂的话 /conflicts、
-        # /abilities、/search/path 在 Foxclaw 下 404 → 星球「冲突裁决」面板拉不到数据、
-        # 永远显示 0(误导),能力/路径面板同样空。这里补挂(同一容器 override 已覆盖)。
-        try:
-            from hkc_api.routes.ability import router as _hkc_ability_router
-            from hkc_api.routes.search  import router as _hkc_search_router
-            app.include_router(_hkc_ability_router)   # /abilities, /conflicts
-            app.include_router(_hkc_search_router)     # /search/path 等
-            _sub = "/abilities, /conflicts, /search/*"
-        except Exception as _e2:
-            _sub = f"(能力/搜索路由未挂: {_e2})"
-        print(f"[Foxclaw API] ✓ HKC 星球数据面已挂载 (/knowledge/*, /config/*, {_sub})")
-    except Exception as _e:
-        print(f"[Foxclaw API] · HKC 星球数据面未挂载(可选): {_e}")
-
-
-def _mount_frontend(app):
-    # ── 前端静态文件 ───────────────────────────────────────────
-    # frontend/ 下现在并存三套:frontend/v3(Vue,当前主界面)、deck_v2.html(旧主界面)、
-    # deck.html(最早的一版)。根路径必须给 v3 —— 之前一直指向 deck_v2,新版只能手输 /v3/,
-    # 等于新界面根本没上线。
-    frontend_dir = Path(__file__).parent.parent.parent / "frontend"
-    if not frontend_dir.exists():
-        return
-
-    v3_index = frontend_dir / "v3" / "index.html"
-
-    @app.get("/")
-    async def serve_root():
-        """主界面。v3 未构建(没跑 npm run build)时退回旧 deck_v2,不让根路径 404。"""
-        if v3_index.exists():
-            return FileResponse(str(v3_index))
-        legacy = frontend_dir / "deck_v2.html"
-        return FileResponse(str(legacy if legacy.exists() else frontend_dir / "deck.html"))
-
-    @app.get("/classic")
-    async def serve_classic():
-        """旧界面(deck_v2,v5.34):新版出问题时的手动回退入口,也留着它的二级面板历史。"""
-        return FileResponse(str(frontend_dir / "deck_v2.html"))
-
-    @app.get("/old")
-    async def serve_deck_old():
-        return FileResponse(str(frontend_dir / "deck.html"))
-
-    app.mount("/", StaticFiles(directory=str(frontend_dir), html=True), name="frontend")