# TransPyC 调试器（vdb）设计文档

> **状态**：设计阶段，暂不实现  
> **创建时间**：2026-06-26  
> **目标**：为 TransPyC 编译的程序提供源码级调试能力，支持断点、变量查看、单步、调用栈、异常栈跟踪

---

## 1. 背景与动机

TransPyC 将 Python 子集编译为 LLVM IR 再编译为原生机器码。当前编译产物**完全不含调试信息**（无 DWARF/PDB），运行时崩溃只能看到错误码和消息，无法定位源码行、查看变量、回溯调用栈。

本设计文档规划一个 TransPyC 专用调试器 **vdb**，目标是：

- 源码级断点（`break main.py:30`）
- 变量查看（`print x` / `info locals`）
- 单步执行（`step` / `next`）
- 调用栈回溯（`backtrace`）
- 异常栈跟踪（`raise` 时记录栈帧）
- 硬错误捕获（segfault / 溢出）

---

## 2. 现状分析

### 2.1 已有可复用资产

| 资产 | 位置 | 复用方式 |
|------|------|---------|
| 变量映射三件套 `variables`/`_direct_values`/`_reg_values` | `lib/core/LLVMCG/BaseGen.py:79-81` | 序列化到 .tpd 供变量查看 |
| 变量类型信息 `var_type_info`/`var_signedness`/`var_struct_class` | `lib/core/LLVMCG/BaseGen.py:82-112,124` | 序列化为 VarBinding.TypeDesc |
| 源码行号跟踪 `_current_lineno`/`_set_node_info`/`_get_source_line` | `lib/core/LLVMCG/BaseGen.py:126-127,138,297-440` | 扩展为 SourceMap |
| 类元信息表 `class_members`/`class_member_defaults`/`class_parent`/`Vtables` | `lib/core/LLVMCG/BaseGen.py:85-100` | 序列化为 TypeMeta |
| 符号表序列化 `SymbolTable.ToDict` | `lib/core/SymbolTable.py:265-319` | vdb 直接加载，无需重建 |
| 异常机制 `__eh_msg_out__`/`__eh_code_out__` | `lib/core/Handles/HandlesRaise.py` / `HandlesTry.py` / `HandlesExprCall.py` | 扩展携带栈信息 |
| VLogger `compile_error(file, line, code)` 三元组 | `lib/core/VLogger.py:286` | 复用错误位置格式 |
| 本地堆指针记录 `_local_heap_ptrs`/`_var_to_heap_ptr` | `lib/core/LLVMCG/MemoryOps.py:7-15` | 堆对象追踪起点 |

### 2.2 关键缺口

| 能力 | 现状 | 缺口说明 |
|------|------|---------|
| DWARF 调试信息 | ❌ 完全未生成 | `lib/` 下无任何 `DIBuilder`/`!dbg`/`DICompileUnit` 调用 |
| PDB 调试信息 | ❌ 完全未生成 | Windows 下 WinDbg/VS 无法源码级调试 |
| 源码行 → IR 指令映射 | ❌ 无数据结构 | 最核心缺口，需从零构建 SourceMap |
| 变量名 → 运行时内存 | ⚠️ 仅编译期 ephemeral | `Gen.variables` 随 Gen 实例销毁，需持久化 |
| 类型元信息运行时查询 | ❌ 无 RTTI/反射 | `class_members` 等均编译期状态，未发射到二进制 |
| 运行时调用栈 | ❌ 完全无 | 异常仅传 `(code, msg)`，无栈帧链 |
| 硬错误处理 | ❌ 无 | `__builtin_trap` 仅声明未实现，segfault/SIGFPE 无捕获 |
| 断点/单步/变量查看 | ❌ 完全无 | `lib/` 下搜索 `breakpoint`/`step`/`watch` 零命中 |

---

## 3. 路线选择

### 3.1 方案 A：纯 DWARF + GDB/LLDB

