foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/agents/base.py

@@ -10,19 +10,22 @@ CognitiveAgent — 认知增强 Agent 基类
 
 import threading
 import uuid
+from typing import TYPE_CHECKING, Any
 
 from ..core.thought_chain import ThoughtChain, ThoughtNode
 from ..harness.harness import Harness, HarnessResult
 
-# 工具并行执行后,多个 worker 线程可能同时走 _think(web_search 命中 / 记忆召回节点),
-# 而 _parent_node_id 是共享可变指针。用模块级 RLock 串行化「建链 + 挪指针」两步,
-# 保证 thought 链仍是一条合法链(节点本身顺序由完成时刻决定,语义可接受)。
+if TYPE_CHECKING:
+    from ..core.recovery import RestartRecovery
+    from ..core.system_bus import SystemBus
+    from ..kernel import ProcessManager
+    from ..skills.lifecycle import HookManager
+    from ..skills.markdown_skill import MarkdownSkillRegistry
+
 _THINK_LOCK = threading.RLock()
 
-# ── S3 步骤 2：按职责拆分到 mixin（纯搬移、零行为变更）────────────────────────
-# 会话状态基础设施（contextvar + 污点 + HarnessBlockedError）搬至 mixins/_context.py；
-# 各职责方法搬至 mixins/{llm,augment,memory,preference,prompt,tool_exec}.py；
-# 主循环（会话管理 / _think / stream_reply / run_task 生命周期）留在本文件。
+_GATE_UNSET = object()
+
 from .mixins._context import (
     _agent_ctx_get,
     _agent_ctx_set,
@@ -46,7 +49,6 @@ from .mixins.preference import PreferenceMixin
 from .mixins.prompt import PromptMixin, KERNEL_PROMPT
 from .mixins.tool_exec import ToolExecMixin
 
-# 历史导入兼容：`from foxclaw.agents.base import X` 的 X 在此 re-export（测试/外部模块仍按此路径取符号）。
 __all__ = [
     "CognitiveAgent", "HarnessBlockedError", "KERNEL_PROMPT",
     "_suppress_memory", "_act_stream", "_taint_get", "_taint_raise", "_taint_reset",
@@ -92,28 +94,32 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
     AGENT_NAME: str = "Base Agent"
     ALLOWED_TOOL_CATEGORIES: set[str] = {"read"}
 
+    md_skills: "MarkdownSkillRegistry"
+    hooks: "HookManager"
+    _system_bus: "SystemBus"
+    _process_manager: "ProcessManager"
+    _recovery: "RestartRecovery"
+
     def __init__(
         self,
-        hmr,                          # HMR 实例（从外部注入）
+        hmr,
         thought_chain: ThoughtChain,
         client=None,
         data_dir: str = "./foxclaw_data",
         shadow_rounds: int = 20,
-        router=None,                  # ModelRouter（多模型路由,从外部注入）
-        spine=None,                   # 【P0】全局 EventSpine（harness 事件汇入脊柱→统一 WS 投影）
-        caps=None,                    # 【P1-3】CapabilityRegistry（按名解析同伴,不再直接互持）
+        router=None,
+        spine=None,
+        caps=None,
     ):
         self.hmr = hmr
         self.thought_chain = thought_chain
         self.client = client
-        # 多模型路由:优先用注入的 router;否则惰性创建(自动探测可用模型)
         if router is None:
             from ..core.model_router import ModelRouter
             router = ModelRouter()
         self.router = router
         self.data_dir = data_dir
 
-        # 独立 Harness
         self.harness = Harness(
             agent_id=self.AGENT_ID,
             thought_chain=thought_chain,
@@ -121,20 +127,12 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
             shadow_rounds=shadow_rounds,
             spine=spine,
         )
-        # 调度层(主管)豁免语义漂移拦截:接收任意输入是其本职,不算异常。
-        # 领域 Agent 保持语义拦截:执行业务时跑题(如财务去写诗)才该拦。
         self.harness.block_on_semantic = not getattr(self, "IS_ROUTER", False)
 
-        # 获取或创建 HMR Workspace
         self.workspace = hmr.get_workspace(self.AGENT_ID)
 
-        # 每任务会话状态改由 contextvars 承载(见文件顶部)。这里只需一个 per-实例 token
-        # 作为分槽 key;_session_id / _parent_node_id 是路由到 contextvar 的 property,
-        # 故 start_session / _think 里既有的读写代码完全无需改动。
         self._ctx_token = uuid.uuid4().hex
 
-        # 【P1-3】能力注册中枢:Agent 不再直接持有 search_runtime,而是按名惰性解析
-        # (打断 agents⇄search_runtime⇄agent_port⇄agents 的直接互持环)。
         self._caps = caps
 
     def search_internal(self, query: str, top_k: int = 5):
@@ -146,7 +144,7 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
             return None
         return rt.search(query, agent_id=self.AGENT_ID, internal_only=True)
 
-    def available_abilities(self, keys: list = None) -> list:
+    def available_abilities(self, keys: list | None = None) -> list:
         """【HKC 第2档 Step2·能力自省】证据驱动地查 HKC 的 ACE 能力:哪些的知识覆盖已达标
         (可编译 sufficient=True)、哪些还差(sufficient=False + missing_skills)。
 
@@ -170,14 +168,12 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
                 out.append({"ability_key": ab.ability_key, "display_name": ab.display_name,
                             "domain": ab.domain, "sufficient": True, "coverage": ab.coverage})
             except Exception as e:
-                if hasattr(e, "missing_skills"):     # 覆盖不足=证据 gate(非错误)
+                if hasattr(e, "missing_skills"):
                     out.append({"ability_key": key, "sufficient": False,
                                 "coverage": getattr(e, "coverage", {}),
                                 "missing_skills": getattr(e, "missing_skills", [])})
-                # 其它异常(未知 key/图错误)→ 跳过该能力,不污染结果
         return out
 
-    # ── 每任务会话指针(contextvar 支撑,property 透明路由)──────
     @property
     def _session_id(self):
         return _agent_ctx_get(self._ctx_token).get("session_id")
@@ -194,23 +190,20 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
     def _parent_node_id(self, value):
         _agent_ctx_set(self._ctx_token, parent_node_id=value)
 
-    # ── 会话管理 ───────────────────────────────────────────
 
-    def start_session(self, goal: str, entities: list[str] = None) -> str:
+    def start_session(self, goal: str, entities: list[str] | None = None) -> str:
         """开始一个新任务会话，注册目标基线"""
         self._session_id = f"sess_{uuid.uuid4().hex[:10]}"
         self._parent_node_id = None
-        _taint_reset(self)   # 新会话从无污点起算(数据敏感度清零)
-        _evidence_reset(self)  # 新会话不继承上一个任务的执行证据(否则证据串台)
+        _taint_reset(self)
+        _evidence_reset(self)
 
-        # 注册 Harness 目标基线
         self.harness.register_goal(
             goal_text=goal,
             allowed_tool_categories=self.ALLOWED_TOOL_CATEGORIES,
             baseline_entities=set(entities or []),
         )
 
-        # 在 ThoughtChain 里记录目标基线节点
         goal_node = ThoughtNode.create(
             session_id=self._session_id,
             agent_id=self.AGENT_ID,
@@ -223,22 +216,14 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
         self.thought_chain.update_harness(goal_node.id, "BASELINE")
         self._parent_node_id = goal_node.id
 
-        # 【深审修复·移除惰性共享写】原先 `self.workspace.active_goal = goal` 把每任务目标
-        # 写到 per-Agent **共享**的 HMR workspace 上,同一 Agent 实例并发多任务会互相覆盖。
-        # 审计确认此写**完全惰性**:foxclaw 召回走显式 query(见 _recall_memory,从不读
-        # workspace.active_goal),save_workspace 从未被调用(不持久化),无测试依赖它——
-        # 故 race 零可观测影响。移除该误导性共享写:**每任务目标的权威来源**是会话隔离的
-        # ThoughtChain(goal 节点,session_id 经 contextvar 隔离)+ 事件驱动的 CognitiveState
-        # (execution.completed 的 active_goal)。共享单值 workspace 本就无法忠实承载 N 个并发目标。
         return self._session_id
 
-    # ── ThoughtChain + Harness 集成推理步骤 ───────────────
 
     def _reasoning_result(self, node):
         """经统一 PolicyGate 做推理准入,返回 HarnessResult(与直接 harness.check 逐字一致)。
         gate 经能力中枢惰性解析并缓存;无 gate(standalone/治理场景)则直接 harness.check。"""
-        gate = getattr(self, "_gate_cache", "unset")
-        if gate == "unset":
+        gate: Any = getattr(self, "_gate_cache", _GATE_UNSET)
+        if gate is _GATE_UNSET:
             caps = getattr(self, "_caps", None)
             gate = caps.get("policy_gate") if caps is not None else None
             self._gate_cache = gate
@@ -251,10 +236,10 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
         content: str,
         node_type="reasoning",
         conf: float = 0.9,
-        mem_refs: list[str] = None,
-        tool_name: str = None,
-        entities: list[str] = None,
-        metadata: dict = None,
+        mem_refs: list[str] | None = None,
+        tool_name: str | None = None,
+        entities: list[str] | None = None,
+        metadata: dict | None = None,
     ) -> tuple[ThoughtNode, HarnessResult]:
         """
         记录一个推理步骤，经过 Harness 校验
@@ -272,17 +257,14 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
             entities=entities or [],
             metadata=metadata,
         )
-        # 锁只护「链插入 + 父指针挪动」这两步共享状态;Harness 判定在锁外,避免钩子阻塞并发工具。
         with _THINK_LOCK:
             self.thought_chain.add_node(node)
 
-        # Harness 校验(经统一 PolicyGate 做推理准入;拿到的仍是同一 HarnessResult,行为一致)
         result = self._reasoning_result(node)
 
         if result.is_blocked:
             raise HarnessBlockedError(result, node)
 
-        # WARN：降低置信度但继续
         if result.is_warned:
             node.conf = max(node.conf - 0.15, 0.1)
 
@@ -364,8 +346,8 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
                              f"但无法提取为可读文本;若需要其内容,请说明并提示用户改用文本/PDF 等可读格式。")
         return "\n\n" + "\n\n".join(parts) if parts else ""
 
