ABI 兼容性专题¶

重要性：⭐⭐（二进制兼容——native-ts / N-API / 跨平台） 真实位置：src/native-ts/ 推测（Yoga 移植）+ src/utils/native/（推测）角色：在多个平台（macOS / Linux / Windows）保持二进制兼容关联：topics/yoga-layout.md、topics/terminal-compatibility.md

1. ABI 是什么¶

ABI (Application Binary Interface) = 程序间二进制接口 - 函数调用约定 - 数据布局 - 类型大小

Claude Code 的 ABI 挑战： - Yoga（推测原本 C++）→ 纯 TS 移植 - N-API（推测） - 跨平台打包

2. 3 大 ABI 场景¶

2.1 纯 TS（已选）¶

// native-ts/yoga-layout/index.ts

纯 TS —— 无 ABI 问题，跨平台一致。

2.2 N-API（推测备选）¶

// N-API 调 .node 文件

N-API —— Node Native API，跨 Node 版本稳定。

2.3 WASM（推测备选）¶

// WASM 调 .wasm 文件

WASM —— WebAssembly，跨平台字节码。

项目选纯 TS —— 避免 ABI 复杂度。

3. native-ts/ 目录¶

src/native-ts/
├── yoga-layout/    (2578 行) Yoga 纯 TS 移植
└── ... (推测)

Yoga 移植 —— 详细见 yoga-layout.md。

3.1 为什么纯 TS¶

✅ 无 ABI 问题
✅ 无 WASM runtime
✅ 跨平台无坑
✅ 启动快（无 native load）
❌ 速度略慢（vs C++）

trade-off —— 项目选简单性。

4. Node ↔ Bun 兼容¶

4.1 Bun 兼容性¶

// bun build --target=bun-...
// 生成单文件可执行

Bun 编译 —— 跨平台。

4.2 Node 兼容性¶

// 推测：支持 Node 18+

Node 18+ —— 现代 Node。

4.3 API 差异¶

// 推测：避免 Bun-only API
// 或：Bun-only 时 feature() 门控

API 差异处理 —— feature gate。

5. N-API 兼容性¶

5.1 N-API 是什么¶

N-API = Node Native API - 跨 Node 版本 ABI 稳定 - 不需要重新编译每个 Node 版本

5.2 Claude Code 是否用¶

推测不直接用 —— 选纯 TS。

但 Yarn / npm install 可能用 C++ addons（推测）。

5.3 跨平台构建¶

# macOS x64
node-gyp build --arch=x64
# macOS arm64
node-gyp build --arch=arm64
# Linux x64
node-gyp build
# Windows
node-gyp build

4 平台 × N 架构 —— 推测有 prebuilt。

6. WASM 兼容性¶

6.1 WASM 优势¶

跨平台字节码
沙箱
性能

6.2 WASM 劣势¶

启动开销（runtime load）
体积
调试困难

6.3 Claude Code 决策¶

不用 WASM —— 选纯 TS。

7. 4 平台支持¶

平台	支持	备注
macOS x64	✅	商业版主要
macOS arm64	✅	M1/M2
Linux x64	✅	服务器
Linux arm64	⚠️ 推测	服务器
Windows x64	✅	商业版
Windows arm64	⚠️ 推测	-

4-6 平台 —— 跨平台。

8. 跨平台差异处理¶

8.1 路径¶

import { dirname, parse, relative, resolve } from 'path'
// Node 内置 path 模块

统一 path API。

8.2 文件系统¶

import { readdir, stat } from 'fs/promises'

async fs API。

8.3 进程¶

process.env, process.platform, process.cwd

process 统一。

8.4 平台特定¶

import { getPlatform } from './utils/platform.js'
// 'darwin' | 'linux' | 'win32'

getPlatform() —— 平台判断。

9. macOS 特有¶

9.1 keychain¶

// 仅 darwin
saveApiKey(apiKey)  // 走 keychain

macOS 特有。

9.2 plutil / reg query¶

// MDM 读取
// darwin: plutil
// win32: reg query

平台相关命令。

9.3 __CFBundleIdentifier¶

if (process.env.__CFBundleIdentifier === 'com.anthropic.claude-code-url-handler') {
  // macOS URL handler
}

macOS 特有。

10. Windows 特有¶

10.1 PATH hijacking¶

// main.tsx
process.env.NoDefaultCurrentDirectoryInExePath = '1'

Windows 特有。

10.2 PowerShell¶

// tools/PowerShellTool/

PowerShell 工具。

10.3 tmux 不支持¶

if (tmuxEnabled) {
  if (getPlatform() === 'windows') {
    process.stderr.write('Error: --tmux is not supported on Windows')
    process.exit(1)
  }
}

Windows 阻止。

11. ABI 稳定策略¶

11.1 纯 TS 优先¶

// 避免 native addon

首选。

11.2 N-API 兜底¶

// 必要时用 N-API

兜底。

11.3 WASM 拒绝¶

// 启动 > 极致速度

不用。

11.4 跨平台测试¶

# CI 跑 4 平台
macos-latest, ubuntu-latest, windows-latest

CI 测试。

12. native-ts 设计选择¶

12.1 不直接用 native¶

Bun 单文件可执行 —— 内置 TS 运行时。

12.2 移植而非 binding¶

// native-ts/yoga-layout/index.ts (2578 行)
// 纯 TS 移植 Facebook Yoga

移植而非 binding。

12.3 性能权衡¶

选项	启动	性能	复杂度
纯 TS	最快	慢	低
N-API	中	快	中
WASM	慢	最快	中

纯 TS 赢 —— 项目决策。

13. native 绑定推测¶

虽然项目主用纯 TS，N-API 绑定仍可能存在：

// 推测：readline / pty
// Node 内置 readline / pty 模块

推测用 Node 内置，不自己 binding。

14. 关键设计模式¶

14.1 纯 TS 优先¶

避免 ABI。

14.2 N-API 兜底¶

必要时用。

14.3 跨平台测试¶

4 平台 CI。

14.4 平台判断¶

getPlatform()。

14.5 平台特定处理¶

macOS / Windows 特性。

14.6 路径统一¶

Node 内置 path。

14.7 文件系统 async¶

fs/promises。

15. 关键洞察¶

15.1 纯 TS 选¶

避免 ABI 复杂度。

15.2 启动优先¶

vs 极致速度。

15.3 4 平台支持¶

mac / Linux / Windows。

15.4 平台特定¶

macOS keychain / Windows PATH。

15.5 跨平台测试¶

CI 4 平台。

15.6 N-API 兜底¶

必要时用。

15.7 WASM 拒绝¶

启动慢。

15.8 Bun 编译¶

单文件可执行。

15.9 Node 内置优先¶

readline / pty。

15.10 移植而非 binding¶

Yoga 是典型。

16. 改进方向¶

16.1 跨平台 binary¶

# 提供 mac / Linux / Windows / arm64 / x64 6 个 binary

6 个 binary。

16.2 平台特定优化¶

// 平台特定 fast path

优化。

16.3 自动更新¶

// 跨平台 auto-update

自动更新。

17. 阅读建议¶

看 src/native-ts/yoga-layout/index.ts —— 移植典范
看 utils/platform.ts —— 平台判断
看 main.tsx 平台特定代码 —— Windows PATH 等
看 .github/workflows/ci.yml —— CI 平台矩阵（推测）

18. 与其他专题的关系¶

文件	关系
`yoga-layout.md`	移植实例
`terminal-compatibility.md`	终端兼容
`i18n-strategy.md`	locale 推断