**优点**：生态成熟，无需自研前端  
**缺点**：
- llvmlite 的 DIBuilder 支持度需验证
- Python 语义与 C 不完全对应（`self` 是指针但 Python 视为对象）
- SHA1 命名导致符号名难读
- 泛型特化类型（`Stack[int]`）在 DWARF 中表达困难
- 跨模块符号（`6d71a13705da41ad.main`）可读性差

### 3.2 方案 B：纯自研 vdb

**优点**：完全匹配 Python 语义，可显示原始源码，理解泛型/SHA1/跨模块  
**缺点**：开发量大，需自研调试协议与前端

### 3.3 方案 C：混合（推荐）

- 生成轻量 DWARF（仅行号 + 变量名）让 GDB 可用作后备
- 同时生成 TransPyC 专用调试元数据 `.tpd` 文件
- vdb 前端优先使用 `.tpd`，可降级到 GDB 后端

**本设计采用方案 C**，但优先实现 `.tpd` + vdb，DWARF 作为可选增强。

---

## 4. 核心数据结构

### 4.1 .tpd 文件格式（TransPyC Debug）

每个 `.ll` 文件配套生成一个 `.tpd` 文件（JSON 格式），包含以下结构：

```python
from dataclasses import dataclass, field
from typing import Any

@dataclass
class IrLocation:
    """单条 IR 指令的源码位置映射"""
    FuncName: str          # mangled 函数名（含 SHA1 头，如 '6d71a13705da41ad.main'）
    BlockName: str         # 基本块名（如 'entry'、'if.then'）
    InstrIdx: int          # 指令在块中的索引
    SourceFile: str        # 源码相对路径
    LineNo: int            # 源码行号
    ColNo: int             # 列号

@dataclass
class VarBinding:
    """变量绑定信息（作用域内）"""
    VarName: str           # Python 变量名（如 'x'、'self'）
    LlvmName: str          # alloca 名或 SSA（如 '%x'、'%".1"'）
    TypeDesc: str          # 类型描述（'i32' / 'Stack[int]*' / 'i8*'）
    IsSigned: bool         # 是否有符号整数
    StructClass: str | None  # 所属结构体类名（如 'Stack[int]'）
    StartLine: int         # 作用域起始行
    EndLine: int           # 作用域结束行
    Storage: str           # 'stack' | 'register' | 'direct' | 'global'
    StackOffset: int | None  # 栈偏移（仅 'stack'）

@dataclass
class TypeMeta:
    """类型元数据"""
    TypeName: str          # 'Stack[int]' / 'IntPair' / 'memory_block'
    Members: list[tuple[str, str, int]]  # (成员名, 类型, 字节偏移)
    Size: int              # 总大小（字节）
    Align: int             # 对齐
    Parent: str | None     # 父类名
    IsException: bool      # 是否异常类
    ExceptionCode: int     # 异常码（仅 IsException=True）
    HasVTable: bool        # 是否有虚表
    IsPacked: bool         # 是否紧凑布局

@dataclass
class FuncSig:
    """函数签名"""
    FuncName: str          # mangled 名
    RawName: str           # 原始 Python 名（去 SHA1）
    ReturnType: str        # 返回类型描述
    ParamNames: list[str]
    ParamTypes: list[str]
    IsExport: bool         # 是否导出（@t.CExport）
    IsMethod: bool         # 是否实例方法
    ClassName: str | None  # 所属类名（方法）
    SourceFile: str
    StartLine: int
    EndLine: int
    HasException: bool     # 是否可能抛异常（有 __eh_msg_out__）

@dataclass
class TpdFile:
    """完整的 .tpd 调试信息文件"""
    SourceMap: list[IrLocation]
    VarScopes: dict[str, list[VarBinding]]  # FuncName -> bindings
    TypeMeta: dict[str, TypeMeta]
    FuncSignatures: dict[str, FuncSig]
    ExceptionCodes: dict[int, str]          # code -> exception name
    SourceFiles: dict[str, list[str]]       # file -> 源码行列表（供 vdb 显示上下文）
    ModuleSha1: str | None
    Version: str = "1.0"
```

### 4.2 序列化格式

`.tpd` 文件使用 JSON，字段名采用 PascalCase（与代码一致）。示例：

