foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/search/agent_port.py

@@ -0,0 +1,194 @@
+"""
+AgentSourcePort —— 内部搜索的「Agent」源。
+
+把五个 Agent 持有的**全部内部数据**连通进 HSR 的内部检索，四类子源:
+  1. 领域内核结构化数据:财务(交易/预算/实体) + 学习(知识条目) + 行程(行程点)
+  2. ThoughtChain 推理链:各 Agent 想过/判过什么(按内容关键词检索)
+  3. 各 Agent 的 HMR 记忆:逐 agent_id 召回(区别于共享 memory_port 的当前-agent 召回)
+  4. 能力/状态目录:skill 目录 + 各 Agent 角色/状态("哪个 Agent 能做这事")
+
+设计边界(与 HSR 一致):
+  · 只读——绝不写回任何持有方状态。
+  · 解耦——只依赖各持有方稳定的公开读接口 + 领域对象文本化,不侵入其内部逻辑。
+  · 降级——任一子源缺失/报错都 try/except 跳过,不影响其它子源与主流程。
+  · 只依赖显式传入的引用(不 import Foxclaw),保持 search 内核与本体的低耦合。
+"""
+from __future__ import annotations
+import re
+from .models import RawEvidence, SourceType
+
+
+def _score(query: str, text: str) -> int:
+    """轻量关键词打分:词级(空格/标点分隔,len>=2 子串命中)+ 中文 2-gram 重叠。
+    纯确定性、可解释,不引入模型——语义匹配由 HKC/HMR 端负责,这里是结构化态势查找。"""
+    q = (query or "").strip()
+    t = text or ""
+    if not q or not t:
+        return 0
+    score = 0
+    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 重叠
+        if q[i:i + 2] in t:
+            score += 1
+    return score
+
+
+def _conf(score: int) -> float:
+    return round(min(0.7, 0.4 + 0.04 * score), 3)
+
+
+class AgentSourcePort:
+    """内部搜索的 Agent 源。query(text, top_k) -> list[RawEvidence(source=AGENT)]。"""
+
+    def __init__(self, agents=None, finance_runtime=None, learning_runtime=None,
+                 itinerary_runtime=None, thought_chain=None, skill_registry=None,
+                 hmr=None):
+        self.agents = agents or {}
+        self.finance = finance_runtime
+        self.learning = learning_runtime
+        self.itinerary = itinerary_runtime
+        self.thought_chain = thought_chain
+        self.skill_registry = skill_registry
+        self.hmr = hmr
+
+    @property
+    def available(self) -> bool:
+        return any([self.agents, self.finance, self.learning, self.itinerary,
+                    self.thought_chain, self.skill_registry, self.hmr])
+
+    def query(self, text: str, top_k: int = 5) -> list[RawEvidence]:
+        scored: list[tuple[int, RawEvidence]] = []
+        for gather in (self._from_finance, self._from_learning, self._from_itinerary,
+                       self._from_thoughtchain, self._from_memories, self._from_capabilities):
+            try:
+                scored += gather(text, top_k)
+            except Exception:
+                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 = []
+        rt = self.finance
+        if rt is None:
+            return out
+        for i, txn in enumerate(getattr(rt, "transactions", []) or []):
+            desc = f"交易 {getattr(txn,'entity','')} {getattr(txn,'amount','')} " \
+                   f"{getattr(txn,'category','')} {' '.join(getattr(txn,'tags',[]) or [])}"
+            s = _score(text, desc)
+            if s:
+                out.append((s, RawEvidence(id=f"agent:finance:txn:{i}", fact=desc.strip(),
+                            source=SourceType.AGENT, origin="agent:finance:transaction",
+                            confidence=_conf(s))))
+        for i, b in enumerate(getattr(rt, "budgets", []) or []):
+            desc = f"预算 {getattr(b,'category','')} 上限 {getattr(b,'monthly_limit','')}"
+            s = _score(text, desc)
+            if s:
+                out.append((s, RawEvidence(id=f"agent:finance:budget:{i}", fact=desc.strip(),
+                            source=SourceType.AGENT, origin="agent:finance:budget",
+                            confidence=_conf(s))))
+        for name, ent in (getattr(rt, "entities", {}) or {}).items():
+            desc = f"财务实体 {name} 累计 {getattr(ent,'total_amount','')} " \
+                   f"次数 {getattr(ent,'txn_count','')}"
+            s = _score(text, desc)
+            if s:
+                out.append((s, RawEvidence(id=f"agent:finance:entity:{name}", fact=desc.strip(),
+                            source=SourceType.AGENT, origin="agent:finance:entity",
+                            confidence=_conf(s))))
+        return out
+
+    def _from_learning(self, text, top_k):
+        out = []
+        rt = self.learning
+        if rt is None:
+            return out
+        for iid, item in (getattr(rt, "items", {}) or {}).items():
+            desc = f"知识 {getattr(item,'content','')} 主题 {getattr(item,'topic','')} " \
+                   f"{' '.join(getattr(item,'tags',[]) or [])}"
+            s = _score(text, desc)
+            if s:
+                out.append((s, RawEvidence(id=f"agent:learning:{iid}", fact=desc.strip(),
+                            source=SourceType.AGENT, origin=f"agent:learning:{iid}",
+                            confidence=_conf(s))))
+        return out
+
+    def _from_itinerary(self, text, top_k):
+        out = []
+        rt = self.itinerary
+        if rt is None:
+            return out
+        for i, wp in enumerate(getattr(rt, "waypoints", []) or []):
+            desc = f"行程点 {getattr(wp,'name','')} {getattr(wp,'address','')} " \
+                   f"{getattr(wp,'city','')} {getattr(wp,'start_time','') or ''}"
+            s = _score(text, desc)
+            if s:
+                out.append((s, RawEvidence(id=f"agent:itinerary:{i}", fact=desc.strip(),
+                            source=SourceType.AGENT, origin="agent:itinerary:waypoint",
+                            confidence=_conf(s))))
+        return out
+
+    # ── 2. ThoughtChain 推理链 ───────────────────────────────
+    def _from_thoughtchain(self, text, top_k):
+        out = []
+        tc = self.thought_chain
+        if tc is None or not hasattr(tc, "search_nodes"):
+            return out
+        for n in tc.search_nodes(text, limit=top_k * 2):
+            content = getattr(n, "content", "")
+            s = _score(text, content)
+            out.append((max(s, 1), RawEvidence(
+                id=f"agent:think:{getattr(n,'id','')}", fact=f"推理[{getattr(n,'agent_id','')}] {content}",
+                source=SourceType.AGENT, origin=f"agent:thoughtchain:{getattr(n,'agent_id','')}",
+                confidence=_conf(max(s, 1)))))
+        return out
+
+    # ── 3. 各 Agent 的 HMR 记忆 ─────────────────────────────
+    def _from_memories(self, text, top_k):
+        out = []
+        if self.hmr is None:
+            return out
+        for aid in (self.agents.keys() if self.agents else []):
+            try:
+                results = self.hmr.recall(query=text, agent_id=aid, top_k=top_k)
+            except Exception:
+                continue
+            for r in results or []:
+                content = r.get("content", "") or r.get("title", "")
+                if not content:
+                    continue
+                s = _score(text, content) or 1
+                out.append((s, RawEvidence(
+                    id=f"agent:mem:{aid}:{r.get('id','')}",
+                    fact=f"[{aid}记忆] {content}", source=SourceType.AGENT,
+                    origin=f"agent:{aid}:hmr:{r.get('id','')}",
+                    confidence=_conf(s))))
+        return out
+
+    # ── 4. 能力/状态目录 ─────────────────────────────────────
+    def _from_capabilities(self, text, top_k):
+        out = []
+        reg = self.skill_registry
+        if reg is not None and hasattr(reg, "catalog"):
+            for sk in reg.catalog():
+                desc = f"技能 {sk.get('name','')} 触发 {','.join(sk.get('triggers',[]) or [])} " \
+                       f"{sk.get('kind','')}/{sk.get('side_effect','')}"
+                s = _score(text, desc)
+                if s:
+                    out.append((s, RawEvidence(id=f"agent:skill:{sk.get('name','')}",
+                                fact=desc.strip(), source=SourceType.AGENT,
+                                origin="agent:capability:skill", confidence=_conf(s))))
+        for aid, agent in (self.agents or {}).items():
+            try:
+                st = agent.get_status()
+            except Exception:
+                st = {}
+            desc = f"Agent {aid} 角色 {st.get('role', st.get('name',''))} 状态 {st.get('status','')}"
+            s = _score(text, desc)
+            if s:
+                out.append((s, RawEvidence(id=f"agent:status:{aid}", fact=desc.strip(),
+                            source=SourceType.AGENT, origin=f"agent:{aid}:status",
+                            confidence=_conf(s))))
+        return out

