foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/kernel/scheduler.py

@@ -29,7 +29,7 @@ class _PriorityAdmission:
         self.max = max_slots
         self._free = max_slots or 0
         self._cv = threading.Condition()
-        self._heap: list = []          # (-priority, seq):优先级降序,同优先级 FIFO
+        self._heap: list = []
         self._seq = 0
 
     def acquire(self, priority: int = 0) -> None:
@@ -43,7 +43,7 @@ class _PriorityAdmission:
                 self._cv.wait()
             heapq.heappop(self._heap)
             self._free -= 1
-            if self._free > 0 and self._heap:   # 还有空槽+等待者 → 唤醒下一个最高优先者
+            if self._free > 0 and self._heap:
                 self._cv.notify_all()
 
     def release(self) -> None:
@@ -58,11 +58,8 @@ class Scheduler:
     def __init__(self, max_concurrency: Optional[int] = None, spine=None,
                  process_manager=None):
         self.max_concurrency = max_concurrency if (max_concurrency and max_concurrency > 0) else None
-        # Step5:优先级准入(满载时高优先排队者先获空位;不抢占正在跑的)。无上限时零等待。
         self._adm = _PriorityAdmission(self.max_concurrency)
         self._spine = spine
-        # 【Step3】统一生命周期:有 ProcessManager 则委托它发 task.lifecycle.*(唯一词汇、
-        # 唯一状态机);无 pm(standalone/测试)则调度器自发 task.lifecycle.* 作回退。
         self.process_manager = process_manager
         self._lock = threading.Lock()
         self._stats = {"submitted": 0, "running": 0, "completed": 0,
@@ -80,7 +77,6 @@ class Scheduler:
             proc = pm.create(task, agent_id=agent_id, schedule={"priority": priority})
         else:
             self._emit("scheduled", agent_id, task, priority)
-        # 优先级准入:满载则排队等空位(高优先先入);无上限时零等待(behavior-preserving)
         self._adm.acquire(priority)
         try:
             with self._lock:
@@ -90,8 +86,6 @@ class Scheduler:
             if proc is not None:
                 pm.mark_running(proc.process_id)
             else:
-                # 【P5-2】回退路径的词汇与 ProcessManager 对齐:started → running
-                # (pm 的词汇是 created/queued/scheduled/running/completed/failed)
                 self._emit("running", agent_id, task, priority)
             result = fn()
             with self._lock:
@@ -116,7 +110,7 @@ class Scheduler:
 
     def stats(self) -> dict:
         with self._lock:
-            s = dict(self._stats)
+            s: dict[str, int | None] = dict(self._stats)
         s["max_concurrency"] = self.max_concurrency
         return s
 

package/python/foxclaw/kernel/sentinel.py

@@ -23,12 +23,9 @@ import secrets
 import sys
 import time
 from pathlib import Path
+from typing import Any
 
 
-# ── 凭证保险箱(vault)────────────────────────────────────────
-# 真实凭证只进守门人进程,主进程内存里从不出现。两个来源:
-#   1. 环境变量前缀 FOXCLAW_GUARDIAN_SECRET_<REF>(REF 统一小写);
-#   2. FOXCLAW_GUARDIAN_SECRETS 指向的 JSON 文件 {"ref": "secret", ...}。
 def load_vault() -> dict:
     vault: dict = {}
     prefix = "FOXCLAW_GUARDIAN_SECRET_"
@@ -42,13 +39,10 @@ def load_vault() -> dict:
             if isinstance(d, dict):
                 vault.update({str(k).lower(): v for k, v in d.items()})
         except Exception:
-            pass  # 损坏的 secrets 文件不拖垮守门人;宁可少借不错借
+            pass
     return vault
 
 
-# ── MCP server 配置(守门人持有凭证)──────────────────────────
-# 与 vault 对称:MCP 的 headers 里可能含真凭证(Authorization/x-api-key 等)。
-# 主进程通过 mcp_register 推送配置;也可用 FOXCLAW_GUARDIAN_MCP_SERVERS 指向 JSON 文件做初始加载。
 def _mcp_servers_path() -> str:
     """守门人侧 MCP 配置持久化文件。优先 FOXCLAW_GUARDIAN_MCP_SERVERS 显式指定;
     否则用 FOXCLAW_GUARDIAN_DATA_DIR 下的 mcp_guardian_servers.json。主进程的 mcp_servers.json 已不含 headers。"""
@@ -79,7 +73,7 @@ def load_mcp_servers() -> dict:
                 "transport": c.get("transport") or "streamable_http",
             }
     except Exception:
