foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/planning/llm_planner.py

@@ -0,0 +1,232 @@
+"""
+LLM 驱动规划器（P0-1）—— 把主管的多步任务拆解从「规则拆分」升级为 LLM function-calling 规划。
+
+病根（与 docs/internal/TOOL_USE_PLAN.md 同源）：planning/planner.py 的拆解靠
+标点/连接词/触发词（"然后""同时""接着"），只能做表面切分，无法理解任务的语义结构；
+LLM 从没机会决定「这个任务该拆成几步、每步派给哪个 Agent」。于是「帮我查最近一周支出，
+再据此定下月预算，最后整理成邮件」这类真实任务，规则拆解经常切错边界、派错 Agent。
+
+本模块给出单一真源：把「规划」声明成一个 function-calling 工具（submit_plan），交给
+LLM 自主拆解，返回结构化计划（每步带目标 Agent 与依赖），由 SupervisorAgent 转成
+Plan 兼容对象。
+
+后半段「反思重规划」：多步执行出现失败/未完成时，再调一次 submit_plan，把上一轮
+各步结果作为反馈喂给 LLM，让它决定「换 Agent / 换表述 / 拆更细 / 补前置 / 放弃」，
+产出修正计划并重新执行（llm_replan）。这就是 plan → 执行 → 反思 → 重规划的闭环。
+
+opt-in + fail-safe（与 FOXCLAW_TOOL_USE 同哲学，默认关、可逆）：
+  · FOXCLAW_LLM_PLAN=1 才开启初次规划；
+  · FOXCLAW_LLM_REPLAN=1 才开启反思重规划；
+  · provider 不支持 tools / 调用失败 / 模型未产出有效计划 → 返回 None，
+    上层自动回退（规划回退规则拆解；重规划回退「保留原结果」）。
+"""
+from __future__ import annotations
+
+import os
+
+
+def _env_flag(name: str) -> bool:
+    return os.environ.get(name, "0").strip() in ("1", "true", "True", "yes", "on")
+
+
+def llm_plan_enabled() -> bool:
+    """是否启用 LLM 规划。默认关（behavior-preserving / 可逆）。"""
+    return _env_flag("FOXCLAW_LLM_PLAN")
+
+
+def replan_enabled() -> bool:
+    """是否启用反思重规划。默认关（behavior-preserving / 可逆）。"""
+    return _env_flag("FOXCLAW_LLM_REPLAN")
+
+
+_PLAN_SYSTEM = (
+    "你是 Foxclaw 的任务规划器。唯一职责：把用户任务拆解成可执行计划，"
+    "并为每个子任务指派最合适的 Agent。\n"
+    "规则：\n"
+    "1. 只拆解真正需要多步或跨领域协作的任务；简单单步任务就返回单个 step。\n"
+    "2. 每个子任务独立可执行、边界清晰、动词开头、不含模糊表述。\n"
+    "3. 子任务有先后依赖（后一步要用前一步的结果）→ flow=sequential；"
+    "彼此独立可同时做 → flow=parallel。\n"
+    "4. 必须通过 submit_plan 工具提交计划，不要输出计划之外的任何文本。\n\n"
+    "可派发的 Agent 及其职责：\n{agent_desc}"
+)
+
+_REPLAN_SYSTEM = (
+    "你是 Foxclaw 的反思规划器。上一轮多步计划的执行结果已经给出，其中存在失败或未完成的步骤。"
+    "你的唯一职责：分析失败原因，产出修正后的计划，让任务最终完成。\n"
+    "规则：\n"
+    "1. 只重排**失败/未完成**的步骤，已经成功的步骤不要重复执行。\n"
+    "2. 可采取的修正手段：换 Agent、换表述、拆得更细、补前置步骤、合并步骤。\n"
+    "3. 若确认任务无法完成（超出能力 / 信息不足 / 反复失败），返回空 steps 数组表示放弃。\n"
+    "4. 必须通过 submit_plan 工具提交计划，不要输出计划之外的任何文本。\n\n"
+    "可派发的 Agent 及其职责：\n{agent_desc}"
+)
+
+
+def build_plan_tool(agent_catalog: dict) -> dict:
+    """构造 submit_plan 的 function schema（OpenAI tools 通用格式）。
+
+    agent_catalog: {agent_id: 职责描述}，用于约束 agent 字段的取值枚举，
+    让 LLM 只能在真实存在的 Agent 里选，避免幻觉出不存在的能力。
+
+    工具描述保持中性（planning / replanning 共用同一工具），具体行为由
+    system prompt（_PLAN_SYSTEM 或 _REPLAN_SYSTEM）引导。
+    """
+    agent_ids = list(agent_catalog.keys())
+    return {
+        "type": "function",
+        "function": {
+            "name": "submit_plan",
+            "description": (
+                "提交任务执行计划（planning/replanning 共用）。steps 为子任务列表，"
+                "每步含 name(一句话、动词开头) / agent(负责的 agent id) / depends_on"
+                "(依赖的前序步骤序号,0-based)。flow 为执行模式。若无需拆解或确认"
+                "无法完成，返回空 steps。"
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "flow": {
+                        "type": "string",
+                        "enum": ["single", "sequential", "parallel"],
+                        "description": "single=单步；sequential=步骤有先后依赖；"
+                                       "parallel=步骤彼此独立可并行",
+                    },
+                    "steps": {
+                        "type": "array",
+                        "description": "子任务列表（flow=single 时仅 1 项）",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "name": {
+                                    "type": "string",
+                                    "description": "子任务的一句话描述，动词开头",
+                                },
+                                "agent": {
+                                    "type": "string",
+                                    "enum": agent_ids,
+                                    "description": "负责该子任务的 agent id",
+                                },
+                                "depends_on": {
+                                    "type": "array",
+                                    "items": {"type": "integer"},
+                                    "description": "依赖的前序步骤序号（0-based）；"
+                                                   "无依赖传空数组",
+                                },
+                            },
+                            "required": ["name", "agent"],
+                        },
+                    },
+                },
+                "required": ["flow", "steps"],
+            },
+        },
+    }
+
+
+def _agent_desc(agent_catalog: dict) -> str:
+    return "\n".join(f"- {a}：{d}" for a, d in agent_catalog.items())
+
+
+def _invoke_plan_tool(router, system: str, user_content: str, agent_catalog: dict,
+                      max_tokens: int):
+    """调用 submit_plan 工具并解析为 {intent, flow, steps}。
+
+    返回 None = 不可用 / 不支持 tools / 调用失败 / 参数解析失败。
+    成功时 steps 可能为空列表（模型判定「无需拆解」或「放弃」），由上层决定含义。
+    """
+    if not agent_catalog or not user_content or not str(user_content).strip():
+        return None
+    try:
+        tool = build_plan_tool(agent_catalog)
+        res = router.call_tools(
+            system,
+            [{"role": "user", "content": str(user_content).strip()}],
+            [tool],
+            tool_choice="auto",
+            max_tokens=max_tokens,
+        )
+    except Exception:
+        return None
+    if not res.get("supported"):
+        return None
+    calls = res.get("tool_calls") or []
+    if not calls:
+        return None
+    if calls[0].get("args_parse_failed"):
+        return None
+    args = calls[0].get("args") or {}
+    steps = args.get("steps")
+    if not isinstance(steps, list):
+        return None
+    norm = []
+    for s in steps:
+        if not isinstance(s, dict):
+            continue
+        name = str(s.get("name") or "").strip()
+        if not name:
+            continue
+        agent = str(s.get("agent") or "office").strip()
+        if agent not in agent_catalog:
+            agent = "office"
+        dep = s.get("depends_on") or []
+        if not isinstance(dep, list):
+            dep = []
+        norm.append({
+            "name": name,
+            "agent": agent,
+            "depends_on": [int(d) for d in dep if isinstance(d, (int, float))],
+        })
+    flow = str(args.get("flow") or "sequential").strip()
+    if flow not in ("single", "sequential", "parallel"):
+        flow = "sequential"
+    if len(norm) == 1:
+        flow = "single"
+    return {"intent": str(user_content).strip(), "flow": flow, "steps": norm}
+
+
+def llm_plan(router, task: str, agent_catalog: dict, max_tokens: int = 1024):
+    """初次规划：用 function-calling 让 LLM 产出结构化计划。
+
+    返回 {intent, flow, steps: [{name, agent, depends_on}]}；
+    返回 None = 不可用 / 不支持 tools / 调用失败 / 模型未产出有效计划（上层回退规则拆解）。
+    """
+    out = _invoke_plan_tool(
+        router,
+        _PLAN_SYSTEM.format(agent_desc=_agent_desc(agent_catalog)),
+        task, agent_catalog, max_tokens)
+    if not out or not out["steps"]:
+        return None
+    return out
+
+
+def _format_prior_results(prior_results) -> str:
+    """把上一轮各步结果序列化为 LLM 可读的反馈文本。"""
+    if not prior_results:
+        return "(无执行结果)"
+    lines = []
+    for i, s in enumerate(prior_results, 1):
+        status = "失败" if (s.get("blocked") or s.get("failed")) else "成功"
+        lines.append(
+            f"第{i}步[{s.get('agent', '?')}]（{status}）：{s.get('subtask', '')}\n"
+            f"  输出：{s.get('output', '')}")
+    return "\n".join(lines)
+
+
+def llm_replan(router, task: str, prior_results, agent_catalog: dict,
+               max_tokens: int = 1024):
+    """反思重规划：把上一轮执行结果作为反馈，让 LLM 产出修正计划。
+
+    prior_results: 上一轮各步结果列表，形如 [{subtask, agent, output, blocked, failed}, ...]
+    返回同 llm_plan 的结构；steps 为空 = 模型判定「放弃/无需重试」；
+    返回 None = 不可用 / 不支持 / 失败 / 解析失败（上层保留原结果）。
+    """
+    feedback = _format_prior_results(prior_results)
+    user_content = (
+        f"原始任务：{task}\n\n"
+        f"上一轮执行结果：\n{feedback}\n\n"
+        f"请反思失败原因，产出修正后的计划（若确认无法完成则返回空 steps）。")
+    return _invoke_plan_tool(
+        router,
+        _REPLAN_SYSTEM.format(agent_desc=_agent_desc(agent_catalog)),
+        user_content, agent_catalog, max_tokens)

