echotools 2.3.99__tar.gz → 2.3.103__tar.gz

{echotools-2.3.99 → echotools-2.3.103}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echotools
-Version: 2.3.99
+Version: 2.3.103
 Summary: 通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链
 Home-page: https://github.com/nichengfuben/echotools
 Author: nichengfuben

{echotools-2.3.99 → echotools-2.3.103}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "echotools"
-version = "2.3.99"
+version = "2.3.103"
 description = "通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -76,7 +76,7 @@ ignore = ["E501", "E402"]
 known-first-party = ["echotools"]
 
 [tool.mypy]
-python_version = "3.8"
+python_version = "3.10"
 warn_return_any = true
 warn_unused_ignores = true
 disallow_untyped_defs = false
@@ -91,6 +91,8 @@ disable_error_code = [
     "arg-type",
     "attr-defined",
     "var-annotated",
+    "has-type",
+    "misc",
 ]
 
 [[tool.mypy.overrides]]
@@ -101,6 +103,10 @@ ignore_errors = true
 module = "echotools.media.console.*"
 ignore_errors = true
 
+[[tool.mypy.overrides]]
+module = "echotools.exec.fncall.parsers.*"
+disable_error_code = ["has-type", "misc", "return-value"]
+
 [tool.pytest.ini_options]
 testpaths = ["src/tests"]
 pythonpath = ["src", "src/tests"]

{echotools-2.3.99 → echotools-2.3.103}/src/echotools/exec/fncall/parsers/stream.py

