foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/itinerary/runtime.py

@@ -6,16 +6,17 @@ Foxclaw 行程子系统 — Itinerary Runtime
 
 import csv
 from pathlib import Path
+from typing import cast
 
-from .models import Waypoint, ItineraryVerdict
-from .reasoning import ItineraryReasoning
+from .models import ItineraryVerdict, TravelMode, Waypoint
+from .reasoning import MODE_SPEED, ItineraryReasoning
 from .amap_client import AMapClient
 
 
 class ItineraryRuntime:
     """行政 Agent 的行程内核。"""
 
-    def __init__(self, amap_key: str = None, hmr=None):
+    def __init__(self, amap_key: str | None = None, hmr=None):
         self.waypoints: list = []
         self.reasoning = ItineraryReasoning()
         self.amap = AMapClient(amap_key)
@@ -25,13 +26,11 @@ class ItineraryRuntime:
     def amap_enabled(self) -> bool:
         return self.amap.enabled
 
-    # ── 采集行程点 ────────────────────────────────────────
-    def add_waypoint(self, name: str, address: str = "", lng: float = None,
-                     lat: float = None, start_time: str = None,
+    def add_waypoint(self, name: str, address: str = "", lng: float | None = None,
+                     lat: float | None = None, start_time: str | None = None,
                      duration_min: int = 0, city: str = "") -> dict:
         wp = Waypoint(name=name, address=address, lng=lng, lat=lat,
                       start_time=start_time, duration_min=duration_min, city=city)
-        # 没坐标但有地址 → 尝试高德地理编码
         if not wp.has_coord and address and self.amap_enabled:
             geo = self.amap.geocode(address, city)
             if geo:
@@ -62,7 +61,6 @@ class ItineraryRuntime:
                 count += 1
         return count
 
-    # ── 真实路线(高德优先,否则估算)─────────────────────
     def real_leg(self, a: Waypoint, b: Waypoint, mode: str = "driving"):
         """两点路线:高德可用且有坐标时用真实数据,否则直线估算。"""
         if self.amap_enabled and a.has_coord and b.has_coord:
@@ -70,12 +68,12 @@ class ItineraryRuntime:
             if r:
                 from .models import RouteLeg
                 return RouteLeg(from_id=a.id, to_id=b.id, from_name=a.name,
-                                to_name=b.name, mode=mode,
+                                to_name=b.name,
+                                mode=cast(TravelMode, mode if mode in MODE_SPEED else "driving"),
                                 distance_km=r["distance_km"],
                                 duration_min=r["duration_min"], source="amap")
         return self.reasoning.estimate_leg(a, b, mode)
 
-    # ── 综合分析(行政 Agent 核心输出)────────────────────
     def plan(self, mode: str = "driving", optimize: bool = True) -> dict:
         """完整行程规划:优化顺序 + 冲突检测 + 聚类 + 守门人裁决。"""
         opt = (self.reasoning.optimize_order(self.waypoints, mode)
@@ -95,7 +93,6 @@ class ItineraryRuntime:
             "map_data": self._to_amap_mapdata(opt),
         }
 
-    # ── 行程守门人 ────────────────────────────────────────
     def _gatekeeper(self, conflicts, clusters, dens) -> list:
         verdicts = []
         for c in conflicts:
@@ -124,7 +121,6 @@ class ItineraryRuntime:
                 payload={"cluster": cl}))
         return verdicts
 
-    # ── 导出高德可视化格式(MapTaskData)──────────────────
     def _to_amap_mapdata(self, opt) -> list:
         """转成高德 MapTaskData(POI + route),可喂给高德生成可视化地图。"""
         data = []

package/python/foxclaw/kernel/capabilities.py

@@ -25,8 +25,8 @@ class CapabilityRegistry:
     def __init__(self):
         self._caps: dict[str, Any] = {}
         self._lazy: dict[str, Callable[[], Any]] = {}
-        self._lock = threading.RLock()             # 只护 _caps/_lazy 表(快照,持锁时间极短)
-        self._build_locks: dict[str, threading.Lock] = {}   # name -> 构造锁(per-name)
+        self._lock = threading.RLock()
+        self._build_locks: dict[str, threading.Lock] = {}
 
     def register(self, name: str, handle: Any) -> None:
         """注册一个已构造好的能力实例(覆盖同名)。"""
@@ -38,7 +38,7 @@ class CapabilityRegistry:
         with self._lock:
             self._lazy[name] = factory
 
