foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/pipeline/supervisor_stages.py

@@ -0,0 +1,230 @@
+"""
+主管专用 pipeline stages(P1-1)—— 把 SupervisorAgent 原 `_run_task_body` 的路由分发逻辑
+拆成可组合、可观测、可中断的 stage,使主管改走 base 统一模板 `_run_task_core`,从而获得
+hooks / 流式(run_task_stream)/ stop_event 中断 / 统一 `_emit_execution` / blocked 顶层提升。
+
+设计约束(与文稿 P1-1 规格 + 现行为逐点对齐):
+  · stage 是操作 ctx 的可调用(async 函数 + stage_name 属性),与 cognitive_pipeline 既有约定一致;
+  · 只操作 ctx 与 agent 的既有方法(_route/_schedule/_plan_task/_dispatch_*),不新增语义;
+  · 分诊 prompt / 自答 prompt / 调度 think 文案全部**逐字搬移**自 agents.py 原实现,不改行为;
+  · 主管自答(无关键词命中+模型可用)是 route 的**决策**、dispatch 的**执行**——决策与执行分 stage,
+    让 stop_event 在"决定自答"与"花钱调 LLM"之间有检查点;
+  · execution.completed 不再由 dispatch 手动 publish(改由 base 模板 `_emit_execution` 统一发,
+    文稿 P1-1 Step 4);无总线时的手动兜底沉淀(_store_memory)保留(standalone/测试场景);
+  · 内部短路标记放 ctx.extra 的 `_meta_answered`/`_self_answer`,aggregate 负责清除,不外泄到返回体。
+"""
+import asyncio
+from datetime import datetime
+
+from .cognitive_pipeline import PipelineContext, stage_recall  # noqa: F401  (recall 复用默认 stage)
+from ..core.dispatch import dispatch_failed  # 谓词在 core:避免 pipeline 反向 import agents
+
+
+# ── Stage 2: meta_check —— 元问题判断(你是谁/能做什么 → 主管以总管身份自答,不分派)──
+async def sv_meta_check(ctx: PipelineContext) -> None:
+    agent = ctx.agent
+    if not agent._is_meta(ctx.task):
+        return
+    agent._think(
+        content=f"元问题「{ctx.task}」由主管直接回答(系统介绍,不分派)",
+        node_type="decision", conf=0.92,
+    )
+    subagents = getattr(agent, "_subagents", {})
+    # 拓扑 5 → 3:助手/行政已下放为指令技能,不再出现在团队介绍里。
+    sub_names = {
+        "finance": "财务 Agent(理财、收支、预算、风控)",
+        "office": "办公学习 Agent(学习、知识管理、研究、写作、日程与行程)",
+    }
+    available = [v for k, v in sub_names.items() if k in subagents]
+    team = "\n".join(f"· {x}" for x in available) if available else "(子 Agent 尚未注册)"
+    intro_prompt = (
+        f"你是 Foxclaw 的主管 Agent(Supervisor),负责统筹协调整个智能体团队。"
+        f"用户问:「{ctx.task}」。请以主管身份友好、简洁地直接回答用户这个问题。\n"
+        f"背景信息(供你回答时参考):\n"
+        f"- 你统领的团队:\n{team}\n"
+        f"- 关于联网:Foxclaw 已接入百度 AI 搜索,具备联网查询实时信息的能力"
+        f"(当用户问最新版本、新闻、价格等时会自动联网)。所以如果用户问你能不能联网,"
+        f"应回答「可以联网」,而不是说没有联网能力。\n"
+        f"请针对用户的实际问题回答,控制在 150 字内,口吻像专业总管,不要自称助手,"
+        f"不要答非所问地只做自我介绍。"
+    )
+    reply = await agent._call_llm([{"role": "user", "content": intro_prompt}])
+    agent._store_memory(
+        content=f"主管自答元问题「{ctx.task}」",
+        mem_type="decision",
+        title=f"主管介绍_{datetime.now().strftime('%Y%m%d_%H%M')}",
+        shared=True,
+    )
+    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"
+
+
+# ── Stage 3: schedule —— 认知调度(优先级/负载/抢占)────────────────
+async def sv_schedule(ctx: PipelineContext) -> None:
+    if ctx.extra.get("_meta_answered"):
+        return
+    agent = ctx.agent
+    subagents = getattr(agent, "_subagents", {})
+    ctx.sched = agent._schedule(ctx.task, subagents)
+    agent._think(
+        content=(f"认知调度:{ctx.sched.reason}"
+                 + (f" · 抢占({ctx.sched.preemption_reason})" if ctx.sched.preemptible else "")),
+        node_type="decision", conf=0.9,
+    )
+sv_schedule.stage_name = "schedule"
+
+
+# ── Stage 4: route —— 路由决策(关键词+调度意图;未命中且模型可用 → 决策主管自答)──
+async def sv_route(ctx: PipelineContext) -> None:
+    if ctx.extra.get("_meta_answered"):
+        return
+    agent = ctx.agent
+    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="无关键词命中 → 主管直接自答(省掉二次分诊派发,正面对话提速)",
+            node_type="decision", conf=0.88)
+        ctx.extra["_self_answer"] = True
+        return
+    agent._think(
+        content=f"任务分诊:「{ctx.task}」→ 派给 {target} Agent。已有相关记忆 {len(ctx.memories)} 条",
+        node_type="decision",
+        conf=0.9,
+    )
+sv_route.stage_name = "route"
+
+
+# ── Stage 5: plan —— planner 拆解(多步?跨 Agent?)────────────────
+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)
+        agent._think(
+            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 / 兜底)──
+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),统筹整个智能体团队。"
+            f"用户说:「{ctx.task}」。请以主管身份**直接、友好、专业**地回答,针对用户的实际"
+            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(
+            content=f"主管自答正面对话「{ctx.task}」", mem_type="decision",
+            title=f"主管自答_{datetime.now().strftime('%Y%m%d_%H%M')}", shared=True)
+        ctx.dispatch_result = {
+            "result": {"dispatched_to": "supervisor", "sub_result": reply,
+                       "self_answered": True},
+        }
+        return
+
+    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(
+                content=f"计划为并行({len(ctx.step_routes)}个无依赖子任务)→ fork-join 并发调度",
+                node_type="decision", conf=0.88,
+            )
+            ctx.dispatch_result = await agent._dispatch_parallel(
+                ctx.task, ctx.step_routes, ctx.sched, ctx.session_id,
+                subagents, ctx.context, ctx.memories)
+        else:
+            ctx.dispatch_result = await agent._dispatch_multi(
+                ctx.task, ctx.step_routes, ctx.sched, ctx.session_id,
+                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 反思 → 修正计划 → 重执行)──
+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                      # 无失败/未完成步骤 → 无需重规划
+    if not agent._replan_enabled():
+        return                      # opt-in 关 / 不支持 tools → 保留原结果(fail-safe)
+    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)──
+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 设好
+    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/__init__.py

