foxclaw 0.1.2 → 0.1.3

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)} 个高遗忘风险知识点,建议优先复习:"

package/python/foxclaw/learning/runtime.py

@@ -20,21 +20,20 @@ class LearningRuntime:
     """office Agent 的学习内核。"""
 
     def __init__(self, hmr=None, hkc_provider=None, persist_path=None):
-        self.items: dict = {}               # id -> KnowledgeItem(内存缓存;知识真源=HKC)
-        self.review_states: dict = {}       # item_id -> ReviewState
+        self.items: dict = {}
+        self.review_states: dict = {}
         self.sr = SpacedRepetition()
         self.hmr = hmr
-        self._hkc_provider = hkc_provider   # 惰性拿 HKC(知识真源);None=纯内存(测试用)
-        self._lock = threading.RLock()      # 跨线程写/改内存加锁(与全系统线程安全铁律一致)
+        self._hkc_provider = hkc_provider
+        self._lock = threading.RLock()
         embedder = None
         if hmr is not None and hasattr(hmr, "_hmr"):
             embedder = self._make_embedder(hmr)
         self.graph = KnowledgeGraph(embedder=embedder)
-        # persist_path 现在只作「离线兜底队列 + 旧 learning.json 迁移源」;知识真源是 HKC。
         self._persist_path = Path(persist_path) if persist_path else None
-        self._hkc_loaded = False            # HKC 首次成功载入的门闩(惰性,见 _ensure_hkc_loaded)
-        self._load_file()                   # 先把离线队列/旧文件载入内存(__init__ 时 HKC 常未就绪)
-        self._ensure_hkc_loaded()           # HKC 若已就绪则立即从真源载入;否则留待后续调用重试
+        self._hkc_loaded = False
+        self._load_file()
+        self._ensure_hkc_loaded()
 
     def _make_embedder(self, hmr):
         """尝试复用 HMR 的 embedding;失败则返回 None(图谱自动降级哈希)。"""
@@ -46,7 +45,6 @@ class LearningRuntime:
             pass
         return None
 
-    # ── 存储:知识内容+笔记+复习状态 全落 HKC(真源);HKC 拿不到时落离线队列(兜底 A)──
     def _graph_store(self):
         """惰性拿 HKC 的 graph_store。拿不到(HKC 未装配/未配/异常)返回 None。"""
         if not self._hkc_provider:
@@ -126,9 +124,9 @@ class LearningRuntime:
         if self._hkc_loaded:
             return
         gs = self._graph_store()
-        if gs is None:                          # HKC 还没就绪 → 下次调用再试
+        if gs is None:
             return
-        try:                                    # 1) 从 HKC 载入(内存已有的以文件版为准,不覆盖)
+        try:
             for ku in gs.query_all(limit=5000):
                 ex = getattr(ku, "extra", {}) or {}
                 if ex.get("kind") != "learning_note":
@@ -146,9 +144,9 @@ class LearningRuntime:
                     except Exception:
                         pass
         except Exception:
-            return                              # 载入失败不置门闩,留待下次重试
+            return
         self._hkc_loaded = True
-        if self._persist_path and self._persist_path.exists():   # 2) 文件残留回迁 HKC + 删文件
+        if self._persist_path and self._persist_path.exists():
             self._save()
 
     def _save(self):
@@ -166,11 +164,11 @@ class LearningRuntime:
             if ok:
                 if self._persist_path and self._persist_path.exists():
                     try:
-                        self._persist_path.unlink()   # 已全部进 HKC → 删掉本地队列文件
+                        self._persist_path.unlink()
                     except Exception:
                         pass
                 return
-        if self._persist_path:                  # 离线兜底:HKC 不可用/部分失败 → 落队列文件
+        if self._persist_path:
             try:
                 data = {
                     "items": [asdict(it) for it in items],
@@ -183,9 +181,8 @@ class LearningRuntime:
             except Exception:
                 pass
 
-    # ── 采集 + 沉淀 ───────────────────────────────────────
     def learn(self, content: str, topic: str = "general",
-              source: str = "", tags: list = None) -> dict:
+              source: str = "", tags: list | None = None) -> dict:
         """采集一个知识点 → 存进 HKC(知识真源)+ 间隔重复队列 + 图谱。
         铁律:知识内容+笔记归 HKC,不进 HMR(HMR 只装 token 上下文/工作运行记忆)。"""
         self._ensure_hkc_loaded()
