foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/pipeline/cognitive_pipeline.py

@@ -15,6 +15,7 @@ import inspect
 import os
 from dataclasses import dataclass, field
 from typing import Any, Callable
+from .stage_meta import named_stage
 
 
 @dataclass
@@ -27,32 +28,27 @@ class PipelineContext:
     反对的是"跨任务/并发共享可变状态"(改一半被读到不一致);ctx 不属于该反模式,可变安全。
     并发隔离由 test_pipeline.py::test_concurrent_ctx_isolation 锁定(24 并发任务零串)。
     (会话指针 _session_id/_parent_node_id 另经 contextvar 隔离,见 base.py。)"""
-    agent: Any                      # 执行本任务的 Agent(CognitiveAgent)
+    agent: Any
     task: str
     context: dict = field(default_factory=dict)
     session_id: str = ""
-    # 各 stage 逐步填充的产物
-    perceived: dict = field(default_factory=dict)   # perceive stage 的输入理解
+    perceived: dict = field(default_factory=dict)
     memories: list = field(default_factory=list)
-    plan: dict = field(default_factory=dict)        # plan stage 的任务结构(多步?并行?)
-    route: dict = field(default_factory=dict)       # route stage 的路由决策(target)
+    plan: dict = field(default_factory=dict)
+    route: dict = field(default_factory=dict)
     result: Any = None
     extra: dict = field(default_factory=dict)
-    verified: dict = field(default_factory=dict)   # verify stage 汇总的 Harness 校验结果
-    reflect: dict = field(default_factory=dict)     # reflect stage 的决策(accept/retry + 次数)
-    trace: list = field(default_factory=list)   # 逐 stage 轨迹(后续步骤 emit 用)
-    # ── 协作式中断(P3,opt-in)──────────────────────────────
-    stop_event: Any = None      # 置位则在下一 stage 边界 / reflect 重试迭代前优雅停止;默认 None=永不停
-    interrupted: bool = False   # 被 stop_event 提前中断(供调用方识别"部分完成、未跑完全部 stage")
-    # ── 【P1-1】主管路由专用字段(领域 Agent 不用,默认空)──────────
-    # 主管 pipeline(supervisor_stages.SUPERVISOR_STAGES)在 schedule/route/plan/dispatch
-    # 各 stage 间经这些字段传递路由决策;领域 Agent 的 DEFAULT_STAGES 从不读它们。
-    sched: Any = None                       # schedule stage 的 ScheduleDecision
-    target: str = ""                        # route stage 的分诊目标(子 Agent id)
-    plan_obj: Any = None                    # plan stage 的 planner 拆解结果(多步计划)
-    step_routes: list = field(default_factory=list)   # [(子任务文本, 目标 Agent)]
-    multi_agent: bool = False               # 是否跨多 Agent(顺序链式 / 并行 fork-join)
-    dispatch_result: dict = field(default_factory=dict)  # dispatch stage 的原始分发返回
+    verified: dict = field(default_factory=dict)
+    reflect: dict = field(default_factory=dict)
+    trace: list = field(default_factory=list)
+    stop_event: Any = None
+    interrupted: bool = False
+    sched: Any = None
+    target: str = ""
+    plan_obj: Any = None
+    step_routes: list = field(default_factory=list)
+    multi_agent: bool = False
+    dispatch_result: dict = field(default_factory=dict)
 
 
 def _emit_stage(ctx: "PipelineContext", stage_name: str) -> None:
@@ -95,16 +91,10 @@ class CognitivePipeline:
         回调异常被吞(fail-safe):流式反馈绝不拖垮任务执行。"""
         from foxclaw.core.tracing import span as _span
         for stage in self.stages:
-            # 协作式中断点(P3):stage **边界**检查 stop_event。opt-in——默认 stop_event=None 恒不触发,
-            # 与改前逐字一致。置位时优雅停:标记 interrupted、保留已完成 stage 的 ctx 产物、不跑后续 stage。
-            # 粒度=stage 边界:一般无法中止已在执行的单个 stage;但**流式路径(run_task_stream,D1)**下
-            # act 的 LLM 生成经 `_act_stream` 的**同一** stop_event 串到 `router.stream`,可 **token 级**
-            # 即时停 → 断连时二者协同:停后续 stage(此处)+ 停 act 生成(base._call_llm),省 token。
             if _stop_requested(ctx):
                 ctx.interrupted = True
                 break
             name = getattr(stage, "stage_name", getattr(stage, "__name__", "stage"))
