1

docs/prompt-compatibility.md

@@ -148,6 +148,7 @@ DS2API 当前的核心思路，不是把客户端传来的 `messages`、`tools`
 4. 把这整段内容并入 system prompt。
 
 工具调用正例仍只示范 canonical XML：`<tool_calls>` → `<invoke name="...">` → `<parameter name="...">`。
+提示词会额外强调：如果要调用工具，工具块的首个非空白字符必须就是 `<tool_calls>`，不能只输出 `</tool_calls>` 而漏掉 opening tag。
 正例中的工具名只会来自当前请求实际声明的工具；如果当前请求没有足够的已知工具形态，就省略对应的单工具、多工具或嵌套示例，避免把不可用工具名写进 prompt。
 对执行类工具，脚本内容必须进入执行参数本身：`Bash` / `execute_command` 使用 `command`，`exec_command` 使用 `cmd`；不要把脚本示范成 `path` / `content` 文件写入参数。
 
@@ -192,6 +193,7 @@ assistant 历史 `tool_calls` 不会保留成 OpenAI 原生 JSON，而会转成
 ```
 
 这也是当前项目里唯一受支持的 canonical tool-calling 形态；其他形态都会作为普通文本保留，不会作为可执行调用语法。
+例外是 parser 会对一个非常窄的模型失误做修复：如果 assistant 输出了 `<invoke ...>` ... `</tool_calls>`，但漏掉最前面的 opening `<tool_calls>`，解析阶段会补回 wrapper 后再尝试识别。
 
 这件事很重要，因为它决定了：
 

docs/toolcall-semantics.md

@@ -23,9 +23,14 @@
 - 工具名必须放在 `invoke` 的 `name` 属性
 - 参数必须使用 `<parameter name="...">...</parameter>`
 
+兼容修复：
+
+- 如果模型漏掉 opening `<tool_calls>`，但后面仍输出了一个或多个 `<invoke ...>` 并以 `</tool_calls>` 收尾，Go 解析链路会在解析前补回缺失的 opening wrapper。
+- 这是一个针对常见模型失误的窄修复，不改变推荐输出格式；prompt 仍要求模型直接输出完整 canonical XML。
+
 ## 2) 非 canonical 内容
 
-任何不满足上述 canonical XML 形态的内容，都会保留为普通文本，不会执行。
+任何不满足上述 canonical XML 形态的内容，都会保留为普通文本，不会执行。一个例外是上一节提到的“缺失 opening `<tool_calls>`、但 closing `</tool_calls>` 仍存在”的窄修复场景。
 
 当前 parser 不把 allow-list 当作硬安全边界：即使传入了已声明工具名列表，XML 里出现未声明工具名时也会尽量解析并交给上层协议输出；真正的执行侧仍必须自行校验工具名和参数。
 
@@ -33,7 +38,8 @@
 
 在流式链路中（Go / Node 一致）：
 
-- 只有从 `<tool_calls` 开始的 canonical wrapper 才会进入结构化捕获
+- canonical `<tool_calls>` wrapper 会进入结构化捕获
+- 如果流里直接从 `<invoke ...>` 开始，但后面补上了 `</tool_calls>`，Go 流式筛分也会按缺失 opening wrapper 的修复路径尝试恢复
 - 已识别成功的工具调用不会再次回流到普通文本
 - 不符合新格式的块不会执行，并继续按原样文本透传
 - fenced code block 中的 XML 示例始终按普通文本处理
@@ -43,14 +49,14 @@
 `ParseToolCallsDetailed` / `parseToolCallsDetailed` 返回：
 
 - `calls`：解析出的工具调用列表（`name` + `input`）
-- `sawToolCallSyntax`：只有检测到 `<tool_calls` 时才会为 `true`
+- `sawToolCallSyntax`：检测到 canonical wrapper，或命中“缺失 opening wrapper 但可修复”的形态时会为 `true`
 - `rejectedByPolicy`：当前固定为 `false`
 - `rejectedToolNames`：当前固定为空数组
 
 ## 5) 落地建议
 
 1. Prompt 里只示范 canonical XML 语法。
-2. 上游客户端需要直接输出 canonical XML；DS2API 不会把其他形态改写成工具调用。
+2. 上游客户端仍应直接输出 canonical XML；DS2API 只对“closing tag 在、opening tag 漏掉”的常见失误做窄修复，不会泛化接受其他旧格式。
 3. 不要依赖 parser 做安全控制；执行器侧仍应做工具名和参数校验。
 
 ## 6) 回归验证