foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/agents/mixins/augment.py

@@ -5,9 +5,13 @@
 import os
 
 from ._context import _taint_raise
+from typing import Any, Callable
 
 
 class AugmentMixin:
+    _think: Callable[..., Any]
+    available_abilities: Any
+    _call_llm: Callable[..., Any]
     def _web_augment(self, query: str, messages: list[dict]) -> list[dict]:
         """若问题含时效性,联网搜索并把结果注入 messages(放在用户问题前)。
         DeepSeek/OpenAI 等基础 API 不自带联网,这里用百度 AI 搜索补上。失败则原样返回。"""
@@ -19,9 +23,6 @@ class AugmentMixin:
             payload = _ws.search_answer(query)
             if not payload or (not payload.get("answer") and not payload.get("references")):
                 print("[联网搜索] ⚠ 无结果(未配 BAIDU_SEARCH_KEY 或网络不通)")
-                # 需要联网但没搜到(未配 key / 网络不通)→ 注入明确指令逼 LLM 如实说,绝不编造。
-                # 否则 LLM 被 system_prompt 告知"已接入联网"却拿不到结果,会凭训练数据瞎编版本号/
-                # 新闻/价格(用户实测踩到)。合并进最后一条 user 消息(与下方注入同法,不新增 user 消息)。
                 note = ("【系统提示:本次问题需要实时/最新信息,但联网搜索未返回任何结果"
                         "(可能未配置搜索服务或网络不可用)。请如实告知用户你暂时无法查询实时信息,"
                         "**切勿编造或凭记忆给出可能过时的答案**(如版本号、新闻、模型列表、价格等)。】")
@@ -39,9 +40,6 @@ class AugmentMixin:
                 content=f"联网搜索「{query}」命中,参考 {n} 条",
                 node_type="tool_use", conf=0.9,
             )
-            # 合并式注入:把联网上下文并进「最后一条 user 消息」,而不是前插一条独立
-            # user 消息 —— 后者会产生连续两条 user,某些 OpenAI-compatible 端点会拒绝,
-            # 与「模型无关」铁律冲突。拷贝后改,不动原 messages。
             merged = list(messages)
             for i in range(len(merged) - 1, -1, -1):
                 if merged[i].get("role") == "user":
@@ -49,14 +47,11 @@ class AugmentMixin:
                     m["content"] = ctx + "\n\n" + (m.get("content") or "")
                     merged[i] = m
                     return merged
-            return [{"role": "user", "content": ctx}] + merged   # 无 user 消息则退回前插
+            return [{"role": "user", "content": ctx}] + merged
         except Exception as e:
             print(f"[联网搜索] 异常: {e}")
             return messages
 
-    # 注:_model_augment 已删除 —— 模型身份注入规则化到 ModelRouter._runtime_context,
-    # 在 LLM 唯一咽喉(complete/stream)对每次调用恒定注入真实 provider/model,
-    # 不再靠"模型/大模型/llm"关键词命中才注入,也就没有了漏判/误判两难。
 
     def _ability_augment_enabled(self) -> bool:
         """能力知识增强是否启用。默认**关**(behavior-preserving)。
@@ -89,17 +84,16 @@ class AugmentMixin:
             if not hits:
                 return messages
             lines = "\n".join(f"- {h.name}: {h.summary}" for h in hits[:5])
-            # 知识由摄入的外部文档蒸馏而来,可能被投毒 → 包裹为不可信数据,防间接注入
             from ...core import injection_guard as _ig
             ctx = (f"【能力知识增强 · {best.get('display_name') or best['ability_key']}】"
                    f"以下是知识库中与本任务相关、且该能力已达覆盖的知识,供参考:\n"
                    + _ig.wrap_untrusted(lines, source="knowledge"))
             self._think(content=f"能力增强「{best['ability_key']}」注入 {len(hits)} 条知识",
                         node_type="tool_use", conf=0.85)
-            _taint_raise(self, _ig.taint_level("knowledge"))   # 知识库(个人数据)→ 会话污点
+            _taint_raise(self, _ig.taint_level("knowledge"))
             return [{"role": "user", "content": ctx}] + messages
         except Exception:
-            return messages   # fail-safe:增强失败绝不影响主流程
+            return messages
 
     def _skill_augment(self, query: str, messages: list[dict]) -> list[dict]:
         """按触发词匹配 SKILL.md 指令技能,把正文注入(合并进最后一条 user 消息)。"""
@@ -107,7 +101,7 @@ class AugmentMixin:
             reg = getattr(self, "md_skills", None)
             if not reg:
                 return messages
-            matched = reg.match(query)[:3]        # 触发词匹配,最多3条控 token
+            matched = reg.match(query)[:3]
             if not matched:
                 return messages
             ctx = "以下是可参照的操作指令(SKILL),请据此执行:\n\n" + \
@@ -144,6 +138,6 @@ class AugmentMixin:
         避免堵死 async 事件循环(否则百度慢/超时时整个服务、前端轮询全部冻住)。"""
         import asyncio
         aug = await asyncio.to_thread(self._web_augment, query, messages)