-            # 单一 stage 循环 → 一处埋点覆盖全部 stage(链路里能看到 perceive→…→reflect 各自耗时)
             with _span(f"stage.{name}", agent=getattr(ctx.agent, "AGENT_ID", "")):
                 r = stage(ctx)
                 if inspect.isawaitable(r):
@@ -113,15 +103,13 @@ class CognitivePipeline:
             _emit_stage(ctx, name)
             if on_stage is not None:
                 try:
-                    on_stage(name, ctx)         # D1:逐 stage 吐进度给流式路径
+                    on_stage(name, ctx)
                 except Exception:
-                    pass                        # 流式回调故障不拖垮任务执行(fail-safe)
+                    pass
         return ctx
 
 
-# ── Stages(Step 1:recall / act)──────────────────────────────
-# stage 是操作 ctx 的可调用;命名 stage_* 便于事件与轨迹标注。
-
+@named_stage("perceive")
 def stage_perceive(ctx: PipelineContext) -> None:
     """感知:把原始输入框定为结构化感知(Step 5)。当前记录轻量输入特征;
     这里是未来"意图识别/输入解析"的落点。也是逐 stage 事件链的起点。"""
@@ -129,14 +117,13 @@ def stage_perceive(ctx: PipelineContext) -> None:
         "task_len": len(ctx.task or ""),
         "has_context": bool(ctx.context),
     }
-stage_perceive.stage_name = "perceive"
 
 
+@named_stage("recall")
 async def stage_recall(ctx: PipelineContext) -> None:
     """召回相关记忆(等价 P1-1 模板的 _recall_memory(_recall_query, top_k))。"""
     a = ctx.agent
     ctx.memories = a._recall_memory(a._recall_query(ctx.task), top_k=a._recall_topk)
-stage_recall.stage_name = "recall"
 
 
 def _plan_text(plan: dict) -> str:
@@ -152,7 +139,7 @@ def _record_plan_node(ctx: PipelineContext) -> None:
     计划节点不参与准入裁决,也不被 act 读取(见下方「informational」边界说明)。
     """
     agent = getattr(ctx, "agent", None)
-    think = getattr(agent, "_think", None)      # 轻量替身/测试 Agent 可能没有 _think
+    think = getattr(agent, "_think", None)
     if think is None:
         return
     try:
@@ -162,6 +149,7 @@ def _record_plan_node(ctx: PipelineContext) -> None:
         pass
 
 
+@named_stage("plan")
 def stage_plan(ctx: PipelineContext) -> None:
     """结构规划:用 **P1-2 统一规划引擎** 分析任务结构(是否多步/并行),记录到 ctx.plan。
 
@@ -187,28 +175,10 @@ def stage_plan(ctx: PipelineContext) -> None:
         steps, flow = [task], "single"
     ctx.plan = {"steps": steps, "flow": flow, "multi_step": len(steps) > 1}
     _record_plan_node(ctx)
