foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/harness/loop_detection.py

@@ -22,8 +22,8 @@ from dataclasses import dataclass
 @dataclass
 class LoopVerdict:
     stuck: bool = False
-    level: str = "ok"             # ok / warning / critical
-    detector: str = ""           # repeat / ping_pong / no_progress
+    level: str = "ok"
+    detector: str = ""
     count: int = 0
     message: str = ""
 
@@ -35,9 +35,9 @@ class LoopVerdict:
 
 @dataclass
 class _ToolCall:
-    signature: str               # 工具名+参数的指纹
+    signature: str
     tool_name: str
-    result_hash: str = ""        # 结果指纹(判 no_progress)
+    result_hash: str = ""
 
 
 class ToolLoopDetector:
@@ -45,14 +45,11 @@ class ToolLoopDetector:
 
     def __init__(self, history_size: int = 30, warning: int = 6,
                  critical: int = 12, circuit_break: int = 20):
-        # 阈值单调递增保证(warning < critical < circuit_break)
         self.warning = max(2, warning)
         self.critical = max(self.warning + 1, critical)
         self.circuit_break = max(self.critical + 1, circuit_break)
         self.history: deque = deque(maxlen=max(history_size, self.circuit_break))
-        self._last_verdict = None
-        # 【深审·线程安全】SkillAdapter 持单个共享实例,invoke(含管线内 dispatch)可被并发任务
-        # 同时调 record → history.append + _detect(list(history)) 非原子,需锁(线程安全铁律)。
+        self._last_verdict: LoopVerdict | None = None
         self._lock = threading.RLock()
 
     @staticmethod
@@ -72,18 +69,19 @@ class ToolLoopDetector:
             s = str(result)[:500]
         return hashlib.sha256(s.encode()).hexdigest()[:16]
 
-    def record(self, tool_name: str, args: dict = None, result=None) -> LoopVerdict:
+    def record(self, tool_name: str, args: dict | None = None, result=None) -> LoopVerdict:
         """记录一次工具调用并即时检测。返回 LoopVerdict。"""
         sig = self._signature(tool_name, args or {})
         rhash = self._result_sig(result) if result is not None else ""
-        with self._lock:                      # append + _detect 必须原子(并发 record 会交错)
+        with self._lock:
             self.history.append(_ToolCall(sig, tool_name, rhash))
-            self._last_verdict = self._detect()
-            return self._last_verdict
+            verdict = self._detect()
+            self._last_verdict = verdict
+            return verdict
 
     def _level_for(self, count: int) -> str:
         if count >= self.circuit_break:
-            return "critical"      # 达熔断阈值仍按 critical 等级(由 stuck+建议中止体现)
+            return "critical"
         if count >= self.critical:
             return "critical"
         if count >= self.warning:
@@ -95,7 +93,6 @@ class ToolLoopDetector:
         if len(h) < self.warning:
             return LoopVerdict()
 
-        # 1. repeat / no_progress:末尾连续相同签名
         last_sig = h[-1].signature
         streak = 0
         for c in reversed(h):
@@ -105,8 +102,6 @@ class ToolLoopDetector:
                 break
         if streak >= self.warning:
             lvl = self._level_for(streak)
-            # no_progress 优先:同签名重复 且 (有结果的那些)结果都相同
-            # (只比对非空 result_hash,避免混合有/无 result 时漏判轮询卡死)
             streak_calls = h[-streak:]
             with_result = [c.result_hash for c in streak_calls if c.result_hash]
             if len(with_result) >= 2 and len(set(with_result)) == 1:
@@ -114,13 +109,11 @@ class ToolLoopDetector:
                     stuck=True, level=lvl, detector="no_progress", count=streak,
                     message=(f"工具「{h[-1].tool_name}」轮询 {streak} 次结果无变化"
                              + ("(已达熔断阈值,建议中止)" if streak >= self.circuit_break else "")))