package/python/foxclaw/search/evidence.py

@@ -0,0 +1,113 @@
+"""
+Evidence Fusion —— 把离散、可能重复/冲突的原始证据，
+构建成一张有 support/contradict/grounded_by 关系的证据图，并算出整体置信度。
+
+相似度/矛盾判断已**语义化**(2026-07-16),与 KEE 冲突检测同款、共用同一份 ST 模型与向量缓存:
+  · 相似度:sentence-transformers 余弦;无 ST/模型未缓存 → 回退 SequenceMatcher(降级不崩)
+  · 矛盾:否定词方向 —— ASCII 按**词边界**、中文按子串
+对外接口(build / confidence)保持不变。
+
+修掉的两个真问题(原为"规则占位"):
+  ① 否定词子串误命中:原 ("不是","并非","no longer","not") 是子串匹配 →
+     "another"/"notebook" 里的 "not" 被命中 → 无关证据被判**矛盾** → 而 confidence()
+     按矛盾数扣分(0.1/条)→ 搜索置信被**幻影矛盾**无端拉低。
+     (与 hkc_kee/kee.py 早已修过的 not⊂nothing / no⊂know 是同一 bug 家族,此处漏同步。)
+  ② 字符级相似度非语义:「机器学习很有用」vs「ML 非常有价值」=0.13、
+     「今天下雨」vs「今日降雨」=0.50(<0.6)→ 语义等价的证据**识别不出互相支持**。
+"""
+from __future__ import annotations
+import os
+import re
+from difflib import SequenceMatcher
+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(
+    r"\b(" + "|".join(re.escape(n) for n in sorted(_NEG_ASCII, key=len, reverse=True)) + r")\b")
+
+
+def _has_neg(text: str) -> bool:
+    t = (text or "").lower()
+    return bool(_NEG_ASCII_RE.search(t)) or any(n in t for n in _NEG_CJK)
+
+
+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")
+            or os.environ.get("HKC_KEE_SEMANTIC_MODEL")
+            or "paraphrase-multilingual-MiniLM-L12-v2")
+
+
+def _semantic_sim(a: str, b: str):
+    """ST 余弦 ∈ [0,1](负相关截到 0)。取不到模型 → None(调用方回退字符级)。
+    走 HKC 共享向量缓存 → 同文本全局只编码一次(与检索/KEE/去重同一份)。"""
+    try:
+        from hkc_search.embedding_backends import get_st_model, encode_cached
+        name = _sem_model_name()
+        model = get_st_model(name)
+        if model is None:
+            return None
+        import numpy as np
+        va, vb = encode_cached(model, name, [a or "", b or ""])
+        return max(0.0, min(1.0, float(np.dot(va, vb))))
+    except Exception:
+        return None
+
+
+class EvidenceFusion:
+    def build(self, raw_list: list[RawEvidence]) -> EvidenceGraph:
+        graph = EvidenceGraph()
+
+        for e in self._dedup(raw_list):
+            graph.add_node(EvidenceNode(
+                id=e.id, fact=e.fact, source=e.source,
+                origin=e.origin, confidence=e.confidence,
+                grounded_by=e.grounded_by,
+            ))
+
+        nodes = list(graph.nodes.values())
+        for i, a in enumerate(nodes):
+            for b in nodes[i + 1:]:
+                sim = self._similarity(a.fact, b.fact)
+                if sim >= _SIMILARITY_SUPPORT:
+                    graph.add_edge(EvidenceEdge(a.id, b.id, "supports"))
+                elif self._contradicts(a.fact, b.fact):
+                    graph.add_edge(EvidenceEdge(a.id, b.id, "contradicts"))
+
+        for node in nodes:
+            if node.grounded_by and node.grounded_by in graph.nodes:
+                graph.add_edge(EvidenceEdge(node.id, node.grounded_by, "grounded_by"))
+
+        return graph
+
+    def confidence(self, graph: EvidenceGraph) -> float:
+        if not graph.nodes:
+            return 0.0
+        base = sum(n.confidence for n in graph.nodes.values()) / len(graph.nodes)
+        penalty = 0.1 * len(graph.contradictions())
+        return max(0.0, min(1.0, base - penalty))
+
+    def _dedup(self, raw_list: list[RawEvidence]) -> list[RawEvidence]:
+        kept: list[RawEvidence] = []
+        for e in raw_list:
+            if not any(self._similarity(e.fact, k.fact) >= _SIMILARITY_DUP for k in kept):
+                kept.append(e)
+        return kept
+
+    def _similarity(self, a: str, b: str) -> float:
+        """语义余弦优先;无 ST/加载失败 → 回退字符级 SequenceMatcher(降级不崩)。"""
+        v = _semantic_sim(a, b)
+        return v if v is not None else SequenceMatcher(None, a, b).ratio()
+
+    def _contradicts(self, a: str, b: str) -> bool:
+        """主题相近但**否定方向相反** → 矛盾。否定词按词边界判,不再被 another/notebook 误命中。"""
+        return _has_neg(a) != _has_neg(b) and self._similarity(a, b) >= 0.4