```json
{
  "Version": "1.0",
  "ModuleSha1": "6d71a13705da41ad",
  "SourceFiles": {
    "App/main.py": ["import t", "import stdio", ...]
  },
  "SourceMap": [
    {"FuncName": "main", "BlockName": "entry", "InstrIdx": 0, "SourceFile": "App/main.py", "LineNo": 255, "ColNo": 0},
    ...
  ],
  "VarScopes": {
    "6d71a13705da41ad.test_generic_stack": [
      {"VarName": "s", "LlvmName": "%s", "TypeDesc": "Stack[int]*", "IsSigned": false, "StructClass": "Stack[int]", "StartLine": 66, "EndLine": 73, "Storage": "stack", "StackOffset": 0}
    ]
  },
  "TypeMeta": {
    "Stack[int]": {
      "TypeName": "Stack[int]",
      "Members": [["data", "[16 x i32]", 0], ["top", "i32", 64]],
      "Size": 68,
      "Align": 4,
      "Parent": null,
      "IsException": false,
      "ExceptionCode": 0,
      "HasVTable": false,
      "IsPacked": false
    }
  },
  "ExceptionCodes": {
    "1": "ValueError",
    "2": "TypeError",
    "99": "Exception",
    "100": "MyCustomError"
  }
}
```

---

## 5. 实现阶段

### 5.1 Phase 1：源码级断点（最小可用）

**目标**：`break main.py:30` + `continue` + `run`

#### 5.1.1 编译器改动

**位置**：`lib/core/LLVMCG/BaseGen.py`

1. **扩展 `_set_node_info`**：记录当前指令的源码位置到 `SourceMap`

```python
def _set_node_info(self, Node: ast.AST) -> None:
    self._current_lineno = getattr(Node, 'lineno', 0)
    self._current_col = getattr(Node, 'col_offset', 0)
    self._current_node_info = f" [line {self._current_lineno}, col {self._current_col}]"
    # 新增：记录到 SourceMap
    if self.func and self.builder and self.builder.block:
        loc: IrLocation = IrLocation(
            FuncName=self.func.name,
            BlockName=self.builder.block.name,
            InstrIdx=len(self.builder.block.instructions),
            SourceFile=self._current_source_file or '',
            LineNo=self._current_lineno,
            ColNo=self._current_col
        )
        self._source_map.append(loc)
```

2. **插入断点桩**：在每行源码对应的首条 IR 指令前插入

```llvm
; 运行时断点桩声明
declare void @__tpc_breakpoint(i32 %line, i8* %file)

; 在 main.py:255 的首条指令前插入
%src_file_ptr = getelementptr [12 x i8], [12 x i8]* @.src.main_py, i32 0, i32 0
call void @__tpc_breakpoint(i32 255, i8* %src_file_ptr)
```

3. **条件性插入**：仅当 `--debug` 编译选项启用时插入，release 构建完全剥离

4. **生成 .tpd 文件**：函数编译结束时，序列化 `SourceMap` 到 `.tpd`

#### 5.1.2 运行时库

新建 `includes/vdb_runtime.py`：

```python
import t
import c

# 全局断点表（行号 -> 是否启用）
_Breakpoints: t.CArray[t.CInt, 65536] | t.CPtr = [0]
# 当前调试器状态（0=运行, 1=暂停）
_DebugState: t.CInt = 0
# 当前源码文件名（用于断点匹配）
_CurrentFile: t.CArray[t.CInt8T, 256] | t.CPtr = [0]

@t.CExport
def __tpc_breakpoint(line: t.CInt, file: t.CPtr) -> None:
    """断点桩入口，由编译器在每个源码行前插入调用"""
    # 检查是否启用断点
    if _Breakpoints[line] == 0:
        return
    # 命中断点，陷入调试器循环
    _DebugState = 1
    _tpc_debug_loop(line, file)

def _tpc_debug_loop(line: t.CInt, file: t.CPtr) -> None:
    """调试器主循环，等待用户命令"""
    # 通过 IPC 或 stdio 与 vdb 前端通信
    # 解析命令：continue / step / next / print / info / backtrace
    while _DebugState == 1:
        cmd: t.CArray[t.CInt8T, 256] | t.CPtr = [0]
        stdio.scanf("%s", cmd)
        # ... 命令分派
```