@@ -0,0 +1,17 @@
+"""
+foxclaw.planning —— 统一规划原语(P1-2)。
+
+三处路由(主管→子Agent / AHS→skill / search→数据源)共用的机制单一真源:
+否定词检测、标点拆分、marker 常量、触发词打分。
+"""
+from .planner import (
+    NEGATIONS, SPLIT_MARKERS, PARALLEL_TRIGGERS, LIST_SEPS,
+    is_negated, split_on, keyword_hits,
+    ScoredCandidate, TriggerRoute, trigger_route,
+)
+
+__all__ = [
+    "NEGATIONS", "SPLIT_MARKERS", "PARALLEL_TRIGGERS", "LIST_SEPS",
+    "is_negated", "split_on", "keyword_hits",
+    "ScoredCandidate", "TriggerRoute", "trigger_route",
+]

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                      # 参数 JSON 解析失败 → 不可信，回退
+    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"             # 幻觉出不存在的 Agent(含已下放的 assistant/admin)→ 兜底办公学习
+        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,99 @@
+"""
+统一规划原语（P1-2:三个 Planner 合并为一个引擎）。
+
+审计结论:主管路由(→子Agent)、AHS(→skill)、search QueryPlanner(→数据源)三处
+各自重复实现了同一套机制——否定词检测、标点拆分、marker 常量、触发词打分。
+本模块把这些机制收敛为**单一真源**,三处保留各自的公共入口与候选空间,内部委托到这里。
+
+不假设三者路由到同一目标:它们的候选集不同(agent/skill/source),但"怎么从文本里
+匹配、拆分、打分选候选"是同一套逻辑,这一套只应有一处定义。
+"""
+from __future__ import annotations
+import re
+from dataclasses import dataclass, field
+
+# ── 单一真源:否定词 + 顺序/并行/列表 标记 ──────────────────────
+NEGATIONS = ["不", "别", "无需", "不要", "取消", "甭", "don't", "no need", "without"]
+# 顺序拆分信号(明确的顺序连接词;不用"和/并"等高风险常用字,避免误拆名词短语)
+SPLIT_MARKERS = ["然后", "接着", "之后", "再", "最后", "；", ";"]
+# 并行信号:出现这些"同时性"连接词 → 子任务彼此无依赖,可并行 fork
+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: str = None
+    confidence: float = 0.0
+    candidates: list = field(default_factory=list)   # [(id, score)]
+    fallback: str = None
+    needs_composition: bool = False
+    reason: str = ""
+
+
+def trigger_route(task: str, candidates: list, fallback_id: str = 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
+        # 第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 字典序(确定性)
+    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",
+]