foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/harness/loop_detection.py

@@ -0,0 +1,152 @@
+"""
+Foxclaw Harness — 工具循环检测 (Tool-Loop Detection)
+
+借鉴 OpenClaw 的循环检测思路,适配 Foxclaw 的 Harness 体系。
+断路器管"失败",循环检测管"无进展死循环"——Agent 不报错却陷入
+重复/横跳,白烧 token。这是行为异常的一种,与 Harness 漂移检测同源。
+
+三种循环模式:
+  repeat    同一调用(工具+参数签名)连续重复 N 次
+  ping_pong 两个调用交替出现(A→B→A→B)
+  no_progress 同工具反复调用但结果无变化(轮询卡死)
+多级:warning(预警)→ critical(严重)→ 熔断(建议中止)
+"""
+from __future__ import annotations
+import hashlib
+import json
+import threading
+from collections import deque
+from dataclasses import dataclass
+
+
+@dataclass
+class LoopVerdict:
+    stuck: bool = False
+    level: str = "ok"             # ok / warning / critical
+    detector: str = ""           # repeat / ping_pong / no_progress
+    count: int = 0
+    message: str = ""
+
+    def to_dict(self) -> dict:
+        return {"stuck": self.stuck, "level": self.level,
+                "detector": self.detector, "count": self.count,
+                "message": self.message}
+
+
+@dataclass
+class _ToolCall:
+    signature: str               # 工具名+参数的指纹
+    tool_name: str
+    result_hash: str = ""        # 结果指纹(判 no_progress)
+
+
+class ToolLoopDetector:
+    """监控工具调用历史,检测无进展死循环。每个 Agent/会话一个实例。"""
+
+    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._lock = threading.RLock()
+
+    @staticmethod
+    def _signature(tool_name: str, args: dict) -> str:
+        """工具名 + 规范化参数 → 指纹。"""
+        try:
+            payload = json.dumps(args or {}, sort_keys=True, ensure_ascii=False)
+        except Exception:
+            payload = str(args)
+        return hashlib.sha256(f"{tool_name}::{payload}".encode()).hexdigest()[:16]
+
+    @staticmethod
+    def _result_sig(result) -> str:
+        try:
+            s = json.dumps(result, sort_keys=True, ensure_ascii=False)[:500]
+        except Exception:
+            s = str(result)[:500]
+        return hashlib.sha256(s.encode()).hexdigest()[:16]
+
+    def record(self, tool_name: str, args: dict = 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 会交错)
+            self.history.append(_ToolCall(sig, tool_name, rhash))
+            self._last_verdict = self._detect()
+            return self._last_verdict
+
+    def _level_for(self, count: int) -> str:
+        if count >= self.circuit_break:
+            return "critical"      # 达熔断阈值仍按 critical 等级(由 stuck+建议中止体现)
+        if count >= self.critical:
+            return "critical"
+        if count >= self.warning:
+            return "warning"
+        return "ok"
+
+    def _detect(self) -> LoopVerdict:
+        h = list(self.history)
+        if len(h) < self.warning:
+            return LoopVerdict()
+
+        # 1. repeat / no_progress:末尾连续相同签名
+        last_sig = h[-1].signature
+        streak = 0
+        for c in reversed(h):
+            if c.signature == last_sig:
+                streak += 1
+            else:
+                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:
+                return LoopVerdict(
+                    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:
+                alt = 0
+                expect = [a, b]
+                for i, c in enumerate(reversed(h)):
+                    if c.signature == expect[i % 2]:
+                        alt += 1
+                    else:
+                        break
+                if alt >= self.warning:
+                    return LoopVerdict(
+                        stuck=True, level=self._level_for(alt),
+                        detector="ping_pong", count=alt,
+                        message=(f"工具「{h[-1].tool_name}」与「{h[-2].tool_name}」"
+                                 f"交替横跳 {alt} 次,无进展"))
+
+        return LoopVerdict()
+
+    def should_abort(self) -> bool:
+        """是否建议中止(达到熔断阈值)。复用最近一次 record 的检测结果。"""
+        with self._lock:
+            v = self._last_verdict or self._detect()
+            return v.stuck and v.count >= self.circuit_break
+
+    def reset(self):
+        with self._lock:
+            self.history.clear()
+            self._last_verdict = None

package/python/foxclaw/itinerary/__init__.py

@@ -0,0 +1,10 @@
+"""Foxclaw — Itinerary: 行政 Agent 的行程行为操作系统内核(接高德地图)"""
+from .models import Waypoint, RouteLeg, ItineraryVerdict
+from .reasoning import ItineraryReasoning, MODE_SPEED
+from .amap_client import AMapClient
+from .runtime import ItineraryRuntime
+
+__all__ = [
+    "Waypoint", "RouteLeg", "ItineraryVerdict",
+    "ItineraryReasoning", "MODE_SPEED", "AMapClient", "ItineraryRuntime",
+]

package/python/foxclaw/itinerary/amap_client.py

@@ -0,0 +1,117 @@
+"""
+Foxclaw 行程子系统 — 高德地图适配层
+封装高德 Web Service API。无 API Key 时所有方法降级返回 None,
+行程内核自动回退到纯算法估算(直线距离)。
+本地配置环境变量 AMAP_MAPS_API_KEY 后即接入真实高德数据。
+
+对齐高德 Web Service API 参数格式:
+  - 坐标:经度在前,纬度在后,逗号分隔 "116.397,39.909"
+  - geocode / regeo / route(walking|driving|transit|cycling) / poi / weather
+
+也可改为接官方 MCP server: @amap/amap-maps-mcp-server
+(通过 npx 启动,环境变量同样是 AMAP_MAPS_API_KEY)。
+"""
+
+import os
+import json
+from typing import Optional
+from urllib import request, parse
+
+
+AMAP_BASE = "https://restapi.amap.com/v3"
+
+
+class AMapClient:
+    """高德 Web Service 客户端。无 Key 则 enabled=False,调用返回 None。"""
+
+    def __init__(self, api_key: str = None):
+        self.api_key = api_key or os.environ.get("AMAP_MAPS_API_KEY")
+        self.enabled = bool(self.api_key)
+
+    def _get(self, path: str, params: dict) -> Optional[dict]:
+        if not self.enabled:
+            return None
+        params["key"] = self.api_key
+        url = f"{AMAP_BASE}/{path}?{parse.urlencode(params)}"
+        try:
+            with request.urlopen(url, timeout=8) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+            return data if data.get("status") == "1" else None
+        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"
+            lng, lat = loc.split(",")
+            return float(lng), float(lat)
+        return None
+
+    def regeo(self, lng: float, lat: float) -> Optional[str]:
+        """坐标 → 地址。"""
+        data = self._get("geocode/regeo", {"location": f"{lng},{lat}"})
+        if data and data.get("regeocode"):
+            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'。
+        返回 {distance_km, duration_min}。"""
+        path_map = {
+            "driving": "direction/driving",
+            "walking": "direction/walking",
+            "cycling": "direction/bicycling",
+            "transit": "direction/transit/integrated",
+        }
+        path = path_map.get(mode, "direction/driving")
+        params = {"origin": origin, "destination": destination}
+        if mode == "transit":
+            params["city"] = city
+        data = self._get(path, params)
+        if not data:
+            return None
+        try:
+            route = data["route"]
+            if mode == "transit":
+                seg = route["transits"][0]
+                return {"distance_km": round(int(seg["distance"]) / 1000, 2),
+                        "duration_min": round(int(seg["duration"]) / 60, 1),
+                        "source": "amap"}
+            else:
+                path0 = route["paths"][0]
+                return {"distance_km": round(int(path0["distance"]) / 1000, 2),
+                        "duration_min": round(int(path0["duration"]) / 60, 1),
+                        "source": "amap"}
+        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})
+        if data and data.get("pois"):
+            return [{"name": p["name"], "address": p.get("address", ""),
+                     "location": p["location"], "type": p.get("type", "")}
+                    for p in data["pois"]]
+        return None
+
+    def nearby(self, location: str, keywords: str = "", radius: int = 1000) -> Optional[list]:
+        data = self._get("place/around",
+                         {"location": location, "keywords": keywords, "radius": radius})
+        if data and data.get("pois"):
+            return [{"name": p["name"], "address": p.get("address", ""),
+                     "location": p["location"]} for p in data["pois"]]
+        return None
+
+    def weather(self, city: str) -> Optional[dict]:
+        data = self._get("weather/weatherInfo", {"city": city})
+        if data and data.get("lives"):
+            w = data["lives"][0]
+            return {"city": w["city"], "weather": w["weather"],
+                    "temperature": w["temperature"], "wind": w["winddirection"]}
+        return None

package/python/foxclaw/itinerary/models.py

@@ -0,0 +1,80 @@
+"""
+Foxclaw 行程子系统 — 数据模型
+行程行为操作系统的结构:
+  Waypoint(行程点:地点+时间+坐标)、RouteLeg(路线段)、
+  ItineraryVerdict(行程守门人裁决)
+核心思想:行程 = 时空中的可计算约束(地理位置 + 时间窗口 + 可达性)。
+坐标格式遵循高德:经度在前,纬度在后 [lng, lat]。
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Optional, Literal
+import uuid
+
+
+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               # 停留时长(分钟)
+    city: str = ""
+    note: str = ""
+    id: str = field(default_factory=lambda: f"wp_{uuid.uuid4().hex[:10]}")
+
+    @property
+    def has_coord(self) -> bool:
+        return self.lng is not None and self.lat is not None
+
+    @property
+    def coord_str(self) -> str:
+        """高德格式坐标字符串 '经度,纬度'"""
+        return f"{self.lng},{self.lat}" if self.has_coord else ""
+
+    @property
+    def dt(self) -> Optional[datetime]:
+        return datetime.fromisoformat(self.start_time) if self.start_time else None
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d.update(has_coord=self.has_coord, coord_str=self.coord_str)
+        return d
+
+
+@dataclass
+class RouteLeg:
+    """两点之间的路线段"""
+    from_id: str
+    to_id: str
+    from_name: str
+    to_name: str
+    mode: TravelMode = "driving"
+    distance_km: float = 0.0
+    duration_min: float = 0.0
+    source: Literal["estimated", "amap"] = "estimated"  # 估算 or 高德真实
+    note: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ItineraryVerdict:
+    """行程守门人裁决(对应财务/学习守门人)"""
+    rule_id: str
+    action: Literal["time_conflict", "unreachable", "too_dense",
+                    "cross_city", "suggest_reorder"]
+    message: str
+    severity: Literal["info", "warn", "critical"] = "warn"
+    waypoint_ids: list = field(default_factory=list)
+    payload: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)

