foxclaw 0.1.0 → 0.1.3

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
+    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]}")
+
+    @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"
+    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,96 @@
+"""
+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
+
+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))
+        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:
+            return ReasonedVerdict(
+                "confirm", "；".join(e.detail for e in triggered),
+                ev, hyps, "rules")
+        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,168 @@
+"""
+Foxclaw 行程子系统 — 推理引擎(行程 Agent 的大脑,纯算法)
+不依赖高德也能跑:路线优化(TSP)、可达性、时间冲突、地理聚类。
+接入高德后,把"直线估算"替换为"真实路线时间"(见 runtime)。
+"""
+
+import math
+from datetime import timedelta
+from itertools import permutations
+from typing import Any, cast
+
+from .models import RouteLeg, TravelMode, Waypoint
+
+
+MODE_SPEED = {"walking": 5, "cycling": 15, "transit": 25, "driving": 35}
+
+
+class ItineraryReasoning:
+    """行程推理:把地点+时间变成可决策的行程智能。"""
+
+    @staticmethod
+    def haversine_km(a: Waypoint, b: Waypoint) -> float:
+        """两点直线距离(km)。Haversine 公式。"""
+        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(lat_b - lat_a)
+        dlng = math.radians(lng_b - lng_a)
+        x = (math.sin(dlat/2)**2 +
+             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))
+
+    @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=cast(TravelMode, mode if mode in MODE_SPEED else "driving"),
+            distance_km=round(road_km, 2),
+            duration_min=round(duration, 1), source="estimated",
+        )
+
+    @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: list = []
+            best_d = 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: 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",
+                    "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]
+
+    @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),
+        }

package/python/foxclaw/itinerary/runtime.py

@@ -0,0 +1,144 @@
+"""
+Foxclaw 行程子系统 — Itinerary Runtime
+行程行为操作系统:采集行程点 → 地理编码(高德或手动) → 路线优化 →
+冲突/可达检测 → 行程守门人。高德可用时自动用真实路线替换估算。
+"""
+
+import csv
+from pathlib import Path
+from typing import cast
+
+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 = None, hmr=None):
+        self.waypoints: list = []
+        self.reasoning = ItineraryReasoning()
+        self.amap = AMapClient(amap_key)
+        self.hmr = hmr
+
+    @property
+    def amap_enabled(self) -> bool:
+        return self.amap.enabled
+
+    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:
+                wp.lng, wp.lat = geo
+        self.waypoints.append(wp)
+        if self.hmr:
+            try:
+                self.hmr.ingest(content=f"行程:{name} @ {address or wp.coord_str} "
+                                        f"{start_time or ''}",
+                                type="task", agent_id="office",
+                                title=f"行程_{name}", tags=["itinerary"])
+            except Exception:
+                pass
+        return wp.to_dict()
+
+    def import_csv(self, path: str) -> int:
+        """CSV 导入。列:name,address,lng,lat,start_time,duration_min,city"""
+        count = 0
+        with open(Path(path), encoding="utf-8") as f:
+            for row in csv.DictReader(f):
+                self.add_waypoint(
+                    name=row["name"], address=row.get("address", ""),
+                    lng=float(row["lng"]) if row.get("lng") else None,
+                    lat=float(row["lat"]) if row.get("lat") else None,
+                    start_time=row.get("start_time") or None,
+                    duration_min=int(row.get("duration_min") or 0),
+                    city=row.get("city", ""))
+                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:
+            r = self.amap.route(a.coord_str, b.coord_str, mode, a.city)
+            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=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)
+
+    def plan(self, mode: str = "driving", optimize: bool = True) -> dict:
+        """完整行程规划:优化顺序 + 冲突检测 + 聚类 + 守门人裁决。"""
+        opt = (self.reasoning.optimize_order(self.waypoints, mode)
+               if optimize else None)
+        conflicts = self.reasoning.detect_conflicts(self.waypoints, mode)
+        clusters = self.reasoning.cluster_by_proximity(self.waypoints)
+        dens = self.reasoning.density(self.waypoints, mode)
+        verdicts = self._gatekeeper(conflicts, clusters, dens)
+        return {
+            "waypoint_count": len(self.waypoints),
+            "amap_enabled": self.amap_enabled,
+            "optimized_route": opt,
+            "conflicts": conflicts,
+            "proximity_clusters": clusters,
+            "density": dens,
+            "gatekeeper_verdicts": [v.to_dict() for v in verdicts],
+            "map_data": self._to_amap_mapdata(opt),
+        }
+
+    def _gatekeeper(self, conflicts, clusters, dens) -> list:
+        verdicts = []
+        for c in conflicts:
+            if c["type"] == "time_conflict":
+                verdicts.append(ItineraryVerdict(
+                    rule_id="time_conflict", action="time_conflict",
+                    severity="critical", message=c["reason"], waypoint_ids=c["ids"]))
+            elif c["type"] == "unreachable":
+                verdicts.append(ItineraryVerdict(
+                    rule_id="unreachable", action="unreachable",
+                    severity="critical", message=c["reason"], waypoint_ids=c["ids"]))
+        if dens["cross_city"]:
+            verdicts.append(ItineraryVerdict(
+                rule_id="cross_city", action="cross_city", severity="warn",
+                message=f"行程跨城市:{','.join(dens['cities'])},注意城际交通时间",
+                payload={"cities": dens["cities"]}))
+        if dens["total_commute_min"] > 180:
+            verdicts.append(ItineraryVerdict(
+                rule_id="too_dense", action="too_dense", severity="warn",
+                message=f"总通勤 {dens['total_commute_min']:.0f} 分钟过长,建议精简或分天",
+                payload=dens))
+        for cl in clusters:
+            verdicts.append(ItineraryVerdict(
+                rule_id="reorder", action="suggest_reorder", severity="info",
+                message=f"这几处相近,建议顺路一起办:{' · '.join(cl)}",
+                payload={"cluster": cl}))
+        return verdicts
+
+    def _to_amap_mapdata(self, opt) -> list:
+        """转成高德 MapTaskData(POI + route),可喂给高德生成可视化地图。"""
+        data = []
+        for wp in self.waypoints:
+            if wp.has_coord:
+                data.append({"type": "poi", "lnglat": [wp.lng, wp.lat],
+                             "text": wp.name, "remark": wp.address or wp.note})
+        if opt and opt.get("legs"):
+            id2wp = {w.id: w for w in self.waypoints}
+            for leg in opt["legs"]:
+                a, b = id2wp.get(leg["from_id"]), id2wp.get(leg["to_id"])
+                if a and b and a.has_coord and b.has_coord:
+                    data.append({"type": "route", "routeType": leg["mode"],
+                                 "start": [a.lng, a.lat], "end": [b.lng, b.lat],
+                                 "remark": f"{a.name}→{b.name}"})
+        return data
+
+    def status(self) -> dict:
+        return {"waypoints": len(self.waypoints),
+                "amap_enabled": self.amap_enabled,
+                "with_coord": sum(1 for w in self.waypoints if w.has_coord)}

package/python/foxclaw/kernel/__init__.py

@@ -0,0 +1,13 @@
+"""Foxclaw 内核层:进程管理、调度、事件脊柱、能力注册等 OS 式抽象。"""
+from .process_manager import ProcessManager, ProcessRecord
+from .spine import EventSpine, Event
+from .capabilities import CapabilityRegistry
+from .scheduler import Scheduler
+from .policy_gate import PolicyGate, Verdict
+
+__all__ = [
+    "ProcessManager", "ProcessRecord",
+    "EventSpine", "Event",
+    "CapabilityRegistry", "Scheduler",
+    "PolicyGate", "Verdict",
+]

package/python/foxclaw/kernel/capabilities.py

@@ -0,0 +1,72 @@
+"""
+CapabilityRegistry —— 能力注册中枢(P1-3:God Object → Composition Root)。
+
+审计结论:Foxclaw.__init__ 是个 God Object,子系统之间还形成两处对象环
+(Supervisor⇄Orchestrator、agents⇄search_runtime⇄agent_port⇄agents)——组件直接
+互相持有具体引用,违反 Clean Architecture。
+
+方案:引入单一注册中枢。组件不再直接持有"同伴组件"的具体引用,而是持有本注册表、
+按名字**惰性解析**(依赖倒置:依赖注册表抽象,而非具体同伴)。于是:
+  · 直接的"A→B 且 B→A"互持消失(两处直接环被打断);
+  · 解析统一走一个 hub(Composition Root 模式),构造顺序不再产生初始化环;
+  · 支持 register_lazy:重/可选能力(HKC、SearchRuntime)首次被解析时才构造。
+
+注:hub 与组件之间仍是可达环(注册表持有组件、组件持有注册表),这是 Service Locator
+的固有形态,由 GC 正常回收;本次要消除的是"具体同伴之间的直接互持",而非对象图可达性。
+"""
+from __future__ import annotations
+import threading
+from typing import Any, Callable
+
+
+class CapabilityRegistry:
+    """按名字注册/解析能力。支持惰性(首次解析才构造)。线程安全。"""
+
+    def __init__(self):
+        self._caps: dict[str, Any] = {}
+        self._lazy: dict[str, Callable[[], Any]] = {}
+        self._lock = threading.RLock()
+        self._build_locks: dict[str, threading.Lock] = {}
+
+    def register(self, name: str, handle: Any) -> None:
+        """注册一个已构造好的能力实例(覆盖同名)。"""
+        with self._lock:
+            self._caps[name] = handle
+
+    def register_lazy(self, name: str, factory: Callable[[], Any]) -> None:
+        """注册惰性能力:首次 get(name) 时调用 factory 构造并缓存。"""
+        with self._lock:
+            self._lazy[name] = factory
+
+    def get(self, name: str, default: Any | None = None) -> Any:
+        """解析能力。已注册直接返回;惰性则首次构造并缓存;都没有返回 default。
+
+        【F1 修复】慢惰性构造(如 search_runtime 首建要装 HKC+载模型)**不持全局锁**,
+        改用 per-name 构造锁:同一能力串行构造(只建一次、无双重构造),不同能力互不阻塞
+        (避免"首建 search 时,并发的 cross_request 解析 agents 被卡住")。factory 内部
+        可安全再 get 其它能力(全局锁此时未被本调用持有)。"""
+        with self._lock:
+            if name in self._caps:
+                return self._caps[name]
+            factory = self._lazy.get(name)
+            if factory is None:
+                return default
+            blk = self._build_locks.get(name)
+            if blk is None:
+                blk = self._build_locks[name] = threading.Lock()
+        with blk:
+            with self._lock:
+                if name in self._caps:
+                    return self._caps[name]
+            inst = factory()
+            with self._lock:
+                self._caps[name] = inst
+                return inst
+
+    def has(self, name: str) -> bool:
+        with self._lock:
+            return name in self._caps or name in self._lazy
+
+    def names(self) -> list[str]:
+        with self._lock:
+            return sorted(set(self._caps) | set(self._lazy))