Native TS

Native TS 模块封装 Bun/Node.js 运行时的原生能力，为上层模块提供类型安全的系统级 API。这包括文件系统操作（异步读写、目录遍历、文件监听）、进程管理（子进程创建、信号处理）、网络通信（HTTP 客户端、WebSocket）等底层能力。模块的核心价值在于将运行时差异（Bun vs Node.js）封装在统一接口之后，上层代码无需关心运行时环境。

职责与设计理念

职责说明

原生 TypeScript/Bun 运行时工具集，提供底层系统能力的类型安全封装

设计理念

封装即安全——原生 API 是危险的（类型不安全、平台差异、错误处理不一致），封装层是类型安全的网关。运行时多态（Bun/Node）在这一层消化，上层只看到统一的 TypeScript 接口。

架构决策

为什么要支持 Bun 和 Node.js 双运行时？

运行时适配层，上层代码运行时无关

Bun 提供更快的启动速度和原生 TypeScript 支持，但 Node.js 的生态更成熟。双运行时支持让 Claude Code 在 Bun 环境下获得性能优势，在 Node.js 环境下保持兼容性。

⚖️ 每个系统 API 都需要写两份实现，但这些 API 数量有限（< 20 个），维护成本可控。

文件清单

文件名	用途
fs.ts	文件系统封装，统一 Bun/Node 的异步文件操作接口
process.ts	进程管理封装，子进程创建与信号处理
net.ts	网络通信封装，HTTP 客户端与 WebSocket 适配

使用场景

任何文件读写操作

上层模块调用 readFile/writeFile，Native TS 自动选择 Bun 或 Node.js 实现

执行 shell 命令

spawn() 统一创建子进程，处理 Bun.spawn 和 child_process.spawn 的 API 差异

依赖关系

无外部模块依赖

关键代码片段

运行时适配层

// 统一 Bun/Node 的文件读取接口
export async function readFile(path: string): Promise<string> {
  if (typeof Bun !== 'undefined') {
    return Bun.file(path).text()
  }
  const { readFile } = await import('node:fs/promises')
  return readFile(path, 'utf-8')
}

// 统一进程创建
export function spawn(cmd: string, args: string[]) {
  if (typeof Bun !== 'undefined') {
    return Bun.spawn([cmd, ...args])
  }
  const { spawn } = require('node:child_process')
  return spawn(cmd, args)
}

运行时检测 + 条件导入，将 Bun/Node 差异封装在统一接口之后

技术笔记

performance

Bun 优先策略

运行时检测使用 typeof Bun !== "undefined"，Bun 环境下直接使用原生 API，避免 Node.js 兼容层的开销。Bun 的文件 I/O 比 Node.js 快约 3-5 倍。

limitation

Bun API 覆盖度

部分 Node.js API（如 worker_threads 的高级特性）在 Bun 中尚未完全实现，这些场景会回退到 Node.js 兼容模式。