foxclaw 0.1.2 → 0.1.4

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)

package/python/foxclaw/orchestration/__init__.py

@@ -22,14 +22,14 @@ RequestStatus = Literal["pending", "approved", "rejected", "needs_confirmation"]
 class CrossAgentRequest:
     """跨 Agent 请求 — 编排的基本单元。
     一个 Agent 向另一个发起请求,目标 Agent 用自己的守门人裁决。"""
-    from_agent: str                     # 发起方
-    to_agent: str                       # 目标方
+    from_agent: str
+    to_agent: str
     request_type: RequestType
-    payload: dict                       # 请求内容(金额/时间/查询等)
+    payload: dict
     reason: str = ""
     status: RequestStatus = "pending"
-    verdict: str = ""                   # 目标 Agent 的裁决说明
-    negotiation: list = field(default_factory=list)   # 协商回合记录(每轮:裁决 + 让步)
+    verdict: str = ""
+    negotiation: list = field(default_factory=list)
     id: str = field(default_factory=lambda: f"req_{uuid.uuid4().hex[:10]}")
     created_at: str = field(default_factory=lambda: datetime.now().isoformat())
 
@@ -40,10 +40,10 @@ class CrossAgentRequest:
 @dataclass
 class GlobalSituation:
     """全局态势 — 主管的驾驶舱视图,汇总各内核关键指标。"""
-    finance: dict = field(default_factory=dict)     # 超支?守门人告警?
-    learning: dict = field(default_factory=dict)    # 待复习?薄弱主题?
-    itinerary: dict = field(default_factory=dict)   # 行程冲突?赶不及?
-    alerts: list = field(default_factory=list)      # 跨域汇总的高优先告警
+    finance: dict = field(default_factory=dict)
+    learning: dict = field(default_factory=dict)
+    itinerary: dict = field(default_factory=dict)
+    alerts: list = field(default_factory=list)
     timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
 
     def to_dict(self) -> dict:
@@ -58,13 +58,8 @@ class Orchestrator:
     不再反向直接持有含主管的 agents 字典)。"""
 
     def __init__(self, caps, auditor=None):
-        self._caps = caps               # CapabilityRegistry
-        # 【P1-3】统一治理审计(可空:standalone 无审计)。裁决事件原本**完全没有**——
-        # 跨 Agent 委派的批准/拒绝/转人工,事前无任何可观测记录。
+        self._caps = caps
         self._auditor = auditor
-        # 【深审修复·长期运行泄漏】原为普通 list、只增不减且**全库从不读**——每次跨 Agent 请求
-        # append 一个 req → 无界增长。改有界 deque(保留最近 N 条供未来观测,符合本库 token_meter/
-        # HookManager 的有界日志惯例);deque.append 原子 ⇒ 并发路由也安全。
         self.request_log: deque = deque(maxlen=1000)
 
     @property
@@ -72,12 +67,11 @@ class Orchestrator:
         """按名字从注册中枢解析 agents(id -> agent 实例)。"""
         return self._caps.get("agents") or {}
 
-    # ── 全局态势汇总(P3:通用聚合,不懂任何领域内部 API)────────────
     def gather_situation(self) -> GlobalSituation:
         """通用聚合各 Agent 自报的领域态势(agent.situation()),形成驾驶舱视图。
         编排层不再直接读 finance/learning/itinerary 内核——领域知识已归属各领域 Agent。"""
         sit = GlobalSituation()
-        alerts = []
+        alerts: list[dict] = []
         for agent in self.agents.values():
             try:
                 s = agent.situation()
@@ -85,12 +79,10 @@ class Orchestrator:
                 continue
             if not s:
                 continue
-            # 一个 Agent 可以自报**多个**领域(拓扑 5→3 后,办公学习 Agent 同时覆盖
-            # learning 与 itinerary),故 `domains: {name: status}` 与旧的单 `domain` 都收。
             doms = s.get("domains")
             if isinstance(doms, dict) and doms:
                 for d, st in doms.items():
-                    if d and hasattr(sit, d):       # finance/learning/itinerary
+                    if d and hasattr(sit, d):
                         setattr(sit, d, st or {})
             else:
                 domain = s.get("domain")
@@ -102,24 +94,16 @@ class Orchestrator:
                             .get(a.get("severity"), 3))
         return sit
 
-    # ── 跨 Agent 请求路由(P3:通用委托,由目标 Agent 用自己的守门人裁决)──────
     def route_request(self, req: CrossAgentRequest) -> CrossAgentRequest:
         """把请求路由给目标 Agent,由**目标 Agent**用自己的守门人裁决(编排层不懂领域)。"""
         target = self.agents.get(req.to_agent)
         if target is None:
-            # 【P1-0】原为 status="approved"(默认放行)—— 那是 fail-open:发起方会拿到
-            # "已批准",但**没有任何 Agent 真的处理过这个请求**。后果是实打实的,例如
-            # 行程 Agent 向未注册的 finance 申请差旅预算,会直接拿到批准并据此下单。
-            # 与下方「裁决异常 → 转人工确认」同属一条原则:裁决权不在编排层,凡未真正
-            # 裁决过的,都不能算通过。改为 needs_confirmation 同样"不崩",只是不再说谎。
             req.status = "needs_confirmation"
             req.verdict = f"目标 Agent '{req.to_agent}' 不存在,无法裁决,转人工确认"
         else:
             try:
                 target.handle_cross_request(req)
             except Exception as e:
-                # 守门人裁决崩溃(如畸形 payload 让解析抛错)必须 **fail-safe**:转人工确认,
-                # 绝不自动放行——对守门人而言,裁决失败时放行=fail-open,是安全隐患。
                 req.status = "needs_confirmation"
                 req.verdict = f"裁决异常,转人工确认: {e}"
         self.request_log.append(req)
@@ -143,7 +127,6 @@ class Orchestrator:
                     "negotiation_round": len(req.negotiation)},
             correlation_id=req.id)
 
-    # ── 协商闭环:被拒 → 发起方让步 → 再裁决 ──────────────────────────
     def negotiate(self, req: CrossAgentRequest, max_rounds: int = 3) -> CrossAgentRequest:
         """跑协商协议。原先裁决是**终局**:财务说预算不足→rejected→到此为止,用户只拿到
         一句"被拒绝"。现在:发起方可拿着拒绝理由降标准重来(改高铁/换酒店/减一天)。
@@ -165,17 +148,17 @@ class Orchestrator:
                                     "verdict": req.verdict,
                                     "payload": dict(req.payload)})
             if req.status != "rejected":
-                break                                  # 通过/待确认 → 协商结束
+                break
             requester = self.agents.get(req.from_agent)
             if requester is None:
                 break
             try:
-                revised = requester.concede(req, req.verdict)   # 问发起方:能让吗?
+                revised = requester.concede(req, req.verdict)
             except Exception as e:
                 req.negotiation.append({"round": rnd, "concede_error": str(e)[:120]})
-                break                                  # 让步逻辑出错 → 停,维持原裁决
+                break
             if not revised or revised == req.payload:
-                break                                  # 让无可让 / 无实质变化 → 停
+                break
             req.negotiation[-1]["conceded_to"] = dict(revised)
             req.payload = revised
         return req