-stage_plan.stage_name = "plan"
-# ⚠【预留·informational,不驱动执行】(2026-07-17 V3·B1 审核标注)
-# stage_plan 写 ctx.plan 供观测/审计,但**没有任何 _execute 读取它**,故不改变执行
-# (act 整段交 LLM/skill)。让 act 真按 plan 多步执行是**行为改变**,须 opt-in + 每步
-# confirm 挂起 + fail-safe(见 V2_ROADMAP「Skill 接入认知管线」),不在此顺手做。
-# (B1 自审:曾在此加 `stage_plan.informational=True` 属性,但无任何消费者=又一个死标记,
-#  已删——注释足以说明,不造没人读的假结构化标记。)
-
-
-# 默认自动派发的门槛(A·Step5,2026-07-16:从"默认关"改为"默认开但严格受限")。
-# 背景:此前 route/dispatch 双双默认关 → 工具中心/MCP 连接器/技能台**在正常对话里根本够不着**
-# (「帮我算 3+5」助手只会用 LLM 硬答,计算器技能不会被调用)。整套工具生态形同虚设。
-# 放量策略:只自动派发**只读**技能、且要求**高置信**;有副作用的(write/send/pay/destructive)
-# 一律不自动选中,仍须显式 use_skill —— 自动执行绝不越过"会改变世界"的那条线。
-# 阈值取 0.6 —— 这是**量出来的**,不是拍的。router 实测分值只有三档:
-#   0.600 强匹配(触发词直接命中,如「帮我计算…」→calculator)
-#   0.480 弱匹配(如「查下去公司的路线」→amap_route、「发邮件给张三」→gmail_send)
-#   0.000 无匹配(闲聊/写代码)
-# 故 (0.48, 0.60] 区间内的任何值都等价于"只要强匹配";再高(如 0.75)则**一个都选不中**、
-# 功能形同虚设。0.6 已是最保守的可用值 —— "比 0.6 更保守"是伪命题。
+
+
 AUTO_ROUTE_THRESHOLD = 0.6
-AUTO_ROUTE_READ_ONLY = True      # 只自动派发只读技能(有副作用的绝不自动动手)
+AUTO_ROUTE_READ_ONLY = True
 
 
 def _is_read_only(skill) -> bool:
@@ -242,6 +212,7 @@ def _route_policy(agent, context: dict) -> dict:
             "read_only": bool(p.get("read_only", AUTO_ROUTE_READ_ONLY))}
 
 
+@named_stage("route")
 def stage_route(ctx: PipelineContext) -> None:
     """路由决策:记录本任务由谁处理到 ctx.route(target=self 或 skill)。
 
@@ -260,33 +231,27 @@ def stage_route(ctx: PipelineContext) -> None:
         return
     reg = getattr(ctx.agent, "skill_registry", None)
     if reg is None:
-        return                      # 无工具箱(finance/admin/office)→ 保持 self
+        return
     try:
         from ..skills.pipeline import route as skill_route
         r = skill_route(ctx.task, reg)
     except Exception:
-        return                      # 选路失败不影响主流程 → 保持 self(fail-safe)
+        return
     if r.primary and r.confidence >= policy["threshold"]:
         sk = reg.get(r.primary)
-        # 只读闸:有副作用的技能(write/send/pay/destructive)**绝不自动选中**——
-        # 自动执行不得越过"会改变世界"的线;要用仍可显式 use_skill(那时用户是知情的)。
         if policy["read_only"] and sk is not None and not _is_read_only(sk):
-            return                      # 保持 self → LLM 作答,不自动动手
-        # 外泄闸:问的是**用户自己的数据**(账本/行程/学习)→ 绝不自动发给**外部**技能。
-        # 与 needs_search 共用同一判定(单一真源)。否则「查一下最新的本月支出」会把私人
-        # 财务问题自动送去外部搜索——那正是 needs_search 已挡住、却从技能这条旁路漏回来的 bug。
+            return
         if sk is not None and getattr(sk, "external", False):
             try:
                 from ..core.web_search import is_personal_query
                 if is_personal_query(ctx.task):
-                    return              # 私人问题不外发 → 保持 self
+                    return
             except Exception:
-                pass                    # 判定不可用 → 不因此放行外部技能之外的行为(保持原逻辑)
+                pass
         ctx.route = {"target": "skill", "skill_id": r.primary,
                      "confidence": round(float(r.confidence), 3),
                      "reason": f"router 选中 skill「{r.primary}」"
                                f"(置信 {r.confidence:.2f}≥{policy['threshold']})"}
-stage_route.stage_name = "route"
 
 
 def _skill_dispatch_enabled(agent, context: dict) -> bool:
@@ -339,21 +304,21 @@ async def _act_via_skill(ctx: "PipelineContext"):
     reg = getattr(agent, "skill_registry", None)
     adp = getattr(agent, "skill_adapter", None)
     if reg is None or adp is None:
-        return None                       # 无工具箱(finance/admin/office)→ 回落 _execute
+        return None
     sid = (ctx.route or {}).get("skill_id")
-    skill = reg.get(sid) if sid else None
+    if not isinstance(sid, str) or not sid:
+        return None
+    skill = reg.get(sid)
     if skill is None:
         return None
     from ..skills.pipeline import _build_args
     from ..skills import set_loop_session, reset_loop_session
     args = _build_args(skill, ctx.task, {})
     confirmed = _confirmed_for(ctx.context, sid)
-    token = set_loop_session(getattr(ctx, "session_id", None))   # 循环检测按会话分槽
+    token = set_loop_session(getattr(ctx, "session_id", None))
     try:
         res = await asyncio.to_thread(adp.invoke, skill, args, confirmed)
     except Exception as e:
-        # invoke 理应自兜底(catches _dispatch 异常);万一权限评估等意外抛错 → **fail-closed**:
-        # 结构化 error 回传,**绝不回落 LLM**(路由到发邮件却让 LLM 代答=幻觉/危险),也不崩整个任务。
         return ({"skill": sid, "status": "error", "message": f"skill dispatch 异常: {e}",
                  "pending": False}, {"via": "skill", "skill_id": sid, "skill_status": "error"})
     finally:
@@ -361,12 +326,11 @@ async def _act_via_skill(ctx: "PipelineContext"):
     extra = {"via": "skill", "skill_id": sid, "skill_status": res.status}
     if res.success:
         return ({"skill": sid, "output": res.output, "status": res.status}, extra)
-    # 非成功:无副作用已发生(权限门+confirmed=False保证)。结构化回传,绝不当完成、绝不回落 LLM
-    # (路由到发邮件却让 LLM 代答=危险/幻觉);needs_confirmation 待用户确认后重跑(带 _confirmed)。
     return ({"skill": sid, "status": res.status, "message": res.message,
              "pending": res.status == "needs_confirmation"}, extra)
 
 
+@named_stage("act")
 async def stage_act(ctx: PipelineContext) -> None:
     """领域执行步骤。默认:领域 `_execute`(→ LLM),等价 P1-1 模板。
 