-        aug = await asyncio.to_thread(self._ability_augment, query, aug)   # Step3:opt-in 能力知识注入(默认关)
-        aug = await asyncio.to_thread(self._skill_augment, query, aug)     # SKILL.md 指令技能注入
+        aug = await asyncio.to_thread(self._ability_augment, query, aug)
+        aug = await asyncio.to_thread(self._skill_augment, query, aug)
         return await self._call_llm(aug, max_tokens=max_tokens)

package/python/foxclaw/agents/mixins/llm.py

@@ -3,9 +3,13 @@
 从 `foxclaw/agents/base.py` 搬移出来的 `_call_llm`。
 """
 from ._context import _reasoning_inject, _act_stream
+from typing import Any
 
 
 class LlmMixin:
+    AGENT_ID: str
+    router: Any
+    system_prompt: str
     async def _call_llm(
         self,
         messages: list[dict],
@@ -28,9 +32,6 @@ class LlmMixin:
         import asyncio
         inj = _reasoning_inject.get()
         if inj:
-            # 合并进**最后一条 user 消息**(与 _web_augment 同法),而非前插独立 user 消息——
-            # 后者会产生连续两条 user,某些 OpenAI-compatible 端点会拒绝,违反「模型无关」铁律
-            # (B4 审核 A3)。拷贝后改,不动原 messages。
             merged = list(messages)
             for i in range(len(merged) - 1, -1, -1):
                 if merged[i].get("role") == "user":
@@ -38,7 +39,7 @@ class LlmMixin:
                     merged[i] = m
                     break
             else:
-                merged = [{"role": "user", "content": str(inj)}] + merged   # 无 user 消息才独立前插
+                merged = [{"role": "user", "content": str(inj)}] + merged
             messages = merged
         sc = _act_stream.get()
         if sc is not None:
@@ -54,13 +55,13 @@ class LlmMixin:
                         try:
                             on_token(chunk)
                         except Exception:
-                            pass          # 单个 token 回调故障不中断收集
+                            pass
                 return "".join(parts)
 
             try:
                 return await asyncio.to_thread(_stream_collect)
             except Exception:
-                pass                      # 流式整体故障 → 落到下方非流式 complete(fail-safe)
+                pass
         return await asyncio.to_thread(
             self.router.complete,
             self.system_prompt, messages, max_tokens, self.AGENT_ID)

package/python/foxclaw/agents/mixins/memory.py

@@ -2,10 +2,16 @@
 
 从 `foxclaw/agents/base.py` 搬移出来的记忆相关方法。
 """
+from typing import Any, Callable
+
 from ._context import _suppress_memory
 
 
 class MemoryMixin:
+    AGENT_ID: str
+    hmr: Any
+    _think: Callable[..., Any]
+
     def _recall_memory(self, query: str, top_k: int = 5) -> list:
         """从 HMR 召回相关记忆，记录到 ThoughtChain"""
         from foxclaw.core.tracing import span as _span