#### 5.1.3 vdb 前端

新建 `lib/vdb/` 目录：

```
lib/vdb/
├── __init__.py
├── TpdLoader.py          # .tpd 文件加载器
├── BreakpointManager.py  # 断点管理
├── DebugSession.py       # 调试会话主循环
├── CommandParser.py      # 命令解析
└── SourceView.py         # 源码显示
```

**核心命令**：
- `break <file>:<line>` / `b <file>:<line>` — 设置断点
- `delete <n>` / `d <n>` — 删除断点
- `continue` / `c` — 继续执行
- `run` / `r` — 启动程序
- `list` / `l` — 显示当前源码上下文
- `info breakpoints` — 列出断点

### 5.2 Phase 2：变量查看

**目标**：`print x` / `info locals` / `info args`

#### 5.2.1 编译器改动

**位置**：`lib/core/LLVMCG/FuncGen.py` 或 `lib/core/Handles/HandlesFunctions.py`

函数编译结束时，序列化变量绑定：

```python
def _serialize_var_scope(self, FuncName: str) -> list[VarBinding]:
    bindings: list[VarBinding] = []
    for var_name, llvm_val in self.variables.items():
        if llvm_val is None:
            continue
        binding: VarBinding = VarBinding(
            VarName=var_name,
            LlvmName=llvm_val.name if hasattr(llvm_val, 'name') else '',
            TypeDesc=self._describe_llvm_type(llvm_val.type),
            IsSigned=self.var_signedness.get(var_name, True),
            StructClass=self.var_struct_class.get(var_name),
            StartLine=self._func_start_line,
            EndLine=self._func_end_line,
            Storage='stack',
            StackOffset=self._get_alloca_offset(llvm_val)  # 新增：记录栈偏移
        )
        bindings.append(binding)
    # 同样处理 _direct_values 和全局变量
    return bindings
```

#### 5.2.2 运行时变量读取

调试器通过以下方式读取变量值：

1. **栈变量**：通过 `StackOffset` + 当前栈帧基址读取
2. **全局变量**：通过符号表查找全局符号地址
3. **寄存器变量**：需调试器理解 SSA 值（较复杂，Phase 2 可跳过，仅支持 stack）

#### 5.2.3 类型渲染

```python
def RenderValue(llvm_val: bytes, type_meta: TypeMeta, type_desc: str) -> str:
    """根据类型渲染变量值"""
    if type_desc == 'i32':
        return str(int.from_bytes(llvm_val, 'little', signed=True))
    elif type_desc == 'i8*':
        # 尝试作为 C 字符串读取
        return f'"{read_cstring(llvm_val)}"'
    elif type_desc.endswith('*') and type_meta:
        # 结构体指针：展开成员
        return RenderStruct(llvm_val, type_meta)
    ...
```

### 5.3 Phase 3：单步执行

**目标**：`step` / `next` / `finish`

基于 SourceMap 实现：

- `step`（步入）：在下一行源码的首条 IR 指令前设临时断点，包括被调用函数内部
- `next`（步过）：在当前函数的下一行设临时断点，跳过函数调用
- `finish`（步出）：在当前函数的返回点设临时断点

**实现**：
1. 查 SourceMap 找到当前行的下一个源码行
2. 设置临时断点（一次性）
3. `continue`
4. 命中后自动删除临时断点

### 5.4 Phase 4：调用栈跟踪

**目标**：`backtrace` / `bt` / `frame <n>`

#### 5.4.1 编译器改动

每个函数入口/出口插入栈帧维护调用：

```llvm
; 函数入口
call void @__tpc_push_frame(
    i8* getelementptr([N x i8], [N x i8]* @.func.name, i32 0, i32 0),  ; 函数名
    i8* getelementptr([M x i8], [M x i8]* @.src.file, i32 0, i32 0),   ; 源文件
    i32 255                                                              ; 起始行
)

; 函数出口（每个 ret 前）
call void @__tpc_pop_frame()
```