package/python/foxclaw/planning/planner.py

@@ -0,0 +1,94 @@
+"""
+统一规划原语（P1-2:三个 Planner 合并为一个引擎）。
+
+审计结论:主管路由(→子Agent)、AHS(→skill)、search QueryPlanner(→数据源)三处
+各自重复实现了同一套机制——否定词检测、标点拆分、marker 常量、触发词打分。
+本模块把这些机制收敛为**单一真源**,三处保留各自的公共入口与候选空间,内部委托到这里。
+
+不假设三者路由到同一目标:它们的候选集不同(agent/skill/source),但"怎么从文本里
+匹配、拆分、打分选候选"是同一套逻辑,这一套只应有一处定义。
+"""
+from __future__ import annotations
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+NEGATIONS = ["不", "别", "无需", "不要", "取消", "甭", "don't", "no need", "without"]
+SPLIT_MARKERS = ["然后", "接着", "之后", "再", "最后", "；", ";"]
+PARALLEL_TRIGGERS = ["同时", "分别", "并行", "一并"]
+LIST_SEPS = ["、", "，", ",", "；", ";"]
+
+
+def is_negated(task: str, trigger: str, window: int = 4) -> bool:
+    """触发词在任务中是否被否定词紧邻(前 window 字)修饰。"""
+    idx = (task or "").find(trigger)
+    if idx < 0:
+        return False
+    prefix = task[max(0, idx - window):idx]
+    return any(neg in prefix for neg in NEGATIONS)
+
+
+def split_on(task: str, markers: list) -> list:
+    """按 markers 把文本切成非空片段(去空白)。"""
+    pat = "|".join(map(re.escape, markers))
+    return [p.strip() for p in re.split(pat, task or "") if p.strip()]
+
+
+def keyword_hits(task: str, keywords: list, negation: bool = False) -> int:
+    """命中的关键词数(negation=True 时排除被否定词修饰的命中)。
+    主管路由用 negation=False(保持原计数行为);AHS 触发打分用 negation=True。"""
+    task = task or ""
+    return sum(1 for kw in keywords
+               if kw in task and not (negation and is_negated(task, kw)))
+
+
+@dataclass
+class ScoredCandidate:
+    """打分候选:id + 触发词 + 描述(领域匹配)。三处把各自候选适配成它。"""
+    id: str
+    triggers: list = field(default_factory=list)
+    description: str = ""
+
+
+@dataclass
+class TriggerRoute:
+    primary: Optional[str] = None
+    confidence: float = 0.0
+    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 = None,
+                  min_conf: float = 0.15, near_gap: float = 0.1) -> TriggerRoute:
+    """触发词路由三步打分:否定过滤后的触发命中(0.8)+ 描述领域匹配(0.2),确定性排序。
+    这是 AHS 原 route 的算法,现作为三处共用的通用引擎。"""
+    if not candidates:
+        return TriggerRoute(reason="候选为空")
+
+    scored = []
+    for c in candidates:
+        triggers = c.triggers or []
+        if not triggers:
+            scored.append((c.id, 0.0)); continue
+        hits = keyword_hits(task, triggers, negation=True)
+        hit_score = 0.0 if hits == 0 else min(0.6 + 0.15 * (hits - 1), 1.0)
+        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]))
+    top_id, top_score = scored[0]
+    cands = [(i, s) for i, s in scored if s > 0]
+
+    fb = fallback_id or candidates[-1].id
+    if top_score < min_conf:
+        return TriggerRoute(primary=fb, confidence=top_score, candidates=cands,
+                            fallback=fb, reason="无显著匹配,使用兜底")
+    near = [c for c in cands if abs(c[1] - top_score) < near_gap]
+    return TriggerRoute(primary=top_id, confidence=top_score, candidates=cands,
+                        fallback=fb, needs_composition=len(near) > 1,
+                        reason=f"主候选 {top_id}(分 {top_score})")

