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：

```json
{
  "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：

```powershell
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：

```json
{
  "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：

```powershell
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：

```json
{
  "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：

```powershell
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：

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

- command：

```powershell
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：

```json
{
  "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：

```powershell
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：

```json
{
  "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（示意）：

```powershell
# 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：

```powershell
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：

```json
{
  "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：

```json
{
  "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：

```json
{
  "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：

```json
{
  "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 结构：

```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` 核对