#### 5.4.2 运行时栈结构

```python
import t

@t.CStruct
class FrameInfo:
    FuncName: t.CPtr        # i8* 函数名
    SrcFile: t.CPtr         # i8* 源文件
    LineNo: t.CInt          # 当前行号（动态更新）
    PrevFrame: 'FrameInfo' | t.CPtr  # 上一帧（链表）

# 全局栈顶
_FrameTop: FrameInfo | t.CPtr = t.CPtr(0)

@t.CExport
def __tpc_push_frame(func_name: t.CPtr, src_file: t.CPtr, line: t.CInt) -> None:
    frame: FrameInfo | t.CPtr = c.cast(FrameInfo, mb.alloc(FrameInfo.__sizeof__()))
    frame.FuncName = func_name
    frame.SrcFile = src_file
    frame.LineNo = line
    frame.PrevFrame = _FrameTop
    _FrameTop = frame

@t.CExport
def __tpc_pop_frame() -> None:
    if _FrameTop != t.CPtr(0):
        old: FrameInfo | t.CPtr = _FrameTop
        _FrameTop = _FrameTop.PrevFrame
        mb.free(old)
```

#### 5.4.3 断点桩更新当前行

`__tpc_breakpoint` 命中时，更新 `_FrameTop.LineNo`：

```python
@t.CExport
def __tpc_breakpoint(line: t.CInt, file: t.CPtr) -> None:
    if _Breakpoints[line] == 0:
        return
    if _FrameTop != t.CPtr(0):
        _FrameTop.LineNo = line
    _DebugState = 1
    _tpc_debug_loop(line, file)
```

### 5.5 Phase 5：异常栈跟踪

**目标**：`raise ValueError("msg")` 时输出完整调用栈

#### 5.5.1 编译器改动

**位置**：`lib/core/Handles/HandlesRaise.py`

在 `_HandleRaiseLlvm` 中，抛异常前捕获栈：

```python
def _HandleRaiseLlvm(self, Node: ast.Raise) -> None:
    # ... 原有错误码计算 ...
    # 新增：捕获调用栈
    capture_call = self.Gen.builder.call(
        self._get_or_declare_function('__tpc_capture_trace', ir.FunctionType(ir.VoidType(), [])),
        []
    )
    # ... 原有异常传播逻辑 ...
```

#### 5.5.2 异常结构扩展

将 `__eh_msg_out__`（i8**）扩展为指向包含栈的结构：

```python
import t

@t.CStruct
class ExceptionInfo:
    Code: t.CInt
    Message: t.CArray[t.CInt8T, 256] | t.CPtr
    TraceDepth: t.CInt
    TraceFuncs: t.CArray[t.CPtr, 64]    # 函数名指针数组
    TraceLines: t.CArray[t.CInt, 64]    # 对应行号
    TraceFiles: t.CArray[t.CPtr, 64]    # 对应源文件
```

#### 5.5.3 未捕获异常处理

在 `main` 函数返回前检查异常，打印栈：

```python
def main() -> t.CInt:
    # ... 用户代码 ...
    # 编译器自动插入：检查未捕获异常
    if _UnhandledException != t.CPtr(0):
        _tpc_print_trace(_UnhandledException)
        return 1
    return testcheck.end()
```

### 5.6 Phase 6：硬错误捕获

**目标**：segfault / 除零 / 栈溢出时进入调试器

#### 5.6.1 信号处理器注册

```python
import t
import c

@t.CExport
def __tpc_signal_handler(sig: t.CInt) -> None:
    """OS 信号处理入口"""
    __tpc_capture_trace()
    # 打印信号类型
    if sig == 11:  # SIGSEGV
        stdio.printf("Segmentation fault\n")
    elif sig == 8:  # SIGFPE
        stdio.printf("Arithmetic exception\n")
    # 陷入调试器
    _tpc_debug_loop(0, t.CPtr(0))

def __tpc_install_signal_handlers() -> None:
    """在 main 入口前自动调用"""
    c.signal(11, __tpc_signal_handler)  # SIGSEGV
    c.signal(8, __tpc_signal_handler)   # SIGFPE
```