@@ -24,7 +30,7 @@ class MemoryMixin:
     def _store_memory(self, content: str, mem_type: str = "concept", **kwargs):
         """存储新记忆到 HMR"""
         if _suppress_memory.get():
-            return   # MCP 外部驱动的任务:不写记忆(防污染)
+            return
         from foxclaw.core.tracing import span as _span
         with _span("memory.store", agent=self.AGENT_ID, type=mem_type):
             self.hmr.ingest(

package/python/foxclaw/agents/mixins/preference.py

@@ -3,10 +3,14 @@
 从 `foxclaw/agents/base.py` 搬移出来的偏好相关方法。
 """
 import os
+from typing import Any, Callable
 
 
 class PreferenceMixin:
-    # 注入近期偏好(不管当前 query),让"越用越懂你"真生效。默认开;FOXCLAW_PREF_CAPTURE=0 关采集。
+    AGENT_ID: str
+    hmr: Any
+    _think: Callable[..., Any]
+    _store_memory: Callable[..., Any]
     _PREF_MARKERS = ("我喜欢", "我不喜欢", "我讨厌", "我希望", "别再", "不要再", "以后都",
                      "以后请", "记住", "我的偏好", "我习惯", "下次请", "下次记得", "我倾向",
                      "请务必", "请一律", "总是用", "我要求")
@@ -20,16 +24,12 @@ class PreferenceMixin:
         t = (task or "").strip()
         if not t or not any(k in t for k in self._PREF_MARKERS):
             return
-        # 偏好通道消毒(防投毒):偏好每轮以"一律以此为准"的权威口吻注入,且无法像外部数据那样
-        # 包 <untrusted>(它本就该被遵循)。所以只能在**存入侧**拦——若这条"偏好"候选里夹带注入/
-        # 越权特征(如用户把含"忽略以上指令/系统覆盖"的文档粘进对话),就不固化,断掉投毒源头。
         from ...core import injection_guard as _ig
         if _ig.scan(t):
             self._think(content="偏好候选含疑似注入特征,已拒绝固化(防记忆投毒)",
                         node_type="reflection", conf=0.9)
             return
         try:
-            # 用 tag 标记(不受 memory_type 白名单降级);shared=True 跨会话跨 Agent 持久
             self._store_memory(f"用户偏好:{t[:200]}", mem_type="preference",
                                tags=["preference"], shared=True)
         except Exception:
@@ -44,9 +44,6 @@ class PreferenceMixin:
             return ""
         if not prefs:
             return ""
-        # prefs 已按"新→旧"排序(recall_by_tag)。偏好会随时间改变(如"最喜欢的颜色"从蓝改灰),
-        # 语义相似度无法区分同话题偏好(实测"颜色"与"回答风格"偏好都 ~0.9),故不能靠自动删旧;
-        # 改由指令让 LLM 以"最新的(最靠前)/当前对话最近说法"为准,避免被已更新的旧偏好带偏。
         lines = "\n".join(f"- {p.get('content', '')}" for p in prefs)
         return ("【用户偏好(按最近→最早排列)】\n" + lines +
                 "\n**注意:偏好会随时间改变。若上面几条彼此冲突,或与当前对话中用户最近的说法不一致,"
@@ -79,3 +76,56 @@ class PreferenceMixin:
             return self.hmr.delete_memory(pref_id)
         except Exception:
             return False
+
+    _NICK_PREFIXES = ("称呼我为", "叫我", "我的名字是", "我的名字叫")
+
+    def remember_preference(self, text: str) -> bool:
+        """写一条用户主动声明的偏好(设置面板 / 首次引导用)。返回是否落库。
+
+        与 `_maybe_store_preference`(对话里自动抓)的区别:这条不经过注入扫描,
+        因为来源是设置表单而非自由文本;但同样限长 200,避免把整段话塞进偏好。
+        """
+        t = (text or "").strip()
+        if not t:
+            return False
+        try:
+            self._store_memory(f"用户偏好:{t[:200]}", mem_type="preference",
+                               tags=["preference"], shared=True)
+            return True
+        except Exception:
+            return False
+
+    @classmethod
+    def _nick_of(cls, content: str) -> str | None:
+        """从一条 preference 文本里取出称呼;不是称呼类返回 None。"""
+        c = (content or "").strip()
+        if c.startswith("用户偏好:"):
+            c = c[len("用户偏好:"):].strip()
+        for prefix in cls._NICK_PREFIXES:
+            if c.startswith(prefix):
+                return c[len(prefix):].strip(" :：,，。.")
+        return None
+
+    def get_nickname(self) -> str:
+        """当前称呼(取最近一条称呼类偏好;没设置过返回空串)。"""
+        for p in self.list_preferences(limit=200):
+            nick = self._nick_of(p.get("content", ""))
+            if nick:
+                return nick
+        return ""
+
+    def set_nickname(self, nick: str) -> str:
+        """设置称呼;传空串 = 清除。返回生效后的值。
+
+        先把旧的称呼条目删掉再写:否则每改一次就多一条「称呼我为 X」,注入时
+        几条互相矛盾(虽然 prompt 里约定「以最新为准」,但没必要让它去猜)。
+        """
+        value = (nick or "").strip()[:24]
+        for p in self.list_preferences(limit=200):
+            if self._nick_of(p.get("content", "")):
+                pid = p.get("id")
+                if pid:
+                    self.delete_preference(pid)
+        if value:
+            self.remember_preference(f"称呼我为 {value}")
+        return value

package/python/foxclaw/agents/mixins/prompt.py

@@ -7,11 +7,6 @@ import os
 from abc import ABC, abstractmethod
 
 
-# ── 内核系统提示词(所有 Agent 共享前缀)────────────────────────────────────────
-# 见 docs/internal/FOXCLAW_SYSTEM_PROMPT.md。融合"认知操作系统"身份 + 系统性原理
-# (真相优先 / Principle 07 / 价值记忆)+ 安全边界(指令/数据隔离、最小权限、人在回路)。
-# 一处定义,base.system_prompt 统一叠加到各 Agent 角色职责之前 → 一处改全体生效。
-# §4 的 <untrusted> 规则与 core/injection_guard.wrap_untrusted 的打标配套,缺一不可。
 KERNEL_PROMPT = """你是 Foxclaw —— 一个面向 Agent 时代的认知操作系统,不是一次性问答机器人。
 你的使命:让信息成为知识,让知识成为能力;守护用户的知识火种,保持认知的连续性。
 以下是所有 Agent 共享的内核准则;你的具体角色职责见随后的说明。
@@ -59,7 +54,6 @@ KERNEL_PROMPT = """你是 Foxclaw —— 一个面向 Agent 时代的认知操
 
 
 class PromptMixin(ABC):
-    # ── 子类必须实现 ───────────────────────────────────────
 
     @property
     @abstractmethod

package/python/foxclaw/agents/mixins/skillbox.py

@@ -4,8 +4,12 @@
 助手降级为指令技能后,工具箱不能再绑在某个 Agent 上 —— 否则主管/财务/办公全都用不了技能,
 而"技能"恰恰是那两个下放的 Agent 的新家。故上移到 mixin,由基类统一混入。
 """
+from typing import Any, Callable
+
 
 class SkillBoxMixin:
+    _session_id: str | None
+    _think: Callable[..., Any]
     def attach_skills(self, registry, adapter):
         """挂载 skill 接入层(注册表 + 执行适配器)。"""
         self.skill_registry = registry
@@ -16,19 +20,18 @@ class SkillBoxMixin:
         reg = getattr(self, "skill_registry", None)
         return reg.catalog() if reg else []
 
-    def use_skill(self, task: str, args: dict = None, confirmed: bool = False) -> dict:
+    def use_skill(self, task: str, args: dict | None = None, confirmed: bool = False) -> dict:
         """按任务匹配 skill 并调用,结果回填 ThoughtChain,过守门人。"""
         reg = getattr(self, "skill_registry", None)
         adp = getattr(self, "skill_adapter", None)
         if not (reg and adp):
             return {"error": "skill 接入层未挂载"}
-        # 用升级版 router(三步打分 + 否定词检测),优于老的 reg.match 纯子串匹配
         try:
             from ...skills.pipeline import route as ahs_route
             r = ahs_route(task, reg)
             skill = reg.get(r.primary) if r.primary else None
         except Exception:
-            skill = reg.match(task)   # 兜底
+            skill = reg.match(task)
         if not skill:
             return {"matched": None, "message": "未匹配到合适的 skill"}
         self._think(
@@ -40,9 +43,6 @@ class SkillBoxMixin:
         from ._context import _taint_get, _untrusted_get
         token = set_loop_session(self._session_id)
         try:
-            # 会话已取回敏感数据(知识库/记忆/网页)后,技能的外发/副作用动作同样要二次确认——
-            # 此前技能路径不带污点,permission.evaluate 的 Stage 3.5 只对工具生效。
-            # 来源不可信(外部聊天渠道)时按同一口径抬到 TAINT_PERSONAL。
             _taint = _taint_get(self)
             if _untrusted_get(self):
                 _taint = max(_taint, _ig.TAINT_PERSONAL)

package/python/foxclaw/agents/mixins/tool_exec.py

@@ -15,8 +15,8 @@ import time
 from ._context import _taint_get, _taint_raise, _untrusted_get
 from ...core import settings
 from ...core.injection_guard import redact_obj, redact_secrets
+from typing import Any
 
-#: 同轮最多并发几个工具(再多也是网络等待,收益递减;避免打爆 provider/搜索服务)
 MAX_PARALLEL = 4
 
 
@@ -46,7 +46,7 @@ class _Spawn:
         def _run():
             try:
                 self.box["v"] = fn()
-            except BaseException as e:      # 统一交主线程降级成错误文本
+            except BaseException as e:
                 self.box["e"] = e
             finally:
                 self.done.set()
@@ -83,29 +83,19 @@ def _guard_tool(agent, name: str, args: dict):
     _reg = _tools.default_registry()
     if not _reg.has(name):
         return f"(未知工具 {name},未执行)", {}
-    # ── 参数校验(用注册表里同一份 JSON Schema)────────────────────
-    # 修复前:schema 只发给模型,执行侧不校验 → 模型给错类型/漏参数会直接流到
-    # 下游。且下方 permission Stage 1 因 params={} 恒不触发,只靠手工 if-not 兜。
-    # 新增校验闸后,错误**回注模型**让其自修正,而不是静默用空参数继续
-    # (那会让模型误以为工具已执行,进而编造基于"工具结果"的结论)。
     _errs = _reg.validate_args(name, args or {})
     if _errs:
         agent._think(content=f"工具 {name} 入参校验失败: {'; '.join(_errs)[:120]}",
                      node_type="tool_intent", conf=0.9)
         return (f"(工具 {name} 入参不合法: {'; '.join(_errs)}。"
                 f"请按工具声明修正参数后重试。)"), {}
-    # ── 权限管线:动作级闸门。构造 tool-spec 交四阶段裁决 ──
     cap = _tools.tool_capability(name)
-    # 传入真实 params schema,使 permission Stage 1(必填校验)真正生效,
-    # 不再依赖下游手工检查兜底。兼容 permission 的两种 params 格式。
     _schema = _reg.param_schema(name)
     _req = set(_schema.get("required") or [])
     _params = {k: {"required": k in _req, "type": v.get("type")}
                for k, v in (_schema.get("properties") or {}).items()
                if isinstance(v, dict)}
     spec = _types.SimpleNamespace(id=f"tool:{name}", params=_params, **cap)
-    # 来源不可信(外部聊天渠道 / 远程驱动)→ 按「已接触敏感数据」处理:写/发送/外发强制 HITL。
-    # 只读工具不受影响(污点分支只作用于副作用动作),所以读操作不会被这一条拖慢。
     _taint = _taint_get(agent)
     if _untrusted_get(agent):
         _taint = max(_taint, _ig.TAINT_PERSONAL)
@@ -115,7 +105,6 @@ def _guard_tool(agent, name: str, args: dict):
     if decision.decision == "deny":
         return f"(工具 {name} 被权限策略拒绝:{decision.reason},未执行)", cap
     if decision.decision == "ask":
-        # 红线/副作用/未声明工具 → 人在回路:不自动执行,交回由用户确认(KERNEL §6 同旨)
         agent._think(content=f"工具 {name} 需用户确认({decision.reason}),已暂停执行",
                      node_type="decision", conf=0.9)
         return (f"(工具 {name} 属于需确认的动作:{decision.reason}。按安全策略我不会自动执行——"
@@ -144,19 +133,17 @@ def _invoke_tool(agent, name: str, args: dict, taint_sink: list | None = None) -
             q = str((args or {}).get("query", "")).strip()
             if not q:
                 return "(web_search 缺少 query 参数)"
-            if _ws.is_personal_query(q):   # 私人账本/行程/记忆 → 绝不外发,让模型用本地信息答
+            if _ws.is_personal_query(q):
                 return "(该问题属于用户本地数据,已跳过联网;请依据本地领域信息回答)"
             payload = _ws.search_answer(q)
             if not payload or (not payload.get("answer") and not payload.get("references")):
                 return ("联网搜索未返回结果(可能未配置搜索服务或网络不可用);"
                         "请如实告知用户暂时无法查询实时信息,切勿编造版本号/新闻/价格等。")
             agent._think(content=f"工具 web_search「{q}」命中", node_type="tool_use", conf=0.9)
-            _raise(_ig.taint_level("web_search"))   # 外部不可控数据 → 会话污点
+            _raise(_ig.taint_level("web_search"))
             return _ws.format_for_prompt(q, payload)
         if name == "recall_memory":
             q = str((args or {}).get("query", "")).strip()
-            # top_k 此前硬编码 5,模型传值无效 → 加边界校验后尊重模型意图
-            # (schema 已声明 top_k,1-20;越界回落默认,防一次召回拉爆上下文)
             try:
                 top_k = max(1, min(20, int((args or {}).get("top_k", 5))))
             except Exception:
@@ -165,8 +152,7 @@ def _invoke_tool(agent, name: str, args: dict, taint_sink: list | None = None) -
             if not res:
                 return "(未召回到相关记忆)"
             lines = "\n".join(f"- {r.get('content', '')}" for r in res[:top_k])
-            # 记忆可能被投毒(此前注入固化) → 当作不可信数据回注,防记忆投毒二次生效
-            _raise(_ig.taint_level("memory"))   # 个人记忆 → 会话污点(高敏感)
+            _raise(_ig.taint_level("memory"))
             return "【召回的相关记忆】\n" + _ig.wrap_untrusted(lines, source="memory")
     except Exception as e:
         return f"(工具 {name} 执行异常:{type(e).__name__})"
@@ -179,7 +165,7 @@ def _timeout_text(name: str) -> str:
 
 
 def _merge_taint(agent, sink: list) -> None:
-    for lvl in sink:                      # 只在主线程动会话污点(单调取 max)
+    for lvl in sink:
         try:
             _taint_raise(agent, lvl)
         except Exception:
@@ -221,8 +207,6 @@ def _run_tools_batch(agent, calls: list) -> list:
             if p[2] is not None:
                 out.append(p[2])
                 continue
-            # 串行走 agent._dispatch_tool(保留「实例级覆盖」这一扩展点,单测常这么替身);
-            # 没有该方法时才直接执行。
             _disp = getattr(agent, "_dispatch_tool", None)
             out.append(_disp(p[0], p[1]) if callable(_disp)
                        else _exec_guarded(agent, p[0], p[1]))
@@ -237,7 +221,7 @@ def _run_tools_batch(agent, calls: list) -> list:
     for n, sp, sink in spawns:
         left = max(0.0, timeout - (time.monotonic() - started))
         try:
-            ok, val = sp.wait(left)        # 各自独立计时:一个超时不拖累已完成的
+            ok, val = sp.wait(left)
         except Exception as e:
             out.append(f"(工具 {n} 执行异常:{type(e).__name__})")
             continue
@@ -249,7 +233,6 @@ def _run_tools_batch(agent, calls: list) -> list:
     return out
 
 
-#: checkpoint 里单步结果最多存多少字符(超出即标记 truncated,续跑时不复用、改为重跑)
 _STEP_RESULT_MAX = 4000
 
 
@@ -337,8 +320,6 @@ def _settle(agent, call: dict, result: str) -> str:
     text, kind = _apply_failure_policy(agent, call, result)
     try:
         cap = _tools.tool_capability(name)
-        # 核验看的是**工具原始返回**,不是我们追加过提示的文本 —— 否则提示里的
-        # "超时/未完成"字样会反过来影响判定。
         v = _verify.verify(name, args, result, cap)
         note = _verify.note_for_model(v, read_only=bool(cap.get("read_only")))
         if note:
@@ -347,12 +328,10 @@ def _settle(agent, call: dict, result: str) -> str:
             "tool": name, "kind": kind, "status": v.status,
             "reason": v.reason, "evidence": [e.to_dict() for e in v.evidence],
         })
-        # 判定"可复用"以核验结论为准,而不是文本开头是不是 "(" ——
-        # 失败文本追加提示后就不再以 "(" 开头,靠形态判会把它当成功存进断点。
         if v.status != _verify.FAILED and _step_ok(result):
             _record_step(agent, call, result)
     except Exception:
-        pass                              # 核验/记账失败不影响工具结果本身
+        pass
     return text
 
 
@@ -381,8 +360,9 @@ def _run_tool_calls(agent, calls: list) -> list:
 
 
 class ToolExecMixin:
-    # 以下四个方法均为薄包装:真实 agent 走 self.xxx;单测可用 SimpleNamespace 直接调
-    # 模块级函数或 `CognitiveAgent._dispatch_tool(fake, ...)`(鸭子类型)。
+    AGENT_ID: str
+    router: Any
+    system_prompt: str
     def _guard_tool(self, name: str, args: dict):
         return _guard_tool(self, name, args)
 
@@ -414,30 +394,24 @@ class ToolExecMixin:
             return None
         conv = list(messages)
         for _ in range(max_rounds):
-            # 上下文预算:工具轮每轮追加 assistant.tool_calls + tool 结果,不压会撑爆窗口
-            # (Compactor 保证 tool_calls 与其结果同进同出,缺口见 core/compaction.py:100)。
-            # getattr 兜底:本 mixin 也被只实现 router 的轻量对象复用(_compact_context
-            # 定义在 CognitiveAgent 上),缺该方法时退化为不压缩。
             _compact = getattr(self, "_compact_context", None)
             if _compact is not None:
                 conv = _compact(conv, "tool_loop")
             if stop_event is not None and stop_event.is_set():
-                return None                      # 断连 → None(回退;fallback 也会因 stop 立即终止)
+                return None
             res = self.router.call_tools(self.system_prompt, conv, schemas,
                                          agent_id=self.AGENT_ID)
             if not res.get("supported"):
-                return None                      # 端点实际不支持 tools → fallback
+                return None
             calls = res.get("tool_calls") or []
             if not calls:
-                return res.get("text") or None   # 模型直接给出最终答案;空答 → None → fallback(不再空回复不回退)
+                return res.get("text") or None
             conv.append(res["assistant_msg"])
-            # 只读并发 / 写串行 / 单工具带超时 + 每步 checkpoint + 续跑复用已完成步骤
             results = _run_tool_calls(self, calls)
             for c, result in zip(calls, results):
                 conv.append(self.router.format_tool_result(c, result))
-        # 轮数超限 → 强制不再调工具、收敛出文本答案
         final = self.router.call_tools(self.system_prompt, conv, schemas,
                                        tool_choice="none", agent_id=self.AGENT_ID)
         if not final.get("supported"):
-            return None                          # 收敛调用失败 → fallback(不再空回复不回退)
-        return final.get("text") or None         # 收敛出空答 → None → fallback
+            return None
+        return final.get("text") or None