-        pass  # 损坏配置不拖垮守门人;宁可少配不错配
+        pass
     return servers
 
 
@@ -94,18 +88,15 @@ def _persist_mcp_servers(servers: dict) -> None:
         tmp.write_text(json.dumps(out, ensure_ascii=False, indent=1), encoding="utf-8")
         tmp.replace(Path(path))
     except Exception:
-        pass  # 持久化失败不拖垮守门人;重启后主进程会重新 mcp_register
+        pass
 
 
-# ── 短期可撤销能力令牌 ──────────────────────────────────────
-# 彻底取代「resolve 真值借出」:主进程只拿得到一个不透明随机 token,真值永不出守门人进程。
-# 令牌 = 一次性 + 过期 + 可撤销,进程内状态表(不依赖 HMAC 签名,因为 token 本身高熵、无法伪造/猜中)。
 class TokenStore:
     def __init__(self, default_ttl: float = 60.0):
         self._default_ttl = default_ttl
         self._tokens: dict = {}
 
-    def mint(self, ref: str, ttl: float = None) -> dict:
+    def mint(self, ref: str, ttl: float | None = None) -> dict:
         """为某 ref 签发能力令牌。返回 {token, expires_in},绝不返回真值。"""
         ttl = ttl if ttl is not None else self._default_ttl
         token = secrets.token_urlsafe(32)
@@ -137,7 +128,6 @@ class TokenStore:
         return True
 
 
-# ── 跨进程重建(守门人侧)─────────────────────────────────────
 def _rebuild_skill(sd: dict):
     """主进程只传 evaluate 需要的字段 + 已算好的 trust。重建为鸭子类型对象。"""
     from types import SimpleNamespace
