TransPyC/MCP/protocol.md

TransPyC / TransPyV MCP 协议规范

版本：2026-08（v1） · 适用根目录：D:\Users\TermiNexus\Desktop\TransPyC

---

1. 概述

本协议定义通过 MCP 操作 Viper 编译器生态的工具集、执行约定与安全约束， 覆盖两大编译器：

名称	实现	入口	说明
TPC	CPython	TransPyC.py（单文件）/ Projectrans.py（工程级）	主路径编译器，所有 Test/ 依赖它
TPV	Viper（自举）	TransPyV\output\TransPyV.exe	Viper 语言自写编译器，由 TPC 编译产出

客户端（AI 助手等）通过 MCP 服务器的工具调用完成：编译、构建、回归测试、诊断。

---

2. 服务器信息

字段	值
name	transpyc-tools
description	TransPyC/TransPyV Viper 编译器控制服务器
transport	stdio
protocol	MCP 2025-03-26 / 2024-11-05 兼容
cwd	D:\Users\TermiNexus\Desktop\TransPyC

工具命名空间前缀：tpc_（TPC 操作）、tpv_（TPV/自举操作）、tp_（只读诊断）。

---

3. 术语与路径约定

• project.json：工程配置，位于 <工程>/project.json；Test/ 下每个子目录即一个测试工程
• 工程编译：Projectrans.py --project <path> 两阶段（Phase1 声明生成 + Phase2 翻译/编译/链接）
• 单文件编译：TransPyC.py -f <in.vp> -o <out.ll>，生成 LLVM IR（可再 -cc/-run 链接运行）
• TPV 产物：TransPyV\output\TransPyV.exe（根目录 TransPyV.exe 可能为旧版，验证必须用 output 新版）
• 自举链：Phase A（TPC 编译 TransPyV → tpv.exe）→ Phase B（tpv.exe 编译自身 → tpv2）→ Phase C（tpv2 → tpv3）
• 缓存目录：工程 temp/、output/、.tpv_build/；全局 .transpyc_cache/（含 .vpi / .stub.ll / .doc.json）
• SHA1 映射：<工程>/temp/_sha1_map.txt，记录源码 SHA1 → 中间产物

路径参数一律使用相对根目录或根目录内绝对路径；禁止指向根目录之外。

---

4. 工具清单（总览）