-    def stream_reply(self, task: str, stop_event=None, images: list = None, history: list = None,
-                     attachments: list = None, on_thinking=None, on_evidence=None):
+    def stream_reply(self, task: str, stop_event=None, images: list | None = None, history: list | None = None,
+                     attachments: list | None = None, on_thinking=None, on_evidence=None):
         """流式直答路径(方案A):对话/问答/分析,不做多步编排(那走 run_task)。同步生成器,
         由端点在线程池迭代成 SSE。stop_event 置位(客户端断连)则提前终止,省 token。
         images(可选)= 多模态图片,随问题发给视觉模型(模型无关,非视觉模型 router 层降级)。
@@ -386,7 +368,7 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
         from ..core import injection_guard as _ig
         from ..core.model_router import _chunk_text
         task = str(task or "")
-        _evidence_reset(self)      # 每轮从零开账:上一轮的证据不能冒充这一轮
+        _evidence_reset(self)
         if attachments:
             ctx = self._attachments_context(attachments)
             if ctx:
@@ -395,7 +377,7 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
         messages = hist + [{"role": "user", "content": task}]
         parts = []
         used_tools = False
-        guarded_out = False                       # 输出护栏是否触发(触发的污染回复不落库,防回流)
+        guarded_out = False
 
         def _emit_thinking(delta: str) -> None:
             """推理内容的最后一道关:思考也不许带密钥/系统提示原文(与正文同等级净化)。"""
@@ -411,26 +393,23 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
             try:
                 on_thinking(delta)
             except Exception:
-                pass                         # 前端断连/回调异常不得影响正文生成
+                pass
 
         if _tools.tool_use_enabled() and self.router.supports_tools() and not images:
-            # 与 fallback 一致地注入偏好/技能/能力(否则开工具化会静默丢掉"总是注入偏好"的保证、
-            # 丢掉 SKILL.md 与能力知识)。**唯独不做 web_augment**——联网交给 LLM 自主调 web_search 工具。
             try:
                 tmsgs = self._ability_augment(task, messages)
                 tmsgs = self._skill_augment(task, tmsgs)
                 tmsgs = self._pref_augment(tmsgs)
             except Exception:
                 tmsgs = messages
-            _compact = getattr(self, "_compact_context", None)   # 轻量替身对象无此方法
+            _compact = getattr(self, "_compact_context", None)
             if _compact is not None:
                 tmsgs = _compact(tmsgs, "tools")
             try:
                 final = self._reply_with_tools(task, tmsgs, stop_event=stop_event)
             except Exception:
                 final = None
-            if final is not None:                # None = 端点不支持 → 落到 fallback
-                # 工具路径有完整文本 → 流出前兜底(密钥脱敏/拦系统提示 dump);传 kernel 用逐字串比对更准
+            if final is not None:
                 final, _oiss = _ig.guard_output(final, kernel=KERNEL_PROMPT)
                 guarded_out = bool(_oiss)
                 used_tools = True
@@ -439,25 +418,23 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
                         break
                     parts.append(chunk)
                     yield chunk
-        if not used_tools:                        # fallback:关键词增强链 + 真流式(行为逐字不变)
+        if not used_tools:
             try:
-                messages = self._web_augment(task, messages)   # 增强都合并进"最后一条 user",历史不受影响
+                messages = self._web_augment(task, messages)
                 messages = self._ability_augment(task, messages)
                 messages = self._skill_augment(task, messages)
                 messages = self._pref_augment(messages)
             except Exception:
                 messages = hist + [{"role": "user", "content": task}]
-            _compact = getattr(self, "_compact_context", None)   # 轻量替身对象无此方法
+            _compact = getattr(self, "_compact_context", None)
             if _compact is not None:
                 messages = _compact(messages, "chat")
-            _tail = ""   # 滑窗尾缓冲:跨 chunk 边界的泄露检测只扫最近 _WIN 字,不再整段重扫(消 O(n²))
-            _WIN = 256   # 覆盖最长敏感串(密钥)跨 chunk 边界的情况
+            _tail = ""
+            _WIN = 256
             for chunk in self.router.stream(self.system_prompt, messages,
                                             agent_id=self.AGENT_ID, stop_event=stop_event,
                                             images=images,
                                             on_thinking=_emit_thinking if on_thinking else None):
-                # 流出前检测(而非"yield 后才检测"):密钥/泄露所在 chunk 不再已发给用户才中断。
-                # 只扫"尾缓冲 + 新 chunk"(增量滑窗),命中则本 chunk 不发、整段 dump 止于此。
                 _probe = _tail + chunk
                 if _ig.scan_output(_probe):
                     guarded_out = True
@@ -471,26 +448,19 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
                 yield _notice
         reply = "".join(parts)
         stopped = stop_event is not None and stop_event.is_set()
-        # 执行证据在正文之后一次性上报(晚于 delta、早于 done):前端拿到时答案已完整,
-        # 可以挂在答案下方供人核对;没有工具步的纯对话不产生任何证据事件。
         if on_evidence is not None:
             try:
                 _evs = _evidence_take(self)
                 if _evs:
                     on_evidence(_evs)
             except Exception:
-                pass                       # 证据上报失败不得影响已生成的回答
-        # 落库前最终兜底(仅 fallback 路径需要):fallback 增量检查(无 kernel、只抓明显 dump)可能漏过
-        # 逐字复现的系统提示,这里用 kernel 逐字串比对再判一次,命中则不落库(防污染回流),不影响已流给
-        # 用户的内容。工具路径在流出前已 guard_output(kernel) 完整防护,无需重复扫(消冗余)。
+                pass
         if reply and not guarded_out and not used_tools and _ig.scan_output(reply, kernel=KERNEL_PROMPT):
             guarded_out = True
         try:
             self._think(content=("流式直答:" + reply)[:500], node_type="reflection", conf=0.8)
         except Exception:
             pass
-        # 活动可观测:对话路径此前**不发任何事件** → /bus/history 恒空、前端"活动"页永远没内容
-        # (run_task 走 _emit_execution 会发,但直答/流式对话不经那条路)。这里补一条同源事件。
         try:
             _caps = getattr(self, "_caps", None)
             _spine = _caps.get("event_spine") if _caps is not None else None
@@ -503,12 +473,6 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
                 }, source=self.AGENT_ID)
         except Exception:
             pass
-        # 写入记忆(与 /api/task 一致;MCP 场景由 _suppress_memory 兜住);断连中止/触发输出护栏则不写
-        #
-        # A 类修复:故障降级回复**禁止写入长期记忆** —— 把「模型失败/未执行」当成
-        # 「对话结论」沉淀,会让 HMR 后续召回持续复读故障文案(一次故障 → 长期污染)。
-        # 判据用 take_call_degraded()(per-call)而非全局 is_stub:is_stub=True 是
-        # 「从未配置模型」的离线态,那个场景下记录任务/占位仍有诊断价值,不该一刀切。
         _degraded = False
         try:
             _degraded = bool(self.router.take_call_degraded())
@@ -516,13 +480,12 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
             _degraded = False
         if reply and not stopped and not guarded_out and not _degraded:
             try:
-                safe_reply = _ig.redact_secrets(reply)   # 落库同样脱敏,防密钥沉进长期记忆
+                safe_reply = _ig.redact_secrets(reply)
                 self._store_memory(f"对话:{task} → {safe_reply}"[:800], mem_type="conversation")
             except Exception:
                 pass
-            self._maybe_store_preference(task)   # 对话里的偏好表达 → 持久记(preference 类型)
+            self._maybe_store_preference(task)
         elif _degraded and reply and not stopped:
-            # 降级:只留事件痕迹(可观测、可归因),不写记忆内容
             try:
                 _spine = _caps.get("event_spine") if _caps is not None else None
                 if _spine is not None:
@@ -534,12 +497,8 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
             except Exception:
                 pass
 
-    # ── 统一任务生命周期(模板方法,P1:5 个 run_task 收敛为 1)──────
-    # 领域 Agent 不再各自重写 run_task,只实现 _execute()(召回后的领域步骤)。
-    # 会话开启、记忆召回、返回体结构、Harness 拦截处理都在此**唯一**定义,
-    # 保证所有 Agent 生命周期一致(修复"每 Agent 各写一份、行为漂移")。
 
-    _recall_topk: int = 5   # 召回条数(office 覆盖为 8)
+    _recall_topk: int = 5
 
     def _task_entities(self, task: str) -> list:
         """本任务的基线实体(用于 Harness 目标基线)。领域 Agent 覆盖。"""
@@ -549,12 +508,6 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
         """记忆召回查询(领域 Agent 可加前缀,如财务/行程)。默认用原任务。"""
         return task
 
-    # ── 【P1-1】任务生命周期钩子 ────────────────────────────────
-    # 崩溃/重启恢复记账(RestartRecovery)。会话开启后、管线执行前触发 started;任务终结时
-    # 触发 settled(done=正常终态含 Harness 兜底/中断;failed=未兜底异常)。run_task 与
-    # run_task_stream 共用 _run_task_core,故两条路径都会触发。
-    # 实现放在基类(而不是只让主管覆盖):P1-1 时只有主管接了线,领域 Agent 跑一半崩掉
-    # 在恢复扫描里根本不可见。没有 _recovery 的 standalone/测试 Agent → 直接跳过。
     def _on_session_started(self, session_id: str, task: str, context: dict) -> None:
         """会话已开、管线未跑:落 task_started(崩溃后才认得出"上次跑到一半")。"""
         rec = getattr(self, "_recovery", None)
@@ -618,7 +571,7 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
             pipe = self._pipeline_cache = CognitivePipeline(DEFAULT_STAGES)
         return pipe
 
-    async def run_task(self, task: str, context: dict = None, stop_event=None) -> dict:
+    async def run_task(self, task: str, context: dict | None = None, stop_event=None) -> dict:
         """统一任务生命周期:开会话 → [认知管线:recall → act] → 组装返回。
         Harness BLOCK 统一在此兜底为结构化错误。返回
         {"result",...,"session_id","agent","thought_summary", **extra}。