-    def get(self, name: str, default: Any = None) -> Any:
+    def get(self, name: str, default: Any | None = None) -> Any:
         """解析能力。已注册直接返回;惰性则首次构造并缓存;都没有返回 default。
 
         【F1 修复】慢惰性构造(如 search_runtime 首建要装 HKC+载模型)**不持全局锁**,
@@ -54,12 +54,11 @@ class CapabilityRegistry:
             blk = self._build_locks.get(name)
             if blk is None:
                 blk = self._build_locks[name] = threading.Lock()
-        # 出全局锁,用 per-name 锁串行化"同一能力"的构造
         with blk:
             with self._lock:
-                if name in self._caps:      # 双检:构造期间可能已被别的线程建好
+                if name in self._caps:
                     return self._caps[name]
-            inst = factory()                # 慢构造:不持全局锁,不阻塞其它能力解析
+            inst = factory()
             with self._lock:
                 self._caps[name] = inst
                 return inst

package/python/foxclaw/kernel/policy_gate.py

@@ -22,12 +22,10 @@ from ..core.governance_audit import new_decision_id
 @dataclass
 class Verdict:
     allowed: bool
-    level: str                 # allow | warn | deny | confirm
+    level: str
     reason: str = ""
-    source: str = ""           # harness | permission
-    raw: Any = None            # 原始 HarnessResult / PermissionDecision(调用方按需取用)
-    # 【P3-4】每次裁决的唯一 ID(P1-2 治理审计的关联键)。放最后+默认值:既有位置参数
-    # 构造(如 Verdict(True,"allow",...,"permission",None))不受影响。
+    source: str = ""
+    raw: Any = None
     decision_id: str = field(default="")
 
 
@@ -35,9 +33,7 @@ class PolicyGate:
     def __init__(self, spine=None, action_evaluator: Optional[Callable] = None,
                  auditor=None):
         self._spine = spine
-        self._eval = action_evaluator   # skills.permission.evaluate,注入(避免 kernel→skills 环)
-        # 【P1-2】统一治理审计(可空:standalone 无审计)。鸭子类型注入,避免 kernel→core 之外
-        # 的装配环;core.governance_audit.GovernanceAuditor 是唯一预期实现。
+        self._eval = action_evaluator
         self._auditor = auditor
 
     @property
@@ -45,7 +41,6 @@ class PolicyGate:
         """SkillAdapter 经此取审计器,把执行终态关联到裁决 decision_id(P3-4 跨层关联)。"""
         return self._auditor
 
-    # ── 推理准入(Harness)──────────────────────────────────────
     def check_reasoning(self, harness, node) -> Verdict:
         """经统一门做推理漂移准入。底层仍是那一次 harness.check(同一 HarnessResult),
         Harness 自身已 emit harness_block/warn 事件,门面**不重复 emit**。行为一致。
@@ -64,7 +59,6 @@ class PolicyGate:
                                 "dominant_dim": getattr(r, "dominant_dim", "")})
         return v
 
-    # ── 动作准入(skill-guard)──────────────────────────────────
     def check_action(self, skill, args: dict, rules=None,
                      confirmed: bool = False, mode: str = "strict",
                      taint_level: int = 0, taint_threshold: int = 0) -> Verdict:

package/python/foxclaw/kernel/process_manager.py

@@ -16,16 +16,16 @@ import threading
 import time
 import uuid
 from dataclasses import dataclass, field
+from typing import Optional
 
 
-# 合法状态与允许的流转(状态机约束:防止非法跳转)
 _VALID_TRANSITIONS = {
     "created":   {"queued", "failed"},
     "queued":    {"scheduled", "failed"},
     "scheduled": {"running", "failed"},
     "running":   {"completed", "failed"},
-    "completed": set(),        # 终态
-    "failed":    set(),        # 终态
+    "completed": set(),
+    "failed":    set(),
 }
 _TERMINAL = {"completed", "failed"}
 
@@ -33,15 +33,15 @@ _TERMINAL = {"completed", "failed"}
 @dataclass
 class ProcessRecord:
     task: str
-    agent_id: str = None
+    agent_id: Optional[str] = None
     state: str = "created"
     process_id: str = field(default_factory=lambda: f"proc_{uuid.uuid4().hex[:8]}")
     priority: float = 0.0
-    route_hint: str = None
+    route_hint: Optional[str] = None
     created_at: float = field(default_factory=time.time)
     updated_at: float = field(default_factory=time.time)
     state_history: list = field(default_factory=list)