-            # 否则按 repeat
             return LoopVerdict(
                 stuck=True, level=lvl, detector="repeat", count=streak,
                 message=(f"工具「{h[-1].tool_name}」连续重复调用 {streak} 次"
                          + ("(已达熔断阈值,建议中止)" if streak >= self.circuit_break else "")))
 
-        # 3. ping_pong:末尾两签名交替(A→B→A→B)
         if len(h) >= 4:
             a, b = h[-1].signature, h[-2].signature
             if a != b:

package/python/foxclaw/itinerary/amap_client.py

@@ -24,7 +24,7 @@ AMAP_BASE = "https://restapi.amap.com/v3"
 class AMapClient:
     """高德 Web Service 客户端。无 Key 则 enabled=False,调用返回 None。"""
 
-    def __init__(self, api_key: str = None):
+    def __init__(self, api_key: str | None = None):
         self.api_key = api_key or os.environ.get("AMAP_MAPS_API_KEY")
         self.enabled = bool(self.api_key)
 
@@ -40,12 +40,11 @@ class AMapClient:
         except Exception:
             return None
 
-    # ── 地理编码 ──────────────────────────────────────────
     def geocode(self, address: str, city: str = "") -> Optional[tuple]:
         """地址 → (lng, lat)。"""
         data = self._get("geocode/geo", {"address": address, "city": city})
         if data and data.get("geocodes"):
-            loc = data["geocodes"][0]["location"]      # "lng,lat"
+            loc = data["geocodes"][0]["location"]
             lng, lat = loc.split(",")
             return float(lng), float(lat)
         return None
@@ -57,7 +56,6 @@ class AMapClient:
             return data["regeocode"].get("formatted_address")
         return None
 