@@ -633,7 +586,7 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
         说明续了哪一次、复用了多少步。"""
         return await self._run_task_core(task, context, stop_event=stop_event, on_stage=None)
 
-    async def _run_task_core(self, task: str, context: dict = None,
+    async def _run_task_core(self, task: str, context: dict | None = None,
                              stop_event=None, on_stage=None) -> dict:
         """run_task 的执行核心 —— 供同步 `run_task` 与流式 `run_task_stream` **共用**,避免两份
         生命周期逻辑漂移。`on_stage`(D1):逐 stage 进度回调,透传给管线;None=同步路径不回调,
@@ -641,29 +594,18 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
         from ..pipeline import PipelineContext
         context = context or {}
         session_id = self.start_session(goal=task, entities=self._task_entities(task))
-        # 来源可信性:渠道入口会带 untrusted_source=True(见 channels/dispatcher)。本任务里的
-        # 写/发送/外发动作据此强制 HITL;本地 HTTP 对话不带此键 → 行为逐字不变。
         _untrusted_set(self, bool(context.get("untrusted_source")))
-        # 【P1-1】生命周期钩子:会话已开、管线未跑。默认 no-op;主管借此做崩溃/重启
-        # 恢复记账(task_started)——恢复记账需先于执行落日志,故必须在管线之前。
         self._on_session_started(session_id, task, context)