@@ -23,8 +23,8 @@ def _make_thinking_filter(protocol: ToolProtocol, *, thinking_enabled: bool = Tr
     return None
 
 
-from echotools.exec.fncall.parsers.stream_feed import StreamFeedMixin
 from echotools.exec.fncall.parsers.stream_delta import StreamDeltaMixin
+from echotools.exec.fncall.parsers.stream_feed import StreamFeedMixin
 from echotools.exec.fncall.parsers.stream_final import StreamFinalMixin
 
 
@@ -101,7 +101,9 @@ class FncallStreamParser(StreamFeedMixin, StreamDeltaMixin, StreamFinalMixin):
         return self._schema_index
 
     def _get_known_tool_names(self):
-        from echotools.exec.fncall.protocols.entml_patterns import resolve_known_tool_names
+        from echotools.exec.fncall.protocols.entml_patterns import (
+            resolve_known_tool_names,
+        )
 
         return resolve_known_tool_names(self._tools, self._get_schema_index())
 

{echotools-2.3.99 → echotools-2.3.103}/src/echotools/exec/fncall/parsers/stream_feed.py

@@ -1,8 +1,6 @@
 """FncallStreamParser waiting/feed helpers."""
 from __future__ import annotations
 
-from typing import Any, Dict, List, Optional, Tuple
-
 
 class StreamFeedMixin:
     def _normalize_stream_chunk(self, text: str) -> str:

{echotools-2.3.99 → echotools-2.3.103}/src/echotools/exec/fncall/parsers/stream_final.py

@@ -1,7 +1,7 @@
 """FncallStreamParser finalize / partial display helpers."""
 from __future__ import annotations
 
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Tuple
 
 
 class StreamFinalMixin:
@@ -13,11 +13,8 @@ class StreamFinalMixin:
         """与 batch ``parse`` 一致：未闭合 thinking 之后的正文不参与可见/剥离。"""
         from echotools.exec.fncall.protocols.entml_think.parse import (
             clean_stream_partial_visible,
-            stream_safe_visible_prefix,
-        )
-
-        from echotools.exec.fncall.protocols.entml_think.parse import (
             split_entml_thinking,
+            stream_safe_visible_prefix,
         )
 
         buf = stream_safe_visible_prefix(
@@ -34,12 +31,12 @@ class StreamFinalMixin:
 
     def _stream_display_text(self) -> str:
         """流式可见正文：在完整 raw 缓冲上剥离伪 history（保留 thinking 保护区）。"""
-        from echotools.exec.fncall.shared.history_markup import (
-            strip_fake_history_markup_for_display,
-        )
         from echotools.exec.fncall.protocols.entml_think.parse import (
             split_entml_thinking,
         )
+        from echotools.exec.fncall.shared.history_markup import (
+            strip_fake_history_markup_for_display,
+        )
 
         buf = self._stream_visible_buffer()
         if not buf:
@@ -52,14 +49,14 @@ class StreamFinalMixin:
 
     def _stream_partial_display_text(self) -> str:
         """流式 ``partial_text``：在 invoke 起点前截断 raw，保留尾部 holdback 空白。"""
-        from echotools.exec.fncall.shared.history_markup import (
-            strip_fake_history_markup_for_display,
-        )
         from echotools.exec.fncall.protocols.entml_think.parse import (
             clean_stream_partial_visible,
             split_entml_thinking,
             stream_safe_visible_prefix,
         )
+        from echotools.exec.fncall.shared.history_markup import (
+            strip_fake_history_markup_for_display,
+        )
 
         raw = self._raw_buf
         if not raw:

{echotools-2.3.99 → echotools-2.3.103}/src/echotools/exec/fncall/parsers/xml_parser.py

@@ -17,7 +17,7 @@ from echotools.exec.fncall.shared.coercion import (
     _coerce_param_value,
 )
 from echotools.exec.fncall.shared.normalization import normalize_tool_calls
-from echotools.exec.fncall.shared.xml_helpers import (
+from echotools.exec.fncall.shared.loop_detect import (
     _PROVIDER_BLOCK_RE,
     _PROVIDER_INVOKE_RE,
     _PROVIDER_PARAM_RE,

{echotools-2.3.99 → echotools-2.3.103}/src/echotools/exec/fncall/prompt/behavior_blocks.py

@@ -40,7 +40,7 @@ You think before answering even when the request appears trivial. When a request
 
 Depth scales with the request. Routine requests receive a short block. Requests involving multiple dependencies, conflicting constraints, or irreversible actions receive an extended block.
 
-Your default reply language to the user is Simplified Chinese. You switch languages only when the user explicitly requests a different language. The final line of every thinking block states the language of the reply that follows.
+Your default reply language to the user is Simplified Chinese. You switch languages only when the user explicitly requests a different language.
 
 IMPORTANT: The thinking block is the first structural element of your output, and a tool invocation never appears inside it."""
 

{echotools-2.3.99 → echotools-2.3.103}/src/echotools/exec/fncall/prompt/history.py

@@ -83,7 +83,7 @@ def _clean_entml_tags(content: str) -> str:
 # ---------------------------------------------------------------------------
 
 
-from echotools.exec.fncall.protocols.entml_invoke import format_entml_parameter_value
+from echotools.exec.fncall.protocols.entml_tool.invoke import format_entml_parameter_value
 
 
 def _render_parameter_value(v: Any) -> str:

echotools-2.3.103/src/echotools/exec/fncall/protocols/entml.py

@@ -0,0 +1,241 @@
+"""Entropy ML (entml) 协议实现。
+
+- 工具调用：<entml:invoke> / <entml:parameter>（legacy ``function_calls`` 外壳仅解析兼容）
+- 对话历史：<entml:conversation_history>
+- 当前用户消息：<current_user_message>
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from echotools.exec.fncall.protocols.entml_patterns import (
+    entml_invoke_open_may_be_streaming,
+    find_actionable_entml_invoke_open,
+    resolve_known_tool_names,
+    strip_actionable_entml_invoke_blocks,
+    strip_legacy_function_calls_wrapper,
+    strip_tool_entml_residue,
+)
+from echotools.exec.fncall.protocols.entml_schema import format_entml_tool_descs
+from echotools.exec.fncall.protocols.entml_tool.fakemarkup import strip_orphan_entml_close_tags
+from echotools.exec.fncall.protocols.entml_tool.invoke import (
+    format_entml_tool_calls,
+    parse_entml_tool_calls,
+)
+from echotools.exec.fncall.shared.coercion import _build_param_schema_index
+from echotools.exec.fncall.shared.entml_format import (
+    _parse_tool_call_args,
+    _render_tool_call_line,
+    _render_tool_history_block,
+    build_entml_render_prompt,
+    format_entml_conversation_history,
+    format_entml_current_user_message,
+    format_entml_functions_results,
+    format_tool_result_id_comment,
+    strip_entml_from_content,
+)
+from echotools.exec.fncall.shared.history_markup import strip_fake_history_markup
+from echotools.exec.fncall.shared.normalization import normalize_tool_calls
+from echotools.exec.protocol.base import ToolProtocol
+
+__all__ = [
+    "EntmlProtocol",
+    "format_entml_conversation_history",
+    "format_entml_current_user_message",
+    "format_entml_functions_results",
+    "format_tool_result_id_comment",
+    "strip_entml_from_content",
+]
+
+
+class EntmlProtocol(ToolProtocol):
+    """Entropy ML (entml) 格式工具调用协议适配器。"""
+
+    @property
+    def id(self) -> str:
+        return "entml"
+
+    _TRIGGER = "<entml:invoke>"
+    _TRIGGER_PREFIX = "<entml:invoke"
+    _LEGACY_WRAPPER_PREFIX = "<entml:function_calls"
+    _THINKING_PREFIX = "<entml:thinking"
+
+    def get_trigger_tags(self) -> List[str]:
+        return [
+            self._TRIGGER,
+            self._TRIGGER_PREFIX,
+            self._THINKING_PREFIX,
+            f"{self._THINKING_PREFIX}>",
+        ]
+
+    def normalize_stream_buffer(self, buffer: str) -> str:
+        return strip_legacy_function_calls_wrapper(buffer)
+
+    def get_stream_end_tags(self) -> List[str]:
+        return []
+
+    @staticmethod
+    def format_tool_descs(tools: List[Dict[str, Any]]) -> str:
+        return format_entml_tool_descs(tools)
+
+    def render_prompt(
+        self,
+        tool_descs: str,
+        lang: str,
+        user_system_prompt: str = "",
+        history_text: str = "",
+        loop_warning: str = "",
+        history_markup_warning: str = "",
+        current_user_message: Optional[str] = None,
+        protocol_options: Optional[Dict[str, Any]] = None,
+        history_has_tool_calls: bool = False,
+        functions_results_text: str = "",
+    ) -> str:
+        _ = (lang, history_has_tool_calls)
+        return build_entml_render_prompt(
+            tool_descs=tool_descs,
+            user_system_prompt=user_system_prompt,
+            history_text=history_text,
+            loop_warning=loop_warning,
+            history_markup_warning=history_markup_warning,
+            current_user_message=current_user_message,
+            protocol_options=protocol_options,
+            functions_results_text=functions_results_text,
+        )
+
+    def detect_start(
+        self,
+        buffer: str,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> Tuple[bool, int]:
+        schema_index = _build_param_schema_index(tools) if tools else None
+        known = resolve_known_tool_names(tools, schema_index)
+        invoke_pos = find_actionable_entml_invoke_open(buffer, known_names=known)
+        if invoke_pos < 0:
+            return (False, -1)
+        return (True, invoke_pos)
+
+    def find_fncall_hold_from(
+        self,
+        buffer: str,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> Optional[int]:
+        schema_index = _build_param_schema_index(tools) if tools else None
+        known = resolve_known_tool_names(tools, schema_index)
+        if find_actionable_entml_invoke_open(buffer, known_names=known) >= 0:
+            return None
+        hold: Optional[int] = None
+        legacy_pos = buffer.find(self._LEGACY_WRAPPER_PREFIX)
+        if legacy_pos >= 0:
+            close = buffer.find(">", legacy_pos)
+            if close < 0 and (hold is None or legacy_pos < hold):
+                hold = legacy_pos
+        invoke_pos = buffer.find(self._TRIGGER_PREFIX)
+        if (
+            invoke_pos >= 0
+            and entml_invoke_open_may_be_streaming(
+                buffer, invoke_pos, known_names=known
+            )
+            and (hold is None or invoke_pos < hold)
+        ):
+            hold = invoke_pos
+        return hold
+
+    def _find_complete_invoke_open(
+        self,
+        buffer: str,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> int:
+        schema_index = _build_param_schema_index(tools) if tools else None
+        known = resolve_known_tool_names(tools, schema_index)
+        return find_actionable_entml_invoke_open(buffer, known_names=known)
+
+    def parse(
+        self,
+        text: str,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        *,
+        include_tool_blocks: bool = True,
+        thinking_enabled: bool = True,
+    ) -> Tuple[str, List[Dict[str, Any]]]:
+        _ = include_tool_blocks
+        from echotools.exec.fncall.protocols.entml_think.parse import (
+            _find_earliest_thinking_open,
+            has_unclosed_entml_thinking,
+            split_entml_thinking,
+        )
+
+        schema_index = _build_param_schema_index(tools) if tools else None
+        parse_text, _thinking = split_entml_thinking(text, thinking_enabled=True)
+        unclosed_open_at = -1
+        if has_unclosed_entml_thinking(text, thinking_enabled=True):
+            unclosed_open_at, _ = _find_earliest_thinking_open(
+                text, thinking_enabled=True
+            )
+            if unclosed_open_at >= 0:
+                parse_text = text[:unclosed_open_at]
+        known = resolve_known_tool_names(tools, schema_index)
+        tool_calls = parse_entml_tool_calls(parse_text, tools, schema_index)
+        clean = text[:unclosed_open_at] if unclosed_open_at >= 0 else text
+        if thinking_enabled:
+            visible, _ = split_entml_thinking(clean, thinking_enabled=True)
+            clean = visible
+        clean, _ = strip_fake_history_markup(clean)
+        if tool_calls:
+            clean = strip_actionable_entml_invoke_blocks(clean, known_names=known)
+        clean = strip_tool_entml_residue(clean, known_names=known)
+        clean, _ = strip_orphan_entml_close_tags(clean)
+        return (clean, normalize_tool_calls(tool_calls, tools))
+
+    def parse_fragment(
+        self,
+        fragment: str,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> List[Dict[str, Any]]:
+        _, tool_calls = self.parse(fragment, tools)
+        return tool_calls
+
+    def clean_tags(self, content: str) -> str:
+        return strip_entml_from_content(content)
+
+    def clean_tool_tags(
+        self,
+        content: str,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> str:
+        schema_index = _build_param_schema_index(tools) if tools else None
+        known = resolve_known_tool_names(tools, schema_index)
+        cleaned = strip_tool_entml_residue(content, known_names=known)
+        cleaned, _ = strip_fake_history_markup(cleaned)
+        return cleaned
+
+    def format_assistant_tool_calls(
+        self,
+        tool_calls: List[Dict[str, Any]],
+    ) -> str:
+        lines: List[str] = []
+        for tc in tool_calls:
+            name, args = _parse_tool_call_args(tc)
+            lines.append(_render_tool_call_line(name, args))
+        return "\n".join(lines)
+
+    def format_assistant_tool_turn_block(
+        self,
+        tool_calls: List[Dict[str, Any]],
+        tid_to_result: Dict[str, Dict[str, Any]],
+    ) -> str:
+        _ = tid_to_result
+        lines: List[str] = []
+        for tc in tool_calls:
+            invoke = format_entml_tool_calls([tc])
+            if invoke:
+                lines.append(invoke)
+            tid = tc.get("id") or ""
+            comment = format_tool_result_id_comment(tid)
+            if comment:
+                lines.append(comment)
+        return "\n".join(lines)
+
+    def supports_streaming(self) -> bool:
+        return True

echotools-2.3.103/src/echotools/exec/fncall/protocols/entml_patterns/__init__.py

@@ -0,0 +1,93 @@
+"""Regex patterns and helpers for entml invoke/parameter parsing."""
+from __future__ import annotations
+
+from ..entml_schema.mangled import (
+    mangled_json_param_tail_in_progress,
+    split_mangled_json_param_tail,
+)
+from .invoke import (
+    entml_invoke_open_is_actionable,
+    entml_invoke_open_may_be_streaming,
+    find_actionable_entml_invoke_open,
+    is_placeholder_invoke_name,
+    iter_actionable_entml_invoke_blocks,
+    resolve_known_tool_names,
+)
+from .params import (
+    extract_attr_value,
+    extract_parameter_type_attr,
+    find_valid_parameter_close,
+    inside_parameter_value,
+    invoke_structural_gap_text,
+    invoke_structural_gaps,
+    normalize_entml_name,
+    parameter_block_spans,
+    parameter_close_at,
+    parameter_value_spans,
+    parse_sub_tags,
+    strip_actionable_entml_invoke_blocks,
+    synthetic_close_invoke_body,
+)
+from .regex import (
+    BARE_INVOKE_CHILD_OPEN_RE,
+    BARE_INVOKE_CHILD_RE,
+    BLOCK_RE,
+    INVOKE_DIRECT_CHILD_OPEN_RE,
+    INVOKE_DIRECT_CHILD_RE,
+    INVOKE_DIRECT_CHILD_SKIP,
+    INVOKE_RE,
+    PARAM_CLOSE_BARE,
+    PARAM_CLOSE_ENTML,
+    PARAM_OPEN_PATTERN,
+    PARAM_RE,
+    PARAMETERS_RE,
+    SUB_TAG_RE,
+    _INVOKE_CLOSE,
+    _INVOKE_OPEN_PREFIX,
+    _PARAM_CLOSE_VALID_RE,
+    _PARAM_CLOSE_VALID_STREAM_RE,
+)
+from .strip import strip_legacy_function_calls_wrapper, strip_tool_entml_residue
+
+__all__ = [
+    "BARE_INVOKE_CHILD_OPEN_RE",
+    "BARE_INVOKE_CHILD_RE",
+    "BLOCK_RE",
+    "INVOKE_DIRECT_CHILD_OPEN_RE",
+    "INVOKE_DIRECT_CHILD_RE",
+    "INVOKE_DIRECT_CHILD_SKIP",
+    "INVOKE_RE",
+    "PARAM_CLOSE_BARE",
+    "PARAM_CLOSE_ENTML",
+    "PARAM_OPEN_PATTERN",
+    "PARAM_RE",
+    "PARAMETERS_RE",
+    "SUB_TAG_RE",
+    "_INVOKE_CLOSE",
+    "_INVOKE_OPEN_PREFIX",
+    "_PARAM_CLOSE_VALID_RE",
+    "_PARAM_CLOSE_VALID_STREAM_RE",
+    "entml_invoke_open_is_actionable",
+    "entml_invoke_open_may_be_streaming",
+    "extract_attr_value",
+    "extract_parameter_type_attr",
+    "find_actionable_entml_invoke_open",
+    "find_valid_parameter_close",
+    "inside_parameter_value",
+    "invoke_structural_gap_text",
+    "invoke_structural_gaps",
+    "is_placeholder_invoke_name",
+    "iter_actionable_entml_invoke_blocks",
+    "mangled_json_param_tail_in_progress",
+    "normalize_entml_name",
+    "parameter_block_spans",
+    "parameter_close_at",
+    "parameter_value_spans",
+    "parse_sub_tags",
+    "resolve_known_tool_names",
+    "split_mangled_json_param_tail",
+    "strip_actionable_entml_invoke_blocks",
+    "strip_legacy_function_calls_wrapper",
+    "strip_tool_entml_residue",
+    "synthetic_close_invoke_body",
+]

echotools-2.3.103/src/echotools/exec/fncall/protocols/entml_patterns/invoke.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Iterator, List, Optional, Set, Tuple
+
+from .params import extract_attr_value, normalize_entml_name
+from .regex import _INVOKE_CLOSE, _INVOKE_OPEN_PREFIX
+
+
+def is_placeholder_invoke_name(name: str) -> bool:
+    """提示词占位符（如 ``$FUNCTION_NAME``）不算真实工具调用。"""
+    n = (name or "").strip()
+    return not n or "$" in n
+
+
+def resolve_known_tool_names(
+    tools: Optional[List[Dict[str, Any]]] = None,
+    schema_index: Optional[Dict[str, Dict[str, Dict[str, Any]]]] = None,
+) -> Optional[Set[str]]:
+    """从 tools / schema_index 解析已知工具名；无约束时返回 ``None``。"""
+    if schema_index:
+        return {normalize_entml_name(str(k)) for k in schema_index.keys()}
+    names: Set[str] = set()
+    for tool in tools or []:
+        fn = tool.get("function") or {}
+        name = fn.get("name")
+        if name:
+            names.add(normalize_entml_name(str(name)))
+    return names if names else None
+
+
+def _name_is_known(name: str, known_names: Optional[Set[str]]) -> bool:
+    if known_names is None:
+        return True
+    if not known_names:
+        return False
+    return normalize_entml_name(name) in known_names
+
+
+def entml_invoke_open_is_actionable(
+    buffer: str,
+    pos: int,
+    *,
+    known_names: Optional[Set[str]] = None,
+) -> bool:
+    """``pos`` 处 ``<entml:invoke`` 是否为已闭合、含真实 name 且（若提供）在已知工具表内的开标签。"""
+    if pos < 0 or not buffer.startswith(_INVOKE_OPEN_PREFIX, pos):
+        return False
+    gt = buffer.find(">", pos + len(_INVOKE_OPEN_PREFIX))
+    if gt < 0:
+        return False
+    attrs = buffer[pos + len(_INVOKE_OPEN_PREFIX) : gt]
+    name = extract_attr_value(attrs, "name")
+    if not name:
+        return False
+    name = normalize_entml_name(name)
+    if not name or is_placeholder_invoke_name(name):
+        return False
+    return _name_is_known(name, known_names)
+
+
+def entml_invoke_open_may_be_streaming(
+    buffer: str,
+    pos: int,
+    *,
+    known_names: Optional[Set[str]] = None,
+) -> bool:
+    """``pos`` 处 ``<entml:invoke`` 是否仍可能长成可解析工具开标签（非 prose 提及）。"""
+    if pos < 0 or not buffer.startswith(_INVOKE_OPEN_PREFIX, pos):
+        return False
+    gt = buffer.find(">", pos + len(_INVOKE_OPEN_PREFIX))
+    if gt < 0:
+        return True
+    return entml_invoke_open_is_actionable(buffer, pos, known_names=known_names)
+
+
+def find_actionable_entml_invoke_open(
+    buffer: str,
+    *,
+    known_names: Optional[Set[str]] = None,
+) -> int:
+    """返回首个可解析 ``<entml:invoke`` 起始下标；否则 ``-1``。"""
+    if not buffer:
+        return -1
+    search_from = 0
+    prefix_len = len(_INVOKE_OPEN_PREFIX)
+    while search_from < len(buffer):
+        pos = buffer.find(_INVOKE_OPEN_PREFIX, search_from)
+        if pos < 0:
+            return -1
+        if entml_invoke_open_is_actionable(buffer, pos, known_names=known_names):
+            return pos
+        gt = buffer.find(">", pos + prefix_len)
+        search_from = (gt + 1) if gt >= 0 else (pos + prefix_len)
+    return -1
+
+
+def _actionable_invoke_open_before_close(
+    content: str,
+    close_pos: int,
+    *,
+    known_names: Optional[Set[str]] = None,
+) -> bool:
+    """``close_pos`` 处的 ``</entml:invoke>`` 是否闭合带真实 name 的开标签。"""
+    search = close_pos - 1
+    while search >= 0:
+        pos = content.rfind(_INVOKE_OPEN_PREFIX, 0, search + 1)
+        if pos < 0:
+            return False
+        if entml_invoke_open_is_actionable(content, pos, known_names=known_names):
+            gt = content.find(">", pos)
+            if gt < 0 or gt >= close_pos:
+                search = pos - 1
+                continue
+            inner_close = content.find(_INVOKE_CLOSE, gt + 1, close_pos)
+            if inner_close < 0:
+                return True
+            search = pos - 1
+            continue
+        search = pos - 1
+    return False
+
+
+def _invoke_close_should_strip(
+    content: str,
+    close_pos: int,
+    *,
+    known_names: Optional[Set[str]] = None,
+) -> bool:
+    """是否应剥离 ``</entml:invoke>``（孤儿噪声或真实工具块残留）。"""
+    if _actionable_invoke_open_before_close(content, close_pos, known_names=known_names):
+        return True
+    open_pos = content.rfind(_INVOKE_OPEN_PREFIX, 0, close_pos)
+    if open_pos < 0:
+        return True
+    return entml_invoke_open_is_actionable(content, open_pos, known_names=known_names)
+
+
+def iter_actionable_entml_invoke_blocks(
+    text: str,
+    *,
+    known_names: Optional[Set[str]] = None,
+) -> Iterator[Tuple[int, int, str, str]]:
+    """迭代含真实 ``name`` 的完整 ``<entml:invoke>…</entml:invoke>`` 块。"""
+    if not text:
+        return
+    search_from = 0
+    prefix_len = len(_INVOKE_OPEN_PREFIX)
+    close_len = len(_INVOKE_CLOSE)
+    while search_from < len(text):
+        pos = text.find(_INVOKE_OPEN_PREFIX, search_from)
+        if pos < 0:
+            break
+        if not entml_invoke_open_is_actionable(text, pos, known_names=known_names):
+            gt = text.find(">", pos + prefix_len)
+            search_from = (gt + 1) if gt >= 0 else (pos + prefix_len)
+            continue
+        gt = text.find(">", pos + prefix_len)
+        if gt < 0:
+            break
+        close = text.find(_INVOKE_CLOSE, gt + 1)
+        if close < 0:
+            break
+        attrs = text[pos + prefix_len : gt]
+        body = text[gt + 1 : close]
+        yield pos, close + close_len, attrs, body
+        search_from = close + close_len
+
+
+def _strip_orphan_invoke_tags(
+    content: str,
+    *,
+    known_names: Optional[Set[str]] = None,
+) -> str:
+    """仅剥离带真实 name 的 invoke 孤儿标签；保留 prose 中的 ``<entml:invoke>`` 提及。"""
+    pattern = re.compile(r"</?entml:invoke\b[^>]*/?>", re.DOTALL)
+
+    def repl(match: re.Match[str]) -> str:
+        tag = match.group(0)
+        if tag.startswith("</"):
+            if _invoke_close_should_strip(content, match.start(), known_names=known_names):
+                return ""
+            return tag
+        if entml_invoke_open_is_actionable(content, match.start(), known_names=known_names):
+            return ""
+        return tag
+
+    return pattern.sub(repl, content)
+
+
+def _strip_orphan_non_invoke_tool_tags(content: str) -> str:
+    return re.sub(
+        r"</?entml:(?:function_calls|parameter|parameters)\b[^>]*/?>",
+        "",
+        content,
+        flags=re.DOTALL,
+    )