package/python/foxclaw/search/external_search.py

@@ -0,0 +1,50 @@
+"""
+BaiduWebSearchPort —— 把已有的 foxclaw.core.web_search（百度 AI 搜索）
+包装成 HSR 的外部检索端口(ExternalSearchPort)，接入 Retriever。
+
+没有另起一套联网搜索实现：Foxclaw 已经在用百度 AI 搜索
+(foxclaw/core/web_search.py，Agent 的 `_web_augment` 也在用它)，
+这里只是把它的返回结果(answer + references)转成 RawEvidence，
+让 HSR 的证据融合/策略循环可以复用它，而不是绕开它另建一套。
+
+未配置 BAIDU_SEARCH_KEY 或网络不通时，底层 web_search.search_answer()
+本身就会静默返回空 dict，这里顺势返回空列表，不影响 HSR 主流程。
+"""
+from __future__ import annotations
+from ..core import web_search as _ws
+from .models import RawEvidence, SourceType
+
+
+class BaiduWebSearchPort:
+    name = "baidu_web_search"
+
+    def search(self, text: str, top_k: int = 5) -> list[RawEvidence]:
+        payload = _ws.search_answer(text)
+        if not payload:
+            return []
+
+        out: list[RawEvidence] = []
+
+        answer = payload.get("answer", "")
+        if answer:
+            out.append(RawEvidence(
+                id="baidu:answer",
+                fact=answer,
+                source=SourceType.WEB,
+                origin="baidu_ai_search",
+                confidence=0.65,
+            ))
+
+        for i, ref in enumerate(payload.get("references", [])[:top_k]):
+            snippet = ref.get("content", "") or ref.get("abstract", "")
+            if not snippet:
+                continue
+            out.append(RawEvidence(
+                id=f"baidu:ref:{i}",
+                fact=snippet,
+                source=SourceType.WEB,
+                origin=ref.get("url", "") or ref.get("web_anchor", ""),
+                confidence=0.55,
+            ))
+
+        return out

