foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/pipeline/supervisor_stages.py

@@ -16,11 +16,12 @@ hooks / 流式(run_task_stream)/ stop_event 中断 / 统一 `_emit_execution` /
 import asyncio
 from datetime import datetime
 
+from ..core.dispatch import dispatch_failed
 from .cognitive_pipeline import PipelineContext, stage_recall  # noqa: F401  (recall 复用默认 stage)
-from ..core.dispatch import dispatch_failed  # 谓词在 core:避免 pipeline 反向 import agents
+from .stage_meta import named_stage
 
 
-# ── Stage 2: meta_check —— 元问题判断(你是谁/能做什么 → 主管以总管身份自答,不分派)──
+@named_stage("meta_check")
 async def sv_meta_check(ctx: PipelineContext) -> None:
     agent = ctx.agent
     if not agent._is_meta(ctx.task):
@@ -30,7 +31,6 @@ async def sv_meta_check(ctx: PipelineContext) -> None:
         node_type="decision", conf=0.92,
     )
     subagents = getattr(agent, "_subagents", {})
-    # 拓扑 5 → 3:助手/行政已下放为指令技能,不再出现在团队介绍里。
     sub_names = {
         "finance": "财务 Agent(理财、收支、预算、风控)",
         "office": "办公学习 Agent(学习、知识管理、研究、写作、日程与行程)",
@@ -57,11 +57,10 @@ async def sv_meta_check(ctx: PipelineContext) -> None:
     )
     ctx.result = {"dispatched_to": "supervisor", "sub_result": reply,
                   "self_answered": True}
-    ctx.extra["_meta_answered"] = True      # 短路标记:后续 stage 跳过(aggregate 清除)
-sv_meta_check.stage_name = "meta_check"
+    ctx.extra["_meta_answered"] = True
 
 
-# ── Stage 3: schedule —— 认知调度(优先级/负载/抢占)────────────────
+@named_stage("schedule")
 async def sv_schedule(ctx: PipelineContext) -> None:
     if ctx.extra.get("_meta_answered"):
         return
@@ -73,10 +72,9 @@ async def sv_schedule(ctx: PipelineContext) -> None:
                  + (f" · 抢占({ctx.sched.preemption_reason})" if ctx.sched.preemptible else "")),
         node_type="decision", conf=0.9,
     )
-sv_schedule.stage_name = "schedule"
 
 
-# ── Stage 4: route —— 路由决策(关键词+调度意图;未命中且模型可用 → 决策主管自答)──
+@named_stage("route")
 async def sv_route(ctx: PipelineContext) -> None:
     if ctx.extra.get("_meta_answered"):
         return
@@ -84,11 +82,6 @@ async def sv_route(ctx: PipelineContext) -> None:
     target = agent._route(ctx.task, ctx.sched)
     ctx.target = target
     ctx.route = {"target": target, "reason": "主管关键词+调度意图分诊"}
-    # 无关键词命中 = 正面对话/泛化问题 → 主管**直接自答一次**,省掉"LLM 分诊 + 派发"的
-    # 第二次串行 LLM 调用(每次约 5s 网络往返,正面对话不值当)。只有命中领域关键词
-    # (财务/行政/办公/…)才派发给对应子 Agent。stub 下保持原路径(零额外调用、离线测试确定)。
-    # 权衡:少数本该派给领域 Agent 的"无关键词"任务会由主管自答——用户明确选速度优先。
-    # (本 stage 只做**决策**置标记;自答的 LLM 调用在 dispatch stage 执行。)
     if not agent._has_keyword_hit(ctx.task) and not agent.router.is_stub:
         agent._think(
             content="无关键词命中 → 主管直接自答(省掉二次分诊派发,正面对话提速)",
@@ -100,16 +93,13 @@ async def sv_route(ctx: PipelineContext) -> None:
         node_type="decision",
         conf=0.9,
     )
-sv_route.stage_name = "route"
 
 
-# ── Stage 5: plan —— planner 拆解(多步?跨 Agent?)────────────────
+@named_stage("plan")
 async def sv_plan(ctx: PipelineContext) -> None:
     if ctx.extra.get("_meta_answered") or ctx.extra.get("_self_answer"):
         return
     agent = ctx.agent
