foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/learning/models.py

@@ -0,0 +1,93 @@
+"""
+Foxclaw 学习子系统 — 数据模型
+学习行为操作系统的四类结构:
+  KnowledgeItem(知识条目)、ReviewState(间隔重复状态)、
+  KnowledgeEdge(知识图谱边)、LearningVerdict(学习策略裁决)
+核心思想:学习 = 可追踪的记忆行为轨迹(纵向掌握度 + 横向知识连接)。
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Optional, Literal
+import uuid
+
+
+EdgeType = Literal["same_topic", "concept_ref", "semantic", "manual"]
+Grade = Literal[0, 1, 2, 3, 4, 5]   # SM-2 回忆质量评分 0=完全忘 5=完美
+
+
+@dataclass
+class KnowledgeItem:
+    """一个知识条目 = 一次学习采集"""
+    content: str                        # 知识点内容
+    topic: str = "general"              # 主题
+    source: str = ""                    # 来源:书名/课程/文章/Readwise
+    tags: list = field(default_factory=list)
+    notes: list = field(default_factory=list)   # 用户读时加的笔记 [{text, ts}]
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    id: str = field(default_factory=lambda: f"ki_{uuid.uuid4().hex[:10]}")
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ReviewState:
+    """SM-2 间隔重复状态(固化层核心)"""
+    item_id: str
+    repetitions: int = 0                # 连续正确次数
+    interval: int = 0                   # 当前间隔(天)
+    ease_factor: float = 2.5            # 难度因子(SM-2 起始 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)
+
+    @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 归一
+        ease_score = max(0.0, min(1.0, ease_score))
+        return round(0.6 * rep_score + 0.4 * ease_score, 3)
+
+    @property
+    def is_due(self) -> bool:
+        return datetime.fromisoformat(self.due_date) <= datetime.now()
+
+    @property
+    def days_until_due(self) -> int:
+        delta = datetime.fromisoformat(self.due_date) - datetime.now()
+        return delta.days
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d.update(mastery=self.mastery, is_due=self.is_due,
+                 days_until_due=self.days_until_due)
+        return d
+
+
+@dataclass
+class KnowledgeEdge:
+    """知识图谱的一条边(连接层核心)"""
+    source_id: str
+    target_id: str
+    edge_type: EdgeType
+    weight: float = 1.0                 # 关联强度
+    reason: str = ""                    # 为什么连接(可解释)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class LearningVerdict:
+    """学习策略裁决(对应财务守门人)"""
+    rule_id: str
+    action: Literal["review_due", "weak_topic_alert", "overload_warn", "suggest_connect"]
+    message: str
+    severity: Literal["info", "warn"] = "info"
+    payload: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)

package/python/foxclaw/learning/reasoner.py

@@ -0,0 +1,70 @@
+"""
+LearningReviewReasoner —— 学习复习推理的认知化(v2 ③ Step4)。
+
+把 SpacedRepetition.forgetting_risk / learning_load 的规则裁决,形式化为
+    观察 → 假设 → 证据 → 裁决,
+**规则永远权威**(存在高遗忘风险知识点 → confirm=建议立即复习,绝不被 LLM 推翻);
+可选 LLM 层(默认关)只对"无高风险、但负荷偏重"的微妙情形**升级** approve→confirm。
+裁决带证据链(可审计)。顾问域(非治理闸口):LLM 出错→维持规则裁决。
+"""
+from __future__ import annotations
+from ..cognitive.reasoner import DomainReasoner, ReasonedVerdict, Evidence
+from .spaced_repetition import SpacedRepetition
+
+# 负荷偏重阈值:未来窗口日均复习量 ≥ 该值即算偏重,交给可选 LLM 复核是否提醒。
+HEAVY_DAILY = 20.0
+
+
+class LearningReviewReasoner(DomainReasoner):
+    """subject = states(list[ReviewState])。裁决:approve(学习状态健康) / confirm(需干预)。"""
+
+    def __init__(self, horizon_days: int = 3, llm=None, llm_enabled: bool = False):
+        self.horizon_days = horizon_days
+        self.llm = llm
+        self.llm_enabled = llm_enabled
+
+    def observe(self, states) -> dict:
+        load = SpacedRepetition.learning_load(states)
+        return {"total": len(states), "overdue": load["overdue"],
+                "daily_avg": load["daily_avg"], "total_due": load["total_due"]}
+
+    def hypothesize(self, obs: dict) -> list:
+        h = []
+        if obs["overdue"]:
+            h.append("可能有逾期未复习")
+        if obs["daily_avg"] >= HEAVY_DAILY:
+            h.append("可能复习负荷过重")
+        return h or ["学习状态可能健康"]
+
+    def gather_evidence(self, states, obs: dict) -> list:
+        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
+
+    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)} 个高遗忘风险知识点,建议优先复习:"
+                + "；".join(e.detail for e in top),
+                ev, hyps, "rules")
+        if DomainReasoner.llm_available(self.llm, self.llm_enabled) and obs["daily_avg"] >= HEAVY_DAILY:
+            if DomainReasoner.llm_should_escalate(self.llm, *self._llm_prompt(obs, ev)):
+                return ReasonedVerdict("confirm", "复习负荷偏重,LLM 建议调整计划", ev, hyps, "llm")
+        return ReasonedVerdict("approve", "学习状态健康:无高遗忘风险知识点", ev, hyps, "rules")
+
+    def _llm_prompt(self, obs, ev):
+        ev_text = "\n".join(f"- {e.factor}: {e.detail}" for e in ev) or "(无)"
+        system = ("你是学习助手。当前无高遗忘风险知识点,但复习负荷偏重。"
+                  "判断是否建议用户调整复习计划。只回答 CONFIRM(建议调整)或 OK(无需)。")
+        user = f"负荷:日均 {obs['daily_avg']} 项。\n证据:\n{ev_text}\n\n只回答一个词:CONFIRM 或 OK。"
+        return system, user

package/python/foxclaw/learning/runtime.py

@@ -0,0 +1,363 @@
+"""
+Foxclaw 学习子系统 — Learning Runtime
+学习行为操作系统:采集 → 沉淀(HMR + 双结构) → 固化(间隔重复) → 连接(知识图谱)。
+对应财务 Runtime,office Agent 的"赫尔墨斯式自学"内核。
+"""
+
+import csv
+import json
+import threading
+from dataclasses import asdict
+from datetime import datetime
+from pathlib import Path
+
+from .models import KnowledgeItem, ReviewState, LearningVerdict
+from .spaced_repetition import SpacedRepetition
+from .knowledge_graph import KnowledgeGraph
+
+
+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.sr = SpacedRepetition()
+        self.hmr = hmr
+        self._hkc_provider = hkc_provider   # 惰性拿 HKC(知识真源);None=纯内存(测试用)
+        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 若已就绪则立即从真源载入;否则留待后续调用重试
+
+    def _make_embedder(self, hmr):
+        """尝试复用 HMR 的 embedding;失败则返回 None(图谱自动降级哈希)。"""
+        try:
+            store = getattr(hmr._hmr, "vector_store", None)
+            if store and hasattr(store, "_embed"):
+                return lambda t: list(store._embed(t))
+        except Exception:
+            pass
+        return None
+
+    # ── 存储:知识内容+笔记+复习状态 全落 HKC(真源);HKC 拿不到时落离线队列(兜底 A)──
+    def _graph_store(self):
+        """惰性拿 HKC 的 graph_store。拿不到(HKC 未装配/未配/异常)返回 None。"""
+        if not self._hkc_provider:
+            return None
+        try:
+            hkc = self._hkc_provider()
+            c = getattr(hkc, "container", None) if hkc else None
+            return getattr(c, "graph_store", None) if c else None
+        except Exception:
+            return None
+
+    def _item_to_ku(self, item):
+        """KnowledgeItem → 一个连续的 ConceptKU:source_text=全文;notes/复习状态/kind 存 extra。"""
+        from hkc_core.models.ku import ConceptKU
+        rs = self.review_states.get(item.id)
+        ku = ConceptKU(
+            ku_id=item.id,
+            name=(item.topic or "学习知识点")[:80],
+            summary=(item.content or "")[:200],
+            tags=list(item.tags or []) + ["learning_note"],
+            domain=item.topic or "learning",
+            source_text=item.content or "",
+        )
+        ku.extra.update({
+            "kind": "learning_note",
+            "notes": list(item.notes or []),
+            "note_source": item.source or "",
+            "learn_created_at": item.created_at,
+            "review": asdict(rs) if rs is not None else None,
+        })
+        return ku
+
+    def _ku_to_item(self, ku):
+        """HKC 的 learning_note KU → (KnowledgeItem, review_dict)。"""
+        ex = getattr(ku, "extra", {}) or {}
+        content = getattr(ku, "source_text", "") or ex.get("source_text", "") or ku.summary
+        tags = [t for t in (ku.tags or []) if t != "learning_note"]
+        item = KnowledgeItem(
+            content=content,
+            topic=ku.name or ku.domain or "general",
+            source=ex.get("note_source", ""),
+            tags=tags,
+            notes=list(ex.get("notes", []) or []),
+            created_at=ex.get("learn_created_at") or ku.created_at,
+            id=ku.ku_id,
+        )
+        return item, ex.get("review")
+
+    def _load_file(self):
+        """把离线队列 / 旧 learning.json 载入内存(__init__ 时 HKC 常未就绪,先撑住 UI)。"""
+        if not (self._persist_path and self._persist_path.exists()):
+            return
+        try:
+            data = json.loads(self._persist_path.read_text(encoding="utf-8"))
+            fields = KnowledgeItem.__dataclass_fields__
+            for d in data.get("items", []):
+                item = KnowledgeItem(**{k: v for k, v in d.items() if k in fields})
+                if item.id in self.items:
+                    continue
+                self.items[item.id] = item
+                self.graph.add_item(item)
+            for d in data.get("reviews", []):
+                try:
+                    rs = ReviewState(**d)
+                    self.review_states.setdefault(rs.item_id, rs)
+                except Exception:
+                    pass
+        except Exception:
+            pass
+
+    def _ensure_hkc_loaded(self):
+        """惰性从 HKC(知识真源)载入 learning_note KU —— 只成功一次。
+        铁律要点:HKC 惰性初始化,__init__ 时(_hkc_api_key 尚未设)常拿不到 gs,
+        故必须在后续任意读写(analyze 轮询/learn/...)里重试载入,否则迁移删文件后
+        重启会「知识凭空消失」(真源仍在 hkc.db,只是没被读回)。加载后把内存里
+        文件残留的条目回迁 HKC 并删本地队列文件。"""
+        if self._hkc_loaded:
+            return
+        gs = self._graph_store()
+        if gs is None:                          # HKC 还没就绪 → 下次调用再试
+            return
+        try:                                    # 1) 从 HKC 载入(内存已有的以文件版为准,不覆盖)
+            for ku in gs.query_all(limit=5000):
+                ex = getattr(ku, "extra", {}) or {}
+                if ex.get("kind") != "learning_note":
+                    continue
+                if getattr(ku, "status", "active") == "deleted":
+                    continue
+                item, review = self._ku_to_item(ku)
+                if item.id in self.items:
+                    continue
+                self.items[item.id] = item
+                self.graph.add_item(item)
+                if review:
+                    try:
+                        self.review_states.setdefault(item.id, ReviewState(**review))
+                    except Exception:
+                        pass
+        except Exception:
+            return                              # 载入失败不置门闩,留待下次重试
+        self._hkc_loaded = True
+        if self._persist_path and self._persist_path.exists():   # 2) 文件残留回迁 HKC + 删文件
+            self._save()
+
+    def _save(self):
+        """把所有知识点 put 进 HKC(真源,upsert)。HKC 拿不到 → 写离线队列文件(兜底 A)。"""
+        with self._lock:
+            items = list(self.items.values())
+        gs = self._graph_store()
+        if gs is not None:
+            ok = True
+            for it in items:
+                try:
+                    gs.put(self._item_to_ku(it))
+                except Exception:
+                    ok = False
+            if ok:
+                if self._persist_path and self._persist_path.exists():
+                    try:
+                        self._persist_path.unlink()   # 已全部进 HKC → 删掉本地队列文件
+                    except Exception:
+                        pass
+                return
+        if self._persist_path:                  # 离线兜底:HKC 不可用/部分失败 → 落队列文件
+            try:
+                data = {
+                    "items": [asdict(it) for it in items],
+                    "reviews": [asdict(rs) for rs in self.review_states.values()],
+                }
+                self._persist_path.parent.mkdir(parents=True, exist_ok=True)
+                tmp = self._persist_path.with_suffix(".tmp")
+                tmp.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+                tmp.replace(self._persist_path)
+            except Exception:
+                pass
+
+    # ── 采集 + 沉淀 ───────────────────────────────────────
+    def learn(self, content: str, topic: str = "general",
+              source: str = "", tags: list = None) -> dict:
+        """采集一个知识点 → 存进 HKC(知识真源)+ 间隔重复队列 + 图谱。
+        铁律:知识内容+笔记归 HKC,不进 HMR(HMR 只装 token 上下文/工作运行记忆)。"""
+        self._ensure_hkc_loaded()
+        item = KnowledgeItem(content=content, topic=topic,
+                             source=source, tags=tags or [])
+        with self._lock:
+            self.items[item.id] = item
+            self.review_states[item.id] = ReviewState(item_id=item.id)
+            self.graph.add_item(item)
+        self._save()   # 存进 HKC(HKC 不可用则离线队列兜底,恢复后自动补进)
+        return {"item": item.to_dict(),
+                "review": self.review_states[item.id].to_dict()}
+
+    def import_csv(self, path: str) -> int:
+        """从 CSV 导入知识点。列:content,topic,source,tags
+        外部工具(Readwise/Obsidian/Anki MCP)接口可在此扩展。"""
+        count = 0
+        with open(Path(path), encoding="utf-8") as f:
+            for row in csv.DictReader(f):
+                tags = [t.strip() for t in (row.get("tags") or "").split("|") if t.strip()]
+                self.learn(content=row["content"],
+                           topic=row.get("topic", "general"),
+                           source=row.get("source", ""), tags=tags)
+                count += 1
+        return count
+
+    # ── 固化:复习 ────────────────────────────────────────
+    def review(self, item_id: str, grade: int) -> dict:
+        """复习一个知识点,提交回忆质量评分(0~5),更新掌握度。"""
+        self._ensure_hkc_loaded()
+        state = self.review_states.get(item_id)
+        if not state:
+            return {"error": "未知知识点"}
+        self.sr.review(state, grade)
+        self._save()
+        return state.to_dict()
+
+    def delete(self, item_id: str) -> bool:
+        """删除一个知识点(内存 + 复习状态 + 图谱)并落盘。返回是否命中。"""
+        self._ensure_hkc_loaded()
+        with self._lock:
+            found = item_id in self.items
+            self.items.pop(item_id, None)
+            self.review_states.pop(item_id, None)
+            try:
+                self.graph.remove_item(item_id)
+            except Exception:
+                pass
+        gs = self._graph_store()
+        if gs is not None:
+            try:
+                gs.delete(item_id)   # HKC 软删除(status='deleted')
+            except Exception:
+                pass
+        if found:
+            self._save()
+        return found
+
+    def add_note(self, item_id: str, text: str) -> dict:
+        """给一个知识点追加一条笔记(有内容才写盘;没新增就不存)。"""
+        self._ensure_hkc_loaded()
+        text = (text or "").strip()
+        if not text:
+            return {"error": "笔记为空"}
+        with self._lock:
+            item = self.items.get(item_id)
+            if item is None:
+                return {"error": "未知知识点"}
+            item.notes.append({"text": text, "ts": datetime.now().isoformat()})
+            notes = list(item.notes)
+        self._save()   # 只有新增了笔记才落盘
+        return {"notes": notes}
+
+    def due_today(self) -> list:
+        """今天该复习的知识点(最弱的优先)。"""
+        due = self.sr.due_items(list(self.review_states.values()))
+        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()
+        semantic_edges = self.graph.auto_link_by_semantic(semantic_threshold)
+        return {"topic_edges": topic_edges,
+                "semantic_edges": semantic_edges,
+                "graph": self.graph.stats()}
+
+    def related(self, item_id: str) -> list:
+        """某知识点的关联知识(连接发现)。"""
+        out = []
+        for nid, etype, weight, reason in self.graph.neighbors(item_id):
+            if nid in self.items:
+                out.append({"item": self.items[nid].to_dict(),
+                            "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(
+                rule_id="review_due", action="review_due", severity="info",
+                message=f"今天有 {len(due)} 个知识点待复习",
+                payload={"count": len(due)}))
+
+        # 遗忘风险(薄弱项)
+        risky = self.sr.forgetting_risk(states)
+        if risky:
+            verdicts.append(LearningVerdict(
+                rule_id="weak_alert", action="weak_topic_alert", severity="warn",
+                message=f"{len(risky)} 个知识点处于高遗忘风险,建议优先复习",
+                payload={"risky": risky[:5]}))
+
+        # 负荷预警
+        load = self.sr.learning_load(states)
+        if load["total_due"] > daily_cap:
+            verdicts.append(LearningVerdict(
+                rule_id="overload", action="overload_warn", severity="warn",
+                message=f"未来复习量 {load['total_due']} 超过每日上限 {daily_cap},建议分批",
+                payload=load))
+
+        # 孤立知识点(无连接)→ 建议建立关联
+        connected = set()
+        for e in self.graph.edges:
+            connected.add(e.source_id)
+            connected.add(e.target_id)
+        isolated = [i for i in self.items if i not in connected]
+        if isolated:
+            verdicts.append(LearningVerdict(
+                rule_id="suggest_connect", action="suggest_connect", severity="info",
+                message=f"{len(isolated)} 个知识点尚无关联,可建立连接以加深理解",
+                payload={"isolated_count": len(isolated)}))
+        return verdicts
+
+    # ── 综合分析(office Agent 核心输出)──────────────────
+    def analyze(self) -> dict:
+        self._ensure_hkc_loaded()   # HKC 就绪后从真源载回知识(迁移删文件后重启也不丢)
+        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():
+            st = self.review_states.get(iid)
+            if st:
+                topic_mastery[item.topic].append(st.mastery)
+        topics = {t: round(sum(m) / len(m), 3) for t, m in topic_mastery.items()}
+
+        return {
+            "total_items": len(self.items),
+            "avg_mastery": avg_mastery,
+            "topic_mastery": topics,
+            "weakest_topic": (min(topics, key=topics.get) 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),
+            "graph": self.graph.stats(),
+            "strategy": [v.to_dict() for v in self.strategy_check()],
+        }
+
+    def status(self) -> dict:
+        self._ensure_hkc_loaded()
+        return {
+            "items": len(self.items),
+            "reviews_tracked": len(self.review_states),
+            "graph": self.graph.stats(),
+        }

package/python/foxclaw/learning/spaced_repetition.py

@@ -0,0 +1,96 @@
+"""
+Foxclaw 学习子系统 — 间隔重复引擎(固化层)
+实现 SM-2 算法(Anki 核心算法的经典版本)。
+核心思想:学习是时间连续系统——追踪每个知识点的记忆强度随时间衰减,
+在最佳时机安排复习,让"越用越熟"变成可计算的机制。
+"""
+
+from datetime import datetime, timedelta
+from .models import ReviewState
+
+
+class SpacedRepetition:
+    """SM-2 间隔重复算法。
+
+    评分 grade(0~5):
+      0-2 = 没记住(算 lapse,重置间隔)
+      3   = 勉强记住
+      4   = 记住了
+      5   = 完美回忆
+    """
+
+    @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:
+                state.interval = 6
+            else:
+                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
+
+    @staticmethod
+    def due_items(states: list) -> list:
+        """返回所有到期需复习的状态,按掌握度升序(最弱的先复习)。"""
+        due = [s for s in states if s.is_due]
+        return sorted(due, key=lambda s: s.mastery)
+
+    @staticmethod
+    def forgetting_risk(states: list, horizon_days: int = 3) -> list:
+        """遗忘风险检测(对应财务异常检测):
+        即将到期且掌握度低的知识点 = 高遗忘风险。"""
+        risky = []
+        for s in states:
+            if s.days_until_due <= horizon_days and s.mastery < 0.5:
+                risky.append({
+                    "item_id": s.item_id,
+                    "mastery": s.mastery,
+                    "days_until_due": s.days_until_due,
+                    "lapses": s.lapses,
+                    "risk": round((1 - s.mastery) * (1 if s.is_due else 0.6), 3),
+                    "reason": f"掌握度仅 {s.mastery},"
+                              + ("已到期" if s.is_due else f"{s.days_until_due} 天内到期"),
+                })
+        return sorted(risky, key=lambda x: -x["risk"])
+
+    @staticmethod
+    def learning_load(states: list, days: int = 7) -> dict:
+        """学习负荷(对应财务烧钱速度):未来 N 天的复习量。"""
+        from collections import defaultdict
+        by_day = 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   # 逾期的算今天
+        total_due = sum(by_day.values())
+        return {
+            "window_days": days,
+            "total_due": total_due,
+            "daily_avg": round(total_due / days, 1),
+            "by_day": dict(sorted(by_day.items())),
+            "overdue": sum(1 for s in states if s.is_due),
+        }