# 架构设计

<cite>
**本文档引用的文件**
- [Cargo.toml](file://Cargo.toml)
- [src/lib.rs](file://src/lib.rs)
- [src/main.rs](file://src/main.rs)
- [src/codegen.rs](file://src/codegen.rs)
- [src/swc_transform.rs](file://src/swc_transform.rs)
- [src/coff.rs](file://src/coff.rs)
- [src/project.rs](file://src/project.rs)
- [src/dep_graph.rs](file://src/dep_graph.rs)
- [src/project_compiler.rs](file://src/project_compiler.rs)
- [src/standalone_gen.rs](file://src/standalone_gen.rs)
- [src/standalone_loader.rs](file://src/standalone_loader.rs)
- [src/tsn_ffi.rs](file://src/tsn_ffi.rs)
- [src/native_linker.rs](file://src/native_linker.rs)
- [build.rs](file://build.rs)
- [loader/src/main.rs](file://loader/src/main.rs)
- [runtime/src/lib.rs](file://runtime/src/lib.rs)
- [src/bin/native_linker_main.rs](file://src/bin/native_linker_main.rs)
</cite>

## 更新摘要
**变更内容**
- 新增编译器管道架构的详细技术说明
- 完善组件交互关系的系统化分析
- 详细阐述数据流设计与转换机制
- 增强系统边界设计的技术细节
- 更新性能考量与故障排查指南

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [编译器管道架构](#编译器管道架构)
6. [组件交互关系](#组件交互关系)
7. [数据流设计](#数据流设计)
8. [系统边界设计](#系统边界设计)
9. [详细组件分析](#详细组件分析)
10. [依赖关系分析](#依赖关系分析)
11. [性能考量](#性能考量)
12. [故障排查指南](#故障排查指南)
13. [结论](#结论)
14. [附录](#附录)

## 简介
ts-native 是一个将 TypeScript 源码编译为本地机器码的编译器系统，采用分层管道设计：前端解析（SWC）、中间表示（HirExpr）、后端代码生成（Cranelift）。系统同时提供命令行编译器、动态库（DLL）接口以及独立可执行文件生成能力，支持 Windows 平台的 JIT 执行与插件机制。该系统通过清晰的编译器管道架构，实现了从 TypeScript 到本地机器码的高效转换。

## 项目结构
项目采用多 crate 组织方式，核心库位于 src/，包含编译器主逻辑；loader/ 提供独立运行时加载器；runtime/ 提供运行时 DLL；bin/ 目录包含原生链接器工具。Cargo.toml 定义了二进制产物与特性开关，支持条件编译和功能特性。

```mermaid
graph TB
subgraph "编译器核心"
CLI["命令行编译器<br/>src/main.rs"]
LIB["库入口<br/>src/lib.rs"]
SWC["前端解析<br/>src/swc_transform.rs"]
CG["代码生成<br/>src/codegen.rs"]
COFF["COFF工具<br/>src/coff.rs"]
FFI["FFI接口<br/>src/tsn_ffi.rs"]
END["项目编译器<br/>src/project_compiler.rs"]
DG["依赖图<br/>src/dep_graph.rs"]
PJ["项目发现<br/>src/project.rs"]
SG["独立生成器<br/>src/standalone_gen.rs"]
NL["原生链接器<br/>src/native_linker.rs"]
end
subgraph "运行时系统"
LDR["加载器<br/>loader/src/main.rs"]
SLDR["独立加载器<br/>src/standalone_loader.rs"]
RT["运行时DLL<br/>runtime/src/lib.rs"]
end
subgraph "工具链"
BIN["原生链接器<br/>src/bin/native_linker_main.rs"]
BUILD["构建脚本<br/>build.rs"]
end
CLI --> SWC
CLI --> CG
SWC --> CG
CG --> COFF
CG --> FFI
END --> PJ
END --> DG
END --> SWC
END --> CG
END --> SG
LDR --> RT
SLDR --> RT
NL --> COFF
BIN --> NL
```

**图表来源**
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [src/project_compiler.rs:1-728](file://src/project_compiler.rs#L1-L728)
- [src/dep_graph.rs:1-257](file://src/dep_graph.rs#L1-L257)
- [src/project.rs:1-461](file://src/project.rs#L1-L461)
- [src/swc_transform.rs:1-800](file://src/swc_transform.rs#L1-L800)
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)
- [src/coff.rs:1-388](file://src/coff.rs#L1-L388)
- [src/standalone_gen.rs:1-637](file://src/standalone_gen.rs#L1-L637)
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)
- [src/standalone_loader.rs:1-339](file://src/standalone_loader.rs#L1-L339)
- [src/native_linker.rs:1-300](file://src/native_linker.rs#L1-L300)
- [src/bin/native_linker_main.rs:1-200](file://src/bin/native_linker_main.rs#L1-L200)
- [runtime/src/lib.rs:1-800](file://runtime/src/lib.rs#L1-L800)

**章节来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [src/main.rs:1-79](file://src/main.rs#L1-L79)

## 核心组件
- **前端解析器**：基于 SWC 5.x 解析 TypeScript，生成中间表达（HirExpr）。
- **代码生成器**：基于 Cranelift 将 HirExpr 编译为 COFF 对象，并支持直接生成原始模块数据。
- **项目编译器**：管理多模块项目，构建依赖图，按拓扑顺序编译并生成独立可执行文件。
- **运行时加载器**：支持从 COFF 文件或 DLL 编译结果直接执行，具备插件加载与重定位能力。
- **FFI 接口**：导出 DLL 函数供外部程序调用，支持编译结果与 COFF 字节流两种输出。
- **原生链接器**：提供 COFF 文件的链接和处理能力，支持独立链接器功能。

**章节来源**
- [src/swc_transform.rs:1-800](file://src/swc_transform.rs#L1-L800)
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)
- [src/project_compiler.rs:1-728](file://src/project_compiler.rs#L1-L728)
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)
- [src/tsn_ffi.rs:1-341](file://src/tsn_ffi.rs#L1-L341)
- [src/native_linker.rs:1-300](file://src/native_linker.rs#L1-L300)

## 架构概览
系统采用"前端解析 → 中间表示 → 后端生成"的经典编译器管道，结合 Cranelift 的模块化与对象输出能力，实现从 TypeScript 到本地可执行代码的完整链路。项目编译器负责多模块场景下的依赖管理与闭包合并，独立生成器将模块数据序列化为 .tsnobj，运行时加载器负责 JIT 执行与符号解析。

```mermaid
sequenceDiagram
participant User as "用户"
participant CLI as "命令行编译器"
participant SWC as "前端解析"
participant CG as "代码生成"
participant COFF as "COFF输出"
participant LDR as "加载器"
User->>CLI : 提交 TypeScript 源码
CLI->>SWC : 解析 TypeScript
SWC-->>CLI : 生成 HirExpr
CLI->>CG : 编译为 COFF
CG->>COFF : 生成 .obj 字节流
COFF-->>CLI : 返回 .obj
CLI-->>User : 输出 .obj 文件
User->>LDR : 运行 tsn-loader
LDR->>LDR : 选择执行模式COFF/DLL
LDR->>LDR : 加载 tsn_runtime.dll
LDR->>LDR : 分配可执行内存
LDR->>LDR : 应用重定位
LDR-->>User : 执行入口函数并返回结果
```

**图表来源**
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/swc_transform.rs:1-800](file://src/swc_transform.rs#L1-L800)
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)

## 编译器管道架构

### 管道设计原则
ts-native 编译器管道遵循以下设计原则：
- **模块化**：每个阶段独立封装，职责明确
- **可扩展性**：支持插件和自定义扩展
- **性能优化**：两遍扫描、字符串池、对齐策略
- **错误处理**：分层错误传播与恢复机制

### 三段式编译架构
```mermaid
flowchart TD
subgraph "前端解析阶段"
TS["TypeScript 源码"] --> SWC["SWC 解析器"]
SWC --> AST["AST 树"]
AST --> HIR["HirExpr 中间表示"]
end
subgraph "中间转换阶段"
HIR --> PASS1["第一遍扫描<br/>收集符号/字符串"]
PASS1 --> PASS2["第二遍扫描<br/>生成 IR 指令"]
PASS2 --> IR["Cranelift IR"]
end
subgraph "后端生成阶段"
IR --> CG["代码生成器"]
CG --> OBJ["COFF 对象文件"]
OBJ --> RAW["RawModuleData<br/>原始模块数据"]
end
```

**图表来源**
- [src/swc_transform.rs:10-176](file://src/swc_transform.rs#L10-L176)
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [src/codegen.rs:607-707](file://src/codegen.rs#L607-L707)

### 阶段间数据转换
- **TypeScript → AST**：SWC 解析器处理语法分析
- **AST → HIR**：模块转换为统一中间表示
- **HIR → IR**：两遍扫描生成 Cranelift IR
- **IR → COFF**：目标码生成与对象文件输出

**章节来源**
- [src/swc_transform.rs:1-800](file://src/swc_transform.rs#L1-L800)
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)

## 组件交互关系

### 分层架构设计
系统采用清晰的分层架构，各层之间通过标准化接口通信：

```mermaid
graph TB
subgraph "用户接口层"
CLI["命令行界面"]
GUI["图形界面"]
end
subgraph "编译协调层"
PC["ProjectCompiler"]
DG["DependencyGraph"]
PM["ProjectManager"]
end
subgraph "编译执行层"
ST["SWC Transformer"]
CG["CodeGen"]
FF["FFI Interface"]
end
subgraph "运行时层"
RT["Runtime Library"]
SL["Standalone Loader"]
end
CLI --> PC
GUI --> PC
PC --> DG
PC --> PM
PM --> ST
ST --> CG
CG --> FF
FF --> RT
SL --> RT
```

**图表来源**
- [src/project_compiler.rs:190-246](file://src/project_compiler.rs#L190-L246)
- [src/tsn_ffi.rs:58-106](file://src/tsn_ffi.rs#L58-L106)
- [loader/src/main.rs:42-127](file://loader/src/main.rs#L42-L127)

### 组件耦合度分析
系统通过以下机制降低耦合度：
1. **接口抽象**：所有模块通过标准化接口进行通信
2. **数据契约**：明确的数据结构和协议规范
3. **功能分离**：每个模块专注于单一职责
4. **异步处理**：编译过程中的并行化处理

### 消息传递协议
系统采用标准化的消息传递协议：

| 协议类型 | 数据结构 | 用途 | 生命周期 |
|---------|----------|------|----------|
| TsnCompileResult | 包含代码、数据、重定位信息 | 编译结果传输 | 请求-响应 |
| ModuleData | 节区、符号、重定位表 | 独立可执行文件数据 | 持久化 |
| TsnSymbol | 符号名称、节区、偏移 | 符号解析 | 临时 |
| TsnRelocation | 重定位类型、目标符号 | 地址重定位 | 临时 |

**章节来源**
- [src/tsn_ffi.rs:27-44](file://src/tsn_ffi.rs#L27-L44)
- [src/standalone_gen.rs:11-34](file://src/standalone_gen.rs#L11-L34)

## 数据流设计

### 数据转换路径
从 TypeScript 源码到可执行文件的完整数据流：

```mermaid
sequenceDiagram
participant TS as "TypeScript 源码"
participant SWC as "SWC 解析器"
participant HIR as "HIR 树 (HirExpr)"
participant CG as "CodeGen"
participant COFF as "COFF 对象"
participant RAW as "RawModuleData"
participant PC as "ProjectCompiler"
participant SG as "StandaloneGen"
participant OBJ as ".tsnobj"
TS->>SWC : "读取并解析"
SWC-->>HIR : "生成 HIR 节点"
HIR->>CG : "遍历函数与表达式"
CG-->>COFF : "生成 COFF 字节流"
COFF->>RAW : "解析节区/符号/重定位"
PC->>COFF : "多模块编译与合并"
COFF->>SG : "合并模块数据"
SG-->>OBJ : "序列化为 .tsnobj"
```

**图表来源**
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:520-707](file://src/codegen.rs#L520-L707)
- [src/project_compiler.rs:334-382](file://src/project_compiler.rs#L334-L382)
- [src/standalone_gen.rs:390-605](file://src/standalone_gen.rs#L390-L605)

### 关键数据结构设计
- **HirExpr**：统一的 TypeScript 语法结构表示
- **RawModuleData**：从 COFF 提取的原始模块数据
- **ModuleData**：StandaloneGen 合并后的模块数据
- **CompileReport**：编译阶段统计与性能指标

### 数据一致性与并发控制
系统采用以下机制确保数据一致性：
- **RAII 模式**：严格的内存管理
- **不可变数据**：编译阶段的数据保护
- **原子操作**：多线程环境下的数据同步
- **事务性处理**：错误发生时的数据回滚

**章节来源**
- [src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)
- [src/codegen.rs:21-43](file://src/codegen.rs#L21-L43)
- [src/standalone_gen.rs:11-34](file://src/standalone_gen.rs#L11-L34)

## 系统边界设计

### FFI 接口边界
ts-native 的 FFI 接口设计遵循严格的 ABI 约定：

```mermaid
classDiagram
class TsnCompileResult {
+uint8* code_ptr
+uint32 code_len
+uint8* data_ptr
+uint32 data_len
+uint8* rdata_ptr
+uint32 rdata_len
+TsnSymbol* symbols
+uint32 symbol_count
+TsnRelocation* relocations
+uint32 reloc_count
+char* error_msg
+uint32 error_line
+uint32 error_col
+char* error_context
+void* _context
}
class TsnSymbol {
+uint8 section
+uint32 offset
+uint8[64] name
}
class TsnRelocation {
+uint8 section
+uint32 offset
+uint8 type_
+uint8 _padding
+uint8[64] target_name
}
class CompileContext {
+Vec~u8~ code
+Vec~u8~ data
+Vec~u8~ rdata
+Vec~TsnSymbol~ symbols
+Vec~TsnRelocation~ relocations
+CString error_msg
+CString error_context
}
TsnCompileResult --> TsnSymbol : "包含"
TsnCompileResult --> TsnRelocation : "包含"
TsnCompileResult --> CompileContext : "拥有"
```

**图表来源**
- [src/tsn_ffi.rs:11-44](file://src/tsn_ffi.rs#L11-L44)
- [src/tsn_ffi.rs:48-56](file://src/tsn_ffi.rs#L48-L56)

### 运行时库集成边界
JavaScript 运行时采用 NaN-tagging 技术实现高效的数据类型表示：

```mermaid
classDiagram
class JsRuntime {
+float64 js_string_from_static(char*)
+float64 js_strict_equals(float64, float64)
+float64 js_print(float64)
+float64 js_add(float64, float64)
+float64 js_sub(float64, float64)
+float64 js_array_new(float64)
+float64 js_object_new()
+float64 js_fs_read_file_sync(float64)
}
class JsValue {
+get_tag(float64) uint64
+is_number(float64) bool
+store_string(String) float64
+get_string(float64) Option~String~
}
class JsArray {
+Vec~float64~ elements
+usize length
}
class JsObject {
+HashMap~uint64, float64~ properties
}
JsRuntime --> JsValue : "使用"
JsRuntime --> JsArray : "管理"
JsRuntime --> JsObject : "管理"
```

**图表来源**
- [runtime/src/lib.rs:138-192](file://runtime/src/lib.rs#L138-L192)
- [runtime/src/lib.rs:65-103](file://runtime/src/lib.rs#L65-L103)
- [runtime/src/lib.rs:108-133](file://runtime/src/lib.rs#L108-L133)

### 安全边界设计
系统在多个层面实施了安全控制：
- **内存安全**：使用 RAII 模式管理内存分配
- **符号安全**：外部符号解析的白名单机制
- **访问控制**：DLL 加载的权限检查
- **指针验证**：边界检查和有效性验证

**章节来源**
- [src/tsn_ffi.rs:85-106](file://src/tsn_ffi.rs#L85-L106)
- [loader/src/main.rs:285-306](file://loader/src/main.rs#L285-L306)

## 详细组件分析

### 前端解析器（SWC）
- **使用 SWC 5.x API** 解析 TypeScript，支持装饰器、类、异步/等待等特性。
- **将 AST 转换为内部 HirExpr 表达式**，便于后续代码生成。
- **处理模块导入绑定**，为依赖分析与跨模块符号解析提供基础。

```mermaid
flowchart TD
Start(["开始：接收 TypeScript 源码"]) --> Parse["SWC 解析<br/>生成 Module"]
Parse --> Transform["转换为 HirExpr<br/>处理导入/导出/函数/类等"]
Transform --> Export["返回 HirExpr 列表"]
```

**图表来源**
- [src/swc_transform.rs:10-176](file://src/swc_transform.rs#L10-L176)

**章节来源**
- [src/swc_transform.rs:1-800](file://src/swc_transform.rs#L1-L800)

### 代码生成器（Cranelift）
- **基于 Cranelift 0.93.2** 生成本地代码，支持对象模块输出与原始模块数据提取。
- **支持字符串池、符号表、重定位表的收集与导出**。
- **提供 COFF 编译与原始数据编译两种路径**，满足不同执行场景。

```mermaid
classDiagram
class CodeGen {
+new()
+compile_coff(exprs) Vec<u8>
+compile_to_raw_data(exprs) RawModuleData
+set_module_symbols(map)
+get_compiled_function_count() usize
+source_map() &[SourceMapEntry]
+stats() &CompileStats
}
class RawModuleData {
+functions : HashMap<String, Vec<u8>>
+data_items : HashMap<String, Vec<u8>>
+symbols : Vec<RawSymbol>
+relocations : Vec<RawRelocation>
}
CodeGen --> RawModuleData : "生成"
```

**图表来源**
- [src/codegen.rs:254-707](file://src/codegen.rs#L254-L707)

**章节来源**
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)

### 项目编译器与依赖图
- **项目发现**：扫描目录，识别入口与模块文件，支持多种入口识别策略。
- **依赖图**：解析 import/export，构建有向无环图，支持拓扑排序与依赖闭包计算。
- **独立可执行**：按编译顺序合并模块，生成 .tsnobj 与预编译加载器，自动复制运行时 DLL。

```mermaid
graph LR
PRJ["项目发现<br/>src/project.rs"] --> DG["依赖图<br/>src/dep_graph.rs"]
DG --> PC["项目编译器<br/>src/project_compiler.rs"]
PC --> SG["独立生成器<br/>src/standalone_gen.rs"]
PC --> SLDR["独立加载器<br/>src/standalone_loader.rs"]
```

**图表来源**
- [src/project.rs:58-153](file://src/project.rs#L58-L153)
- [src/dep_graph.rs:43-132](file://src/dep_graph.rs#L43-L132)
- [src/project_compiler.rs:205-332](file://src/project_compiler.rs#L205-L332)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)

**章节来源**
- [src/project.rs:1-461](file://src/project.rs#L1-L461)
- [src/dep_graph.rs:1-257](file://src/dep_graph.rs#L1-L257)
- [src/project_compiler.rs:1-728](file://src/project_compiler.rs#L1-L728)
- [src/standalone_gen.rs:1-637](file://src/standalone_gen.rs#L1-L637)

### 运行时加载器与执行引擎
- **传统模式**：直接加载 COFF .obj 文件，解析节区、符号与重定位，分配可执行内存并执行。
- **DLL 模式**：调用 ts-native.dll 导出函数进行编译，支持编译结果与 COFF 字节流两种接口。
- **插件机制**：支持动态加载插件 DLL，解析外部符号（js_*）以实现运行时功能。

```mermaid
sequenceDiagram
participant LDR as "加载器"
participant RT as "运行时DLL"
participant MEM as "内存管理"
participant PLG as "插件DLL"
LDR->>RT : 加载 tsn_runtime.dll
LDR->>MEM : 分配可执行内存
LDR->>MEM : 复制代码/数据节区
LDR->>LDR : 应用重定位内部/外部
LDR->>PLG : 解析外部符号js_*
LDR->>MEM : 调用入口函数 main()
LDR-->>LDR : 返回执行结果
```

**图表来源**
- [loader/src/main.rs:537-743](file://loader/src/main.rs#L537-L743)
- [src/standalone_loader.rs:127-302](file://src/standalone_loader.rs#L127-L302)

**章节来源**
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)
- [src/standalone_loader.rs:1-339](file://src/standalone_loader.rs#L1-L339)

### FFI 接口与 DLL 导出
- **导出 tsn_compile、tsn_free_result、tsn_version** 等函数，供外部程序调用。
- **支持 COFF 可选导出**（启用 feature），返回标准 COFF 字节流。
- **统一错误处理与内存管理**，确保调用方正确释放资源。

**章节来源**
- [src/tsn_ffi.rs:1-341](file://src/tsn_ffi.rs#L1-L341)

## 依赖关系分析
- **语言与框架**：Rust 2021 edition，SWC 5.x、Cranelift 0.93.2、object crate。
- **构建依赖**：cc 1.0，用于编译 C 语言启动与运行时片段。
- **特性开关**：coff、native-linker，分别控制 COFF 导出与独立链接器功能。
- **运行时**：Windows 平台，依赖 kernel32 进行动态库加载与内存分配。

```mermaid
graph TB
Cargo["Cargo.toml 依赖"] --> SWC["swc_* 5.x"]
Cargo --> CL["cranelift-* 0.93.*"]
Cargo --> OBJ["object 0.29"]
Cargo --> LOG["log/env_logger"]
Build["build.rs"] --> CC["cc 1.0"]
Build --> CRT["runtime_nocrt/start_nocrt"]
```

**图表来源**
- [Cargo.toml:22-57](file://Cargo.toml#L22-L57)
- [build.rs:1-33](file://build.rs#L1-L33)

**章节来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [build.rs:1-33](file://build.rs#L1-L33)

## 性能考量
- **编译阶段**：解析与代码生成阶段均提供性能统计（parse_time_ms、codegen_time_ms 等），便于瓶颈定位。
- **内存管理**：项目编译器提供内存使用估算与阶段计时，支持大型项目分阶段编译。
- **执行阶段**：加载器对重定位应用进行计数与日志输出，便于评估执行开销。
- **优化建议**：合理划分模块、减少不必要的导入、利用 Cranelift 的优化设置。

**章节来源**
- [src/codegen.rs:240-252](file://src/codegen.rs#L240-L252)
- [src/project_compiler.rs:27-52](file://src/project_compiler.rs#L27-L52)

## 故障排查指南
- **编译错误**：FFI 接口会提取错误行号与上下文，便于快速定位问题。
- **重定位失败**：加载器会记录未解析的外部符号与内部符号，检查插件是否正确加载及符号命名是否一致。
- **运行时缺失**：确保 tsn_runtime.dll 与预编译加载器存在于输出目录，或手动复制运行时 DLL。
- **循环依赖**：依赖图构建阶段若检测到循环依赖会抛出错误，需调整模块导入关系。

**章节来源**
- [src/tsn_ffi.rs:294-341](file://src/tsn_ffi.rs#L294-L341)
- [loader/src/main.rs:632-711](file://loader/src/main.rs#L632-L711)
- [src/dep_graph.rs:205-210](file://src/dep_graph.rs#L205-L210)

## 结论
ts-native 通过清晰的编译器管道与模块化设计，实现了从 TypeScript 到本地机器码的高效转换。其多模式执行能力（COFF 直接执行、DLL 编译、独立可执行）满足不同场景需求；完善的依赖管理与性能统计为大规模项目提供了可扩展的基础。系统边界设计清晰，FFI 接口稳定，运行时库提供高效的 JavaScript 运行时支持。

## 附录

### 技术栈与版本兼容性
- **Rust**: 2021 edition
- **SWC**: 5.0.1/5.0.0/7.0.0
- **Cranelift**: 0.93.2
- **object**: 0.29
- **serde**: 1.0.197（固定版本）
- **serde_json**: 1.0.114（固定版本）

**章节来源**
- [Cargo.toml:22-57](file://Cargo.toml#L22-L57)

### 基础设施与部署拓扑
- **平台**：Windows（依赖 kernel32 与 VirtualAlloc/VirtualFree）
- **运行时**：tsn_runtime.dll（提供 js_* 符号）
- **输出**：.obj/.tsnobj 与独立 .exe（内嵌预编译加载器）
- **构建**：Rust 编译器与 cc 构建 C 片段

**章节来源**
- [loader/src/main.rs:106-127](file://loader/src/main.rs#L106-L127)
- [src/standalone_loader.rs:62-70](file://src/standalone_loader.rs#L62-L70)
- [runtime/src/lib.rs:1-800](file://runtime/src/lib.rs#L1-L800)

### 编译器管道扩展指南
- **新增前端**：实现新的解析器接口，适配不同的源码格式
- **自定义后端**：扩展 CodeGen 接口，支持新的目标架构
- **插件系统**：通过 FFI 接口扩展运行时功能
- **优化器**：在 IR 阶段插入自定义优化 pass