-        # E2:pre_reasoning(agent_start)钩子——推理开始前触发,可注入 additionalContext(前插进 act
-        # 的 LLM 上下文,见 _call_llm)。默认无钩子/无注入 → 行为逐字不变。hooks 由 Foxclaw 装配注入;
-        # standalone/测试 Agent 无 hooks 属性 → getattr None → 整个钩子逻辑跳过。
         _hooks = getattr(self, "hooks", None)
         _inject_parts = []
         if _hooks is not None:
             _hr = _hooks.fire("agent_start", "", {"task": task, "agent_id": self.AGENT_ID})
             if _hr.additional_context:
                 _inject_parts.append(_hr.additional_context)
-        _pref = self._prefs_context()          # 偏好优先注入(独立于语义 query → 每次推理总是注入)
+        _pref = self._prefs_context()
         if _pref:
             _inject_parts.append(_pref)
-        # 偏好 + agent_start 钩子上下文合并进同一 _reasoning_inject → _call_llm 前插(复用 E2 机制)
         _inject_tok = _reasoning_inject.set("\n\n".join(_inject_parts)) if _inject_parts else None
-        # 【P1 断点续跑】context={"_resume_task_id": <上次的 task_id/session_id>} 时,把上次
-        # 已完成的工具步骤装进 contextvar(root_key→结果):工具轮命中同指纹步骤直接复用结果、
-        # 不再重复执行。opt-in——不带该键 → 不装载、行为逐字不变。
         _resume_tid = str(context.get("_resume_task_id") or "").strip()
         _resume_cache = self._load_resume_cache(_resume_tid) if _resume_tid else {}
         _resume_tok = _resume_steps.set(_resume_cache) if _resume_cache else None