package/python/foxclaw/itinerary/reasoner.py

@@ -0,0 +1,101 @@
+"""
+ItineraryConflictReasoner —— 行程冲突推理的认知化(v2 ③ Step4)。
+
+把 ItineraryReasoning.detect_conflicts 的规则裁决,形式化为
+    观察 → 假设 → 证据 → 裁决,
+**规则永远权威**(检测到时间冲突/通勤赶不及 → confirm,绝不被 LLM 推翻);
+可选 LLM 层(默认关)只对"无硬冲突、但排程紧凑"的微妙情形**升级** approve→confirm,
+结构上无从推翻规则、无从隐藏已检出的冲突。裁决带证据链(可审计)。
+
+顾问域(非治理闸口):无硬冲突时规则裁决=approve;LLM 出错→维持 approve(见基座
+DomainReasoner.llm_should_escalate 的 fail-safe 语义说明)。
+"""
+from __future__ import annotations
+from ..cognitive.reasoner import DomainReasoner, ReasonedVerdict, Evidence
+from .reasoning import ItineraryReasoning
+
+# "紧凑"阈值:某段空档 / 所需通勤 < 该比例的倍数即算逼近(未赶不及但很赶),
+# 交给可选 LLM 复核是否提醒用户。仅在启用 LLM 时生效。
+TIGHT_RATIO = 1.5
+
+
+class ItineraryConflictReasoner(DomainReasoner):
+    """subject = (waypoints, mode)。裁决:approve(行程可行) / confirm(有冲突或需注意)。"""
+
+    def __init__(self, mode: str = "driving", llm=None, llm_enabled: bool = False):
+        self.mode = mode
+        self.llm = llm
+        self.llm_enabled = llm_enabled
+
+    def observe(self, subject) -> dict:
+        waypoints, mode = subject
+        timed = [w for w in waypoints if getattr(w, "dt", None) is not None]
+        return {"count": len(waypoints), "timed": len(timed), "mode": mode or self.mode}
+
+    def hypothesize(self, obs: dict) -> list:
+        h = []
+        if obs["timed"] >= 2:
+            h += ["可能存在时间重叠", "可能通勤赶不及"]
+        if obs["count"] >= 2:
+            h.append("可能排程紧凑")
+        return h or ["行程点不足以产生冲突"]
+
+    def gather_evidence(self, subject, obs: dict) -> list:
+        waypoints, mode = subject
+        mode = obs["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:
+                ev.append(Evidence("proximity_clusters",
+                                   f"{len(clusters)} 组可顺路合并:{clusters}", 0.3))
+            dens = ItineraryReasoning.density(waypoints, mode)
+            ev.append(Evidence("density",
+                               f"{dens['waypoints']} 点/{dens['total_commute_min']:.0f} 分通勤"
+                               + ("/跨城" if dens["cross_city"] else ""), 0.3))
+        except Exception:
+            pass
+        return ev
+
+    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")
+        return ReasonedVerdict("approve", "行程可行:无时间冲突、通勤可达", ev, hyps, "rules")
+
+    def _is_tight(self, subject, obs) -> bool:
+        """无硬冲突,但存在某段空档紧贴所需通勤(available < TIGHT_RATIO×need)。"""
+        waypoints, mode = subject
+        mode = obs["mode"]
+        timed = sorted([w for w in waypoints if getattr(w, "dt", None) is not None],
+                       key=lambda w: w.dt)
+        from datetime import timedelta
+        for i in range(len(timed) - 1):
+            cur, nxt = timed[i], timed[i + 1]
+            if not (cur.has_coord and nxt.has_coord):
+                continue
+            cur_end = cur.dt + timedelta(minutes=cur.duration_min)
+            gap = (nxt.dt - cur_end).total_seconds() / 60
+            leg = ItineraryReasoning.estimate_leg(cur, nxt, mode)
+            if 0 < gap and leg.duration_min <= gap < leg.duration_min * TIGHT_RATIO:
+                return True
+        return False
+
+    def _llm_prompt(self, subject, obs, ev):
+        ev_text = "\n".join(f"- {e.factor}: {e.detail}" for e in ev) or "(无)"
+        system = ("你是行程助手。这份行程规则检查未发现硬冲突,但排程较紧。"
+                  "判断是否仍建议用户人工确认。只回答 CONFIRM(建议确认)或 OK(无需)。")
+        user = f"行程:{obs['count']} 个点,方式 {obs['mode']}。\n证据:\n{ev_text}\n\n只回答一个词:CONFIRM 或 OK。"
+        return system, user

package/python/foxclaw/itinerary/reasoning.py

@@ -0,0 +1,174 @@
+"""
+Foxclaw 行程子系统 — 推理引擎(行程 Agent 的大脑,纯算法)
+不依赖高德也能跑:路线优化(TSP)、可达性、时间冲突、地理聚类。
+接入高德后,把"直线估算"替换为"真实路线时间"(见 runtime)。
+"""
+
+import math
+from datetime import timedelta
+from itertools import permutations
+
+from .models import Waypoint, RouteLeg
+
+
+# 各出行方式的估算平均速度(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):
+            return 0.0
+        R = 6371.0
+        dlat = math.radians(b.lat - a.lat)
+        dlng = math.radians(b.lng - a.lng)
+        x = (math.sin(dlat/2)**2 +
+             math.cos(math.radians(a.lat)) * math.cos(math.radians(b.lat)) *
+             math.sin(dlng/2)**2)
+        return R * 2 * math.atan2(math.sqrt(x), math.sqrt(1-x))
+
+    @staticmethod
+    def estimate_leg(a: Waypoint, b: Waypoint, mode: str = "driving") -> RouteLeg:
+        """估算两点路线段(直线距离 × 1.3 绕路系数 / 速度)。"""
+        straight = ItineraryReasoning.haversine_km(a, b)
+        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),
+            duration_min=round(duration, 1), source="estimated",
+        )
+
+    # ── 路线优化(TSP)────────────────────────────────────
+    @staticmethod
+    def optimize_order(waypoints: list, mode: str = "driving",
+                       fixed_start: bool = True) -> dict:
+        """最优访问顺序。≤8 点用精确全排列,更多用最近邻启发式。
+        fixed_start=True 时第一个点固定为起点(比如"从公司出发")。"""
+        pts = [w for w in waypoints if w.has_coord]
+        if len(pts) < 2:
+            return {"order": [w.id for w in waypoints], "total_km": 0,
+                    "total_min": 0, "method": "trivial"}
+
+        def total_dist(seq):
+            return sum(ItineraryReasoning.haversine_km(seq[i], seq[i+1])
+                       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")
+            for perm in permutations(rest):
+                seq = ([start] + list(perm)) if start else list(perm)
+                d = total_dist(seq)
+                if d < best_d:
+                    best_d, best = d, seq
+            method = "exact"
+            ordered = best
+        else:
+            # 最近邻启发式
+            remaining = pts[1:]
+            ordered = [pts[0]]
+            while remaining:
+                last = ordered[-1]
+                nxt = min(remaining, key=lambda w: ItineraryReasoning.haversine_km(last, w))
+                ordered.append(nxt)
+                remaining.remove(nxt)
+            method = "nearest_neighbor"
+
+        # 计算总距离/时间
+        legs = [ItineraryReasoning.estimate_leg(ordered[i], ordered[i+1], mode)
+                for i in range(len(ordered)-1)]
+        return {
+            "order": [w.id for w in ordered],
+            "order_names": [w.name for w in ordered],
+            "total_km": round(sum(l.distance_km for l in legs), 2),
+            "total_min": round(sum(l.duration_min for l in legs), 1),
+            "legs": [l.to_dict() for l in legs],
+            "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 = []
+        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",
+                    "between": [cur.name, nxt.name],
+                    "ids": [cur.id, nxt.id],
+                    "reason": f"「{cur.name}」结束({cur_end.strftime('%H:%M')})"
+                              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
+                if leg.duration_min > gap_min:
+                    issues.append({
+                        "type": "unreachable",
+                        "between": [cur.name, nxt.name],
+                        "ids": [cur.id, nxt.id],
+                        "need_min": round(leg.duration_min, 0),
+                        "available_min": round(gap_min, 0),
+                        "reason": f"从「{cur.name}」到「{nxt.name}」需 {leg.duration_min:.0f} 分钟,"
+                                  f"但只有 {gap_min:.0f} 分钟空档",
+                    })
+        return issues
+
+    # ── 地理聚类(顺路归组)───────────────────────────────
+    @staticmethod
+    def cluster_by_proximity(waypoints: list, radius_km: float = 3.0) -> list:
+        """把相近的行程点聚成簇,建议"顺路一起办"。"""
+        pts = [w for w in waypoints if w.has_coord]
+        clusters, used = [], set()
+        for w in pts:
+            if w.id in used:
+                continue
+            cluster = [w]
+            used.add(w.id)
+            for other in pts:
+                if other.id in used:
+                    continue
+                if ItineraryReasoning.haversine_km(w, other) <= radius_km:
+                    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+点的簇
+
+    # ── 行程密度 ──────────────────────────────────────────
+    @staticmethod
+    def density(waypoints: list, mode: str = "driving") -> dict:
+        """行程密度:总点数、总通勤、跨城。"""
+        timed = sorted([w for w in waypoints if w.dt], key=lambda w: w.dt)
+        cities = set(w.city for w in waypoints if w.city)
+        total_commute = 0.0
+        for i in range(len(timed) - 1):
+            if timed[i].has_coord and timed[i+1].has_coord:
+                total_commute += ItineraryReasoning.estimate_leg(
+                    timed[i], timed[i+1], mode).duration_min
+        span_hours = 0
+        if len(timed) >= 2:
+            span_hours = (timed[-1].dt - timed[0].dt).total_seconds() / 3600
+        return {
+            "waypoints": len(waypoints),
+            "cities": list(cities),
+            "cross_city": len(cities) > 1,
+            "total_commute_min": round(total_commute, 1),
+            "span_hours": round(span_hours, 1),
+        }