-    # P0-1:LLM 规划含同步网络调用(call_tools),放线程池避免阻塞事件循环;
-    # 规则拆解路径是纯 CPU,放线程池开销可忽略、行为不变。
     plan_obj, step_routes = await asyncio.to_thread(agent._plan_task, ctx.task, ctx.sched)
     if plan_obj is not None:
         routes_desc = " → ".join(f"{name}[{ag}]" for name, ag in step_routes)
@@ -117,23 +107,20 @@ async def sv_plan(ctx: PipelineContext) -> None:
             content=f"planner 判定为多步任务({len(plan_obj.tasks)}步):{routes_desc}",
             node_type="decision", conf=0.85,
         )
-        # 若子任务跨不同 Agent,标记为多 Agent 顺序执行
         distinct_agents = {ag for _, ag in step_routes}
         ctx.multi_agent = len(distinct_agents) > 1
     else:
         ctx.multi_agent = False
     ctx.plan_obj = plan_obj
     ctx.step_routes = step_routes or []
-sv_plan.stage_name = "plan"
 
 
-# ── Stage 6: dispatch —— 分发执行(自答 / 多 Agent / 单 Agent / 兜底)──
+@named_stage("dispatch")
 async def sv_dispatch(ctx: PipelineContext) -> None:
     agent = ctx.agent
     if ctx.extra.get("_meta_answered"):
         return
 
-    # 主管自答(route stage 的决策在此执行)
     if ctx.extra.get("_self_answer"):
         _msgs = [{"role": "user", "content": (
             f"你是 Foxclaw 的主管 Agent(Supervisor),统筹整个智能体团队。"
@@ -141,9 +128,6 @@ async def sv_dispatch(ctx: PipelineContext) -> None:
             f"问题作答,不要只做自我介绍、不要答非所问。若确属需要专门领域深办的任务,可"
             f"简要引导用户去对应能力,但仍先给出有用的直接回应。"
         )}]