#	工具	分类	作用
1	tpc_build	TPC 工程	编译任意 Viper 工程（两阶段 + 可选清理/运行/重建）
2	tpc_build_file	TPC 单文件	单文件 .vp → LLVM IR（可选链接运行）
3	tpc_run_test	TPC 测试	编译并运行单个 Test/<Name> 工程
4	tpc_run_regression	TPC 测试	全量回归（遍历 Test/* 编译 + 运行判定）
5	tpc_clean_project	TPC 维护	清理工程 output/ 与 temp/（--clean）
6	tpc_clear_cache	TPC 维护	清除全局 .transpyc_cache（--clear-cache）
7	tpc_rebuild_includes	TPC 维护	删除 includes.binary 并重编译所有 includes
8	tpv_build	TPV 构建	TPC 编译 TransPyV → TransPyV\output\TransPyV.exe
9	tpv_bootstrap	TPV 自举	执行自举链 Phase A/B/C 并对比产物
10	tpv_compile_project	TPV 编译	用 TPV.exe 编译任意工程（参数同 tpc_build）
11	tpv_run_test	TPV 测试	运行 TransPyV/Test 自测（含 NegativeTest/Sha1Test）
12	tp_read_ast	诊断	解析 .vp 源码输出 AST dump（vast）
13	tp_read_log	诊断	读取项目内日志/输出文件末尾 N 行
14	tp_sha1_map	诊断	读取工程 SHA1 映射（_sha1_map.txt）

---

5. 执行约定

5.1 工作目录

所有命令在 D:\Users\TermiNexus\Desktop\TransPyC（根目录）执行；路径参数先规范化（resolve）再校验。

5.2 Python 解释器

统一使用 python（Python 3.12）。禁止使用系统内置 3.10。 约定：t.py / c.py 为语言基础模块，不参与编译。

5.3 清理策略

禁止手动删除文件。清理一律通过工具参数映射到命令行选项：

• --clean：清理 output/ 与 temp/
• --rebuild-includes：删除 includes.binary 预编译缓存并重编译 includes
• --clear-cache：清除 .transpyc_cache 全局缓存

5.4 串行与并发

• 同一工程目录禁止并行编译（temp/output 共享，冲突会损坏产物）
• 服务端维护按工程路径的锁；客户端不应并发发起同一工程的两个 build
• TPC 并行 worker 数由编译器按可用内存自动限制（_PickWorkerCount），服务端不干预

5.5 缓存与重建

• .vp 源码 SHA1 未变时，缓存命中会复用旧 .ll/.vpi
• 修改 TPC 的 .py 编译逻辑后：需 --clear-cache + --rebuild-includes 才彻底生效
• 修改 TPV 的 .vp 源码后：必须 tpv_build（内含 --clean）做 Phase A 全量重建，否则新逻辑不生效
• 编译器（TPC 侧）输出内容不可靠时（如 bitcast i8* null t 类垃圾 IR），应 --clear-cache 后重编

5.6 fail-fast

TPC 编译错误必须立即终止并原样返回错误（traceback 风格），不兜底、不静默发明值。 工具返回值中的 ok=false + exit_code!=0 即表示失败，客户端应停止后续依赖操作。

5.7 环境依赖

• llc（LLVM 静态编译器）、clang++（mingw-w64 链接器）须在 PATH
• TPV 运行时需 ≥ 1 GiB 空闲内存（启动时 malloc(1<<30) 内存池）
• ASan 模式（--asan）需 clang64 环境

5.8 ASan 推荐（非生产环境默认启用）

默认启用（asan 参数默认 true，非生产环境）：--asan（opt -passes=asan 插桩 + 链接 -fsanitize=address）， 可捕获越界读写、use-after-free 等运行时内存错误；生产环境显式传 asan: false 关闭（性能与体积开销）。

注意：ASan 与非 ASan 构建共享 includes.binary 缓存时会互相污染（ASan 插桩 obj 在普通链接下报 undefined symbol: __asan_*）， 切换模式必须 --rebuild-includes 重建缓存。

6. 工具详细定义

每个工具给出：name / description / inputSchema（JSON Schema）/ command（底层执行）/ output（返回结构）。 所有 command 均以工作目录为根，路径参数经规范化与根目录白名单校验后方可拼接。

6.1 tpc_build — 编译 Viper 工程（两阶段）

• description：用 TransPyC 编译任意工程，对应 Projectrans.py --project。支持清理、运行、阶段选择、缓存维护。
• inputSchema：

{
  "type": "object",
  "properties": {
    "project":       {"type": "string", "description": "project.json 路径（相对根），如 Test/CoroTest/project.json"},
    "clean":         {"type": "boolean", "default": false, "description": "先清理 output/temp 再编译"},
    "run":           {"type": "boolean", "default": false, "description": "编译成功后立即运行产物"},
    "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": true, "description": "ASan 插桩（默认启用）"},
    "nowarn_register": {"type": "boolean", "default": false, "description": "抑制外部函数返回类型未登记 WARN"},
    "src":           {"type": "string", "description": "覆盖 source_dir"},
    "temp":          {"type": "string", "description": "覆盖 temp_dir"},
    "output":        {"type": "string", "description": "覆盖 output_dir"},
    "cc":            {"type": "string", "description": "覆盖 LLVM 编译器命令"}
  },
  "required": ["project"]
}

• command：

python Projectrans.py --project <project> [--clean] [--run] [--phase <1|2|all>] [--rebuild-includes] [--clear-cache] [--asan] [--nowarn-register] [--src <src>] [--temp <temp>] [--output <output>] [--cc <cc>]

• output：见 §7；artifacts.exe 取 output_dir 下新生成的可执行文件路径（依 project.json 的 linker.output）。

6.2 tpc_build_file — 单文件编译

• description：单文件 .vp → LLVM IR（TransPyC.py -f），可选 -cc 链接 + -run 运行。
• inputSchema：

{
  "type": "object",
  "properties": {
    "input":  {"type": "string", "description": "输入 .vp 路径（相对根）"},
    "output": {"type": "string", "description": "输出 .ll 路径（相对根）"},
    "run":    {"type": "boolean", "default": false, "description": "链接并运行"},
    "args":   {"type": "string", "description": "运行时参数（空格分隔）"},
    "level":  {"type": "string", "description": "切片级别，数字或 s"},
    "encoding": {"type": "string", "default": "utf-8"},
    "cc":     {"type": "string", "description": "覆盖编译命令（默认见 lib/constants/config）"},
    "cflags": {"type": "string", "description": "覆盖编译标志"}
  },
  "required": ["input", "output"]
}

• command：

python TransPyC.py -f <input> -o <output> [-cc <cc>] [-cflags <cflags>] [-run] [-args <args>] [-level <level>] [-e <encoding>]

6.3 tpc_run_test — 编译并运行单个测试

• description：对 Test/<Name> 执行 --clean --run（等价手工验证单测试）。
• inputSchema：

{
  "type": "object",
  "properties": {
    "name": {"type": "string", "description": "测试名，即 Test/ 下子目录名，如 CoroTest"},
    "rebuild_includes": {"type": "boolean", "default": false},
    "clear_cache": {"type": "boolean", "default": false},
    "asan": {"type": "boolean", "default": true}
  },
  "required": ["name"]
}

• command：

python Projectrans.py --project Test/<name>/project.json --clean --run [--rebuild-includes] [--clear-cache] [--asan]

• 说明：测试工程无 linker.output 时产物为 Test/<name>/output/<name>.exe（由 project.json 决定）。

6.4 tpc_run_regression — 全量回归

• description：运行 Test/regression_test.py（遍历所有含 project.json 的测试，编译 + 运行 + 关键词判定）。
• inputSchema：

{
  "type": "object",
  "properties": {
    "name": {"type": "string", "description": "可选：只跑匹配名字的测试（按需实现过滤）"},
    "timeout": {"type": "integer", "default": 300, "description": "单测试编译超时秒数"}
  },
  "required": []
}

• command：

python Test/regression_test.py

• 说明：默认全量耗时较长；客户端应按需使用 name 过滤或分片调用。

6.5 tpc_clean_project — 清理并编译工程

• description：执行 Projectrans.py --clean——先清理 output/ 与 temp/，随后仍继续完整编译流程（--clean 是编译前置步骤，非独立清理命令）。等价 tpc_build(clean=true)，仅不含运行。
• inputSchema：{ "project": {"type":"string"} }，required: ["project"]。
• command：python Projectrans.py --project <project> --clean

6.6 tpc_clear_cache — 清除全局缓存

• description：清除 .transpyc_cache（.vpi / .stub.ll / .doc.json），解决缓存腐化。
• inputSchema：{ "project": {"type":"string"} }，required: ["project"]。
• command：python Projectrans.py --project <project> --clear-cache
• 说明：腐化典型症状——(1<<N) 被求值为 1、类型推断退化导致指针截断、bitcast i8* null t 垃圾 IR。

6.7 tpc_rebuild_includes — 重建 includes 预编译缓存

• description：删除 includes.binary 并重编译所有 includes。

• inputSchema：{ "project": {"type":"string"} }，required: ["project"]。

• command：python Projectrans.py --project <project> --rebuild-includes

• 说明：修改 includes/ 下基础模块后必须执行，否则旧符号表残留。### 6.8 tpv_build — 构建 TransPyV

• description：用 TPC 编译 TransPyV（自举第一阶段），产物 TransPyV\output\TransPyV.exe。

• inputSchema：

{
  "type": "object",
  "properties": {
    "clean": {"type": "boolean", "default": true, "description": "默认全量清理重建（TPV 源码改动必须清缓存）"},
    "rebuild_includes": {"type": "boolean", "default": true, "description": "TPC 侧 includes 改动时置 true"},
    "clear_cache": {"type": "boolean", "default": true, "description": "TPC 侧编译器逻辑改动时置 true"}
    "asan":          {"type": "boolean", "default": true, "description": "ASan 插桩（默认启用，编译器自身带 ASan 可定位内部崩溃）"}
  },
  "required": []
}

• command：

python Projectrans.py --project TransPyV/project.json --clean [--rebuild-includes] [--clear-cache]

• output：artifacts.exe = TransPyV/output/TransPyV.exe
• 注意：验证 TPV 行为必须用 TransPyV\output\TransPyV.exe；根目录 TransPyV.exe 可能为旧版。TPV 源码 .vp SHA1 不变时不清缓存会复用旧 .ll，新逻辑不生效。

6.9 tpv_bootstrap — 自举链验证

• description：执行 Phase A/B/C 自举，验证 TPV 能编译自身（B/C 阶段由 tpv.exe 驱动）。
• inputSchema：

{
  "type": "object",
  "properties": {
    "phases": {"type": "array", "items": {"type": "string", "enum": ["A", "B", "C"]}, "description": "默认 [A,B,C]"},
    "compare": {"type": "boolean", "default": true, "description": "对比相邻阶段产物（如 tpv vs tpv2 的 sha1）"}
  },
  "required": []
}

• command（示意）：

# Phase A：TPC 编译 TransPyV → tpv.exe
python Projectrans.py --project TransPyV/project.json --clean
# Phase B：tpv.exe 编译自身 → tpv2
TransPyV\output\TransPyV.exe --project TransPyV/project.json --clean --output TransPyV/output2
# Phase C：tpv2 编译自身 → tpv3
TransPyV\output\tpv2.exe --project TransPyV/project.json --clean --output TransPyV/output3

• 说明：B/C 阶段的 --project 参数与 TPC Projectrans.py 一致；产物命名/目录按实现约定。服务器应返回各阶段 exit_code 与产物路径，供客户端对比。

6.10 tpv_compile_project — 用 TPV 编译工程

• description：用 TransPyV\output\TransPyV.exe 编译任意工程（参数同 tpc_build）。
• inputSchema：同 tpc_build（project/clean/run/phase/...）。
• command：

TransPyV\output\TransPyV.exe --project <project> [--clean] [--run] [--phase <1|2|all>] [--rebuild-includes] [--clear-cache]

• 说明：用于验证 TPV 对既有工程的兼容性；TPV 运行需 ≥ 1 GiB 空闲内存。

6.11 tpv_run_test — 运行 TPV 自测

• description：运行 TransPyV/Test 下编译器自测（App 用例 + NegativeTest + Sha1Test）。
• inputSchema：

{
  "type": "object",
  "properties": {
    "suite": {"type": "string", "enum": ["App", "NegativeTest", "Sha1Test", "all"], "default": "all"},
    "filter": {"type": "string", "description": "按名字过滤（可选）"}
  },
  "required": []
}

• command（示意）：TransPyV\output\TransPyV.exe --project TransPyV/Test/project.vpj --clean --run（或按 suite 分目录调用）。
• 说明：Test 工程配置在 TransPyV/Test/project.vpj，参数透传方式与 tpv_compile_project 一致。

6.12 tp_read_ast — 解析 AST

• description：解析指定 .vp 源码，返回 vast AST dump（compact）与符号级信息。
• inputSchema：

{
  "type": "object",
  "properties": {
    "file": {"type": "string", "description": ".vp 源文件路径（相对根）"},
    "dump": {"type": "string", "enum": ["compact", "full"], "default": "compact"}
  },
  "required": ["file"]
}

• command（示意）：python -c "import vast as ast,io; print(ast.dump(ast.parse(open(r'<file>',encoding='utf-8').read())))"
• 用途：定位 AST 形态（如 -> None 是 Constant(CONST_NONE)、await 节点位置、extern/export 软关键字标志）。

6.13 tp_read_log — 读取日志

• description：读取项目内文本文件（1.log、deps.json、stub.ll 等）末尾 N 行或按正则过滤。
• inputSchema：

{
  "type": "object",
  "properties": {
    "file": {"type": "string", "description": "文件路径（相对根），如 1.log"},
    "lines": {"type": "integer", "default": 50, "description": "返回末尾行数"},
    "pattern": {"type": "string", "description": "正则过滤（可选）"}
  },
  "required": ["file"]
}

• 说明：用于崩溃栈定位、输出核对；避免整文件灌入上下文。

6.14 tp_sha1_map — 读取 SHA1 映射

• description：读取工程 temp/_sha1_map.txt，确认哪些源码命中缓存（诊断缓存腐化）。
• inputSchema：

{
  "type": "object",
  "properties": {
    "project": {"type": "string", "description": "工程目录（相对根），如 Test/CoroTest"},
    "filter": {"type": "string", "description": "按文件名过滤（可选）"}
  },
  "required": ["project"]
}

• command：读取 <project>/temp/_sha1_map.txt（不存在则返回 ok=false, error="sha1 map not found"）。

---

7. 输出格式

所有工具返回统一 JSON 结构：

{
  "ok": true,
  "exit_code": 0,
  "stdout": "…编译末尾 50 行…",
  "stderr": "…错误末尾 50 行…",
  "artifacts": {
    "exe": "Test/CoroTest/output/CoroTest.exe",
    "ir": "…",
    "logs": ["Test/CoroTest/output/…"]
  },
  "elapsed_ms": 12345
}

约定：

• ok=false 且 exit_code!=0 即失败；stderr 原样保留（traceback 风格），禁止改写/兜底
• stdout/stderr 默认截断为末尾 50 行（tp_read_log 可通过 lines 调整），防止长日志污染上下文
• artifacts 为可选；无产物时省略该字段
• 运行超时：编译 300s、程序运行 30s（与 Test/regression_test.py 对齐）；超时返回 ok=false, error="timeout"

8. 安全约束

1. 路径白名单：所有 file/project/src/temp/output 参数必须先规范化，且必须位于根目录 D:\Users\TermiNexus\Desktop\TransPyC 内；越界即拒绝（ok=false, error="path outside root"）
2. 命令白名单：工具只拼接本协议 §6 中列出的固定命令模板与参数；参数值经 shell 分隔（shlex.split）传入，禁止拼接任意 shell
3. 不手动删文件：清理仅通过 --clean / --rebuild-includes / --clear-cache
4. 不执行任意代码：tp_read_ast 只解析不执行；编译类工具只跑编译器
5. 串行锁：同一工程路径并发 build 会被拒绝（error="project busy"）
6. 内存保护：TPV 相关工具调用前检查可用内存 ≥ 1 GiB，不足则拒绝并提示

9. 错误码

code	含义
0	成功
1	编译/运行失败（stdout/stderr 携带详情）
2	参数错误（缺 required / 非法 enum）
3	路径越界（安全约束 §8.1）
4	文件不存在（如 project.json / sha1_map）
5	工程忙（并发冲突，§5.4/§8.5）
6	超时（编译 > 300s / 运行 > 30s）
7	内存不足（TPV 需 ≥ 1 GiB）

10. 扩展

• 工具演进：新增工具沿用前缀约定与 §6 模板；破坏性变更 bump 协议版本号
• 只读优先：诊断类（tp_）保持纯只读，可被客户端安全探测
• 推荐工作流：改 TPC/TPV 源码 → tpc_clear_cache/tpv_build（全量重建）→ 目标测试 tpc_run_test → 必要时 tp_read_ast/tp_sha1_map 定位根因 → tp_read_log 核对