@@ -145,7 +135,7 @@ def _rebuild_skill(sd: dict):
     return SimpleNamespace(
         id=sd.get("id", ""),
         kind=sd.get("kind", "local"),
-        side_effect=sd.get("side_effect", "write"),     # 未声明 → 有副作用
+        side_effect=sd.get("side_effect", "write"),
         destructive=bool(sd.get("destructive", False)),
         external=bool(sd.get("external", False)),
         read_only=sd.get("read_only", None),
@@ -187,7 +177,7 @@ def _handle_mint(msg: dict, vault: dict, store: TokenStore) -> dict:
     ttl = float(ttl) if ttl else None
     out = store.mint(ref, ttl)
     print(f"[Sentinel] mint {ref}", file=sys.stderr, flush=True)
-    return out  # {"token", "expires_in"} —— 不含真值
+    return out
 
 
 def _handle_revoke(msg: dict, store: TokenStore) -> dict:
@@ -212,7 +202,7 @@ def _handle_mcp_register(msg: dict, servers: dict) -> dict:
         headers = dict(c.get("headers") or {})
         old = servers.get(sid)
         if not headers and old:
-            headers = dict(old.get("headers") or {})  # 主进程不持 headers,不覆盖守门人已有凭证
+            headers = dict(old.get("headers") or {})
         new_servers[sid] = {
             "name": c.get("name") or sid,
             "url": c.get("url", ""),
@@ -251,7 +241,7 @@ def _handle_mcp_call(msg: dict, servers: dict) -> dict:
         if out.get("isError"):
             return SkillResult(skill_id, False, status="blocked",
                                message=f"MCP 工具返回错误: {out.get('content') or 'unknown'}").to_dict()
-        out = _mark_untrusted(out)   # 外部 MCP 返回=不可信,防提示注入
+        out = _mark_untrusted(out)
         print(f"[Sentinel] mcp_call {server_id}.{tool}", file=sys.stderr, flush=True)
         return SkillResult(skill_id, True, output=out,
                            message="MCP 调用完成(外部不可信数据)").to_dict()
@@ -329,7 +319,7 @@ def _handle_execute_web(msg: dict, vault: dict, store: TokenStore) -> dict:
     secret = None
     used_ref = None
     if token:
-        ref = store.redeem(token)   # 一次性:兑换即作废
+        ref = store.redeem(token)
         if ref is None:
             return SkillResult(skill_id, False, status="blocked",
                                message="能力令牌无效/已过期/已使用/已撤销").to_dict()
@@ -345,7 +335,6 @@ def _handle_execute_web(msg: dict, vault: dict, store: TokenStore) -> dict:
             return SkillResult(skill_id, False, status="blocked",
                                message=f"凭证 ref「{secret_ref}」未在守门人 vault 中配置").to_dict()
 
-    # SSRF 校验:守门人侧也做(主进程可能被攻破传内网地址,不能只信主进程)
     block = ssrf_check(endpoint, allow_local=allow_local)
     if block:
         return SkillResult(skill_id, False, status="blocked",
@@ -364,7 +353,7 @@ def _handle_execute_web(msg: dict, vault: dict, store: TokenStore) -> dict:
         return SkillResult(skill_id, False, status="blocked",
                            message="缺少 httpx 依赖,无法发起 Web API 调用").to_dict()
 
-    req_kwargs = {"headers": headers, "timeout": timeout, "follow_redirects": False}
+    req_kwargs: dict[str, Any] = {"headers": headers, "timeout": timeout, "follow_redirects": False}
     if loc == "query":
         req_kwargs["params"] = args
     else:
@@ -416,6 +405,7 @@ def serve_stdio(vault: dict, store: TokenStore, servers: dict) -> None:
         mid = msg.get("id")
         op = msg.get("op")
         try:
+            result: dict[str, object]
             if op == "ping":
                 result = {"pong": True}
             elif op == "evaluate":
@@ -438,7 +428,7 @@ def serve_stdio(vault: dict, store: TokenStore, servers: dict) -> None:
             else:
                 result = {"error": f"unknown op: {op}"}
             _reply({"id": mid, "ok": True, "result": result})
-        except Exception as e:  # 单条请求失败不影响守门人存活
+        except Exception as e:
             _reply({"id": mid, "ok": False, "error": str(e)})
 
 

package/python/foxclaw/kernel/sentinel_client.py

@@ -22,20 +22,18 @@ class SentinelUnavailable(RuntimeError):
 
 
 def _project_root() -> str:
-    # foxclaw/kernel/sentinel_client.py → parents[0]=kernel, [1]=foxclaw, [2]=Foxclaw
     return str(Path(__file__).resolve().parents[2])
 
 
 class SentinelClient:
-    def __init__(self, timeout: float = 5.0, cmd=None, data_dir: str = None):
+    def __init__(self, timeout: float = 5.0, cmd=None, data_dir: str | None = None):
         self._timeout = timeout
         self._data_dir = data_dir
         self._lock = threading.Lock()
         self._req_id = 0
-        self._proc = None
+        self._proc: subprocess.Popen[str] | None = None
         self._spawn(cmd)
 
-    # ── 进程生命周期 ─────────────────────────────────────────
     def _spawn(self, cmd) -> None:
         if cmd is None:
             cmd = [sys.executable, "-m", "foxclaw.kernel.sentinel"]
@@ -50,7 +48,7 @@ class SentinelClient:
         except Exception as e:
             raise RuntimeError(f"Sentinel 启动失败: {e}")
         try:
-            self._request("ping", {})  # 握手:启动失败/坏路径在此显式报错,不静默降级
+            self._request("ping", {})
         except Exception as e:
             self._kill()
             raise RuntimeError(f"Sentinel 握手失败: {e}")
@@ -73,16 +71,18 @@ class SentinelClient:
             except Exception:
                 pass
 
-    # ── IPC 核心 ─────────────────────────────────────────────
     def _request(self, op: str, payload: dict):
         with self._lock:
             self._req_id += 1
             mid = self._req_id
             msg = json.dumps({"id": mid, "op": op, **payload}, ensure_ascii=False)
             try:
-                self._proc.stdin.write(msg + "\n")
-                self._proc.stdin.flush()
-                line = self._proc.stdout.readline()
+                proc = self._proc
+                if proc is None or proc.stdin is None or proc.stdout is None:
+                    raise SentinelUnavailable("守门人进程未启动")
+                proc.stdin.write(msg + "\n")
+                proc.stdin.flush()
+                line = proc.stdout.readline()
             except Exception as e:
                 raise SentinelUnavailable(f"IPC 通信失败: {e}")
             if not line:
@@ -95,7 +95,6 @@ class SentinelClient:
                 raise SentinelUnavailable(resp.get("error", "unknown error"))
             return resp.get("result")
 
-    # ── 序列化(只传 evaluate 需要的字段,不含 handler/凭证)────
     @staticmethod
     def _serialize_skill(skill) -> dict:
         _tl = getattr(skill, "trust_level", None)
@@ -106,7 +105,7 @@ class SentinelClient:
         return {
             "id": getattr(skill, "id", ""),
             "kind": getattr(skill, "kind", "local"),
-            "side_effect": getattr(skill, "side_effect", "write"),   # 未声明 → 有副作用
+            "side_effect": getattr(skill, "side_effect", "write"),
             "destructive": bool(getattr(skill, "destructive", False)),
             "external": bool(getattr(skill, "external", False)),
             "read_only": getattr(skill, "read_only", None),
@@ -124,7 +123,6 @@ class SentinelClient:
             "allow": list(getattr(rules, "allow", []) or []),
         }
 
-    # ── 对外接口 ─────────────────────────────────────────────
     def evaluate(self, skill, args, rules=None, confirmed=False, mode="strict",
                  taint_level=0, taint_threshold=0):
         """动作裁决(跨进程)。签名对齐 skills.permission.evaluate,返回 PermissionDecision。"""
@@ -141,7 +139,6 @@ class SentinelClient:
         try:
             d = self._request("evaluate", payload)
         except SentinelUnavailable as e:
-            # fail-closed:守门人不可达 → deny,绝不降级放行
             return PermissionDecision("deny", 0,
                                       reason=f"守门人不可达(fail-closed): {e}",
                                       reason_code="SENTINEL_UNAVAILABLE")
@@ -154,9 +151,9 @@ class SentinelClient:
             reason_code=d.get("reason_code", ""),
         )
 
-    def mint(self, ref: str, ttl: float = None):
+    def mint(self, ref: str, ttl: float | None = None):
         """为 ref 签发一次性能力令牌。返回 token(绝不返回真值);失败返回 None。"""
-        payload = {"ref": ref}
+        payload: dict[str, object] = {"ref": ref}
         if ttl is not None:
             payload["ttl"] = ttl
         try:

package/python/foxclaw/kernel/spine.py

@@ -32,7 +32,6 @@ class Event:
     source: str = ""
     correlation_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
 
-    # ── 与旧 BusMessage 同形,便于 SystemBus 无痛门面化 ──
     @property
     def channel(self) -> str:
         return self.topic
@@ -46,8 +45,8 @@ class EventSpine:
     """进程内唯一事件脊柱。发布/订阅(前缀匹配) + 投影 + 有界历史。线程安全。"""
 
     def __init__(self, history_limit: int = 1000):
-        self._subs: list[tuple[str, Callable]] = []      # (topic_prefix, handler)
-        self._projections: list[Callable] = []           # 每条事件都收到
+        self._subs: list[tuple[str, Callable]] = []
+        self._projections: list[Callable] = []
         self._history: deque = deque(maxlen=history_limit)
         self._lock = threading.RLock()
 
@@ -61,13 +60,15 @@ class EventSpine:
         with self._lock:
             self._projections.append(sink)
 
-    def publish(self, topic: str, payload: dict = None, source: str = "",
-                correlation_id: str = None) -> Event:
-        evt = Event(topic=topic, payload=payload or {}, source=source,
-                    **({"correlation_id": correlation_id} if correlation_id else {}))
+    def publish(self, topic: str, payload: dict | None = None, source: str = "",
+                correlation_id: str | None = None) -> Event:
+        if correlation_id:
+            evt = Event(topic=topic, payload=payload or {}, source=source,
+                        correlation_id=correlation_id)
+        else:
+            evt = Event(topic=topic, payload=payload or {}, source=source)
         with self._lock:
             self._history.append(evt)
-            # 锁内只做"快照",handler/sink 在锁外执行(避免与 pm/hmr 锁形成环)
             handlers = [h for pfx, h in self._subs if topic.startswith(pfx)]
             projections = list(self._projections)
         for h in handlers:
@@ -90,7 +91,6 @@ class EventSpine:
 
     def stats(self) -> dict:
         with self._lock:
-            # 【P4-2】补 history_limit(deque.maxlen):只报 history_size 无法判断「是否已满」。
             return {"subscriptions": len(self._subs),
                     "projections": len(self._projections),
                     "history_size": len(self._history),

package/python/foxclaw/knowledge/__init__.py

@@ -64,7 +64,6 @@ def _read_custom_model(data_dir, name):
     if not match:
         return None
     key = ""
-    # OS 凭据库优先,回退 base64(旧记录)/ 更早的明文字段
     from ..core.secrets import load as _load_secret
     key = _load_secret(name, match.get("api_key_obf") or "")
     key = key or (match.get("api_key") or "")
@@ -101,7 +100,6 @@ def _selected_llm():
         return None
 
     source = (sel.get("source") or "").strip().lower()
-    # preset 落盘的是 provider;custom 落盘的是 name。两者都当"选中的名字"用。
     name = (sel.get("name") or sel.get("provider") or "").strip()
     model = (sel.get("model_id") or sel.get("model") or "").strip()
 
@@ -113,7 +111,6 @@ def _selected_llm():
         return _to_hkc_provider("generic"), key, base, model or custom_model
 
     if source == "preset" and name:
-        # 界面里配过的同名自定义项(更新的 key)优先,env 只作最后兜底
         got = _read_custom_model(data_dir, name)
         if got:
             key, base, custom_model = got
@@ -144,7 +141,6 @@ def _detect_llm(api_key=None):
 
     返回 ``(provider, key, base_url, model)``。
     """
-    # 1. 显式 HKC_LLM_PROVIDER 覆盖(向后兼容「HKC 独立配」场景)
     env_provider = (os.environ.get("HKC_LLM_PROVIDER") or "").strip().lower()
     if env_provider in ("anthropic", "deepseek", "openai", "openai-compatible"):
         key = (os.environ.get("HKC_LLM_API_KEY")
@@ -158,15 +154,11 @@ def _detect_llm(api_key=None):
                  or "")
         return env_provider, key or api_key, base, model
 
-    # 2. 界面里当前选中的模型(用户显式动作,优先于 env 默认)
     selected = _selected_llm()
     if selected:
         provider, key, base, model = selected
         return provider, (key or api_key or "").strip(), (base or "").strip(), model
 
-    # 3. 单入口 env。未显式指定 provider 时**复用主对话的自动探测**,
-    #    不能默认成 "generic" —— 那是个空 key 的壳,会让抽取打 api.openai.com
-    #    拿 Missing credentials,每次摄入都 0 条。
     provider = (os.environ.get("LLM_PROVIDER") or "").strip().lower()
     key = (os.environ.get("LLM_API_KEY") or api_key or "").strip()
     base = os.environ.get("LLM_BASE_URL", "").strip()
@@ -194,7 +186,7 @@ class HKCService:
 
     def __init__(self, container, client):
         self._container = container
-        self.client = client   # DirectClient;供 HSR 检索 / /api/knowledge 路由使用
+        self.client = client
 
     @property
     def available(self) -> bool:
@@ -245,22 +237,18 @@ def init_hkc(data_dir, api_key=None):
         return None
     try:
         provider, llm_key, llm_base_url, llm_model = _detect_llm(api_key)
-        # 【P2·单 LLM 入口】embedding 模型名优先 EMBEDDING_MODEL(系统唯一本地入口),
-        # 再 HKC_EMBEDDING_MODEL(向后兼容);其他 HKC 行为开关不变。
         _emb_model = (os.environ.get("EMBEDDING_MODEL")
                       or os.environ.get("HKC_EMBEDDING_MODEL")) or None
         container = HKCContainer(
             data_dir=str(Path(data_dir) / "hkc"),
-            embedding_kind=os.environ.get("HKC_EMBEDDING", "auto"),   # 默认真语义(本地优先,无 ST 回退 stub)
+            embedding_kind=os.environ.get("HKC_EMBEDDING", "auto"),
             embedding_url=os.environ.get("HKC_EMBEDDING_URL", "http://localhost:8080"),
-            embedding_model=_emb_model,                                # local/auto 模型名(如 bge-m3)
+            embedding_model=_emb_model,
             llm_api_key=llm_key or None,
             llm_provider=provider,
             llm_model=llm_model or None,
             llm_base_url=llm_base_url or None,
         ).assemble()
-        # 注册为 hkc_api 全局单例:若将来挂 HKC 自身 /hkc REST 路由,
-        # 其 Depends(get_container) 能取到这同一个容器,而非"未初始化"。
         from hkc_api import container as _cm
         _cm._container = container
         print(f"[Foxclaw] ✓ HKC 知识核心已进程内融合 (provider={provider}, "
@@ -275,8 +263,6 @@ def init_hkc(data_dir, api_key=None):
 from .truth_crystallizer import TruthCrystallizer
 
 
-# HKC 知识生命周期事件 → 桥接到 EventSpine 的类型。**刻意不含 memory.***(那是 HMR 域,
-# Foxclaw 已有自己的记忆事件,转发 HKC 的会重复/混淆)。
 _HKC_BRIDGED_EVENTS = (
     "knowledge.created", "knowledge.updated", "knowledge.merged", "knowledge.deleted",
     "conflict.detected", "conflict.resolved", "claim.status_changed",
@@ -351,7 +337,7 @@ def register_abilities_as_skills(registry, hkc) -> list:
     registered = []
     for key in keys:
         try:
-            ab = client.compile_ability(key)   # 覆盖不足抛异常 → 证据 gate 跳过、不注册
+            ab = client.compile_ability(key)
         except Exception:
             continue
         sid = f"ability:{key}"
@@ -363,8 +349,6 @@ def register_abilities_as_skills(registry, hkc) -> list:
             handler=_make_ability_handler(client, ab),
             params={"query": "str"}))
         registered.append(sid)
-    # 【深审修复·陈旧清理】重新同步时,移除此前注册但**本轮不再达标**的 ability skill
-    # (coverage 掉了/能力定义删了)——register-only 会残留陈旧项;prune 使 registry 反映当前覆盖。
     fresh = set(registered)
     for spec in registry.all():
         if spec.id.startswith("ability:") and spec.id not in fresh:

package/python/foxclaw/knowledge/truth_crystallizer.py

@@ -15,17 +15,17 @@ Step1(叠加、默认关、行为不变):
 from __future__ import annotations
 import threading
 from concurrent.futures import ThreadPoolExecutor
-from typing import Callable, Optional
+from typing import Any, Callable, cast, Optional
 
 
 class TruthCrystallizer:
     def __init__(self, hkc_provider: Callable[[], object], enabled: bool = False):
-        self._hkc_provider = hkc_provider     # 惰性取 HKCService(或 None)
+        self._hkc_provider = hkc_provider
         self.enabled = enabled
         self._executor: Optional[ThreadPoolExecutor] = None
         self._closed = False
         self._lock = threading.Lock()
-        self._pending: list = []              # 供测试 drain
+        self._pending: list = []
 
     def _ex(self) -> Optional[ThreadPoolExecutor]:
         with self._lock:
@@ -41,7 +41,7 @@ class TruthCrystallizer:
         if not self.enabled:
             return
         p = getattr(msg, "payload", None) or {}
-        if p.get("blocked"):                  # 被拦截任务不结晶(与 TruthPipeline 一致)
+        if p.get("blocked"):
             return
         fact = ((p.get("truth") or {}).get("fact") or "").strip()
         if not fact:
@@ -52,16 +52,13 @@ class TruthCrystallizer:
             return
         fut = ex.submit(self._crystallize, fact, domain)
         with self._lock:
-            # 【深审修复·长期运行泄漏】_pending 原先只增不减(drain 仅在 close/测试时调用),
-            # 启用后每来一次 truth.appended 就永久累积一个已完成 Future → 无界内存泄漏。
-            # 改为每次提交时 prune 掉已完成的,_pending 只保留在飞行中的任务(仍支持测试 drain)。
             self._pending = [f for f in self._pending if not f.done()]
             self._pending.append(fut)
 
     def _crystallize(self, fact: str, domain: str) -> bool:
         """后台执行:惰性取 HKC → ingest_text(KDE→KEE)。任何失败都吞掉,不影响主流程。"""
         try:
-            hkc = self._hkc_provider()
+            hkc = cast(Any, self._hkc_provider())
         except Exception:
             hkc = None
         if hkc is None or not getattr(hkc, "available", False):

package/python/foxclaw/learning/knowledge_graph.py

@@ -17,9 +17,9 @@ class KnowledgeGraph:
     DIM = 256
 
     def __init__(self, embedder=None):
-        self.items: dict = {}           # id -> KnowledgeItem
-        self.edges: list = []           # KnowledgeEdge
-        self._embedder = embedder       # 可选:HMR 的向量能力
+        self.items: dict = {}
+        self.edges: list = []
+        self._embedder = embedder
 
     def add_item(self, item: KnowledgeItem):
         self.items[item.id] = item
@@ -30,7 +30,6 @@ class KnowledgeGraph:
         self.edges = [e for e in self.edges
                       if e.source_id != item_id and e.target_id != item_id]
 
-    # ── 三种连接 ──────────────────────────────────────────
     def link_manual(self, source_id: str, target_id: str, reason: str = ""):
         self.edges.append(KnowledgeEdge(
             source_id=source_id, target_id=target_id,
@@ -72,7 +71,6 @@ class KnowledgeGraph:
                     new_edges += 1
         return new_edges
 
-    # ── 图分析 ────────────────────────────────────────────
     def neighbors(self, item_id: str) -> list:
         """某知识点的所有关联点。"""
         out = []
@@ -105,7 +103,7 @@ class KnowledgeGraph:
         return result
 
     def stats(self) -> dict:
-        type_count = defaultdict(int)
+        type_count: defaultdict[str, int] = defaultdict(int)
         for e in self.edges:
             type_count[e.edge_type] += 1
         return {
@@ -115,7 +113,6 @@ class KnowledgeGraph:
             "clusters": len(self.clusters()),
         }
 
-    # ── 向量工具 ──────────────────────────────────────────
     def _embed(self, text: str):
         if self._embedder is not None:
             try:
@@ -138,8 +135,6 @@ class KnowledgeGraph:
 
     @staticmethod
     def _cosine(a, b) -> float:
-        # 自己归一化,不假设输入已是单位向量:外部 embedder(如 HMR)返回的向量
-        # 未必归一化,直接用点积当余弦会系统性偏高(threshold 失效,什么都连上)。
         import math
         dot = sum(x * y for x, y in zip(a, b))
         na = math.sqrt(sum(x * x for x in a))

package/python/foxclaw/learning/models.py

@@ -13,17 +13,17 @@ import uuid
 
 
 EdgeType = Literal["same_topic", "concept_ref", "semantic", "manual"]
-Grade = Literal[0, 1, 2, 3, 4, 5]   # SM-2 回忆质量评分 0=完全忘 5=完美
+Grade = Literal[0, 1, 2, 3, 4, 5]
 
 
 @dataclass
 class KnowledgeItem:
     """一个知识条目 = 一次学习采集"""
-    content: str                        # 知识点内容
-    topic: str = "general"              # 主题
-    source: str = ""                    # 来源:书名/课程/文章/Readwise
+    content: str
+    topic: str = "general"
+    source: str = ""
     tags: list = field(default_factory=list)
-    notes: list = field(default_factory=list)   # 用户读时加的笔记 [{text, ts}]
+    notes: list = field(default_factory=list)
     created_at: str = field(default_factory=lambda: datetime.now().isoformat())
     id: str = field(default_factory=lambda: f"ki_{uuid.uuid4().hex[:10]}")
 
@@ -35,19 +35,19 @@ class KnowledgeItem:
 class ReviewState:
     """SM-2 间隔重复状态(固化层核心)"""
     item_id: str
-    repetitions: int = 0                # 连续正确次数
-    interval: int = 0                   # 当前间隔(天)
-    ease_factor: float = 2.5            # 难度因子(SM-2 起始 2.5)
+    repetitions: int = 0
+    interval: int = 0
+    ease_factor: float = 2.5
     due_date: str = field(default_factory=lambda: datetime.now().isoformat())
     last_review: Optional[str] = None
     total_reviews: int = 0
-    lapses: int = 0                     # 遗忘次数(评分<3)
+    lapses: int = 0
 
     @property
     def mastery(self) -> float:
         """掌握度 0~1:综合连续正确次数和难度因子。"""
-        rep_score = min(self.repetitions / 6.0, 1.0)      # 6 次连对算掌握
-        ease_score = (self.ease_factor - 1.3) / (2.5 - 1.3)  # 1.3~2.5 归一
+        rep_score = min(self.repetitions / 6.0, 1.0)
+        ease_score = (self.ease_factor - 1.3) / (2.5 - 1.3)
         ease_score = max(0.0, min(1.0, ease_score))
         return round(0.6 * rep_score + 0.4 * ease_score, 3)
 
@@ -73,8 +73,8 @@ class KnowledgeEdge:
     source_id: str
     target_id: str
     edge_type: EdgeType
-    weight: float = 1.0                 # 关联强度
-    reason: str = ""                    # 为什么连接(可解释)
+    weight: float = 1.0
+    reason: str = ""
 
     def to_dict(self) -> dict:
         return asdict(self)

package/python/foxclaw/learning/reasoner.py

@@ -11,7 +11,6 @@ from __future__ import annotations
 from ..cognitive.reasoner import DomainReasoner, ReasonedVerdict, Evidence
 from .spaced_repetition import SpacedRepetition
 
-# 负荷偏重阈值:未来窗口日均复习量 ≥ 该值即算偏重,交给可选 LLM 复核是否提醒。
 HEAVY_DAILY = 20.0
 
 
@@ -37,13 +36,12 @@ class LearningReviewReasoner(DomainReasoner):
         return h or ["学习状态可能健康"]
 
     def gather_evidence(self, states, obs: dict) -> list:
-        risky = SpacedRepetition.forgetting_risk(states, self.horizon_days)   # 规则=裁决证据
+        risky = SpacedRepetition.forgetting_risk(states, self.horizon_days)
         ev = [Evidence(factor="forgetting_risk",
                        detail=r["reason"] + f"(item {r['item_id']})", weight=1.0, raw=r)
               for r in risky]
         if not risky:
             ev.append(Evidence("no_urgent_risk", "无即将到期且掌握度低的知识点", 0.5))
-        # informational(raw=None):学习负荷,不参与裁决
         ev.append(Evidence("learning_load",
                            f"未来窗口共 {obs['total_due']} 项待复习,日均 {obs['daily_avg']}", 0.3))
         return ev
@@ -51,7 +49,6 @@ class LearningReviewReasoner(DomainReasoner):
     def arbitrate(self, states, obs, hyps, ev) -> ReasonedVerdict:
         triggered = [e for e in ev if e.raw is not None]
         if triggered:
-            # 【规则权威】存在高遗忘风险 → confirm(建议立即复习),绝不被 LLM 推翻/隐藏
             top = triggered[:3]
             return ReasonedVerdict(
                 "confirm", f"发现 {len(triggered)} 个高遗忘风险知识点,建议优先复习:"