#### 5.6.2 编译器改动

在 `main` 函数入口自动插入 `__tpc_install_signal_handlers()` 调用（仅 `--debug` 模式）。

---

## 6. vdb 命令参考

### 6.1 启动与控制

| 命令 | 缩写 | 说明 |
|------|------|------|
| `run [args]` | `r` | 启动被调试程序 |
| `continue` | `c` | 继续执行至下一断点 |
| `step` | `s` | 单步进入函数 |
| `next` | `n` | 单步跳过函数 |
| `finish` | `f` | 执行至当前函数返回 |
| `quit` | `q` | 退出调试器 |

### 6.2 断点管理

| 命令 | 缩写 | 说明 |
|------|------|------|
| `break <file>:<line>` | `b` | 设置源码行断点 |
| `break <func>` | `b` | 设置函数入口断点 |
| `tbreak <file>:<line>` | `tb` | 临时断点（命中后删除） |
| `delete <n>` | `d` | 删除断点 n |
| `info breakpoints` | `i b` | 列出所有断点 |

### 6.3 变量查看

| 命令 | 缩写 | 说明 |
|------|------|------|
| `print <expr>` | `p` | 打印表达式值 |
| `info locals` | `i lo` | 列出当前局部变量 |
| `info args` | `i ar` | 列出函数参数 |
| `display <expr>` | - | 每次暂停自动显示 |
| `set <var>=<val>` | - |修改变量值 |

### 6.4 栈操作

| 命令 | 缩写 | 说明 |
|------|------|------|
| `backtrace` | `bt` | 显示调用栈 |
| `frame <n>` | `fr` | 切换到第 n 帧 |
| `up` | - | 向上切换一帧 |
| `down` | `do` | 向下切换一帧 |

### 6.5 源码浏览

| 命令 | 缩写 | 说明 |
|------|------|------|
| `list` | `l` | 显示当前行上下文 |
| `list <file>:<line>` | `l` | 显示指定位置 |
| `info source` | `i so` | 显示当前源文件信息 |

### 6.6 类型与结构

| 命令 | 缩写 | 说明 |
|------|------|------|
| `ptype <typename>` | `pt` | 显示类型定义 |
| `info types` | `i ty` | 列出所有类型 |
| `info exceptions` | `i ex` | 列出异常码表 |

---

## 7. 实现优先级

| 优先级 | 阶段 | 价值 | 改动量 |
|--------|------|------|--------|
| P0 | Phase 1（源码断点）+ Phase 2（变量查看） | 80% 调试价值 | 小 |
| P1 | Phase 4（调用栈） | 崩溃定位关键 | 中 |
| P2 | Phase 5（异常栈） | Python 语义匹配 | 中 |
| P3 | Phase 3（单步） | 体验提升 | 中（依赖 Phase 1） |
| P4 | Phase 6（硬错误） | 兜底保护 | 中 |
| P5 | DWARF 生成 | GDB 互操作 | 大（可选） |

---

## 8. 风险与考量

### 8.1 性能开销

- **断点桩**：仅 `--debug` 构建启用，release 完全剥离
- **IR 膨胀**：每行插入断点桩约增加 10-20% IR 体积，可接受
- **运行时开销**：断点桩检查为单次数组访问 + 分支预测，开销极低
- **栈帧维护**：每函数调用增加 2 次 `push/pop_frame`，约 5-10% 调用开销

### 8.2 兼容性

- **SHA1 命名**：vdb 需理解 SHA1 前缀，通过 `ModuleSha1` 字段还原为 `模块名.函数名` 显示
- **泛型特化**：`Stack[int]` 需作为完整类型名处理，TypeMeta 中保留特化名
- **跨模块**：`.tpd` 文件按模块生成，vdb 启动时合并所有相关 `.tpd`
- **`main` 特化**：`main` 函数无 SHA1 头，vdb 需特殊处理