package/python/foxclaw/search/__init__.py

@@ -0,0 +1,24 @@
+"""Foxclaw — Search: 认知搜索内核 (HSR)
+统一内部记忆(HMR)与外部联网检索，供五个 Agent 共享调用。"""
+from .models import (
+    RouteType, SourceType, SubQuery, SearchPlan,
+    RawEvidence, EvidenceNode, EvidenceEdge, EvidenceGraph,
+    StrategyDecision, SearchResult,
+)
+from .planner import QueryPlanner
+from .internal_search import InternalSearchEngine
+from .external_search import BaiduWebSearchPort
+from .hkc_read_port import HKCReadPort
+from .agent_port import AgentSourcePort
+from .retriever import Retriever
+from .evidence import EvidenceFusion
+from .strategy import SearchStrategy
+from .runtime import SearchRuntime
+
+__all__ = [
+    "RouteType", "SourceType", "SubQuery", "SearchPlan",
+    "RawEvidence", "EvidenceNode", "EvidenceEdge", "EvidenceGraph",
+    "StrategyDecision", "SearchResult",
+    "QueryPlanner", "InternalSearchEngine", "BaiduWebSearchPort", "HKCReadPort",
+    "AgentSourcePort", "Retriever", "EvidenceFusion", "SearchStrategy", "SearchRuntime",
+]

package/python/foxclaw/search/agent_port.py

@@ -0,0 +1,190 @@
+"""
+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):
+        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)]]
+
+    def _from_finance(self, text, top_k):
+        out: list[tuple[float, RawEvidence]] = []
+        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: list[tuple[float, RawEvidence]] = []
+        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: list[tuple[float, RawEvidence]] = []
+        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
+
+    def _from_thoughtchain(self, text, top_k):
+        out: list[tuple[float, RawEvidence]] = []
+        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
+
+    def _from_memories(self, text, top_k):
+        out: list[tuple[float, RawEvidence]] = []
+        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
+
+    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,109 @@
+"""
+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
+
+_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:
+    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