echotools 2.3.55__tar.gz → 2.3.56__tar.gz

{echotools-2.3.55 → echotools-2.3.56}/PKG-INFO

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

{echotools-2.3.55 → echotools-2.3.56}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "echotools"
-version = "2.3.55"
+version = "2.3.56"
 description = "通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链"
 readme = "docs/README.md"
 requires-python = ">=3.8"

{echotools-2.3.55 → echotools-2.3.56}/src/echotools/exec/fncall/protocols/entml_tools.py

@@ -87,6 +87,33 @@ def _expand_description_multiline(json_text: str) -> str:
     return _DESC_LINE_RE.sub(_repl, json_text)
 
 
+def _normalize_tool_description(description: Any) -> str:
+    """将上游字面量 \\n / \\_ / \\* 等还原为可读文本。"""
+    if not description:
+        return ""
+    text = str(description)
+    while "\\n" in text or "\\r" in text or "\\t" in text:
+        prev = text
+        text = (
+            text.replace("\\r\\n", "\n")
+            .replace("\\n", "\n")
+            .replace("\\t", "\t")
+        )
+        if text == prev:
+            break
+    for old, new in (("\\_", "_"), ("\\*", "*")):
+        text = text.replace(old, new)
+    return text
+
+
+def _format_top_level_description(description: Any) -> str:
+    """顶层 Description：真换行排版，不再包 JSON 字符串引号。"""
+    text = _normalize_tool_description(description)
+    if not text:
+        return "Description:"
+    return f"Description:\n{text}"
+
+
 def _format_parameters_json(params: Mapping[str, Any]) -> str:
     sorted_params = _sort_schema_keys(dict(params))
     body = json.dumps(sorted_params, ensure_ascii=False, indent=2)
@@ -103,12 +130,11 @@ def format_entml_tool_descs(tools: List[Dict[str, Any]]) -> str:
         fn = tool.get("function", tool)
         name = str(fn.get("name") or "unknown")
         description = fn.get("description") or ""
-        # Description 外置为 JSON 字符串字面量（含转义），与示范一致
-        desc_literal = json.dumps(description, ensure_ascii=False)
+        desc_block = _format_top_level_description(description)
         params_body = _format_parameters_json(_normalize_parameters(fn.get("parameters")))
         blocks.append(
             f"### {name}\n\n"
-            f"Description: {desc_literal}\n\n"
+            f"{desc_block}\n\n"
             f"```json\n{params_body}\n```"
         )
     return "\n\n".join(blocks)

{echotools-2.3.55 → echotools-2.3.56}/src/echotools.egg-info/PKG-INFO

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

{echotools-2.3.55 → echotools-2.3.56}/src/tests/test_entml_protocol.py

@@ -572,7 +572,7 @@ def test_entml_instruction_matches_spec_format() -> None:
     assert "```text" not in prompt
     assert "### ask_user_input_v0" in prompt
     assert "**ask_user_input_v0**" not in prompt
-    assert 'Description: "Ask user"' in prompt
+    assert "Description:\nAsk user" in prompt
     assert '"name": "ask_user_input_v0"' not in prompt
     assert "<entml:function_calls>" not in prompt
     assert '<entml:invoke name="$FUNCTION_NAME">' in prompt

{echotools-2.3.55 → echotools-2.3.56}/src/tests/test_entml_tool_pipeline.py

@@ -670,7 +670,9 @@ class TestBuildMechanisms:
     def test_format_tool_descs_structure(self) -> None:
         out = format_entml_tool_descs(RICH_TOOLS)
         assert "### rich_tool" in out
-        assert 'Description: "All scalar and container types.\\nLine two."' in out
+        assert (
+            "Description:\nAll scalar and container types.\nLine two."
+        ) in out
         assert '"properties"' in out
         assert out.index('"properties"') < out.index('"type"')
         assert "```json" in out

{echotools-2.3.55 → echotools-2.3.56}/src/tests/test_entml_tools.py

@@ -51,7 +51,7 @@ def test_entml_tool_descs_heading_and_description_outside_json() -> None:
     out = format_entml_tool_descs([ASK_USER_TOOL])
     assert "### ask_user_input_v0" in out
     assert "**ask_user_input_v0**" not in out
-    assert 'Description: "USE THIS TOOL WHENEVER YOU HAVE A QUESTION FOR THE USER.' in out
+    assert "Description:\nUSE THIS TOOL WHENEVER YOU HAVE A QUESTION FOR THE USER." in out
     # name / top-level description 不再塞进 parameters JSON
     assert '"name": "ask_user_input_v0"' not in out
     assert out.count("```json") == 1
@@ -71,12 +71,39 @@ def test_entml_tool_descs_include_schema_types_and_required() -> None:
 
 def test_entml_tool_descs_expand_multiline_description() -> None:
     out = format_entml_tool_descs([ASK_USER_TOOL])
-    # 外置 Description 为 JSON 字符串字面量，换行以 \n 转义
-    assert "USE THIS TOOL WHENEVER YOU HAVE A QUESTION FOR THE USER.\\n\\nUSE THIS TOOL WHEN:\\n" in out
-    # parameters 内嵌 description 仍可展开多行
+    # 外置 Description 展开为物理换行，不再堆在一行的 \\n 转义里
+    assert (
+        "Description:\nUSE THIS TOOL WHENEVER YOU HAVE A QUESTION FOR THE USER.\n\n"
+        "USE THIS TOOL WHEN:\n"
+    ) in out
+    assert "\\n" not in out.split("```json")[0]
     assert "1-3 questions to ask the user" in out
 
 
+def test_entml_tool_descs_unescape_api_markdown_escapes() -> None:
+    desc = (
+        r"Launch agent.\n\n"
+        r'Use `subagent\_type: "fork"` for forks.\n'
+        r"**Don't peek.**"
+    )
+    tool = {
+        "type": "function",
+        "function": {
+            "name": "Agent",
+            "description": desc,
+            "parameters": {"type": "object", "properties": {}},
+        },
+    }
+    out = format_entml_tool_descs([tool])
+    head = out.split("```json")[0]
+    assert "subagent_type:" in head
+    assert "fork" in head
+    assert "\\_" not in head
+    assert "**Don't peek.**" in head
+    assert "\\n\\n" not in head
+    assert "Launch agent.\n\n" in out
+
+
 def test_entml_tool_descs_schema_key_order() -> None:
     out = format_entml_tool_descs([ASK_USER_TOOL])
     # parameters 块内：properties 先于 type
@@ -114,6 +141,6 @@ def test_entml_tool_descs_matches_design_shape() -> None:
         }
     ]
     out = format_entml_tool_descs(tools)
-    assert out.startswith("### bash_tool\n\nDescription: \"Run a bash command")
+    assert out.startswith("### bash_tool\n\nDescription:\nRun a bash command")
     assert '"title": "BashInput"' in out
     assert '"name":' not in out