package/python/foxclaw/search/hkc_read_port.py

@@ -0,0 +1,60 @@
+"""
+HKCReadPort —— 把 foxclaw-hkc 的检索能力接入 HSR 的 knowledge_port。
+
+融合之后:HKC 是 Foxclaw 内部的一个模块，不是外挂的独立系统。
+Foxclaw 启动时会在同一个 Python 进程里直接装配 HKCContainer
+(`foxclaw/__init__.py` 里的 `_init_hkc()`)，这里只是拿 hkc_sdk 的
+DirectClient 包一层，调用的是同进程里的对象方法，不发 HTTP 请求、
+不需要单独起服务、不存在"服务没启动"这种降级场景。
+
+这一层只暴露 query()，没有 ingest_text()——写不写知识回 HKC
+不是 HSR 的职责范围，那是 foxclaw-hkc 自己的 KDE/KEE 摄入管线，
+或者未来 Runtime 层的决定。
+
+如果确实需要把 foxclaw-hkc 单独部署成另一个服务(比如给其它系统复用)，
+client 换成 hkc_sdk.connect(base_url=...) 返回的 HTTPClient 依然能用——
+DirectClient/HTTPClient 方法签名完全一致，这里的代码不用改一行。
+"""
+from __future__ import annotations
+import logging
+
+from .models import RawEvidence, SourceType
+
+logger = logging.getLogger(__name__)
+
+
+class HKCReadPort:
+    """只读查询 foxclaw-hkc。需要一个已经连好的 hkc_sdk 客户端
+    (DirectClient 或 HTTPClient，两者接口一致)；没有就永远返回空列表，
+    不影响 HSR 主流程——和整个项目的降级哲学一致(没配就跳过，不报错)。"""
+
+    def __init__(self, client=None):
+        self._client = client
+
+    @property
+    def available(self) -> bool:
+        return self._client is not None
+
+    def query(self, text: str, top_k: int = 5) -> list[RawEvidence]:
+        if self._client is None:
+            return []
+
+        try:
+            hits = self._client.search(text, mode="hybrid", top_k=top_k)
+        except Exception as e:
+            logger.info(f"[HKC] 搜索「{text}」失败({e})")
+            return []
+
+        out: list[RawEvidence] = []
+        for h in hits:
+            fact = (h.summary or h.name or "").strip()
+            if not fact:
+                continue
+            out.append(RawEvidence(
+                id=h.ku_id,
+                fact=fact,
+                source=SourceType.KNOWLEDGE,
+                origin=f"hkc:{h.ku_id}",
+                confidence=float(h.score) if h.score else 0.6,
+            ))
+        return out

