From 4640211e3c98e6c7ae5948ef1daeac336f7a6be3 Mon Sep 17 00:00:00 2001 From: TermiNexus Date: Fri, 21 Aug 2026 14:08:37 +0800 Subject: [PATCH] =?UTF-8?q?docs(mcp):=20=E9=9D=9E=E7=94=9F=E4=BA=A7?= =?UTF-8?q?=E7=8E=AF=E5=A2=83=E9=BB=98=E8=AE=A4=E6=8E=A8=E8=8D=90=E5=90=AF?= =?UTF-8?q?=E7=94=A8=20ASan=EF=BC=8CASan/=E9=9D=9E=20ASan=20=E5=88=87?= =?UTF-8?q?=E6=8D=A2=E9=9C=80=20--rebuild-includes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - protocol.md 新增 5.8 ASan 推荐：非生产环境 --asan 捕获内存错误，生产环境不启用 - 明确 ASan 与非 ASan 共享 includes.binary 缓存会互相污染（undefined symbol: __asan_*），切换必须重建缓存 - README/tools.json 同步更新 asan 字段描述 --- MCP/README.md | 3 ++- MCP/protocol.md | 10 +++++++++- MCP/tools/tools.json | 6 ++++-- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/MCP/README.md b/MCP/README.md index ec6fb99..e283bcd 100644 --- a/MCP/README.md +++ b/MCP/README.md @@ -64,4 +64,5 @@ MCP 服务器（`transpyc-tools`）以 stdio 方式运行于项目根目录： - 编译输出仅返回**末尾 N 行**（默认 50），避免长日志污染上下文 - 同一工程目录禁止并行编译（temp/output 冲突） - TPC 编译错误 **fail-fast**：立即返回错误，不静默兜底 -- 修改 TPV `.vp` 源码后必须清缓存 + Phase A 全量重建才生效（SHA1 缓存复用旧 .ll） \ No newline at end of file +- 修改 TPV `.vp` 源码后必须清缓存 + Phase A 全量重建才生效（SHA1 缓存复用旧 .ll） +- 非生产环境默认推荐 `--asan`；ASan/非 ASan 切换必须 `--rebuild-includes` 重建 includes.binary 缓存 \ No newline at end of file diff --git a/MCP/protocol.md b/MCP/protocol.md index c9c6072..49fc291 100644 --- a/MCP/protocol.md +++ b/MCP/protocol.md @@ -101,6 +101,14 @@ TPC 编译错误必须立即终止并原样返回错误（traceback 风格）， - `llc`（LLVM 静态编译器）、`clang++`（mingw-w64 链接器）须在 PATH - TPV 运行时需 **≥ 1 GiB 空闲内存**（启动时 `malloc(1<<30)` 内存池） - ASan 模式（`--asan`）需 clang64 环境 + +### 5.8 ASan 推荐（非生产环境默认启用） + +默认**非生产环境**（开发/测试/回归）推荐启用 ASan：`--asan`（opt -passes=asan 插桩 + 链接 -fsanitize=address）， +可捕获越界读写、use-after-free 等运行时内存错误；**生产环境不启用**（性能与体积开销）。 + +注意：ASan 与非 ASan 构建共享 includes.binary 缓存时会互相污染（ASan 插桩 obj 在普通链接下报 `undefined symbol: __asan_*`）， +**切换模式必须 `--rebuild-includes` 重建缓存**。 --- ## 6. 工具详细定义 @@ -123,7 +131,7 @@ TPC 编译错误必须立即终止并原样返回错误（traceback 风格）， "phase": {"type": "string", "enum": ["1", "2", "all"], "default": "all", "description": "阶段：1=声明生成，2=翻译+编译，all=全部"}, "rebuild_includes": {"type": "boolean", "default": false, "description": "删除 includes.binary 并重编译 includes"}, "clear_cache": {"type": "boolean", "default": false, "description": "清除全局 .transpyc_cache"}, - "asan": {"type": "boolean", "default": false, "description": "ASan 插桩模式"}, + "asan": {"type": "boolean", "default": false, "description": "ASan 插桩（非生产环境推荐启用）"}, "nowarn_register": {"type": "boolean", "default": false, "description": "抑制外部函数返回类型未登记 WARN"}, "src": {"type": "string", "description": "覆盖 source_dir"}, "temp": {"type": "string", "description": "覆盖 temp_dir"}, diff --git a/MCP/tools/tools.json b/MCP/tools/tools.json index 5ead1d1..cf5a15c 100644 --- a/MCP/tools/tools.json +++ b/MCP/tools/tools.json @@ -34,7 +34,8 @@ }, "asan": { "type": "boolean", - "default": false + "default": false, + "description": "ASan 插桩（非生产环境推荐启用）" }, "nowarn_register": { "type": "boolean", @@ -119,7 +120,8 @@ }, "asan": { "type": "boolean", - "default": false + "default": false, + "description": "ASan 插桩（非生产环境推荐启用）" } }, "required": [