-        # 联网增强:新闻/实时类(_web_augment 内 needs_search 命中)走百度搜索注入真实结果
-        # 再作答,避免主管凭空编造(系统 prompt 明令严禁模拟搜索)。纯闲聊 needs_search=False,
-        # 不搜、不减速。阻塞 I/O 放线程池(与 base._execute 同法),不堵 async 事件循环。
         _msgs = await asyncio.to_thread(agent._web_augment, ctx.task, _msgs)
         reply = await agent._call_llm(_msgs)
         agent._store_memory(
@@ -157,7 +141,6 @@ async def sv_dispatch(ctx: PipelineContext) -> None:
 
     subagents = getattr(agent, "_subagents", {})
 
-    # 多 Agent 执行:并行计划(无依赖)→ fork-join 并发;否则顺序执行后汇聚
     if ctx.multi_agent and ctx.step_routes:
         if getattr(ctx.plan_obj, "flow_type", "sequential") == "parallel":
             agent._think(
@@ -173,58 +156,46 @@ async def sv_dispatch(ctx: PipelineContext) -> None:
                 subagents, ctx.context, ctx.memories)
         return
 
-    # 单 Agent 分发
     if ctx.target in subagents:
         ctx.dispatch_result = await agent._dispatch_single(
             ctx.task, ctx.target, ctx.sched, ctx.session_id,
             subagents, ctx.context, ctx.memories, ctx.plan_obj)
         return
 
-    # 子 Agent 不可用(未注册)→ 主管自处理
     ctx.dispatch_result = await agent._dispatch_fallback(ctx.task, ctx.context)
-sv_dispatch.stage_name = "dispatch"
 
 
-# ── Stage 6.5: replan —— 反思重规划(P0-1:失败步骤 → LLM 反思 → 修正计划 → 重执行)──
+@named_stage("replan")
 async def sv_replan(ctx: PipelineContext) -> None:
     if ctx.extra.get("_meta_answered") or ctx.extra.get("_self_answer"):
         return
     agent = ctx.agent
     dr = ctx.dispatch_result or {}
     if not dispatch_failed(dr):
-        return                      # 无失败/未完成步骤 → 无需重规划
+        return
     if not agent._replan_enabled():
-        return                      # opt-in 关 / 不支持 tools → 保留原结果(fail-safe)
+        return
     subagents = getattr(agent, "_subagents", {})
     max_rounds = int((ctx.context or {}).get("replan_max_rounds", 2))
     ctx.dispatch_result = await agent._replan_and_redo(
         ctx.task, ctx.sched, ctx.session_id, subagents, ctx.context, ctx.memories,
         dr, max_rounds=max_rounds)
-sv_replan.stage_name = "replan"
 
 
-# ── Stage 7: aggregate —— 结果组装(dispatch_result → ctx.result/extra)──
+@named_stage("aggregate")
 async def sv_aggregate(ctx: PipelineContext) -> None:
-    # 清除内部短路标记,不外泄到返回体(它们会经 **ctx.extra 透传进 resp)
     ctx.extra.pop("_meta_answered", None)
     ctx.extra.pop("_self_answer", None)
     dr = ctx.dispatch_result or {}
     if not dr:
-        return                      # meta 路径:result 已在 meta_check 设好
+        return
     ctx.result = dr.get("result", ctx.result)
-    # 白名单透传(与原主管返回体逐字一致的顶层键);session_id/agent/thought_summary
-    # 由 base 模板统一组装,不从 dispatch_result 取。
     for k in ("schedule", "plan", "process_id"):
         if k in dr:
             ctx.extra[k] = dr[k]
-    # 「未完成 ⇒ 不作为已完成真值沉淀」:任一子任务被 Harness 拦截 → 提升为顶层
-    # status=blocked(与 base 模板的 skill_status 提升同一机制),执行事件 blocked=True,
-    # 真值链不沉淀(呼应 P3-5)。成功/自答路径不带此键,行为逐字不变。
     if isinstance(ctx.result, dict) and ctx.result.get("blocked"):
         ctx.extra["skill_status"] = "blocked"
-sv_aggregate.stage_name = "aggregate"
 
 
-# 主管 pipeline 的 stage 序列(recall 复用默认实现:与旧 `self._recall_memory(task)` 逐字等价)
 SUPERVISOR_STAGES = [stage_recall, sv_meta_check, sv_schedule, sv_route,
                      sv_plan, sv_dispatch, sv_replan, sv_aggregate]

package/python/foxclaw/planning/llm_planner.py

@@ -152,9 +152,9 @@ def _invoke_plan_tool(router, system: str, user_content: str, agent_catalog: dic
         return None
     calls = res.get("tool_calls") or []
     if not calls:
-        return None                      # 模型未调用工具 → 不可用，回退
+        return None
     if calls[0].get("args_parse_failed"):
-        return None                      # 参数 JSON 解析失败 → 不可信，回退
+        return None
     args = calls[0].get("args") or {}
     steps = args.get("steps")
     if not isinstance(steps, list):
@@ -168,7 +168,7 @@ def _invoke_plan_tool(router, system: str, user_content: str, agent_catalog: dic
             continue
         agent = str(s.get("agent") or "office").strip()
         if agent not in agent_catalog:
-            agent = "office"             # 幻觉出不存在的 Agent(含已下放的 assistant/admin)→ 兜底办公学习
+            agent = "office"
         dep = s.get("depends_on") or []
         if not isinstance(dep, list):
             dep = []

package/python/foxclaw/planning/planner.py

@@ -11,14 +11,11 @@
 from __future__ import annotations
 import re
 from dataclasses import dataclass, field
+from typing import Optional
 
-# ── 单一真源:否定词 + 顺序/并行/列表 标记 ──────────────────────
 NEGATIONS = ["不", "别", "无需", "不要", "取消", "甭", "don't", "no need", "without"]
-# 顺序拆分信号(明确的顺序连接词;不用"和/并"等高风险常用字,避免误拆名词短语)
 SPLIT_MARKERS = ["然后", "接着", "之后", "再", "最后", "；", ";"]
-# 并行信号:出现这些"同时性"连接词 → 子任务彼此无依赖,可并行 fork
 PARALLEL_TRIGGERS = ["同时", "分别", "并行", "一并"]
-# 列表分隔符(仅在检出并行触发词时才当拆分点,避免误拆普通名词短语)
 LIST_SEPS = ["、", "，", ",", "；", ";"]
 
 
@@ -55,15 +52,15 @@ class ScoredCandidate:
 
 @dataclass
 class TriggerRoute:
-    primary: str = None
+    primary: Optional[str] = None
     confidence: float = 0.0
-    candidates: list = field(default_factory=list)   # [(id, score)]
-    fallback: str = None
+    candidates: list = field(default_factory=list)
+    fallback: Optional[str] = None
     needs_composition: bool = False
     reason: str = ""
 
 
-def trigger_route(task: str, candidates: list, fallback_id: str = None,
+def trigger_route(task: str, candidates: list, fallback_id: str | None = None,
                   min_conf: float = 0.15, near_gap: float = 0.1) -> TriggerRoute:
     """触发词路由三步打分:否定过滤后的触发命中(0.8)+ 描述领域匹配(0.2),确定性排序。
     这是 AHS 原 route 的算法,现作为三处共用的通用引擎。"""
@@ -75,17 +72,15 @@ def trigger_route(task: str, candidates: list, fallback_id: str = None,
         triggers = c.triggers or []
         if not triggers:
             scored.append((c.id, 0.0)); continue
-        # 第1步:否定过滤后的触发命中数 → 命中即给强基础分,不被触发词总数稀释
         hits = keyword_hits(task, triggers, negation=True)
         hit_score = 0.0 if hits == 0 else min(0.6 + 0.15 * (hits - 1), 1.0)
-        # 第2步:领域匹配(描述里的词出现在任务中,粗略语义近似)
         desc_words = [w for w in re.split(r"[\s,，、]", c.description or "") if len(w) >= 2]
         domain_hit = sum(1 for w in desc_words if w in task)
         domain_score = min(domain_hit / max(len(desc_words), 1), 1.0)
         score = 0.8 * hit_score + 0.2 * domain_score
         scored.append((c.id, round(score, 3)))
 
-    scored.sort(key=lambda x: (-x[1], x[0]))   # 分降序,平局按 id 字典序(确定性)
+    scored.sort(key=lambda x: (-x[1], x[0]))
     top_id, top_score = scored[0]
     cands = [(i, s) for i, s in scored if s > 0]
 

package/python/foxclaw/search/agent_port.py

@@ -29,7 +29,7 @@ def _score(query: str, text: str) -> int:
     for term in re.split(r"[\s,，、;；:：/]+", q):
         if len(term) >= 2 and term in t:
             score += 2
-    for i in range(len(q) - 1):          # 中文/无分隔场景的 2-gram 重叠
+    for i in range(len(q) - 1):
         if q[i:i + 2] in t:
             score += 1
     return score
@@ -65,13 +65,12 @@ class AgentSourcePort:
             try:
                 scored += gather(text, top_k)
             except Exception:
-                continue  # 单一子源失败不影响其它子源
+                continue
         scored.sort(key=lambda x: x[0], reverse=True)
         return [ev for _, ev in scored[:max(top_k * 2, top_k)]]
 
-    # ── 1. 领域内核 ──────────────────────────────────────────
     def _from_finance(self, text, top_k):
-        out = []
+        out: list[tuple[float, RawEvidence]] = []
         rt = self.finance
         if rt is None:
             return out
@@ -101,7 +100,7 @@ class AgentSourcePort:
         return out
 
     def _from_learning(self, text, top_k):
-        out = []
+        out: list[tuple[float, RawEvidence]] = []
         rt = self.learning
         if rt is None:
             return out
@@ -116,7 +115,7 @@ class AgentSourcePort:
         return out
 
     def _from_itinerary(self, text, top_k):
-        out = []
+        out: list[tuple[float, RawEvidence]] = []
         rt = self.itinerary
         if rt is None:
             return out
@@ -130,9 +129,8 @@ class AgentSourcePort:
                             confidence=_conf(s))))
         return out
 
-    # ── 2. ThoughtChain 推理链 ───────────────────────────────
     def _from_thoughtchain(self, text, top_k):
-        out = []
+        out: list[tuple[float, RawEvidence]] = []
         tc = self.thought_chain
         if tc is None or not hasattr(tc, "search_nodes"):
             return out
@@ -145,9 +143,8 @@ class AgentSourcePort:
                 confidence=_conf(max(s, 1)))))
         return out
 
