foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/harness/harness.py

@@ -20,7 +20,6 @@ from typing import Optional
 
 from ..core.thought_chain import ThoughtChain, ThoughtNode, HarnessStatus
 
-# ── S3 步骤 4：按检测维度拆分（纯搬移、零行为变更）────────────────────────
 from ._base import (
     HarnessResult,
     GoalBaseline,
@@ -32,7 +31,6 @@ from .drift import SemanticDrift, ToolIntentDrift, ScopeCreepDrift
 from .event_bus import HarnessEventBus
 from ._policy import PolicyMixin
 
-# 历史导入兼容：`from foxclaw.harness.harness import X` 的 X 在此 re-export。
 __all__ = [
     "Harness", "HarnessResult", "GoalBaseline",
     "SemanticDrift", "ToolIntentDrift", "ScopeCreepDrift",
@@ -51,18 +49,10 @@ class Harness(PolicyMixin):
         thought_chain: ThoughtChain,
         policy_path: str = "./foxclaw_data/policy.yaml",
         shadow_rounds: int = 20,
-        embedding_model: str = None,
-        spine=None,                       # 【P0】全局 EventSpine(可空:standalone/governance 场景)
-        promote_min_obs: int = None,      # 【P0-1】影子规则升迁所需观察次数(None→env/默认 50)
+        embedding_model: str | None = None,
+        spine=None,
+        promote_min_obs: int | None = None,
     ):
-        # embedding 模型解析 —— 【P2·单 embedding 入口】优先级:
-        #   1. 显式传参(测试/单 Agent 切模型用)
-        #   2. EMBEDDING_MODEL(系统唯一本地 embedding 入口,.env 一处配 bge-m3 全局生效)
-        #   3. HKC_EMBEDDING_MODEL(向后兼容,EMBEDDING_MODEL 未设时回退)
-        #   4. FOXCLAW_EMBEDDING_MODEL(向后兼容)
-        #   5. all-MiniLM-L6-v2(传统兜底)
-        # 中文部署设 paraphrase-multilingual-MiniLM-L12-v2 时,语义漂移对中文硬拦率
-        # 从 0 升到 1.0(见 evals/governance/compare_embeddings.py)。
         embedding_model = (embedding_model
                            or os.environ.get("EMBEDDING_MODEL")
                            or os.environ.get("HKC_EMBEDDING_MODEL")
@@ -72,83 +62,47 @@ class Harness(PolicyMixin):
         self.thought_chain = thought_chain
         self.policy_path = Path(policy_path).resolve()
         self.shadow_rounds = shadow_rounds
-        # per-实例分槽 token(目标基线走 contextvar,见文件顶部)
         self._ctx_token = uuid.uuid4().hex
-        # 累积学习态(_delta_history/_run_count/weights/_policy/阈值)的并发锁。
-        # 为把请求 offload 到线程池提速做准备:多线程会并发调 check 打同一 harness,
-        # 昂贵的语义嵌入放锁外(线程安全、可并行),只有廉价的累积态改写进锁。RLock:
-        # _trigger_policy_learning 在锁内调用,同线程可重入。
         self._lock = threading.RLock()
 
-        # 检测引擎
         self.sem_drift = SemanticDrift(embedding_model)
         self.tool_drift = ToolIntentDrift()
         self.scope_drift = ScopeCreepDrift()
 
-        # 事件总线:本地订阅(向后兼容)+ 转发进全局脊柱(spine 非空时)
         self.bus = HarnessEventBus(spine=spine, source=agent_id)
 
-        # 目标基线(每任务)—— 由 contextvar 承载;_baseline 是路由到 contextvar 的
-        # property,register_goal/check 里对 self._baseline 的读写代码完全不变。
         self._baseline = None
 
-        # 权重（Policy 学习后动态调整）
         self.weights = {"semantic": 0.5, "tool": 0.3, "scope": 0.2}
 
-        # 是否因「语义漂移」而 BLOCK。领域 Agent=True(执行业务任务时跑题要拦);
-        # 调度层(主管)=False(接收任意输入是其职责,语义距离大不算异常)。
         self.block_on_semantic = True
 
-        # ── 降级方向修正(B 类修复)────────────────────────────────────
-        # 语义嵌入不可用时(SemanticDrift.mode == "hash"),3-gram 哈希对中文几乎
-        # 无区分度 —— 实测同域相似度 -0.17、跨域 +0.00,差异 <0.17 → 漂移分
-        # 1-sim 裁剪后**恒为 1.0**。该维度一旦参与加权(semantic 权重 0.5),
-        # Δ 恒 0.5 > block 阈值 0.25 → **所有请求一律 BLOCK**,包括评测集里
-        # ground-truth 标注为 pass 的正常请求。
-        # 治理层从「精准拦截」退化为「无差别拦截」,比不治理更危险(阻塞全部正常
-        # 业务),且失败是静默的(仅 mode 属性变化,无告警)。
-        #
-        # 正确处置:安全组件的降级方向必须是 **fail-open(失效但可见)**,
-        # 而不是 fail-closed-with-garbage(过度拦截且静默)。故降级时**停用语义
-        # 维度**,而 tool/scope 两个维度是确定性规则(工具类别匹配、实体集合运算),
-        # 不依赖模型质量,降级后仍可信,照常工作。
         self.semantic_degraded: bool = (self.sem_drift.mode != "transformer")
-        # 降级只告警一次,避免每节点刷屏
         self._degrade_warned: bool = False
 
-        # Shadow mode 状态
         self._shadow_mode = True
         self._run_count = 0
         self._delta_history: list[float] = []
 
-        # 阈值（shadow mode 结束后用真实数据替换）
         self._warn_threshold = 0.15
         self._block_threshold = 0.25
 
-        # Policy
         self._policy: dict = self._load_policy()
-        # 【P0-1】影子学习段(旧 YAML 没有 → 补空段;不重命名既有键,版本兼容)
         self._policy.setdefault("shadow_rules", [])
         self._policy.setdefault("history", [])
 
-        # 【P0-1】影子观察达标线:observations 凑满才做 promote/discard 判定。
-        # 显式构造参数 > 环境变量 > 默认 50(文稿建议值)。个人级低频使用下一条影子
-        # 规则可能长期 observing —— 这正是影子的目的:证据不够就不生效。
         if promote_min_obs is not None:
             self.promote_min_obs = promote_min_obs
         else:
             _env = os.environ.get("FOXCLAW_SHADOW_PROMOTE_MIN_OBS", "").strip()
             self.promote_min_obs = int(_env) if _env.isdigit() else 50
 
-        # 把已学习规则的 action 编译成 check() 可直接应用的结构(规则级生效)
         self._penalized_tools: set[str] = set()
         self._scope_limit: Optional[int] = None
         self._reindex_learned_actions()
 
-        # 注册默认事件处理
         self._setup_default_handlers()
 
-    # ── 目标基线(每任务,contextvar 支撑,property 透明路由)──────
     @property
     def _baseline(self):
         return _harness_ctx_get(self._ctx_token)
@@ -157,13 +111,12 @@ class Harness(PolicyMixin):
     def _baseline(self, value):
         _harness_ctx_set(self._ctx_token, value)
 
-    # ── 目标基线注册 ───────────────────────────────────────
 
     def register_goal(
         self,
         goal_text: str,
         allowed_tool_categories: set[str],
-        baseline_entities: set[str] = None,
+        baseline_entities: set[str] | None = None,
     ) -> GoalBaseline:
         """接口层调用 — 注册任务目标基线"""
         baseline = GoalBaseline(
@@ -171,14 +124,11 @@ class Harness(PolicyMixin):
             allowed_tool_categories=allowed_tool_categories,
             baseline_entities=baseline_entities or set(),
         )
-        # 用 encode(纯函数)算每任务自持的基线向量,不写共享的 _baseline_vec →
-        # 并发顶层任务的语义基线互不覆盖(check 用 self._baseline.goal_embedding 打分)。
         baseline.goal_embedding = self.sem_drift.encode(goal_text)
         self._baseline = baseline
         self.bus.emit("goal_registered", baseline.to_dict())
         return baseline
 
-    # ── 核心校验方法 ───────────────────────────────────────
 
     def check(self, node: ThoughtNode, ignore_semantic: bool = False) -> HarnessResult:
         """
@@ -195,9 +145,8 @@ class Harness(PolicyMixin):
         停用不可信维度,保留可信的 tool/scope 判定,并在 reason 显式标注降级
         (失效但可见)。走 _check_degraded 分支,正常路径逻辑逐字不变。
         """
-        baseline = self._baseline    # contextvar 读(每任务/线程独立)
+        baseline = self._baseline
         if baseline is None:
-            # 没有注册目标基线，只观测不截断
             result = HarnessResult(
                 status="PASS", delta=0.0, dominant_dim="none",
                 scores={"semantic": 0.0, "tool": 0.0, "scope": 0.0},
@@ -208,12 +157,9 @@ class Harness(PolicyMixin):
         if self.semantic_degraded and not ignore_semantic:
             return self._check_degraded(node)
 
-        # 语义嵌入(昂贵、线程安全)—— **放锁外**,使请求 offload 到线程池后,并发请求的
-        # 嵌入计算真正并行(torch/ST CPU 前向会释放 GIL)。这是吞吐提速的关键点。
         sem_score = 0.0 if ignore_semantic else \
             self.sem_drift.score(node.content, baseline.goal_embedding)
 
-        # 以下累积态的读改写进锁(廉价):weights/_delta_history/_run_count/阈值/_policy。
         with self._lock:
             scores = {
                 "semantic": sem_score,
@@ -224,10 +170,6 @@ class Harness(PolicyMixin):
                     set(node.entities), baseline.baseline_entities),
             }
 
-            # 应用已学习规则的 action(规则级生效,区别于权重级自学习):
-            #   · penalize_tool —— 之前触发过 BLOCK 的工具,即便类别本在允许集里,也判最高
-            #     工具风险(1.0),让「学到某工具危险」下次真正拦得住,而非只微调 tool 权重。
-            #   · restrict_scope —— 学到的实体扩张上限;新增实体超限直接判范围越界(scope=1.0)。
             if node.tool_name and self._is_penalized_tool(node.tool_name):
                 scores["tool"] = 1.0
             if (self._scope_limit is not None and baseline.baseline_entities):
@@ -236,27 +178,19 @@ class Harness(PolicyMixin):
                     scores["scope"] = 1.0
 
             delta = sum(self.weights[k] * v for k, v in scores.items())
-            dominant = max(scores, key=scores.get)
+            dominant = max(scores, key=lambda k: scores[k])
 
-            # 更新 shadow mode 历史。【深审修复·长期运行泄漏】原先**无条件**每次 check 都 append,
-            # 但 _delta_history 仅在 _calibrate_thresholds(shadow 结束时跑一次)被读;shadow_mode 只在
-            # init 置 True、永不重入,故校准后继续 append 是**纯无界泄漏**(每个推理节点一个 float)。
-            # 改为**仅 shadow 期 append**:样本上限=shadow_rounds,校准看到的样本完全一致(行为不变)。
             if self._shadow_mode:
                 self._delta_history.append(delta)
             self._run_count += 1
 
-            # Shadow mode 结束：用真实数据校准阈值
             if self._shadow_mode and self._run_count >= self.shadow_rounds:
                 self._calibrate_thresholds()
 
-            # 判断状态
             if self._shadow_mode:
-                status: HarnessStatus = "PASS"  # 观测期永不截断
+                status: HarnessStatus = "PASS"
                 reason = None
             elif delta > self._block_threshold:
-                # 调度层(如主管)豁免「语义漂移」拦截:它的职责就是接收任意输入,
-                # 语义距离天然大,不应因此 BLOCK。但工具越权/范围越界仍然拦截。
                 if not self.block_on_semantic and dominant == "semantic":
                     status = "WARN"
                     reason = f"semantic drift Δ={delta:.3f}(调度层仅告警不拦截)"
@@ -275,19 +209,12 @@ class Harness(PolicyMixin):
                 scores=scores, reason=reason,
             )
 
-            # 【P0-1】影子规则双轨观察(锁内):用**已算好的 scores** 模拟应用影子规则的
-            # action,只记录 would_block/would_pass,绝不改变上面的 real result。
-            # 不重新做语义嵌入 —— 开销是 O(观察中规则数) 的纯算术,远优于文稿预估的 2x。
-            # 顺序有意**先于**下方的 BLOCK 学习:本次 check 是对**既有**候选的一次观察样本;
-            # 本次 BLOCK 诞生的新候选从**下一次** check 才开始积累证据(诞生事件≠观察样本)。
             if self._policy.get("shadow_rules"):
                 self._observe_shadow_rules(node, result, scores)
 
-            # BLOCK：触发 Policy 学习(mutates weights/_policy,须在锁内)
             if status == "BLOCK":
                 self._trigger_policy_learning(node, result)
 
-        # 锁外:SQLite 写(WAL 线程安全)+ 事件广播(HarnessEventBus 独立)
         self.thought_chain.update_harness(node.id, status, reason, delta, dominant)
         self.bus.emit(f"harness_{status.lower()}", {
             "agent_id": self.agent_id, "node_id": node.id, "node_type": node.type,
@@ -311,7 +238,6 @@ class Harness(PolicyMixin):
         baseline = self._baseline
         if not self._degrade_warned:
             self._degrade_warned = True
-            # 一次性告警:降级 = 治理能力缺失,属需人工知晓的事件,不能只靠属性静默。
             import logging as _lg
             _lg.getLogger("foxclaw.harness").warning(
                 "[harness] 语义嵌入不可用(mode=%s),语义漂移维度已停用 —— "
@@ -320,8 +246,6 @@ class Harness(PolicyMixin):
                 self.sem_drift.mode)
 
         with self._lock:
-            # 降级期间不污染 shadow 样本:把语义分置 0 后再 append,否则恒 1.0 的
-            # 语义分会污染阈值校准,装回 ST 后阈值仍不准。
             saved_w = self.weights.get("semantic", 0.0)
             self.weights["semantic"] = 0.0
             try:
@@ -333,7 +257,6 @@ class Harness(PolicyMixin):
                     "scope": self.scope_drift.score(
                         set(node.entities), baseline.baseline_entities),
                 }
-                # 规则级学习(action)照常生效 —— 这部分不依赖 embedding
                 if node.tool_name and self._is_penalized_tool(node.tool_name):
                     scores["tool"] = 1.0
                 if (self._scope_limit is not None and baseline.baseline_entities):
@@ -342,7 +265,7 @@ class Harness(PolicyMixin):
                         scores["scope"] = 1.0
 
                 delta = sum(self.weights[k] * v for k, v in scores.items())
-                dominant = max(scores, key=scores.get)
+                dominant = max(scores, key=lambda k: scores[k])
                 if self._shadow_mode:
                     self._delta_history.append(delta)
                 self._run_count += 1
@@ -350,7 +273,7 @@ class Harness(PolicyMixin):
                     self._calibrate_thresholds()
 
                 if self._shadow_mode:
-                    status: HarnessStatus = "PASS"  # 观测期永不截断
+                    status: HarnessStatus = "PASS"
                     reason = None
                 elif delta > self._block_threshold:
                     status = "BLOCK"
@@ -361,7 +284,6 @@ class Harness(PolicyMixin):
                 else:
                     status = "PASS"
                     reason = None
-                # 降级标记:让上层/前端能识别「本次判定不含语义维度」(失效但可见)
                 reason = ((reason + " [semantic-degraded:治理降级]") if reason
                           else "[semantic-degraded:语义维度停用]")
             finally:
@@ -376,7 +298,6 @@ class Harness(PolicyMixin):
             if status == "BLOCK":
                 self._trigger_policy_learning(node, result)
 
-        # 锁外:SQLite 写 + 事件广播(同 check,额外带 degraded 标记)
         self.thought_chain.update_harness(node.id, status, reason, delta, dominant)
         self.bus.emit(f"harness_{status.lower()}", {
             "agent_id": self.agent_id, "node_id": node.id, "node_type": node.type,
@@ -385,7 +306,6 @@ class Harness(PolicyMixin):
         })
         return result
 
-    # ── 默认事件处理 ───────────────────────────────────────
 
     def _setup_default_handlers(self):
         def on_block(data):
@@ -405,7 +325,6 @@ class Harness(PolicyMixin):
         self.bus.on("harness_block", on_block)
         self.bus.on("policy_updated", on_policy_updated)
 
-    # ── 状态查询 ───────────────────────────────────────────
 
     @property
     def is_shadow_mode(self) -> bool:
@@ -419,10 +338,6 @@ class Harness(PolicyMixin):
             "shadow_mode": self._shadow_mode,
             "run_count": self._run_count,
             "shadow_rounds": self.shadow_rounds,
-            # ── 降级可见性(B 类修复)────────────────────────────────
-            # 语义嵌入是否降级。semantic_degraded=True 意味着漂移检测只剩
-            # tool/scope 两维,**跑题不会被拦截** —— 这是需要人工知晓的治理
-            # 能力缺失,不能只体现在日志里。
             "semantic_degraded": self.semantic_degraded,
             "embedding_mode": self.sem_drift.mode,
         }
@@ -435,12 +350,9 @@ class Harness(PolicyMixin):
             "total_rules": len(rules),
             "manual_rules": sum(1 for r in rules if r.get("source") == "manual"),
             "learned_rules": sum(1 for r in rules if r.get("source") == "harness_learned"),
-            # 【P0-1】影子学习账本:observing=观察中(不生效);discarded/rolled_back 保留供审计
             "shadow_observing": sum(1 for r in shadow
                                     if (r.get("shadow") or {}).get("status") == "observing"),
             "shadow_total": len(shadow),
             "history_events": len(self._policy.get("history", [])),
-            # 返回**副本**:此前直接返回 self.weights 引用 —— 调用方拿到的不是快照,
-            # 既可能被后续权重更新"隔空改写"(读到的值取决于时机),也能反向改坏内部状态。
             "weights": dict(self.weights),
         }

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:
         """行程密度:总点数、总通勤、跨城。"""