@@ -381,9 +345,9 @@ async def stage_act(ctx: PipelineContext) -> None:
             return
     ctx.result, ctx.extra = await ctx.agent._execute(
         ctx.task, ctx.context, ctx.session_id, ctx.memories)
-stage_act.stage_name = "act"
 
 
+@named_stage("verify")
 def stage_verify(ctx: PipelineContext) -> None:
     """把本次执行的 Harness 校验**结果**显式化到 ctx.verified(Step 2)。
 
@@ -399,19 +363,15 @@ def stage_verify(ctx: PipelineContext) -> None:
     except Exception:
         nodes = []
     warns = sum(1 for n in nodes if getattr(n, "harness_status", "") == "WARN")
-    deltas = [n.harness_delta for n in nodes            # get_chain 按 timestamp 升序
+    deltas = [n.harness_delta for n in nodes
               if getattr(n, "harness_delta", None) is not None]
     ctx.verified = {
-        "passed": True,                          # 未被 BLOCK
+        "passed": True,
         "nodes": len(nodes),
         "warns": warns,
-        "max_delta": round(max(deltas), 3) if deltas else 0.0,   # 全 session 峰值(信息量)
-        # last_delta = 最近一次推理的漂移(本次尝试的最终状态)。reflect 用它作重试信号——
-        # 深审修复:max_delta 是 max over 累积历史(单调不减),重试追加节点后仍是旧峰值,
-        # 会让重试永远到上限、无法因"重试改善"提前退出;last_delta 反映当前尝试,可正确早退。
+        "max_delta": round(max(deltas), 3) if deltas else 0.0,
         "last_delta": round(deltas[-1], 3) if deltas else 0.0,
     }
-stage_verify.stage_name = "verify"
 
 
 def _reflect_policy(agent, context: dict) -> dict:
@@ -426,10 +386,11 @@ def _reflect_policy(agent, context: dict) -> dict:
     if p is True:
         p = {}
     return {"enabled": True,
-            "max_retries": int(p.get("max_retries", 1)),          # 硬上限,防成环
+            "max_retries": int(p.get("max_retries", 1)),
             "drift_threshold": float(p.get("drift_threshold", 0.5))}
 
 
+@named_stage("reflect")
 async def stage_reflect(ctx: PipelineContext) -> None:
     """反思:读 verify 信号(max_delta),决定接受还是**有上限地**重试(Step 3)。
 