@@ -195,7 +192,7 @@ class LearningRuntime:
             self.items[item.id] = item
             self.review_states[item.id] = ReviewState(item_id=item.id)
             self.graph.add_item(item)
-        self._save()   # 存进 HKC(HKC 不可用则离线队列兜底,恢复后自动补进)
+        self._save()
         return {"item": item.to_dict(),
                 "review": self.review_states[item.id].to_dict()}
 
@@ -212,7 +209,6 @@ class LearningRuntime:
                 count += 1
         return count
 
-    # ── 固化:复习 ────────────────────────────────────────
     def review(self, item_id: str, grade: int) -> dict:
         """复习一个知识点,提交回忆质量评分(0~5),更新掌握度。"""
         self._ensure_hkc_loaded()
@@ -237,7 +233,7 @@ class LearningRuntime:
         gs = self._graph_store()
         if gs is not None:
             try:
-                gs.delete(item_id)   # HKC 软删除(status='deleted')
+                gs.delete(item_id)
             except Exception:
                 pass
         if found:
@@ -256,7 +252,7 @@ class LearningRuntime:
                 return {"error": "未知知识点"}
             item.notes.append({"text": text, "ts": datetime.now().isoformat()})
             notes = list(item.notes)
-        self._save()   # 只有新增了笔记才落盘
+        self._save()
         return {"notes": notes}
 
     def due_today(self) -> list:
@@ -265,7 +261,6 @@ class LearningRuntime:
         return [{"item": self.items[s.item_id].to_dict(),
                  "review": s.to_dict()} for s in due]
 
-    # ── 连接:构建图谱 ────────────────────────────────────
     def build_connections(self, semantic_threshold: float = 0.55) -> dict:
         """自动构建知识连接(同主题 + 语义)。"""
         topic_edges = self.graph.auto_link_by_topic()
@@ -283,13 +278,11 @@ class LearningRuntime:
                             "edge_type": etype, "weight": weight, "reason": reason})
         return out
 
-    # ── 学习策略(对应财务守门人)─────────────────────────
     def strategy_check(self, daily_cap: int = 20) -> list:
         """学习策略裁决:复习提醒、薄弱主题、负荷预警、连接建议。"""
         verdicts = []
         states = list(self.review_states.values())
 
-        # 到期复习
         due = self.sr.due_items(states)
         if due:
             verdicts.append(LearningVerdict(
@@ -297,7 +290,6 @@ class LearningRuntime:
                 message=f"今天有 {len(due)} 个知识点待复习",
                 payload={"count": len(due)}))
 
-        # 遗忘风险(薄弱项)
         risky = self.sr.forgetting_risk(states)
         if risky:
             verdicts.append(LearningVerdict(
@@ -305,7 +297,6 @@ class LearningRuntime:
                 message=f"{len(risky)} 个知识点处于高遗忘风险,建议优先复习",
                 payload={"risky": risky[:5]}))
 
-        # 负荷预警
         load = self.sr.learning_load(states)
         if load["total_due"] > daily_cap:
             verdicts.append(LearningVerdict(
@@ -313,7 +304,6 @@ class LearningRuntime:
                 message=f"未来复习量 {load['total_due']} 超过每日上限 {daily_cap},建议分批",
                 payload=load))
 
-        # 孤立知识点(无连接)→ 建议建立关联
         connected = set()
         for e in self.graph.edges:
             connected.add(e.source_id)
@@ -326,14 +316,12 @@ class LearningRuntime:
                 payload={"isolated_count": len(isolated)}))
         return verdicts
 
-    # ── 综合分析(office Agent 核心输出)──────────────────
     def analyze(self) -> dict:
-        self._ensure_hkc_loaded()   # HKC 就绪后从真源载回知识(迁移删文件后重启也不丢)
+        self._ensure_hkc_loaded()
         states = list(self.review_states.values())
         masteries = [s.mastery for s in states]
         avg_mastery = round(sum(masteries) / len(masteries), 3) if masteries else 0.0
 
-        # 按主题统计掌握度
         from collections import defaultdict
         topic_mastery = defaultdict(list)
         for iid, item in self.items.items():