package/python/foxclaw/search/internal_search.py

@@ -0,0 +1,73 @@
+"""
+Internal Search Engine —— HSR-I 路由的内部检索器
+
+串联 HMR(记忆)与 HKC(知识，在同一进程内直连，Foxclaw 启动时装配好后
+通过 knowledge_port 传进来)：
+
+    1. 若配置了 knowledge_port：先查它拿权威知识候选
+    2. 查 HMR 拿原始记忆，补充上下文 + 给①做溯源材料
+    3. 交叉关联：knowledge 候选如果能在 HMR 里找到对应记忆，
+       标记 grounded_by；找不到就做置信度惩罚（孤证）
+    4. 没配置 knowledge_port / 没查到候选时，自然退化为纯 HMR 检索
+
+knowledge_port 只需要实现 query(text, top_k) -> list[RawEvidence]，
+这里不关心它具体是 foxclaw-hkc、还是别的什么知识源。
+"""
+from __future__ import annotations
+from difflib import SequenceMatcher
+from .models import RawEvidence
+
+_GROUNDING_SIMILARITY = 0.5
+_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记忆 + 能力/状态
+
+    @staticmethod
+    def _safe_query(port, text: str, top_k: int) -> list[RawEvidence]:
+        """【深审修复·内部源隔离】逐个内部源 try/except → [],与 external 端口的隔离对称:
+        任一内部源(知识/记忆/Agent)失败都只让该源返回空,**不掀翻整个 search**。
+        现有三端口虽各自兜异常,但此处防御式隔离让"接入不兜异常的自定义 port"也安全。"""
+        if port is None:
+            return []
+        try:
+            return port.query(text, top_k) or []
+        except Exception:
+            return []
+
+    def search(self, text: str, top_k: int = 5) -> list[RawEvidence]:
+        from foxclaw.core.tracing import span as _span
+        with _span("search.internal", top_k=top_k):
+            knowledge_hits = self._safe_query(self.knowledge_port, text, top_k)
+            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)
+
+        return knowledge_hits + memory_hits + agent_hits
+
+    def _cross_link(self, knowledge_hits, memory_hits) -> list[RawEvidence]:
+        linked = []
+        for k in knowledge_hits:
+            trace = self._find_trace(k, memory_hits)
+            if trace:
+                k.grounded_by = trace.id
+            else:
+                k.confidence = max(0.0, k.confidence - _UNGROUNDED_PENALTY)
+            linked.append(k)
+        return linked
+
+    def _find_trace(self, knowledge: RawEvidence, memory_hits: list[RawEvidence]):
+        best, best_sim = None, 0.0
+        for m in memory_hits:
+            sim = SequenceMatcher(None, knowledge.fact, m.fact).ratio()
+            if sim >= _GROUNDING_SIMILARITY and sim > best_sim:
+                best, best_sim = m, sim
+        return best

package/python/foxclaw/search/models.py