-    fail_reason: str = None
+    fail_reason: Optional[str] = None
 
     def to_dict(self) -> dict:
         return {
@@ -58,21 +58,13 @@ class ProcessManager:
 
     def __init__(self, bus=None, history_limit: int = 1000):
         self._processes: dict[str, ProcessRecord] = {}
-        self.bus = bus                      # 可选:状态变更发事件
+        self.bus = bus
         self._history_limit = history_limit
-        # 【深审优化】活跃(非终态)进程数的 O(1) 增量计数:create 时 +1、进入终态时 -1
-        # (集中在 _transition)。供 CognitiveState 每次 lifecycle 事件 O(1) 取用,
-        # 免去原先每事件 stats() 遍历全部进程(O(n),n≤1000)。
         self._active = 0
-        # 并行子 Agent 会让多个线程并发 create/mark_*/_evict 同一个 _processes dict,
-        # 且状态机流转是"读 state → 校验 → 写 state"的非原子序列。RLock 保证:
-        #   · dict 增删与遍历(list/stats/_evict)不撞"dict changed size";
-        #   · 同一进程的并发二次流转不会都通过终态校验后重复 transition。
-        # 可重入:_emit→bus.publish 的处理器可能回调 pm 的方法(同线程重入安全)。
         self._lock = threading.RLock()
 
-    def create(self, task: str, agent_id: str = None,
-               schedule: dict = None) -> ProcessRecord:
+    def create(self, task: str, agent_id: str | None = None,
+               schedule: dict | None = None) -> ProcessRecord:
         """创建进程(任务进入系统)。携带调度决策。"""
         rec = ProcessRecord(
             task=task, agent_id=agent_id,
@@ -81,36 +73,33 @@ class ProcessManager:
         )
         with self._lock:
             rec.state_history.append("created")
-            # 创建后立即入队 → 已调度(调度决策此时已有)
             self._transition(rec, "queued")
             if schedule:
                 self._transition(rec, "scheduled")
             self._processes[rec.process_id] = rec
-            self._active += 1              # 新进程为活跃(此刻处于 queued/scheduled 非终态)
+            self._active += 1
             self._evict_if_needed()
             self._emit(rec)
         return rec
 
-    def mark_running(self, process_id: str) -> ProcessRecord:
+    def mark_running(self, process_id: str) -> Optional[ProcessRecord]:
         with self._lock:
             rec = self._processes.get(process_id)
             if rec is None:
                 return None
-            # 若仍在 queued(create 未带 schedule),先补 scheduled 再 running
             if rec.state == "queued":
                 self._transition(rec, "scheduled")
             return self._safe_transition(process_id, "running")
 
-    def mark_completed(self, process_id: str) -> ProcessRecord:
+    def mark_completed(self, process_id: str) -> Optional[ProcessRecord]:
         with self._lock:
             return self._safe_transition(process_id, "completed")
 
-    def mark_failed(self, process_id: str, reason: str = "") -> ProcessRecord:
+    def mark_failed(self, process_id: str, reason: str = "") -> Optional[ProcessRecord]:
         with self._lock:
             rec = self._processes.get(process_id)
             if rec is None:
                 return None
-            # 已是终态 → 幂等忽略(重试/并发下的二次标记不算错误,不崩溃)
             if rec.state in _TERMINAL:
                 return rec
             self._transition(rec, "failed")
@@ -118,11 +107,11 @@ class ProcessManager:
             self._emit(rec)
             return rec
 
-    def get(self, process_id: str) -> ProcessRecord:
+    def get(self, process_id: str) -> Optional[ProcessRecord]:
         with self._lock:
             return self._processes.get(process_id)
 
-    def list(self, state: str = None, limit: int = 50) -> list:
+    def list(self, state: str | None = None, limit: int = 50) -> list:
         with self._lock:
             items = list(self._processes.values())
         if state:
@@ -138,21 +127,18 @@ class ProcessManager:
 
     def stats(self) -> dict:
         with self._lock:
-            counts = {}
+            counts: dict[str, int] = {}
             for r in self._processes.values():
                 counts[r.state] = counts.get(r.state, 0) + 1
             return {"total": len(self._processes), "by_state": counts,
                     "active": self._active}
 
-    # ── 内部 ──
-    def _safe_transition(self, process_id: str, next_state: str) -> ProcessRecord:
+    def _safe_transition(self, process_id: str, next_state: str) -> Optional[ProcessRecord]:
         rec = self._processes.get(process_id)
         if rec is None:
             return None
-        # 已是终态 → 幂等忽略(不崩溃)
         if rec.state in _TERMINAL:
             return rec
-        # 已在目标状态 → 幂等忽略(重复标记不报错)
         if rec.state == next_state:
             return rec
         self._transition(rec, next_state)
@@ -167,15 +153,12 @@ class ProcessManager:
         新增调用点直接调本方法,活跃计数会被重复扣减(可扣成负数,stats 失真)。
         这里是双保险。注意行为变更:终态 → 任何状态,从抛 ValueError 变为静默忽略。
         """
-        # 已是终态 → 幂等忽略(不再 -1,不再改状态)
         if rec.state in _TERMINAL:
             return
         allowed = _VALID_TRANSITIONS.get(rec.state, set())
         if next_state not in allowed:
             raise ValueError(
                 f"非法状态流转: {rec.state} → {next_state}(进程 {rec.process_id})")
-        # 进入终态 → 活跃计数 -1(每进程恰好 create 时 +1、首次入终态时 -1;
-        # 上面的终态守卫保证不会重复扣减)。
         if next_state in _TERMINAL:
             self._active -= 1
         rec.state = next_state
@@ -183,8 +166,6 @@ class ProcessManager:
         rec.state_history.append(next_state)
 
     def _emit(self, rec: ProcessRecord):
-        # 【v2 ① Step3·Lifecycle 统一】emit 唯一生命周期词汇 task.lifecycle.<state>
-        # (取代旧 process.state_changed;Scheduler 委托本 pm,不再自发另一套词汇)。
         if self.bus is not None:
             try:
                 self.bus.publish(f"task.lifecycle.{rec.state}", {

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),