@@ -440,42 +401,29 @@ async def stage_reflect(ctx: PipelineContext) -> None:
     policy = _reflect_policy(ctx.agent, ctx.context)
     decision, retries = "accept", 0
     if policy["enabled"]:
-        # 用 last_delta(当前尝试的最终漂移)作重试信号,而非 max_delta(累积峰值,单调不减)——
-        # 否则重试改善了也无法早退。重试若把漂移降到阈值内,下一轮 last_delta 达标即停止。
         while (ctx.verified.get("last_delta", 0.0) > policy["drift_threshold"]
                and retries < policy["max_retries"]):
-            # 协作式中断点(P3):每次重试都是一次 `_execute`(LLM 调用)——这里是本管线里最接近
-            # 范式"agentic loop 每轮检查中断"的地方。置位则停在下一轮 LLM 调用**之前**(省 token),
-            # 保留已有最好结果。opt-in:stop_event=None 恒不触发,重试行为逐字不变。
             if _stop_requested(ctx):
-                # 中断:decision 统一记 "interrupted",已发生的重试次数由 retries 字段承载。
-                # (B2 审核 F1:此前分 interrupted/retry_interrupted 两值,其中 retries==0 一支仅在
-                #  外部线程于"pre-reflect 边界检查"与"首个 while 检查"之间置位才可达——单线程测试无法
-                #  稳定覆盖。合并为单值消除该未覆盖分支,信息量不减: retries 已表达重试了几次。)
                 ctx.interrupted = True
                 decision = "interrupted"
                 break
-            prev_result, prev_extra = ctx.result, ctx.extra   # 重试前的最好结果
+            prev_result, prev_extra = ctx.result, ctx.extra
             try:
                 retries += 1
                 decision = "retry"
                 ctx.result, ctx.extra = await ctx.agent._execute(
                     ctx.task, ctx.context, ctx.session_id, ctx.memories)
-                stage_verify(ctx)                              # 重新汇总校验(刷新 last_delta)
+                stage_verify(ctx)
             except Exception:
-                # 重试出错(含重跑被 BLOCK)→ 回滚到上一次好结果,停止重试(不让重试变差)
                 ctx.result, ctx.extra = prev_result, prev_extra
                 decision = "retry_reverted"
                 break
-        # 重试后 last_delta 已达标 → 视为改善接受
         if decision == "retry" and ctx.verified.get("last_delta", 0.0) <= policy["drift_threshold"]:
             decision = "retry_accepted"
     ctx.reflect = {"decision": decision, "retries": retries,
                    "final_last_delta": ctx.verified.get("last_delta", 0.0),
                    "final_max_delta": ctx.verified.get("max_delta", 0.0)}
-stage_reflect.stage_name = "reflect"
 
 
-# 默认管线的 stage 序列(完整八阶段之七;persist=run_task 里的 emit + 领域 _store_memory)。
 DEFAULT_STAGES = [stage_perceive, stage_recall, stage_plan, stage_route,
                   stage_act, stage_verify, stage_reflect]

package/python/foxclaw/pipeline/stage_meta.py

@@ -0,0 +1,21 @@
+"""stage 的命名元数据。
+
+pipeline 的两个模块都按「函数 + stage_name 属性」标注阶段,读侧用 getattr 兜底
+(见 cognitive_pipeline 里取 name 的那处)。属性赋值 `fn.stage_name = ...` 在类型
+检查里不成立 —— 函数对象的类型没有这个属性;setattr 是运行期真做的同一件事,
+而且让「名字」与「定义」写在同一处,不会漏标。
+"""
+from __future__ import annotations
+
+from typing import Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def named_stage(name: str) -> Callable[[F], F]:
+    """给 stage 可调用挂 stage_name(stage 事件与轨迹标注用这个键)。"""
+    def deco(fn: F) -> F:
+        vars(fn)["stage_name"] = name
+        return fn
+
+    return deco

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]