@@ -0,0 +1,129 @@
+"""
+Foxclaw — Search 内核数据模型 (HSR)
+
+设计原则：这一层只产出"证据"，不做任何持久化决策。
+是否把搜索结果沉淀回 HMR、是否提交知识库(未来的 foxclaw-hkc)，
+由调用方(Agent / Runtime)决定，这里的数据结构都是只读产物。
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class RouteType(str, Enum):
+    INTERNAL = "HSR-I"   # 查内部（HMR 记忆 / 未来的 HKC 知识）
+    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 搜索）
+
+
+@dataclass
+class SubQuery:
+    id: str
+    text: str
+    source_hint: Optional[SourceType] = None
+    depends_on: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SearchPlan:
+    route: RouteType
+    steps: list[SubQuery]
+    reasoning: str = ""
+
+
+@dataclass
+class RawEvidence:
+    id: str
+    fact: str
+    source: SourceType
+    origin: str              # 具体来源：hmr 记忆 id / 网页 url
+    confidence: float = 0.5
+    raw: Any = None
+    grounded_by: Optional[str] = None  # 指向另一条证据的 id：
+                                        # "这条知识由这条 HMR 记忆溯源支撑"
+
+
+@dataclass
+class EvidenceNode:
+    id: str
+    fact: str
+    source: SourceType
+    origin: str
+    confidence: float
+    grounded_by: Optional[str] = None
+
+
+@dataclass
+class EvidenceEdge:
+    src: str
+    dst: str
+    relation: str  # "supports" | "contradicts" | "grounded_by"
+
+
+@dataclass
+class EvidenceGraph:
+    nodes: dict[str, EvidenceNode] = field(default_factory=dict)
+    edges: list[EvidenceEdge] = field(default_factory=list)
+
+    def add_node(self, node: EvidenceNode) -> None:
+        self.nodes[node.id] = node
+
+    def add_edge(self, edge: EvidenceEdge) -> None:
+        self.edges.append(edge)
+
+    def contradictions(self) -> list[EvidenceEdge]:
+        return [e for e in self.edges if e.relation == "contradicts"]
+
+    def to_dict(self) -> dict:
+        """给 API / ThoughtChain 用的精简序列化。"""
+        return {
+            "nodes": [
+                {
+                    "id": n.id, "fact": n.fact, "source": n.source.value,
+                    "origin": n.origin, "confidence": round(n.confidence, 2),
+                    "grounded_by": n.grounded_by,
+                }
+                for n in self.nodes.values()
+            ],
+            "edges": [
+                {"src": e.src, "dst": e.dst, "relation": e.relation}
+                for e in self.edges
+            ],
+        }
+
+
+@dataclass
+class StrategyDecision:
+    action: str  # "continue" | "stop" | "switch_query" | "switch_source"
+    reason: str
+    next_steps: list[SubQuery] = field(default_factory=list)
+
+
+@dataclass
+class SearchResult:
+    """search() 的唯一返回值。到这里为止，Search 内核不再做任何事。"""
+    query: str
+    route: RouteType
+    graph: EvidenceGraph
+    iterations: int
+    confidence: float
+    trace: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "query": self.query,
+            "route": self.route.value,
+            "confidence": round(self.confidence, 2),
+            "iterations": self.iterations,
+            "graph": self.graph.to_dict(),
+            "trace": self.trace,
+        }

package/python/foxclaw/search/planner.py

@@ -0,0 +1,44 @@
+"""
+Query Planner —— 决定路由(HSR-I / HSR-E / HYBRID)，并把任务拆成多跳检索步骤。
+
+当前是规则实现(触发词 + 标点拆句)，接口(SearchPlan)保持稳定，
+未来要换成 LLM function-calling 结构化拆解时，只需替换这个文件内部实现，
+不影响 Retriever / EvidenceFusion / SearchStrategy。
+"""
+from __future__ import annotations
+from .models import SearchPlan, SubQuery, RouteType
+from ..planning import planner as P   # 统一拆分原语(P1-2)
+
+_MEMORY_HINTS = ("我之前", "我们讨论过", "上次", "记得", "history", "之前说")
+_HYBRID_HINTS = ("为什么", "对比", "分析", "综合", "评估")
+
+
+class QueryPlanner:
+    def route(self, query: str, context: dict | None = None) -> RouteType:
+        if any(h in query for h in _MEMORY_HINTS):
+            return RouteType.INTERNAL
+        if any(h in query for h in _HYBRID_HINTS):
+            return RouteType.HYBRID
+        return RouteType.EXTERNAL
+
+    def plan(self, query: str, context: dict | None = None) -> SearchPlan:
+        route = self.route(query, context)
+
+        if route == RouteType.INTERNAL:
+            steps = [SubQuery(id="s1", text=query)]
+        elif route == RouteType.EXTERNAL:
+            steps = self._decompose(query)
+        else:  # HYBRID：先查内部，再拆外部子问题
+            steps = [SubQuery(id="s1", text=query), *self._decompose(query, offset=2)]
+
+        return SearchPlan(
+            route=route,
+            steps=steps,
+            reasoning=f"route={route.value}, steps={len(steps)}",
+        )
+
+    def _decompose(self, query: str, offset: int = 1) -> list[SubQuery]:
+        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)]