-    # ── 3. 各 Agent 的 HMR 记忆 ─────────────────────────────
     def _from_memories(self, text, top_k):
-        out = []
+        out: list[tuple[float, RawEvidence]] = []
         if self.hmr is None:
             return out
         for aid in (self.agents.keys() if self.agents else []):
@@ -167,7 +164,6 @@ class AgentSourcePort:
                     confidence=_conf(s))))
         return out
 
-    # ── 4. 能力/状态目录 ─────────────────────────────────────
     def _from_capabilities(self, text, top_k):
         out = []
         reg = self.skill_registry

package/python/foxclaw/search/evidence.py

@@ -24,7 +24,6 @@ from .models import RawEvidence, EvidenceGraph, EvidenceNode, EvidenceEdge
 _SIMILARITY_SUPPORT = 0.6
 _SIMILARITY_DUP = 0.92
 
-# 否定词:ASCII 按词边界(防 not⊂another/notebook、no⊂know);中文按子串(中文无词边界)
 _NEG_ASCII = ("not", "no longer", "never", "cannot", "isn't", "aren't", "won't")
 _NEG_CJK = ("不是", "并非", "并不", "没有", "无法", "不会", "未能")
 _NEG_ASCII_RE = re.compile(
@@ -37,9 +36,6 @@ def _has_neg(text: str) -> bool:
 
 
 def _sem_model_name() -> str:
-    # 【P2·单 embedding 入口】解析链:与 harness.py 一致 ——
-    # 显式传参 > EMBEDDING_MODEL(单入口) > HKC_EMBEDDING_MODEL > FOXCLAW_EVIDENCE_MODEL > HKC_KEE_SEMANTIC_MODEL > MiniLM 兜底。
-    # 与 KEE 默认同名 → get_st_model 共享同一实例;可经环境变量换任意 ST 模型(模型无关)
     return (os.environ.get("FOXCLAW_EVIDENCE_MODEL")
             or os.environ.get("EMBEDDING_MODEL")
             or os.environ.get("HKC_EMBEDDING_MODEL")

package/python/foxclaw/search/internal_search.py

@@ -23,9 +23,9 @@ _UNGROUNDED_PENALTY = 0.15
 
 class InternalSearchEngine:
     def __init__(self, memory_port=None, knowledge_port=None, agent_port=None):
-        self.memory_port = memory_port      # 只读查询 HMR：query(text, top_k) -> list[RawEvidence]
-        self.knowledge_port = knowledge_port  # HKC 只读查询接口(同进程 DirectClient)
-        self.agent_port = agent_port        # Agent 源:领域内核 + 推理链 + 各Agent记忆 + 能力/状态
+        self.memory_port = memory_port
+        self.knowledge_port = knowledge_port
+        self.agent_port = agent_port
 
     @staticmethod
     def _safe_query(port, text: str, top_k: int) -> list[RawEvidence]:
@@ -46,8 +46,6 @@ class InternalSearchEngine:
             memory_hits = self._safe_query(self.memory_port, text, top_k)
             agent_hits = self._safe_query(self.agent_port, text, top_k)
 
-        # 知识候选用「内部一切可溯源证据」(记忆 + Agent 态势)交叉验证:找得到就 grounded,
-        # 找不到就做孤证惩罚。这样 HKC 权威知识与 Agent 实际持有的数据互为印证。
         if knowledge_hits:
             knowledge_hits = self._cross_link(knowledge_hits, memory_hits + agent_hits)
 

package/python/foxclaw/search/models.py

@@ -12,17 +12,16 @@ from typing import Any, Optional
 
 
 class RouteType(str, Enum):
-    INTERNAL = "HSR-I"   # 查内部（HMR 记忆 / 未来的 HKC 知识）
-    EXTERNAL = "HSR-E"   # 查外部世界（联网搜索）
-    HYBRID = "HYBRID"    # 内外混合 + 交叉验证
+    INTERNAL = "HSR-I"
+    EXTERNAL = "HSR-E"
+    HYBRID = "HYBRID"
 
 
 class SourceType(str, Enum):
-    MEMORY = "memory"        # 来自 HMR（只读查询）
-    KNOWLEDGE = "knowledge"  # 来自 HKC（通过 foxclaw-hkc 的 hkc_sdk 只读查询）
-    AGENT = "agent"          # 来自五个 Agent 持有的内部数据:领域内核(财务/学习/行程)
-                             # + ThoughtChain 推理链 + 各 Agent HMR 记忆 + 能力/状态目录
-    WEB = "web"              # 来自联网搜索（当前接的是百度 AI 搜索）
+    MEMORY = "memory"
+    KNOWLEDGE = "knowledge"
+    AGENT = "agent"
+    WEB = "web"
 
 
 @dataclass
@@ -45,11 +44,10 @@ class RawEvidence:
     id: str
     fact: str
     source: SourceType
-    origin: str              # 具体来源：hmr 记忆 id / 网页 url
+    origin: str
     confidence: float = 0.5
     raw: Any = None
-    grounded_by: Optional[str] = None  # 指向另一条证据的 id：
-                                        # "这条知识由这条 HMR 记忆溯源支撑"
+    grounded_by: Optional[str] = None
 
 
 @dataclass
@@ -66,7 +64,7 @@ class EvidenceNode:
 class EvidenceEdge:
     src: str
     dst: str
-    relation: str  # "supports" | "contradicts" | "grounded_by"
+    relation: str
 
 
 @dataclass
@@ -103,7 +101,7 @@ class EvidenceGraph:
 
 @dataclass
 class StrategyDecision:
-    action: str  # "continue" | "stop" | "switch_query" | "switch_source"
+    action: str
     reason: str
     next_steps: list[SubQuery] = field(default_factory=list)
 

package/python/foxclaw/search/planner.py

@@ -7,7 +7,7 @@ Query Planner —— 决定路由(HSR-I / HSR-E / HYBRID)，并把任务拆成
 """
 from __future__ import annotations
 from .models import SearchPlan, SubQuery, RouteType
-from ..planning import planner as P   # 统一拆分原语(P1-2)
+from ..planning import planner as P
 
 _MEMORY_HINTS = ("我之前", "我们讨论过", "上次", "记得", "history", "之前说")
 _HYBRID_HINTS = ("为什么", "对比", "分析", "综合", "评估")
@@ -28,7 +28,7 @@ class QueryPlanner:
             steps = [SubQuery(id="s1", text=query)]
         elif route == RouteType.EXTERNAL:
             steps = self._decompose(query)
-        else:  # HYBRID：先查内部，再拆外部子问题
+        else:
             steps = [SubQuery(id="s1", text=query), *self._decompose(query, offset=2)]
 
         return SearchPlan(
@@ -38,7 +38,7 @@ class QueryPlanner:
         )
 
     def _decompose(self, query: str, offset: int = 1) -> list[SubQuery]:
-        parts = P.split_on(query, P.LIST_SEPS)   # 统一拆分原语(等价于原 [,，、；;])
+        parts = P.split_on(query, P.LIST_SEPS)
         if len(parts) <= 1:
             parts = [query]
         return [SubQuery(id=f"s{offset + i}", text=p) for i, p in enumerate(parts)]

package/python/foxclaw/search/retriever.py

@@ -35,5 +35,5 @@ class Retriever:
             try:
                 out += port.search(step.text)
             except Exception:
-                continue  # 单个外部数据源失败不影响其它数据源/主流程
+                continue
         return out

package/python/foxclaw/search/runtime.py

@@ -69,22 +69,16 @@ class SearchRuntime:
     def __init__(self, hmr=None, knowledge_port=None, agent_port=None,
                  external_ports: list | None = None):
         self.hmr = hmr
-        # knowledge_port 由 foxclaw/__init__.py 在启动时构造好传进来
-        # (进程内直连的 HKCReadPort)。这里不做任何自动连接/默认值——
-        # 连不连 HKC、怎么连，是 Foxclaw 启动流程的事，不是 SearchRuntime 的事。
         self.knowledge_port = knowledge_port
-        # agent_port:内部搜索的「Agent」源(领域内核 + 推理链 + 各Agent记忆 + 能力/状态),
-        # 同样由 Foxclaw 启动时用各持有方引用构造好传进来。
         self.agent_port = agent_port
         self.planner = QueryPlanner()
         self.fusion = EvidenceFusion()
         self.strategy = SearchStrategy()
-        # 外部端口(联网)面向 AI/Agent:是证据/工具管线的一环,不是给人的搜索框。
         self.external_ports = (
             external_ports if external_ports is not None else [BaiduWebSearchPort()]
         )
 
-    def search(self, query: str, agent_id: str = None, context: dict = None,
+    def search(self, query: str, agent_id: str | None = None, context: dict | None = None,
                internal_only: bool = False) -> SearchResult:
         """唯一公开入口。给定 query，返回 SearchResult，过程中不写任何持久化状态。
 
@@ -101,7 +95,6 @@ class SearchRuntime:
         trace: list[str] = []
         plan = self.planner.plan(query, context)
         if internal_only and plan.route == RouteType.EXTERNAL:
-            # 只查内部时,把纯外部路由拉回内部,保证内部三源(记忆/知识/Agent)被检索
             plan.route = RouteType.INTERNAL
             trace.append("[internal_only] 路由改写为 HSR-I(仅内部)")
         trace.append(f"[plan] {plan.reasoning}")