@@ -346,7 +334,7 @@ class LearningRuntime:
             "total_items": len(self.items),
             "avg_mastery": avg_mastery,
             "topic_mastery": topics,
-            "weakest_topic": (min(topics, key=topics.get) if topics else None),
+            "weakest_topic": (min(topics, key=lambda t: topics[t]) if topics else None),
             "due_today": len(self.sr.due_items(states)),
             "forgetting_risk": self.sr.forgetting_risk(states),
             "learning_load": self.sr.learning_load(states),

package/python/foxclaw/learning/spaced_repetition.py

@@ -22,19 +22,16 @@ class SpacedRepetition:
     @staticmethod
     def review(state: ReviewState, grade: int) -> ReviewState:
         """根据本次回忆质量,更新间隔重复状态。返回更新后的 state。"""
-        # grade 钳制到 SM-2 定义域 [0,5],防止越界输入让 EF 公式算出无意义值
         grade = max(0, min(5, int(grade)))
         now = datetime.now()
         state.total_reviews += 1
         state.last_review = now.isoformat()
 
         if grade < 3:
-            # 没记住:重置,短期内再复习
             state.repetitions = 0
             state.interval = 1
             state.lapses += 1
         else:
-            # 记住了:按 SM-2 推进间隔
             if state.repetitions == 0:
                 state.interval = 1
             elif state.repetitions == 1:
@@ -43,11 +40,9 @@ class SpacedRepetition:
                 state.interval = round(state.interval * state.ease_factor)
             state.repetitions += 1
 
-        # 更新难度因子(SM-2 公式)
         ef = state.ease_factor + (0.1 - (5 - grade) * (0.08 + (5 - grade) * 0.02))
         state.ease_factor = max(1.3, round(ef, 3))
 
-        # 下次复习时间
         state.due_date = (now + timedelta(days=state.interval)).isoformat()
         return state
 
@@ -79,13 +74,13 @@ class SpacedRepetition:
     def learning_load(states: list, days: int = 7) -> dict:
         """学习负荷(对应财务烧钱速度):未来 N 天的复习量。"""
         from collections import defaultdict
-        by_day = defaultdict(int)
+        by_day: defaultdict[int, int] = defaultdict(int)
         for s in states:
             d = s.days_until_due
             if 0 <= d <= days:
                 by_day[d] += 1
             elif d < 0:
-                by_day[0] += 1   # 逾期的算今天
+                by_day[0] += 1
         total_due = sum(by_day.values())
         return {
             "window_days": days,

package/python/foxclaw/mcp_server.py

@@ -90,7 +90,6 @@ def build_foxclaw_mcp(os_getter, expose_agents: bool = False) -> FastMCP:
     """os_getter:无参回调,返回当前 Foxclaw 实例(惰性,启动后才有)。
     expose_agents:另开一道开关才暴露 Agent 调度(有副作用面,默认关)。"""
     mcp = FastMCP("Foxclaw Knowledge", stateless_http=True, streamable_http_path="/")
-    # 限流(env 可配):读工具较宽松、ask_foxclaw(驱动 LLM,贵)较紧
     read_limiter = _RateLimiter(_env_int("FOXCLAW_MCP_RATE_READ", 120))
     agent_limiter = _RateLimiter(_env_int("FOXCLAW_MCP_RATE_AGENT", 20))
 
@@ -111,7 +110,7 @@ def build_foxclaw_mcp(os_getter, expose_agents: bool = False) -> FastMCP:
                      "type": str(getattr(h, "ku_type", ""))}
                     for h in (hits or [])]
         except Exception:
-            return [{"error": "internal error"}]        # 对外脱敏:不回传 str(e)
+            return [{"error": "internal error"}]
 
     @mcp.tool()
     def knowledge_get(ku_id: str) -> dict:
@@ -172,7 +171,7 @@ def build_foxclaw_mcp(os_getter, expose_agents: bool = False) -> FastMCP:
 
             def _work():
                 from foxclaw.agents.base import _suppress_memory
-                _suppress_memory.set(True)   # 外部驱动的任务不写 HMR(防污染),随上下文传到 run_task
+                _suppress_memory.set(True)
                 return os_.scheduler.run(
                     lambda: _a.run(os_.run(task, agent)),
                     agent_id=agent, task=task)