@@ -685,19 +627,14 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
                 "thought_summary": self.thought_chain.get_summary(self.AGENT_ID),
                 **(ctx.extra or {}),
             }
-            _plan = _plan_payload(ctx)   # 计划可见:阻塞路径也回传,客户端无需再猜步骤
+            _plan = _plan_payload(ctx)
             if _plan:
                 resp["plan"] = _plan
-            if _resume_cache:        # 续跑透明化:告诉调用方"用了几个已完成步骤、从哪续的"
+            if _resume_cache:
                 resp["resumed_from"] = _resume_tid
                 resp["resumed_steps"] = len(_resume_cache)
-            if ctx.interrupted:      # P3:被 stop_event 提前中断 → 让调用方识别"部分完成"
+            if ctx.interrupted:
                 resp["interrupted"] = True
-            # 【A·Step3·确认闸提升】act 若经 skill dispatch 且未成功(needs_confirmation/blocked/
-            # circuit_open/error),把该态提升为 run_task **顶层 status**,让调用方无需深挖 result
-            # 即可识别"待确认/未完成动作";needs_confirmation 附 pending_action(供确认后带
-            # _confirmed 重跑恢复执行)。**未完成 ⇒ 不作为已完成真值沉淀**(blocked=True,呼应
-            # "被拦截任务不沉淀记忆");成功/纯 LLM 路径行为逐字不变。
             skill_status = (ctx.extra or {}).get("skill_status")
             skill_incomplete = bool(skill_status) and skill_status != "done"
             if skill_incomplete:
@@ -711,41 +648,35 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
                         "hint": "确认后带 context={'_confirmed': <skill_id>, ...} 重跑本任务以执行"
                                 "(绑定到 skill_id 更安全;_confirmed=True 为概括确认)",
                     }
-            # 「未完成 ⇒ 不作为已完成真值沉淀」的 blocked 判定,须同时覆盖两类未完成:
-            #   ① skill 未成功(needs_confirmation/blocked/circuit_open/error);
-            #   ② 被 stop_event **中断**(B3 深审 G2):流式任务客户端断连 → 中断,ctx.result 只是
-            #      部分/空产物,绝不能当"已完成真值"沉淀进 HMR 共享记忆(呼应 P5/Principle07)。
-            #      P3 引入 interrupted 时未联动此处;B3 的 /api/task/stream 是首个真正会 set stop_event
-            #      的生产调用方,才使这条路径可达。非中断路径 blocked 值与改前逐字一致。
             blocked = skill_incomplete or ctx.interrupted
             self._emit_execution(task, ctx.result, blocked=blocked, context=context)
-            self._maybe_store_preference(task)   # 用户偏好表达 → 持久记(preference 类型,下次总是注入)
-            if _hooks is not None:   # E2:task_complete(agent_end)——任务完成后只读观测/上报(对应范式 Stop)
+            self._maybe_store_preference(task)
+            if _hooks is not None:
                 _hooks.fire("agent_end", "", {"task": task, "agent_id": self.AGENT_ID,
                                               "result": resp.get("result"),
                                               "interrupted": bool(ctx.interrupted)})