### 8.3 安全性

- **栈帧分配**：使用 `mb.alloc` 而非 `c.malloc`，确保与 TransPyC 内存管理一致
- **信号处理器**：异步信号中避免调用非异步信号安全函数，仅设置标志位

### 8.4 限制

- **优化构建**：高优化级别（`-O2`+）下变量可能被优化掉，`.tpd` 中的 VarBinding 可能失效
- **内联函数**：内联后栈帧信息丢失，需在 `.tpd` 中标记 `IsInline`
- **尾调用优化**：破坏调用栈链，需禁用或特殊处理

---

## 9. 文件结构规划

```
lib/vdb/                          # vdb 调试器前端
├── __init__.py
├── TpdLoader.py                  # .tpd 文件加载与合并
├── BreakpointManager.py          # 断点管理
├── DebugSession.py               # 调试会话主循环
├── CommandParser.py              # 命令解析
├── SourceView.py                 # 源码显示
├── ValueRenderer.py              # 变量值渲染
├── StackWalker.py                # 调用栈遍历
└── IpcChannel.py                 # 与被调试进程的 IPC 通信

lib/core/LLVMCG/
└── DebugInfoGen.py               # 新增：.tpd 生成器（编译器侧）

includes/
└── vdb_runtime.py                # 运行时断点/栈帧/信号处理库
```

---

## 10. 与现有系统的集成点

### 10.1 编译器集成

- **`Phase2Translator.py`**：在生成 `.ll` 后，调用 `DebugInfoGen.GenerateTpd(module, gen, output_path)`
- **`BaseGen.py`**：`_set_node_info` 扩展记录 SourceMap；函数编译结束序列化 VarScope
- **`HandlesFunctions.py`**：函数入口/出口插入 `__tpc_push_frame`/`__tpc_pop_frame`（仅 debug 模式）
- **`HandlesRaise.py`**：`_HandleRaiseLlvm` 插入 `__tpc_capture_trace`

### 10.2 project.json 配置

新增 `debug` 选项：

```json
{
  "options": {
    "debug": true,
    "debug_info": "tpd"
  }
}
```

- `debug: true` — 启用调试构建（插入断点桩、栈帧维护、信号处理）
- `debug_info: "tpd"` — 生成 .tpd 文件（默认）
- `debug_info: "dwarf"` — 生成 DWARF（未来支持）
- `debug_info: "both"` — 同时生成（未来支持）

### 10.3 命令行集成

```bash
# 编译带调试信息
transpyc build --debug

# 直接启动调试器
transpyc debug ./output/MyApp.exe
# 等价于
vdb ./output/MyApp.exe
```

---

## 11. 开放问题

1. **llvmlite DIBuilder 支持度**：需验证 llvmlite 是否暴露 DIBuilder 接口，决定 DWARF 生成可行性
2. **IPC 协议**：vdb 前端与被调试进程的通信方式（管道/Socket/共享内存）待定
3. **远程调试**：是否支持远程调试（如 ViperOS 裸机目标）需进一步设计
4. **表达式求值**：`print x.y.z` 等复杂表达式是否需要完整 Python 解释器，还是简化为路径访问
5. **多线程**：TransPyC 当前是否支持多线程，调试器如何处理线程切换

---

## 12. 参考文档

- 现状分析：基于 2026-06-26 对 `lib/core/` 和 `lib/Projectrans/` 的完整搜索
- 异常机制：`wiki/09-exceptions.md`
- 导入机制：`wiki/10-imports.md`
- 符号表：`lib/core/SymbolTable.py`
- 类型系统：`lib/core/TypeSpec.py` / `lib/core/Handles/HandlesBase.py`
- LLVM 生成：`lib/core/LLVMCG/BaseGen.py` / `FuncGen.py` / `MemoryOps.py`

---

> **本文档为设计阶段产物，暂不实现。待社区需求或开发优先级提升后，按 Phase 1 → 2 → 4 → 5 → 3 → 6 顺序推进。**