-    # ── 路线规划 ──────────────────────────────────────────
     def route(self, origin: str, destination: str, mode: str = "driving",
               city: str = "") -> Optional[dict]:
         """真实路线。origin/destination 为 'lng,lat'。
@@ -90,7 +88,6 @@ class AMapClient:
         except Exception:
             return None
 
-    # ── POI / 周边 / 天气 ─────────────────────────────────
     def search_poi(self, keywords: str, city: str = "", offset: int = 10) -> Optional[list]:
         data = self._get("place/text",
                          {"keywords": keywords, "city": city, "offset": offset})

package/python/foxclaw/itinerary/models.py

@@ -19,12 +19,12 @@ TravelMode = Literal["walking", "driving", "transit", "cycling"]
 @dataclass
 class Waypoint:
     """一个行程点 = 时空中的一个约束"""
-    name: str                           # 地点名:公司、客户A、机场
-    address: str = ""                   # 地址(可经地理编码转坐标)
-    lng: Optional[float] = None         # 经度(高德:经度在前)
-    lat: Optional[float] = None         # 纬度
-    start_time: Optional[str] = None    # 计划到达时间 ISO
-    duration_min: int = 0               # 停留时长(分钟)
+    name: str
+    address: str = ""
+    lng: Optional[float] = None
+    lat: Optional[float] = None
+    start_time: Optional[str] = None
+    duration_min: int = 0
     city: str = ""
     note: str = ""
     id: str = field(default_factory=lambda: f"wp_{uuid.uuid4().hex[:10]}")
@@ -58,7 +58,7 @@ class RouteLeg:
     mode: TravelMode = "driving"
     distance_km: float = 0.0
     duration_min: float = 0.0
-    source: Literal["estimated", "amap"] = "estimated"  # 估算 or 高德真实
+    source: Literal["estimated", "amap"] = "estimated"
     note: str = ""
 
     def to_dict(self) -> dict:

package/python/foxclaw/itinerary/reasoner.py

@@ -14,8 +14,6 @@ from __future__ import annotations
 from ..cognitive.reasoner import DomainReasoner, ReasonedVerdict, Evidence
 from .reasoning import ItineraryReasoning
 
-# "紧凑"阈值:某段空档 / 所需通勤 < 该比例的倍数即算逼近(未赶不及但很赶),
-# 交给可选 LLM 复核是否提醒用户。仅在启用 LLM 时生效。
 TIGHT_RATIO = 1.5
 
 
@@ -43,12 +41,11 @@ class ItineraryConflictReasoner(DomainReasoner):
     def gather_evidence(self, subject, obs: dict) -> list:
         waypoints, mode = subject
         mode = obs["mode"]
-        conflicts = ItineraryReasoning.detect_conflicts(waypoints, mode)   # 规则=裁决证据
+        conflicts = ItineraryReasoning.detect_conflicts(waypoints, mode)
         ev = [Evidence(factor=c["type"], detail=c["reason"], weight=1.0, raw=c)
               for c in conflicts]
         if not conflicts:
             ev.append(Evidence("no_conflict", "未检测到时间冲突或通勤不可达", 0.5))
-        # informational(raw=None):顺路簇/密度,丰满证据链但不参与裁决
         try:
             clusters = ItineraryReasoning.cluster_by_proximity(waypoints)
             if clusters:
@@ -65,11 +62,9 @@ class ItineraryConflictReasoner(DomainReasoner):
     def arbitrate(self, subject, obs, hyps, ev) -> ReasonedVerdict:
         triggered = [e for e in ev if e.raw is not None]
         if triggered:
-            # 【规则权威】检出硬冲突 → confirm,绝不被 LLM 推翻/隐藏
             return ReasonedVerdict(
                 "confirm", "；".join(e.detail for e in triggered),
                 ev, hyps, "rules")
-        # 无硬冲突:可选让 LLM 就"紧凑排程"复核是否升级(只 approve→confirm)
         if DomainReasoner.llm_available(self.llm, self.llm_enabled) and self._is_tight(subject, obs):
             if DomainReasoner.llm_should_escalate(self.llm, *self._llm_prompt(subject, obs, ev)):
                 return ReasonedVerdict("confirm", "排程紧凑,LLM 建议人工确认", ev, hyps, "llm")

package/python/foxclaw/itinerary/reasoning.py

@@ -7,28 +7,29 @@ Foxclaw 行程子系统 — 推理引擎(行程 Agent 的大脑,纯算法)
 import math
 from datetime import timedelta
 from itertools import permutations
+from typing import Any, cast
 
-from .models import Waypoint, RouteLeg
+from .models import RouteLeg, TravelMode, Waypoint
 
 
-# 各出行方式的估算平均速度(km/h),接高德后用真实数据替换
 MODE_SPEED = {"walking": 5, "cycling": 15, "transit": 25, "driving": 35}
 
 
 class ItineraryReasoning:
     """行程推理:把地点+时间变成可决策的行程智能。"""
 
-    # ── 距离与可达性(直线估算)──────────────────────────
     @staticmethod
     def haversine_km(a: Waypoint, b: Waypoint) -> float:
         """两点直线距离(km)。Haversine 公式。"""
-        if not (a.has_coord and b.has_coord):
+        lat_a, lng_a = a.lat, a.lng
+        lat_b, lng_b = b.lat, b.lng
+        if lat_a is None or lng_a is None or lat_b is None or lng_b is None:
             return 0.0
         R = 6371.0
-        dlat = math.radians(b.lat - a.lat)
-        dlng = math.radians(b.lng - a.lng)
+        dlat = math.radians(lat_b - lat_a)
+        dlng = math.radians(lng_b - lng_a)
         x = (math.sin(dlat/2)**2 +
-             math.cos(math.radians(a.lat)) * math.cos(math.radians(b.lat)) *
+             math.cos(math.radians(lat_a)) * math.cos(math.radians(lat_b)) *
              math.sin(dlng/2)**2)
         return R * 2 * math.atan2(math.sqrt(x), math.sqrt(1-x))
 
@@ -36,16 +37,16 @@ class ItineraryReasoning:
     def estimate_leg(a: Waypoint, b: Waypoint, mode: str = "driving") -> RouteLeg:
         """估算两点路线段(直线距离 × 1.3 绕路系数 / 速度)。"""
         straight = ItineraryReasoning.haversine_km(a, b)
-        road_km = straight * 1.3                       # 绕路系数
+        road_km = straight * 1.3
         speed = MODE_SPEED.get(mode, 35)
         duration = (road_km / speed) * 60 if speed else 0
         return RouteLeg(
             from_id=a.id, to_id=b.id, from_name=a.name, to_name=b.name,
-            mode=mode, distance_km=round(road_km, 2),
+            mode=cast(TravelMode, mode if mode in MODE_SPEED else "driving"),
+            distance_km=round(road_km, 2),
             duration_min=round(duration, 1), source="estimated",
         )
 
-    # ── 路线优化(TSP)────────────────────────────────────
     @staticmethod
     def optimize_order(waypoints: list, mode: str = "driving",
                        fixed_start: bool = True) -> dict:
@@ -61,10 +62,10 @@ class ItineraryReasoning:
                        for i in range(len(seq)-1))
 
         if len(pts) <= 8:
-            # 精确解
             start = pts[0] if fixed_start else None
             rest = pts[1:] if fixed_start else pts
-            best, best_d = None, float("inf")
+            best: list = []
+            best_d = float("inf")
             for perm in permutations(rest):
                 seq = ([start] + list(perm)) if start else list(perm)
                 d = total_dist(seq)
@@ -73,7 +74,6 @@ class ItineraryReasoning:
             method = "exact"
             ordered = best
         else:
-            # 最近邻启发式
             remaining = pts[1:]
             ordered = [pts[0]]
             while remaining:
@@ -83,7 +83,6 @@ class ItineraryReasoning:
                 remaining.remove(nxt)
             method = "nearest_neighbor"
 
-        # 计算总距离/时间
         legs = [ItineraryReasoning.estimate_leg(ordered[i], ordered[i+1], mode)
                 for i in range(len(ordered)-1)]
         return {
@@ -95,17 +94,15 @@ class ItineraryReasoning:
             "method": method,
         }
 
-    # ── 时间冲突 + 可达性 ─────────────────────────────────
     @staticmethod
     def detect_conflicts(waypoints: list, mode: str = "driving") -> list:
         """按时间排序的行程,检测:① 时间重叠 ② 通勤赶不及。"""
         timed = [w for w in waypoints if w.dt is not None]
         timed.sort(key=lambda w: w.dt)
-        issues = []
+        issues: list[dict[str, Any]] = []
         for i in range(len(timed) - 1):
             cur, nxt = timed[i], timed[i+1]
             cur_end = cur.dt + timedelta(minutes=cur.duration_min)
-            # 时间重叠
             if cur_end > nxt.dt:
                 issues.append({
                     "type": "time_conflict",
@@ -115,7 +112,6 @@ class ItineraryReasoning:
                               f"晚于「{nxt.name}」开始({nxt.dt.strftime('%H:%M')})",
                 })
                 continue
-            # 可达性:中间通勤时间够不够
             if cur.has_coord and nxt.has_coord:
                 leg = ItineraryReasoning.estimate_leg(cur, nxt, mode)
                 gap_min = (nxt.dt - cur_end).total_seconds() / 60
@@ -131,7 +127,6 @@ class ItineraryReasoning:
                     })
         return issues
 
-    # ── 地理聚类(顺路归组)───────────────────────────────
     @staticmethod
     def cluster_by_proximity(waypoints: list, radius_km: float = 3.0) -> list:
         """把相近的行程点聚成簇,建议"顺路一起办"。"""
@@ -149,9 +144,8 @@ class ItineraryReasoning:
                     cluster.append(other)
                     used.add(other.id)
             clusters.append([c.name for c in cluster])
-        return [c for c in clusters if len(c) > 1]   # 只返回有2+点的簇
+        return [c for c in clusters if len(c) > 1]
 
-    # ── 行程密度 ──────────────────────────────────────────
     @staticmethod
     def density(waypoints: list, mode: str = "driving") -> dict:
         """行程密度:总点数、总通勤、跨城。"""

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}", {