# Node.js 模块兼容性提案

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [NODE_MODULE_SUPPORT_PROPOSAL.md](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md)
- [project.rs](file://src/project.rs)
- [codegen.rs](file://src/codegen.rs)
- [swc_transform.rs](file://src/swc_transform.rs)
- [standalone_gen.rs](file://src/standalone_gen.rs)
- [tsn_ffi.rs](file://src/tsn_ffi.rs)
- [lib.rs](file://runtime/src/lib.rs)
- [Cargo.toml](file://Cargo.toml)
- [main.rs](file://loader/src/main.rs)
- [test_standalone.rs](file://test_standalone.rs)
- [ts-native.toml](file://tsnp/console/ts-native.toml)
</cite>

## 更新摘要
**变更内容**
- 更新了已实现的 Phase 1（Shim 机制）和 Phase 2（node_modules 解析）功能
- 新增了 ts-native.toml 配置解析的详细实现
- 更新了模块解析流程和依赖图构建
- 增强了 CJS/ESM 转换机制的实现细节
- 添加了实际的代码示例和测试用例

## 目录
1. [项目概述](#项目概述)
2. [问题分析](#问题分析)
3. [解决方案架构](#解决方案架构)
4. [分阶段实施方案](#分阶段实施方案)
5. [关键技术实现](#关键技术实现)
6. [模块系统设计](#模块系统设计)
7. [性能考虑](#性能考虑)
8. [测试策略](#测试策略)
9. [风险评估](#风险评估)
10. [结论](#结论)

## 项目概述

ts-native 是一个将 TypeScript 编译为原生可执行文件的 AOT（Ahead-of-Time）编译器，基于 Cranelift 代码生成引擎。该项目的核心目标是在保持高性能的同时，提供对 Node.js 生态系统的模块兼容能力。

### 核心特性

- **AOT 编译**：TypeScript → SWC 解析 → HIR → Cranelift IR → 机器码 → COFF → 可执行文件
- **NaN-boxing 运行时**：64 位统一表示所有 JavaScript 值
- **跨模块编译**：支持多文件项目的依赖分析和编译顺序
- **可观测性**：编译报告包含内存使用、代码覆盖率、各阶段耗时
- **Node.js 模块兼容**：已实现 Phase 1（Shim 机制）和 Phase 2（node_modules 解析）

### 技术栈

- **编译器**：Rust + Cranelift + SWC
- **运行时**：C + Rust 混合实现
- **平台**：Windows x64（当前）
- **特性标志**：native-linker、coff

**章节来源**
- [README.md:1-163](file://README.md#L1-L163)
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)

## 问题分析

### 当前状态

**已实现的功能**：
- Phase 1：Shim 机制已完全实现，支持常见的纯算法 npm 包
- Phase 2：node_modules 解析已完全实现，支持 npm 包的源码编译
- ts-native.toml 配置解析已完全实现
- CJS/ESM 转换机制已完全实现

**模块解析流程**：
```typescript
// 项目中存在 src/fs.ts 时
import { readFile } from "fs";  // 解析为用户模块 src/fs.ts（带提示）
import { readFile } from "./fs"; // 始终解析为相对路径
```

### 核心挑战

| 挑战 | 说明 | 当前状态 |
|------|------|----------|
| **ABI 不兼容** | ts-native 用 NaN-tagged f64 表示所有值，Node.js 用 V8 对象 | 部分解决（值转换层） |
| **模块系统差异** | ts-native 无 node_modules 解析、无 require/exports 机制 | 已解决（Phase 2 实现） |
| **运行时差异** | ts-native 运行在 bare-metal，无 Node.js 事件循环/Buffer/Stream | 部分解决（Shim 机制） |
| **包类型多样** | npm 包分为纯 JS、C++ Addon、WASM 三类，处理方式完全不同 | 部分解决（Shim + npm 包解析） |

### npm 包分类

| 类型 | 占比 | 示例 | 可原生化的难度 | 当前支持状态 |
|------|------|------|---------------|-------------|
| **纯算法/工具** | ~40% | lodash、dayjs、underscore | 低——纯计算，可重写为 native | ✅ Phase 1 + Phase 2 |
| **DOM/浏览器** | ~15% | jquery、react、vue | 不适用——ts-native 无 DOM | ❌ 不支持 |
| **Node.js 专属** | ~25% | express、koa、fastify | 高——依赖事件循环/Stream | ⚠️ 部分支持（Shim） |
| **C++ Addon** | ~5% | sharp、node-gyp、bcrypt | 中——需 FFI 桥接 | ✅ Phase 3（计划中） |
| **WASM** | ~5% | sql.js、wasm-pack 包 | 低——WASM 可直接嵌入 | ⚠️ 部分支持（Shim） |
| **混合型** | ~10% | axios、uuid | 中——部分可原生化 | ⚠️ 部分支持（Shim + npm） |

**章节来源**
- [NODE_MODULE_SUPPORT_PROPOSAL.md:1-497](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L1-L497)

## 解决方案架构

### 总体架构

```mermaid
graph TB
subgraph "编译时"
TS[TypeScript 源码]
SWC[SWC 解析器]
HIR[HIR 生成]
CRANELIFT[Cranelift IR]
MACHINE[机器码]
COFF[COFF 生成]
end
subgraph "运行时"
LOADER[tsn-loader]
RUNTIME[tsn_runtime.dll]
SHIMS[Shim 模块]
FFI[FFI 桥接]
QUICKJS[QuickJS 引擎]
end
TS --> SWC --> HIR --> CRANELIFT --> MACHINE --> COFF
COFF --> LOADER
LOADER --> RUNTIME
RUNTIME --> SHIMS
RUNTIME --> FFI
RUNTIME --> QUICKJS
```

**图表来源**
- [README.md:18-31](file://README.md#L18-L31)
- [NODE_MODULE_SUPPORT_PROPOSAL.md:242-260](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L242-L260)

### 模块兼容性层次

```mermaid
flowchart TD
A[用户导入请求] --> B{模块类型判断}
B --> |相对路径| C[直接解析为相对文件]
B --> |用户模块| D[解析为项目内模块]
B --> |Shim 模块| E[使用预定义 Shim 实现]
B --> |npm 包| F{npm 包类型}
F --> |纯 JS| G[源码编译]
F --> |C++ Addon| H[FFI 桥接]
F --> |WASM| I[WASM 嵌入]
F --> |Node.js 专属| J[QuickJS 回退]
C --> K[编译链接]
D --> K
E --> K
G --> K
H --> K
I --> K
J --> K
```

**图表来源**
- [project.rs:285-354](file://src/project.rs#L285-L354)
- [NODE_MODULE_SUPPORT_PROPOSAL.md:363-432](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L363-L432)

**章节来源**
- [NODE_MODULE_SUPPORT_PROPOSAL.md:31-322](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L31-L322)

## 分阶段实施方案

### 阶段 1：包注册与 Shim 机制（已完成）

**目标**：为常用的纯算法 npm 包提供 native shim，在编译期替换为等价的 native 实现。

**实现机制**：

```mermaid
sequenceDiagram
participant User as 用户代码
participant Resolver as 模块解析器
participant Config as 配置系统
participant CodeGen as 代码生成器
User->>Resolver : import { debounce } from "lodash"
Resolver->>Config : 检查 ts-native.toml 配置
Config-->>Resolver : 返回 shim 映射
Resolver->>CodeGen : 生成 import_bindings
CodeGen->>CodeGen : 替换为 shim 函数调用
CodeGen-->>User : 编译后的原生代码
```

**配置示例**：
```toml
[shims]
lodash = "ts_native_shim_lodash"
dayjs = "ts_native_shim_dayjs"
uuid = "ts_native_shim_uuid"
```

**Shim 函数签名**：
```rust
#[no_mangle]
pub extern "C" fn js_ts_native_shim_lodash_debounce(fn_ref: f64, wait_ms: f64) -> f64 {
    // native 实现 debounce 逻辑
}
```

**优点**：
- 实现简单，复用现有 FFI 机制
- 零运行时开销（编译为原生代码）
- 渐进式：按需添加 shim

**缺点**：
- 需要逐个包编写 shim
- 无法覆盖所有 npm 包

**修改范围**：
- `project.rs`：`resolve_import` 增加 shim 查找
- `codegen.rs`：`import_bindings` 处理 shim 模块名
- 新增 `runtime/shims/` 目录

**章节来源**
- [NODE_MODULE_SUPPORT_PROPOSAL.md:33-86](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L33-L86)
- [project.rs:338-344](file://src/project.rs#L338-L344)

### 阶段 2：node_modules 解析 + CJS/ESM 转 HIR（已完成）

**目标**：支持解析 node_modules 目录，将纯 JS npm 包的源码作为 ts-native 编译输入。

**实现机制**：

```mermaid
flowchart TD
A[resolve_import() 增强] --> B{导入路径类型}
B --> |相对路径| C[现有逻辑]
B --> |用户模块| D[现有逻辑]
B --> |Shim| E[阶段 1 逻辑]
B --> |node_modules| F[新增逻辑]
F --> G[查找 package.json]
G --> H[解析 "main" / "exports" 字段]
H --> I[检查入口文件是否存在]
I --> J{文件类型}
J --> |纯 JS| K[加入编译队列]
J --> |C/C++| L[走 FFI 桥接]
J --> |WASM| M[走 WASM 嵌入]
```

**包兼容性检查**：
```json
{
  "type": "module",           // ESM，直接编译
  "type": "commonjs",         // CJS，需转换  
  "exports": {               // 条件导出解析
    ".": {
      "import": "dist/index.mjs",
      "require": "dist/index.js"
    }
  },
  "main": "lib/index.js",     // 入口文件
  "types": "types/index.d.ts" // 类型信息
}
```

**CJS → HIR 转换示例**：
```typescript
// npm 包中的 CommonJS 代码
const _ = require("lodash");
module.exports = _.debounce;

// 转换为 HIR
ImportBinding { local: "_", module: "lodash", imported: "default" }
VarDecl { name: "module_exports", init: Property { object: "_", name: "debounce" } }
```

**优点**：
- 支持大部分纯 JS 包
- 源码级编译，零运行时依赖
- 复用现有 HIR + codegen 管线

**缺点**：
- 需要实现 CJS → HIR 转换
- 不支持运行时动态 require
- 不支持 C++ Addon 和复杂 Node.js API 依赖的包

**修改范围**：
- `project.rs`：node_modules 解析、package.json 读取
- `swc_transform.rs`：CJS require/module.exports → HIR
- `dep_graph.rs`：npm 包依赖加入依赖图

**章节来源**
- [NODE_MODULE_SUPPORT_PROPOSAL.md:89-156](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L89-L156)
- [project.rs:356-401](file://src/project.rs#L356-L401)

### 阶段 3：FFI 桥接 Node.js C++ Addon（进行中）

**目标**：对于包含 C/C++ 原生代码的 npm 包（如 `sharp`、`bcrypt`），通过 FFI 直接调用其编译后的 DLL。

**实现机制**：

```mermaid
sequenceDiagram
participant Compiler as 编译器
participant Config as 配置系统
participant Runtime as 运行时
participant DLL as C++ Addon DLL
Compiler->>Config : 读取 ts-native.toml [native_addons]
Config-->>Compiler : 返回 DLL 配置
Compiler->>Compiler : 生成 FFI 调用代码
Compiler-->>Runtime : 编译后的可执行文件
Runtime->>Runtime : 加载 DLLstandalone_gen.rs 增强
Runtime->>DLL : GetProcAddress("resize")
DLL-->>Runtime : 返回结果
Runtime-->>Caller : 转换为 NaN-tagged 值
```

**配置示例**：
```toml
[native_addons.sharp]
dll = "sharp.dll"

[native_addons.sharp.functions]
resize = "sharp_resize"
rotate = "sharp_rotate"
```

**值转换层**：
```rust
pub extern "C" fn tsn_ffi_sharp_resize(input: f64, width: f64, height: f64) -> f64 {
    // f64(NaN-tagged) → 原生 Buffer 指针
    let buf = nan_to_buffer(input);
    let w = nan_to_i32(width) as u32;
    let h = nan_to_i32(height) as u32;
    
    // 调用 sharp DLL
    let result = sharp_resize(buf, w, h);
    
    // 原生结果 → f64(NaN-tagged)
    buffer_to_nan(result)
}
```

**优点**：
- 支持高性能 C/C++ 库
- 直接调用原生代码，性能最优

**缺点**：
- 需要为每个包编写 FFI 桥接配置
- 值转换复杂（Buffer、回调等）
- 平台相关（Windows DLL / Linux SO）

**修改范围**：
- `standalone_gen.rs`：支持加载额外 DLL
- 新增 `runtime/ffi_bridge.rs`
- 新增 FFI 桥接配置解析

**章节来源**
- [NODE_MODULE_SUPPORT_PROPOSAL.md:159-224](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L159-L224)
- [standalone_gen.rs:94-107](file://src/standalone_gen.rs#L94-L107)

### 阶段 4：嵌入 QuickJS 运行时（计划中）

**目标**：在 runtime 中嵌入轻量 JS 引擎 QuickJS，将无法原生化的 npm 包调用委托给 JS 引擎执行。

**实现机制**：

```mermaid
graph TB
subgraph "ts-native 编译输出"
EXE[可执行文件]
CODE[编译后的原生代码<br/>(用户代码 + 已原生化的 npm 包)]
end
subgraph "tsn_runtime.dll"
NATIVE[Native FFI<br/>(js_xxx 函数)]
QUICKJS[QuickJS 引擎<br/>(fallback 执行)]
end
EXE --> NATIVE
EXE --> QUICKJS
NATIVE --> CODE
QUICKJS --> CODE
```

**调用流程**：
```mermaid
sequenceDiagram
participant User as 用户代码
participant Compiler as 编译器
participant Runtime as 运行时
participant QuickJS as QuickJS 引擎
User->>Compiler : import { get } from "axios"
Compiler->>Compiler : 检测到 axios 在 fallback 列表中
Compiler->>Runtime : 生成 tsn_js_engine_call 调用
Runtime->>QuickJS : 加载 axios 的 JS 源码
QuickJS->>QuickJS : 执行 axios.get(url, config)
QuickJS-->>Runtime : 结果转换
Runtime-->>User : 返回给原生代码
```

**配置示例**：
```toml
[js-engine]
enabled = true
fallback = ["express", "axios", "koa"]
```

**值转换**：
```rust
pub extern "C" fn tsn_js_engine_call(module: f64, method: f64, args: f64) -> f64 {
    let mod_name = nan_to_string(module);  // "axios"
    let fn_name = nan_to_string(method);   // "get"
    let args_array = nan_to_array(args);   // [url, config]
    
    // 在 QuickJS 中执行
    let result = qjs_call_function(&mod_name, &fn_name, &args_array);
    
    // QuickJS 值 → NaN-tagged f64
    qjs_value_to_nan(result)
}
```

**QuickJS 选择理由**：
- 轻量（~210KB 编译后）
- 支持 ES2020（包括 ESM）
- 可嵌入（C API，BSD 协议）
- 快速启动（无 V8 的 JIT 预热开销）
- 支持 WASM

**优点**：
- 兼容所有纯 JS npm 包（100% 覆盖）
- 渐进式：已原生化的包走快速路径，未原生化的走 QuickJS
- 可运行时动态加载模块

**缺点**：
- QuickJS 执行比原生慢 10-100x
- 增加 runtime 体积（~200KB）
- 值转换有性能开销
- 不支持 C++ Addon（除非 QuickJS 也通过 FFI 桥接）

**修改范围**：
- 新增 `runtime/js_engine.rs`：QuickJS 嵌入和 FFI
- `codegen.rs`：fallback 调用生成
- `standalone_gen.rs`：QuickJS runtime 加载
- `project.rs`：fallback 配置解析

**章节来源**
- [NODE_MODULE_SUPPORT_PROPOSAL.md:227-321](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L227-L321)

## 关键技术实现

### 模块解析增强

```mermaid
flowchart TD
A[resolve_import 增强伪代码] --> B{导入路径判断}
B --> C[相对路径处理]
B --> D[用户模块优先]
B --> E[Shim 查找]
B --> F[node_modules 查找]
B --> G[内置模块处理]
C --> H[现有逻辑]
D --> I[项目内文件检查]
E --> J[ts-native.toml 配置]
F --> K[package.json 解析]
G --> L[None 返回]
```

**实现细节**：
- **相对路径**：`./utils/math` → `src/utils/math.ts`
- **用户模块优先**：项目中存在同名文件优先于内置模块
- **Shim 机制**：配置文件映射到预定义的 native 实现
- **npm 包解析**：支持 `exports`、`main`、`types` 字段

**章节来源**
- [NODE_MODULE_SUPPORT_PROPOSAL.md:363-432](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md#L363-L432)
- [project.rs:285-354](file://src/project.rs#L285-L354)

### 代码生成器增强

```mermaid
classDiagram
class CodeGen {
+HashMap import_bindings
+HashMap module_symbols
+compile_coff(exprs) Vec~u8~
+compile_to_raw_data(exprs) RawModuleData
+call_import(ctx, builder, name, args) Value
}
class ImportBinding {
+UserModule
+BuiltinModule
+ShimModule(String)
+NpmPackage
}
class RawModuleData {
+HashMap functions
+HashMap data_items
+Vec symbols
+Vec relocations
}
CodeGen --> ImportBinding : "使用"
CodeGen --> RawModuleData : "生成"
```

**图表来源**
- [codegen.rs:254-272](file://src/codegen.rs#L254-L272)
- [codegen.rs:434-444](file://src/codegen.rs#L434-L444)

**章节来源**
- [codegen.rs:446-477](file://src/codegen.rs#L446-L477)

### 运行时函数映射

```mermaid
graph LR
A[模块函数名] --> B[to_runtime_fn_name]
B --> C[驼峰转下划线]
C --> D[js_fs_read_file_sync]
C --> E[js_process_cwd]
C --> F[js_math_sin]
```

**函数映射规则**：
- `fs.readFileSync` → `js_fs_read_file_sync`
- `process.cwd` → `js_process_cwd`
- `Math.sin` → `js_math_sin`

**章节来源**
- [codegen.rs:393-433](file://src/codegen.rs#L393-L433)

## 模块系统设计

### 依赖图构建

```mermaid
flowchart TD
A[项目入口] --> B[解析导入语句]
B --> C{导入类型}
C --> |相对路径| D[本地文件]
C --> |用户模块| E[项目内模块]
C --> |Shim| F[预定义实现]
C --> |npm 包| G[node_modules]
D --> H[添加到依赖图]
E --> H
F --> H
G --> I[解析 package.json]
I --> H
H --> J[拓扑排序]
J --> K[编译顺序确定]
```

**依赖图实现**：
- 支持循环依赖检测
- 自动处理模块间依赖关系
- 生成编译顺序

**章节来源**
- [project.rs:98-171](file://src/project.rs#L98-L171)

### CJS/ESM 转换机制

```mermaid
sequenceDiagram
participant Parser as SWC 解析器
participant Transformer as 转换器
participant HIR as HIR 表达式
Parser->>Transformer : 解析 ES 模块导入
Transformer->>Transformer : 转换为 ImportBinding
Transformer-->>HIR : 生成 HIR 表达式
Parser->>Transformer : 解析 CJS require
Transformer->>Transformer : 转换为 ImportBinding
Transformer-->>HIR : 生成 HIR 表达式
```

**转换规则**：
- `import { debounce } from "lodash"` → `ImportBinding { local: "debounce", module: "lodash", imported: "debounce" }`
- `const _ = require("lodash")` → `ImportBinding { local: "_", module: "lodash", imported: "default" }`

**章节来源**
- [swc_transform.rs:60-104](file://src/swc_transform.rs#L60-L104)
- [swc_transform.rs:195-251](file://src/swc_transform.rs#L195-L251)

## 性能考虑

### 性能对比矩阵

| 维度 | 阶段 1: Shim | 阶段 2: 源码编译 | 阶段 3: FFI 桥接 | 阶段 4: QuickJS |
|------|:---:|:---:|:---:|:---:|
| **实现难度** | 低 | 中 | 中 | 高 |
| **包覆盖率** | 逐个添加 | ~40%（纯 JS） | ~5%（C++ 包） | ~95%（纯 JS） |
| **运行时性能** | 原生速度 | 原生速度 | 原生速度 | 10-100x 慢 |
| **额外依赖** | 无 | 无 | 原生 DLL | QuickJS (~200KB) |
| **修改范围** | 小 | 中 | 中 | 大 |
| **推荐优先级** | ★★★★★ | ★★★★☆ | ★★★☆☆ | ★★☆☆☆ |

### 编译性能优化

```mermaid
graph TB
subgraph "编译阶段"
A[解析 TypeScript] --> B[生成 HIR]
B --> C[代码生成]
C --> D[COFF 输出]
end
subgraph "性能指标"
E[总耗时]
F[内存使用]
G[代码大小]
H[函数数量]
end
A --> E
B --> F
C --> G
D --> H
```

**编译报告示例**：
```
╔══════════════════════════════════════════════════════════════╗
║              Compile Report                                  ║
╠══════════════════════════════════════════════════════════════╣
║ Total Duration:          4 ms
║ Memory Usage:       9.9 MB
║ Code Size:            2 KB  (6 modules)
║ Data Size:            58 B
║ Functions:      14/14 compiled (100%)
╠══════════════════════════════════════════════════════════════╣
║ Phase Timings:                                               ║
║   Module Compilation                              1 ms      9.7 MB
║   Executable Generation                           3 ms      9.9 MB
║   Report Generation                               0 ms      9.9 MB
```

**章节来源**
- [README.md:89-107](file://README.md#L89-L107)

## 测试策略

### 测试覆盖范围

1. **单元测试**：核心模块功能验证
2. **集成测试**：模块解析和编译流程
3. **性能测试**：编译时间和运行时性能
4. **兼容性测试**：不同 npm 包的兼容性

### 测试用例设计

```mermaid
flowchart TD
A[测试套件] --> B[模块解析测试]
A --> C[代码生成测试]
A --> D[运行时函数测试]
A --> E[性能基准测试]
B --> F[相对路径解析]
B --> G[用户模块优先级]
B --> H[Shim 匹配]
B --> I[npm 包解析]
C --> J[HIR 生成]
C --> K[代码优化]
C --> L[COFF 生成]
D --> M[内置函数]
D --> N[FFI 调用]
D --> O[错误处理]
```

**章节来源**
- [project.rs:459-744](file://src/project.rs#L459-L744)

## 风险评估

### 技术风险

| 风险类型 | 风险描述 | 影响程度 | 缓解措施 |
|----------|----------|----------|----------|
| **ABI 不兼容** | NaN-tagged vs V8 对象 | 高 | 值转换层、类型系统 |
| **模块系统差异** | 无 node_modules 解析 | 中 | 增加 npm 包解析支持 |
| **运行时差异** | 无事件循环/Stream | 中 | QuickJS 嵌入 |
| **包类型复杂性** | C++ Addon/WASM 处理 | 高 | 分阶段实现 |

### 实施风险

| 风险类型 | 风险描述 | 影响程度 | 时间安排 |
|----------|----------|----------|----------|
| **开发延期** | 复杂的 FFI 桥接 | 中 | 2-3 周 |
| **兼容性问题** | 不同 npm 包行为差异 | 高 | 持续测试 |
| **性能下降** | QuickJS 引擎引入 | 中 | 优化转换层 |
| **维护成本** | 多种兼容方案 | 中 | 渐进式迁移 |

## 结论

Node.js 模块兼容性提案提供了一个分阶段、渐进式的解决方案，能够在保持 ts-native 性能优势的同时，逐步扩展对 Node.js 生态系统的兼容能力。

### 已完成的里程碑

**Phase 1（Shim 机制）已完成**：
- 支持常见的纯算法 npm 包（lodash、dayjs、uuid 等）
- 完整的 ts-native.toml 配置解析
- 编译期替换为原生实现

**Phase 2（node_modules 解析）已完成**：
- 支持 npm 包的源码编译
- 完整的 package.json 解析（exports、main、types）
- CJS/ESM 源码转换

### 推荐实施路径

```mermaid
gantt
title 实施时间线
dateFormat YYYY-MM-DD
section 阶段 1
Shim 机制 :2024-01-01, 2w
section 阶段 2
npm 包解析 :2024-01-15, 3-4w
section 阶段 3
FFI 桥接 :2024-02-01, 2-3w
section 阶段 4
QuickJS 嵌入 :2024-02-15, 4-6w
```

### 预期成果

1. **阶段 1 + 2 组合**：覆盖 ~50% 的常用 npm 包使用场景
2. **完整实现**：支持 95%+ 的 npm 包兼容性
3. **性能保持**：原生代码执行，无运行时性能损失
4. **渐进迁移**：现有项目可平滑迁移到新模块系统

该方案在功能完整性、性能表现和实施复杂度之间取得了良好平衡，为 ts-native 的生态扩展奠定了坚实基础。

**章节来源**
- [test_standalone.rs:1-36](file://test_standalone.rs#L1-L36)
- [ts-native.toml:1-16](file://tsnp/console/ts-native.toml#L1-L16)