-            self._on_task_settled(session_id, "done")   # 【P1-1】正常终态(含中断/被拦提升)
+            self._on_task_settled(session_id, "done")
             return resp
         except HarnessBlockedError as e:
             self._emit_execution(
                 task, {"error": "harness_blocked", "reason": e.result.reason},
                 blocked=True, context=context)
-            if _hooks is not None:   # task_complete 也覆盖被拦截结束(带 error 供上报)
+            if _hooks is not None:
                 _hooks.fire("agent_end", "", {"task": task, "agent_id": self.AGENT_ID,
                                               "error": "harness_blocked"})
-            self._on_task_settled(session_id, "done")   # 被拦截是已兜底的正常终态(非崩溃)
+            self._on_task_settled(session_id, "done")
             return {"error": "harness_blocked", "reason": e.result.reason,
                     "session_id": session_id}
         except Exception:
-            self._on_task_settled(session_id, "failed")  # 【P1-1】未兜底异常 → failed(供恢复)
+            self._on_task_settled(session_id, "failed")
             raise
         finally:
             if _inject_tok is not None:
-                _reasoning_inject.reset(_inject_tok)   # 复位注入 contextvar,不泄漏到后续任务
+                _reasoning_inject.reset(_inject_tok)
             if _resume_tok is not None:
