feat:自动剥离大模型返回的markdown代码围栏

2026-03-22 00:43:47 +08:00
parent da15500808
commit bb630358af
6 changed files with 93 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -44,6 +44,7 @@
 | `source` | string | 否 | 来源标识，建议填智能体名称、工作流名或插件名，最大 80 个字符 |
 | `request_id` | string | 否 | 请求追踪 ID，方便排查问题，最大 120 个字符 |
 | `ttl_days` | integer | 否 | 文件保留天数，默认 7 天，最大 30 天 |
+| `preserve_markdown_fence` | boolean | 否 | 默认为 `false`。当智能体返回的是 ```html fenced code block 时，服务会自动剥离最外层围栏；如果你就是要保留围栏原文，传 `true` |

 #### 兼容别名

@@ -111,6 +112,39 @@

 这个地址会直接返回 `text/html` 内容。智能体侧通常只需要使用生成接口返回的 `url` 字段即可。

+## Markdown 代码围栏处理
+
+很多模型会把 HTML 包在下面这种 Markdown 代码块里：
+
+```text
+```html
+<!DOCTYPE html>
+<html>...</html>
+```
+```
+
+当前服务默认会自动剥离最外层围栏，然后再保存 HTML。
+
+为了避免误判，剥离逻辑是保守的，只有在以下条件同时满足时才会剥离：
+
+- 整个请求内容几乎就是一个外层 fenced code block
+- 代码块语言是 `html`、`htm`、`xhtml`、`xml`，或者虽然没写语言但内容明显像 HTML
+
+以下情况不会剥离：
+
+- HTML 正文内部只是包含了几个 ``` 代码围栏示例
+- 代码块语言是 `js`、`python` 等非 HTML
+- 内容整体看起来不像 HTML
+
+如果你确实希望把最外层 ``` 原样保留到页面中，可以在请求体里传：
+
+```json
+{
+  "html_content": "```html\n<div>hello</div>\n```",
+  "preserve_markdown_fence": true
+}
+```
+
 ## 智能体调用约定

 建议腾讯云智能体在工具描述中遵守以下规则：
@@ -215,6 +249,7 @@ NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
 | `MAX_HTML_LENGTH` | integer | `200000` | 单次 HTML 最大字节数 |
 | `API_KEY` | string | 空 | 非空时启用 `X-API-Key` 鉴权 |
 | `ALLOW_UNSAFE_HTML` | boolean | `true` | 是否关闭 HTML 安全拦截；当前默认开启，便于执行 JS |
+| `STRIP_MARKDOWN_CODE_FENCE` | boolean | `true` | 是否自动剥离最外层 Markdown 代码围栏 |
 | `ENABLE_REQUEST_DEBUG_LOG` | boolean | `true` | 是否输出 422 请求调试日志 |
 | `REQUEST_LOG_MAX_CHARS` | integer | `10000` | 单次请求日志最多记录多少字符 |