-                _resume_steps.reset(_resume_tok)       # 续跑缓存不泄漏到后续任务
+                _resume_steps.reset(_resume_tok)
 
-    def run_task_stream(self, task: str, context: dict = None, stop_event=None):
+    def run_task_stream(self, task: str, context: dict | None = None, stop_event=None):
         """流式任务执行(D1):**同步 generator**,逐 stage 吐进度 + act 逐 token 出字 + 最终结果。
         产出事件(dict,逐条给 SSE):
           {"stage": name}   每完成一个认知 stage(perceive→…→reflect)
@@ -769,7 +700,7 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
 
         def _on_stage(name, _ctx):
             bridge.put({"stage": name})
-            if name == "plan":               # 计划显式化:steps 随事件送给前端/调用方
+            if name == "plan":
                 _plan = _plan_payload(_ctx)
                 if _plan:
                     bridge.put({"plan": _plan})
@@ -783,11 +714,11 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
                 resp = _asyncio.run(self._run_task_core(
                     task, context, stop_event=stop_event, on_stage=_on_stage))
                 bridge.put({"result": resp})
-            except Exception as e:                 # 核心已兜底 HarnessBlock;此处兜其余意外
+            except Exception as e:
                 bridge.put({"error": str(e)})
             finally:
                 _act_stream.reset(token)
-                bridge.put(_SENTINEL)              # 结束哨兵:保证 generator 必定收尾
+                bridge.put(_SENTINEL)
 
         _threading.Thread(target=_worker, daemon=True, name="task-stream").start()
         while True:
@@ -824,7 +755,6 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
         (路由分发由 supervisor_stages 的 dispatch stage 承担),不会走到本钩子。"""
         raise NotImplementedError(f"{self.AGENT_ID} 未实现 _execute()")
 
-    # ── 编排协作接口(P3:领域知识归属领域 Agent,编排层只做通用聚合/路由)──────
     def situation(self) -> dict:
         """本 Agent 的领域态势:声明自己的 domain + 状态 + 告警。默认无领域态势。
         领域 Agent 覆盖。编排层据此**通用聚合**,不需懂任何领域内部 API。
@@ -849,7 +779,6 @@ class CognitiveAgent(AugmentMixin, LlmMixin, MemoryMixin,
         req.status = "approved"
         req.verdict = "无需特殊审批"
 
-    # ── 通用状态查询 ───────────────────────────────────────
 
     def get_status(self) -> dict:
         return {

package/python/foxclaw/agents/impl/_helpers.py

@@ -2,10 +2,8 @@
 
 from ...core.dispatch import dispatch_failed as _dispatch_failed  # noqa: F401  (re-export)
 
-# ── 多步链式上下文 ────────────────────────────────────────────
-# 注入的前序步数与单步字符必须封顶:长链会把提示词越滚越大(且越往后越贵/越容易超窗)。
-PRIOR_MAX_STEPS = 3      # 只带最近 N 步(更早的通常已被后续步骤消化)
-PRIOR_MAX_CHARS = 300    # 单步输出截断
+PRIOR_MAX_STEPS = 3
+PRIOR_MAX_CHARS = 300
 
 
 def _with_prior(subtask: str, prior: list) -> str:
@@ -49,12 +47,6 @@ def _fmt_mem(m: dict, max_chars: int | None = None) -> str:
     return f"{head}：{content}" if head else content
 
 
-# ── P0-1 反思重规划:执行结果判定 ────────────────────────────
-# 实现已下沉到 core.dispatch(见文件头 import):pipeline 的 replan stage 也要用它,
-# 而 pipeline 不能反向 import agents —— 两处都只依赖 core,依赖方向单一。
-# `_dispatch_failed` 在此保留为 re-export,历史导入路径(agents.agents / impl.supervisor)不变。
-
-
 def _extract_step_results(dr) -> list:
     """从 dispatch_result 提取各步结果(供 LLM 反思:含成功/失败状态与输出)。"""
     if not isinstance(dr, dict):