xbintsc 0.5.6 → 0.5.21

package/doc/zh-CN/implemented/binder.md

@@ -0,0 +1,13 @@
+# 名字绑定与作用域（Binder）
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/binder.md)
+
+实现位置：`src/binder/binder.ts`
+
+- 作用域种类：模块、函数、块、`for`、`catch`
+- 符号种类：`var` / `let` / `const` / `function` / `parameter` / `class` / `interface` / `type` / `enum` / `import` / `namespace`
+- `var` 与函数声明提升到函数作用域；`let` / `const` 保持块作用域
+- 标识符 → 声明 的解析；未解析标识符收集（`CannotFindName`）
+- 闭包捕获分析：被内层函数引用的外部变量标记 `captured` / `boxed`，并穿过中间闭包传递捕获索引
+- 参数登记为局部符号；命名函数表达式自名登记为 `const`
+- 类型专用声明（interface / type alias）不参与值捕获

package/doc/zh-CN/implemented/cli.md

@@ -0,0 +1,46 @@
+# CLI 与编程接口
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/cli.md)
+
+实现位置：`src/cli/main.ts`、`src/index.ts`、`bin/xbintsc.js`
+
+## CLI 命令
+
+```
+xbintsc build <file.ts> [options]   编译为原生二进制
+xbintsc run   <file.ts> [-- args]   编译并执行
+xbintsc emit  <file.ts>             打印 LLVM IR
+xbintsc version                     打印版本
+xbintsc help                        帮助
+```
+
+## CLI 选项
+
+```
+-o, --output <path>   输出路径
+    --out <dir>       输出目录（默认 build/）
+    --emit <kind>     exe | obj | ir（默认 exe）
+-O0..-O3              优化级别（默认 -O2）
+    --ext <names>     逗号分隔扩展（如 node）
+    --ext-native <m>  从 JSON manifest 注册 C++/Rust 扩展
+    --config <path>   使用项目配置（默认自动查找 xbintsc.config.json）
+    --no-config       不读取任何项目配置
+    --icon <path>     内嵌应用图标（PNG/ICO/ICNS）
+    --bundle          macOS：同时生成 .app bundle
+    --app-name <name> bundle / 显示名称
+    --app-id <id>     macOS bundle 标识符（如 com.example.demo）
+    --force           忽略增量缓存
+    --verbose         打印进度信息
+```
+
+## 编程接口
+
+```ts
+import { build, compileString } from "xbintsc";
+
+const { ir } = compileString("console.log(1 + 1);");
+const result = build("program.ts", { emit: "exe", outDir: "build" });
+```
+
+选项与结果类型（`BuildOptions`、`BuildResult`、`EmitKind`、`PhaseTiming`）位于
+`src/driver/options.ts`，并由 `src/driver/compiler.ts` / `xbintsc` 重新导出。

package/doc/zh-CN/implemented/codegen.md

@@ -0,0 +1,33 @@
+# LLVM IR 代码生成（Codegen）
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/codegen.md)
+
+实现位置：`src/codegen/llvm.ts`
+
+- 生成 LLVM IR 文本（`.ll`），无需自建寄存器分配（依赖 `alloca` + mem2reg）。
+- 语句 / 块边界值放在 `alloca`；条件与短路运算物化为临时槽，不使用 `phi`。
+- 属性读取按源码位置生成内联缓存：每个访问点拥有一个零初始化的 `[2 x i64]` 全局（`@ic.N`），传给 `xt_get_ic`。普通对象带有驻留的隐藏类 shape（`xt_shape`，`(parent, key)` 转移树），缓存保存 `(shape, 属性下标)`，命中时只需比较 shape 指针并校验一次键，无需线性扫描属性表。插入/删除属性以及整数键重排会重建或转移 shape，从而使旧缓存失效；数组、函数与容器回退到 `xt_get`。
+- 数值运算符保留内联双精度快路径；数值字面量操作数跳过标签检查。若条件表达式本身是比较、`in`、`instanceof` 或 `!`，其值已经是布尔标签，代码生成用 `icmp eq i64 value, XT_TRUE` 代替调用 `xt_truthy`（热循环条件因此少一次调用）。
+- 控制流：`if` / `while` / `do` / `for` / `for...of` / `for...in`，`switch`，`try/catch/finally`，`break` / `continue` / `return`。
+  - `for...of` 与展开通过 `xt_iter_open` → `xt_iter_has` / `xt_iter_value` 迭代数组、字符串、类型化数组、`Map`、`Set`、生成器以及任何暴露 `[Symbol.iterator]()` 的对象（`Map` 产出 `[key, value]` 对）；非可迭代值抛出 `TypeError`。数组还暴露稳定的 `Array.prototype[Symbol.iterator]`，调用后返回带 `next()` 且自身可迭代的迭代器对象。
+  - `switch` 以严格相等逐 `case` 测试，命中后执行并在 `break` 前穿透。
+  - `try/catch/finally` 通过运行时 `_setjmp` 帧实现：`xt_try_enter` 入栈、`_setjmp` 捕获、`xt_throw` 长跳转；IR 会把调用方的帧地址（`@llvm.frameaddress(0)`）作为 `_setjmp` 的第二个参数传入，与 clang 编译 MSVC 时的降级方式一致：Windows UCRT 的 `_setjmp` 会把这个帧存入 `_JUMP_BUFFER.Frame`，`longjmp` 再交给 `RtlUnwind` 执行栈展开；若不传该参数，`longjmp` 会展开到错误目标（`STATUS_BAD_FUNCTION_TABLE`）。使用 `_setjmp` 而非导出的 `setjmp` 符号，因为后者的 Windows ABI 是不兼容的双参数例程。含 `try` 的函数会强制局部变量驻留内存（内联汇编逃生点）以保证长跳转后值不丢失。
+  - `for...in` 复用 `xt_object_keys` 枚举键（数组 / 字符串得到字符串下标）。
+- 表达式：
+  - 标识符、数字、BigInt（任意精度）、字符串、模板、布尔、`null`、`undefined`、`arguments`
+  - 算术 / 比较 / 逻辑 / 短路 / 条件 / 位运算 / 一元（含 `typeof` `void`）/ 前后缀增减 / 复合赋值 / 逻辑赋值
+  - 数组字面量（含展开 `[...]`）、对象字面量（含简写 / 方法 / 对象展开 `{...obj}`）
+  - 类型化数组、`ArrayBuffer`、`DataView`、`TextEncoder` / `TextDecoder`：见[类型化数组与二进制数据](./typed-arrays.md)与[字符串与文本](./strings.md)
+  - 属性访问（含 `length` 特判、`Math` 常量）、元素访问、调用
+  - 一等公民内建构造器（`const A = Array`、`const M = Map`、`const E = TypeError`、类型化数组）：裸引用下降为 `xt_builtin_constructor`，得到带 `name` / `length`、`prototype` 与静态成员（`A.isArray`、`A.from`、`M.prototype` 等）的缓存函数。通过别名调用或 `new` 会分派到同一运行时构造器，`x instanceof A` 沿共享原型链判断。
+  - 可选链 `?.` / `?.[]` / `?.()`：以空值判断短路到 `undefined`
+  - `delete`、`in`、`instanceof`
+  - `this`（保存到函数 `%saved.this`；箭头函数从环境槽读）、`super`（`super.x` / `super(...)`）、`new`、`await`
+  - 闭包（箭头函数 / 函数表达式）与捕获环境构建
+- 类：构造器闭包 + 原型对象，存入 LLVM 全局（`@class.<id>`）；实例字段在构造器体前初始化；`static` 成员存于构造器属性包；`extends` 设置原型链；`super(...)` 通过原型上的隐藏 `__ctor` 调用。
+- `async` / `async function*`：闭包分别用 `xt_function_set_async` / `xt_function_set_async_generator` 标记，并在栈式协程上运行——见[异步、Promise 与生成器](./async.md)。
+- 标准库调用统一走 `xt_call_method` / `xt_math_call` / `xt_object_*` 与各构造器的 `xt_*` 入口；完整表面见[标准库](./stdlib.md)。
+- 全局字符串池（`@.str.N` 私有常量，UTF-8 转义）。
+- 内置调用：`console.log` / `info` / `warn` / `error`、`Math.*`、`Object.*`、数组 / 字符串方法、全局函数、扩展 builtins（统一 `(argc, argv)` ABI）。
+- `main` 入口（返回 0，调用模块函数，并在返回前 `xt_drain_microtasks`）。
+- 未支持节点统一报 `UnsupportedFeature`，不会崩溃。

package/doc/zh-CN/implemented/collections.md

@@ -0,0 +1,26 @@
+# 集合
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/collections.md)
+
+实现位置：`runtime/xt_stdlib2/container.inc`（Map / Set）与
+`runtime/xt_weak.c`（WeakMap / WeakSet / WeakRef）。
+
+## Map 与 Set
+
+- `new Map()` / `new Map(iterable)`、`new Set()` / `new Set(iterable)`。
+- `Map`：`size`、`get` / `set` / `has` / `delete` / `clear` / `forEach` / `keys` / `values` / `entries`。
+- `Set`：`size`、`add` / `has` / `delete` / `clear` / `forEach` / `values` / `keys` / `entries`。
+- `for...of` 与展开通过 `[Symbol.iterator]` 迭代；`Map` 产出 `[key, value]` 对，`keys` / `values` / `entries` 按插入序返回数组。
+- `Object.keys` / `values` / `entries` 不会看到集合内部结构。
+- `structuredClone` 支持 `Map` 与 `Set`，保留循环引用与共享引用。
+
+## WeakMap、WeakSet 与 WeakRef
+
+- `WeakMap`：`get` / `set` / `has` / `delete`；`WeakSet`：`add` / `has` / `delete`；`WeakRef`：`deref()`。
+- 键（以及 `WeakRef` 目标）不会让被引用对象存活：`WeakMap` / `WeakSet` 的键是 **ephemeron**（只有键可达时才保留值），`WeakRef` 目标不可达时会被清空。
+- 栈扫描是保守的，残留的栈字可能延迟弱目标清空。完整 GC 描述见[运行时偏差](../unimplemented/deviations.md)与[未实现：工具链](../unimplemented/toolchain.md)。
+
+## 迭代
+
+- 任何暴露 `[Symbol.iterator]()` 的对象都可在 `for...of` 与展开中使用。`Array.prototype[Symbol.iterator]` 稳定，调用后返回带 `next()` 且自身可迭代的迭代器对象。
+- 迭代细节另见[代码生成](./codegen.md)与 [Symbol](./stdlib.md)。

package/doc/zh-CN/implemented/driver.md

@@ -0,0 +1,19 @@
+# 驱动、增量编译与工具链
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/driver.md)
+
+实现位置：`src/driver/compiler.ts`（编排）、`src/driver/frontend.ts`、
+`src/driver/build-key.ts`、`src/driver/runtime-objects.ts`、
+`src/driver/app-artifacts.ts`、`src/driver/cache.ts`、`src/driver/toolchain.ts`、
+`src/driver/paths.ts`、`src/driver/version.ts`。
+
+- 编译流水线：读源 → 模块打包（`src/driver/modules.ts`，当入口含 `import`/`export` 时）→ 解析 → 绑定/检查 → IR → 目标文件 → 链接。
+- 增量缓存：以「编译器版本 + 源码哈希 + emit 类型 + 优化级别 + LTO/PGO 模式 + 平台 + 扩展指纹（名称、链接参数、原生对象内容）」为键，产物存在且新鲜则跳过构建。`--pgo-use` 总是重新构建，因为 profile 数据可能变化而源码不变。缓存键在 `src/driver/build-key.ts` 中组装。
+- C 运行时与扩展源按内容哈希缓存目标文件，只编译一次（缓存键包含 LTO/PGO 参数）。核心翻译单元列表 `RUNTIME_SOURCES` 位于 `src/driver/runtime-objects.ts`。
+- 工具链封装：查找 `clang`（可用 `xbintsc_CLANG` 覆盖）、编译 IR、编译 C、链接。
+- LTO（`--lto` / `"lto": true`）：程序与运行时都编译为 LLVM bitcode（`-flto`），并用 `-fuse-ld=lld` 链接；需要 lld。
+- PGO（先 `--pgo-generate[=dir]`，再 `--pgo-use[=dir]`，或配置 `"pgo"` / `"pgoDir"`）：生成 IR 与运行时 C 都用 `-fprofile-generate=<dir>` 插桩；运行插桩后的二进制，`--pgo-use` 会用 `llvm-profdata` 合并 `.profraw`（优先使用 clang 旁边的副本，可用 `xbintsc_LLVM_PROFDATA` 覆盖），再以 `-fprofile-use=<dir>` 重新构建。
+- 链接参数：非 Windows 自动加 `-lm`；扩展可追加链接参数。
+- 项目编译配置（`src/driver/config.ts`、`xbintsc.config.json`）：`entry`、`outDir`、`output`、`optimize`、`lto`、`pgo`、`pgoDir`、`extensions`、`extNative`、`force` 与 `app`（`name`、`icon`、`bundle`、`bundleId`）。从入口/当前目录向上查找，可用 `--config` 指定、`--no-config` 关闭；所有路径以配置文件所在目录为基准；CLI 参数优先于配置。
+- 应用图标（`src/driver/icon.ts`、`win-icon.ts`、`mac-bundle.ts`，`--icon`/`app.icon`）：PNG/ICO/ICNS 以 `xt_app_icon_*` 符号内嵌；Windows 上通过 `llvm-rc` 合成 PE 资源；macOS 上打包为 `Foo.app`（用 `sips`/`iconutil` 生成 `AppIcon.icns`）。`gui` 扩展用内嵌字节调用 `SDL_SetWindowIcon`；`xbintsc_RC` 可覆盖资源编译器。
+- 编译器版本：`COMPILER_VERSION` 位于 `src/driver/version.ts`，是缓存键的一部分。pre-commit 钩子只在 `main`/`master` 上（与 `package.json` 一起）提升它，因此功能分支不会改动版本文件。

package/doc/zh-CN/implemented/extensions.md

@@ -0,0 +1,19 @@
+# 扩展机制（Extensions）
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/extensions.md)
+
+实现位置：`src/extensions/registry.ts`、`src/extensions/node/`
+
+- 扩展是普通对象：`runtimeSources()`（额外 C 源）、`linkerFlags()`（额外链接参数）、`builtins()`（全局标识符 → 运行时符号，统一 `(argc, argv)` ABI）与 `modules()`（导入说明符 → 命名导出 / 命名空间）。
+- `ExtensionRegistry`：注册 / 注销 / 查询 / 汇总 builtins、modules、runtime 源、链接参数。
+- 内置核心扩展 `core`：暴露 `print`（映射 `xt_println`），始终注册。
+- Node 扩展 `node`：
+  - 模块化组织：`src/extensions/node/fs/` + `runtime/ext_node/fs/read_file.c`
+  - 暴露可导入模块（`fs`、`fs/promises`、`path`、`os`、`process` 等），同时支持裸名称与 `node:` 前缀；`import { readFileSync } from "fs"` 解析到 `xt_node_read_text_file`，`path`/`os`/`process` 的导出映射到命名空间分发器。
+- 添加新模块只需新增目录 + C 实现，核心编译器无需改动。
+- 原生 C++/Rust 扩展（`src/extensions/native.ts`、`--ext-native`）：
+  - `nativeObjects()` 链接以 `(argc, argv)` ABI 暴露 `extern "C"` 符号的预编译对象/静态库；JSON manifest 把它们映射为 builtins/modules（`linkerFlags` / `linkerFlagsByPlatform` 用于 C++/Rust 运行时）。
+  - 编写辅助位于 `runtime/xt_ext.h`（C/C++）与 `runtime/xt_ext.rs`（Rust）；可运行工程在 `examples/extensions/`。
+  - 驱动原样链接这些产物，增量缓存会对其内容取指纹，因此重建库会使缓存二进制失效。
+  - CI 在 Linux、macOS、Windows 上都会构建两种语言的示例；Windows 下系统 clang 链接 MSVC ABI（C++ `-lmsvcprt`，Rust `*-pc-windows-msvc` 加 Windows 系统库）。
+- Node 模块覆盖情况见 [Node 扩展](./node.md)。

package/doc/zh-CN/implemented/fetch.md

@@ -0,0 +1,31 @@
+# fetch
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/fetch.md)
+
+实现位置：`runtime/xt_fetch.c`、`runtime/xt_fetch/async.inc`、`runtime/xt_async_io.c`。
+
+- 全局 `fetch(input, init)` 是 HTTP/1.1 客户端。阻塞的套接字交换（`getaddrinfo`、connect、send、receive）运行在异步 I/O 工作线程池上，因此进行中的请求**不会**卡住事件循环：定时器、套接字与其他 `await` 继续运行，promise 在 reactor 派发完成结果时 settle。
+- 重定向在主线程上处理：每一跳是一次 offload 交换，最多 20 次；301/302/303 会把 POST 改成 GET。
+- 只接受 `http://` URL —— 由于未链接 TLS 后端，`https://` 会以 `TypeError` 拒绝。
+- 选项：`method`、`headers`（普通对象或 `Headers`）、`body` 与 `redirect`（`follow` / `manual` / `error`）。
+- 解析出的 `Response` 形状对象暴露 `ok` / `status` / `statusText` / `url` / `headers` 以及 `text()` / `json()` / `arrayBuffer()` / `bytes()` / `clone()`。响应体在 promise settle 前已完整缓冲；不支持流式响应体。
+- `Headers` 大小写不敏感，提供 `get` / `has` / `set` / `append` / `delete` / `keys` / `values` / `entries` / `forEach` / `getSetCookie`。
+- 非法 URL 与网络失败会以 `TypeError` 拒绝。
+
+```ts
+async function main(): Promise<void> {
+  const response = await fetch("http://127.0.0.1:8080/status");
+  console.log(response.status, await response.text());
+}
+main();
+```
+
+在请求完成前安排的定时器会在交换仍在进行时触发：
+
+```ts
+const pending = fetch("http://127.0.0.1:8080/slow");
+setTimeout(() => console.log("timer"), 10); // 会在 150ms 的响应之前运行
+await pending;
+```
+
+已知限制（仅 `http://`、无 TLS、响应体整体缓冲）列在[运行时偏差](../unimplemented/deviations.md)。

package/doc/zh-CN/implemented/lexer.md

@@ -0,0 +1,23 @@
+# 词法分析（Lexer）
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/lexer.md)
+
+实现位置：`src/lexer/scanner.ts`、`src/lexer/token.ts`
+
+- 完整 Token 分类：标识符、关键字、私有标识符、数字、字符串、模板、正则（扫描）、所有标点与运算符。
+- 完整关键字表：`abstract any as asserts async await bigint boolean break case catch class const constructor continue debugger declare default delete do else enum export extends false finally for from function get if implements import in infer instanceof interface is keyof let module namespace never new null number object package private protected public readonly return satisfies set static string super switch symbol this throw true try type typeof undefined unique unknown var void while with yield`
+- 数字字面量：
+  - 十进制、`0x` 十六进制、`0o` 八进制、`0b` 二进制
+  - 下划线分隔 `1_000_000`
+  - 小数、指数 `1.5e3`
+  - BigInt 字面量（`10n`、`0xFFn`）求值为任意精度整数（算术、位运算、移位、比较、`toString(radix)`、`BigInt()` / `BigInt.asIntN` / `BigInt.asUintN`）
+  - BigInt 字面量的值在词法 / 语法阶段即精确解析为 `bigint`（不经过 `Number`），超过 2^53 的字面量在 token / AST 中也保持完整精度
+- 字符串字面量：
+  - 单引号 / 双引号
+  - 转义：`\n \t \r \b \f \0 \\ \' \"`、`\xHH`、`\uHHHH`、`\u{...}`
+- 模板字面量（词法层）：无替换模板、模板头 `TemplateHead`、模板中 `TemplateMiddle`、模板尾 `TemplateTail`，支持 `${}` 与转义。
+- 正则字面量扫描（`/pattern/flags`），并区分除法 `/`。
+- 私有标识符 `#name`。
+- 注释：单行 `//` 与块注释 `/* */`（含未闭合诊断）。
+- 换行与空白跟踪（用于 ASI），BOM / CRLF 规范化（`SourceFile`）。
+- 词法诊断：未终止字符串 / 模板 / 注释、非法字符、非法数字、非法转义。

package/doc/zh-CN/implemented/modules.md

@@ -0,0 +1,28 @@
+# 模块系统
+
+> 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/modules.md)
+
+实现位置：`src/parser/parser.ts`（语法）、`src/driver/modules.ts`（打包）、
+`src/driver/frontend.ts`（`parseEntry`）。
+
+## 语法
+
+- `import default, { named } from "..."`、`import * as ns from "..."`（相对模块的命名空间导入会降级为合成对象字面量；扩展模块如 `path` 亦已支持）、`import "./side-effect"`、`import type`
+- `export default`、`export { a as b }`、`export *`、`export =`
+- import attributes（`with` / `assert`）
+
+## 运行时语义
+
+- `import` / `export` 的**运行时语义**由 `src/driver/modules.ts` 在驱动层完成：递归解析相对依赖**以及裸名称的 `node_modules` 包**（遵循 `exports` / `module` / `main` 与包子路径），按模块前缀重命名顶层符号、改写引用，合并为单文件后重新绑定。
+- 包可以是 ESM 或 CommonJS：`node_modules` 内的 CJS 文件会获得合成的 `module` / `exports`，`require` 调用被降级为依赖的导出对象，静态识别出的导出对 ESM 导入方可见；`node_modules` 之外的 `require()` 仍报错并提示改用 `import`。循环依赖报错。
+- `.js` 系列说明符解析到对应 `.ts` 源码；省略后缀时优先 TypeScript 后缀而非同名的 JavaScript 文件；纯 `.js` / `.jsx` / `.mjs` / `.cjs` 源码也可直接打包。
+- 导入绑定与命名空间成员是模块求值时的快照（无实时绑定）—— 见[未实现：模块系统](../unimplemented/modules.md)。
+- 纯类型导入与再导出（`import type { T } from "..."`、`import { type T } from "..."`、`export type { T } from "..."`）会被擦除，**不构成模块依赖边**：目标模块不会被加载或打包，模块之间的纯类型循环也不属于循环依赖。若需要仅求值一个模块而不绑定名字，请使用副作用导入（`import "./mod"`）。
+
+## import.meta
+
+- `import.meta.url` / `.dirname` / `.filename`，由正在运行的可执行文件路径解析。
+
+## 扩展模块
+
+- 扩展模块（如 `fs`）可通过裸名称或 `node:` 前缀的 `import` 引入，并解析到运行时入口；见[扩展机制](./extensions.md)。

package/doc/zh-CN/implemented/node/assert.md

@@ -0,0 +1,17 @@
+# `assert` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/assert.md)
+
+实现位置：`src/extensions/node/assert/index.ts`、`runtime/ext_node/assert/assert.c`
+
+`assert.ok` / `fail` / `equal` / `notEqual` / `strictEqual` / `notStrictEqual` /
+`deepEqual` / `notDeepEqual` / `deepStrictEqual` / `notDeepStrictEqual` /
+`throws` / `doesNotThrow` / `rejects` / `doesNotReject` / `match` /
+`doesNotMatch` / `ifError`。
+
+具名导入与命名空间形式都分发到 `xt_assert_static`：
+
+```ts
+import assert from "node:assert";
+assert.strictEqual(1 + 1, 2);
+```

package/doc/zh-CN/implemented/node/buffer.md

@@ -0,0 +1,25 @@
+# `buffer` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/buffer.md)
+
+实现位置：`src/extensions/node/buffer/index.ts`、`runtime/ext_node/buffer/buffer.c`
+
+xbintsc 没有原生的二进制值类型，`Buffer` 以**普通对象**表示：每个字节是数字属性 `"0".."n-1"`，再加一个 `length` 属性，并共享 `xt_buffer_proto()` 原型提供实例方法。`xt_node_is_buffer` / `xt_node_buffer_bytes` 供其它模块跨模块访问字节。
+
+| 静态方法 | 说明 |
+| --- | --- |
+| `Buffer.from(value[, encoding])` | 从字符串（hex / base64 / utf8）、数组或 Buffer 构造 |
+| `Buffer.alloc(size[, fill])` | 分配并填充 |
+| `Buffer.allocUnsafe(size)` | 分配 |
+| `Buffer.isBuffer(value)` | 判定 |
+| `Buffer.byteLength(value[, encoding])` | 字节长度 |
+| `Buffer.concat(list[, totalLength])` | 拼接 |
+| `Buffer.compare(a, b)` | 比较 |
+
+实例方法：`toString([encoding])`、`toJSON()`、`slice(start, end)`、`subarray(...)`、`equals(other)`、`compare(other)`、`copy(target[, targetStart, sourceStart, sourceEnd])`、`write(string[, offset[, length[, encoding]]])`、`fill(value)`、`reverse()`、`indexOf(value)`、`lastIndexOf(value)`、`includes(value)`、`keys()`、`values()`，以及 `readUInt8/UInt16LE/UInt16BE/UInt32LE/UInt32BE`、`writeUInt8/UInt16LE/UInt16BE/UInt32LE/UInt32BE`。
+
+```ts
+const buf = Buffer.from("hello");
+console.log(buf.toString(), buf.length);      // hello 5
+console.log(Buffer.alloc(4, 65).toString());  // AAAA
+```

package/doc/zh-CN/implemented/node/child-process.md

@@ -0,0 +1,27 @@
+# `child_process` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/child-process.md)
+
+位置：`src/extensions/node/child_process/index.ts`、`runtime/ext_node/child_process/child_process.c`
+
+`spawnSync(command, args[, options])` 运行一个程序直到结束，返回
+`{ status, stdout, stderr }`。`options.cwd` 设置子进程工作目录；
+`options.stdio: "inherit"` 让子进程共用父进程的 stdout/stderr（`xbintsc run`
+用它把被编译程序的输出实时透传），否则 stdout/stderr 会作为 UTF-8 字符串捕获。
+
+| 选项 | 说明 |
+| --- | --- |
+| `cwd` | 子进程的工作目录 |
+| `stdio: "inherit"` | 共用父进程的 stdout/stderr，而不是捕获 |
+| `encoding` | 接受但忽略（输出始终按 UTF-8 解码） |
+
+Windows 上子进程通过 `CreateProcess` 启动，stdout/stderr 由读线程经匿名管道持续排空。
+不使用临时文件，因此受限的 `%TEMP%` 不会让 `spawnSync` 失败，输出超过管道缓冲区时
+也不会死锁。
+
+```ts
+import { spawnSync } from "child_process";
+
+const result = spawnSync("clang", ["--version"], { encoding: "utf8" });
+console.log(result.status, result.stdout.split("\n")[0]);
+```

package/doc/zh-CN/implemented/node/crypto.md

@@ -0,0 +1,9 @@
+# `crypto` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/crypto.md)
+
+实现位置：`src/extensions/node/crypto/index.ts`、`runtime/ext_node/crypto/crypto.c`
+
+- `createHash(algorithm)` 返回带 `update(...)` 与 `digest([encoding])` 的哈希对象。
+- 支持流式形式（`setEncoding` / `write` / `end` / `read`）。
+- 提供 SHA-1 与 SHA-256。

package/doc/zh-CN/implemented/node/dgram.md

@@ -0,0 +1,15 @@
+# `dgram` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/dgram.md)
+
+实现位置：`src/extensions/node/dgram/index.ts`、`runtime/ext_node/dgram/dgram.c`
+
+UDP 套接字。`dgram.createSocket(type | options[, cb])` 返回 EventEmitter。
+
+| 方法 | 说明 |
+| --- | --- |
+| `bind([port][, address][, cb])` | 绑定（未绑定时 `send` 会自动绑定） |
+| `send(msg[, offset, length,] port[, address][, cb])` | 发送数据报 |
+| `close([cb])` / `address()` | 关闭 / 查询地址 |
+| `setBroadcast(b)` / `setTTL(n)` / `setMulticastTTL(n)` | 套接字选项 |
+| `on('message', (msg, rinfo) => ...)` | 收到数据报，`rinfo` 含 `address` / `port` / `family` / `size` |

package/doc/zh-CN/implemented/node/events.md

@@ -0,0 +1,36 @@
+# `events` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/events.md)
+
+位置：`src/extensions/node/events/index.ts`、`runtime/ext_node/events/events.c`
+
+提供独立的 `EventEmitter`，既可以作为**全局构造函数**使用
+（`new EventEmitter()`），也可以作为命名导出（`import { EventEmitter } from
+"events"`）。实例与 `stream` / `net` / `http` 共用运行时事件发射器（监听器存放
+在内部的 `__xt_events` 属性上），并在此基础上提供更完整的 `events` 接口：
+
+| 方法 | 说明 |
+| --- | --- |
+| `on(name, fn)` / `addListener(name, fn)` | 追加监听器 |
+| `once(name, fn)` | 最多触发一次，然后自行移除 |
+| `prependListener(name, fn)` / `prependOnceListener(name, fn)` | 插入到最前 |
+| `off(name, fn)` / `removeListener(name, fn)` | 移除监听器 |
+| `removeAllListeners([name])` | 清空某个（或全部）事件 |
+| `emit(name[, ...args])` | 触发监听器 |
+| `listeners(name)` / `rawListeners(name)` | 监听器数组 |
+| `listenerCount(name)` | 监听器数量 |
+| `eventNames()` | 当前有监听器的事件名 |
+| `setMaxListeners(n)` / `getMaxListeners()` | 记录（默认 10） |
+
+通过命名空间（`import ee from "events"`）可访问的静态方法：`listenerCount`、
+`getEventListeners`、`getMaxListeners`、`setMaxListeners`、`once`、
+`addAbortListener`。
+
+```ts
+import { EventEmitter } from "events";
+
+const em = new EventEmitter();
+em.once("ready", () => console.log("ready"));
+em.emit("ready"); // ready
+em.emit("ready"); // 无输出：监听器已执行过
+```

package/doc/zh-CN/implemented/node/fs-promises.md

@@ -0,0 +1,30 @@
+# `fs/promises` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/fs-promises.md)
+
+实现位置：`src/extensions/node/fs-promises/index.ts`、`runtime/ext_node/fs/async_*.c`、`runtime/ext_node/fs/promises.c`
+
+每个函数都会向运行时的异步 I/O 线程池（`runtime/xt_async_io.c`）提交一个 job：阻塞的系统调用在 worker 线程上执行，promise 在事件循环上 settle。因此 `await` 在大文件读取、慢速网络文件系统或描述符操作进行期间会让出，`then` / `catch` 保持标准 Promise 语义。失败时会以与同步形式相同的 Node `Error`（含 `code` / `errno` / `syscall` / `path`）**reject**。
+
+`fs.promises` 也可从 `fs` 模块访问（`import { promises as fsp } from "fs"`），两个命名空间都暴露 `constants` 对象。
+
+Promise 导出：`readFile`、`writeFile`、`appendFile`、`mkdir`、`readdir`、`rm`、`unlink`、`rmdir`、`rename`、`copyFile`、`cp`、`realpath`、`stat`、`lstat`、`statfs`、`access`、`open`、`chmod`、`lchmod`、`chown`、`lchown`、`truncate`、`utimes`、`lutimes`、`link`、`symlink`、`readlink`、`mkdtemp`、`opendir`、`glob`、`watch`。
+
+`open(...)` 解析为 **`FileHandle`**，带有：`read`、`write`、`readFile`、`writeFile`、`appendFile`、`close`、`stat`、`truncate`、`chmod`、`chown`、`utimes`、`sync`、`datasync`。这些方法同样会 offload；`read(buffer, …)` 会在 worker 完成后填充调用方的 `Buffer`。
+
+```ts
+import { readFile, writeFile, open } from "fs/promises";
+
+async function main(): Promise<void> {
+  await writeFile("/tmp/a.txt", "hi");
+  console.log(await readFile("/tmp/a.txt"));
+  const handle = await open("/tmp/a.txt", "r");
+  console.log(await handle.readFile("utf8"));
+  await handle.close();
+}
+main();
+```
+
+工作由固定的小型线程池（4 个 worker）执行，完成结果按每个 worker 的提交顺序派发；相互独立的操作可以重叠。任何 job 都不会阻塞其他 `await`、定时器或套接字回调。
+
+已知偏差见[未实现：`fs/promises`](../../unimplemented/node/fs-promises.md)。

package/doc/zh-CN/implemented/node/fs.md

@@ -0,0 +1,105 @@
+# `fs` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/fs.md)
+
+实现位置：`src/extensions/node/fs/*.ts`、`runtime/ext_node/fs/*.c`
+
+## 可用函数（从 `fs` 导入）
+
+| 导入函数 | 运行时符号 | 说明 |
+| --- | --- | --- |
+| `readFileSync(path[, options])` | `xt_node_read_text_file` | 同步读取文件，返回字符串；支持编码选项 |
+| `readTextFile(path)` | `xt_node_read_text_file` | `readFileSync` 的别名（同一符号） |
+| `writeFileSync(path, data[, options])` | `xt_node_write_file` | 覆盖写入；接受字符串或 `Buffer` |
+| `appendFileSync(path, data[, options])` | `xt_node_append_file` | 追加写入；接受字符串或 `Buffer` |
+| `existsSync(path)` | `xt_node_exists` | 是否存在，返回布尔值 |
+| `readdirSync(path[, options])` | `xt_node_read_dir` | 目录项名称；`{ withFileTypes: true }` 返回 `Dirent`，`{ recursive: true }` 递归 |
+| `mkdirSync(path[, options])` | `xt_node_mkdir` | 创建目录，`{ recursive: true }` 递归创建，`{ mode }` 生效 |
+| `rmSync(path[, options])` | `xt_node_rm` | 删除文件/目录，`{ recursive: true }` 递归删除 |
+| `unlinkSync(path)` | `xt_node_unlink` | 删除文件 |
+| `rmdirSync(path)` | `xt_node_rmdir` | 删除空目录 |
+| `renameSync(oldPath, newPath)` | `xt_node_rename` | 重命名 / 移动 |
+| `copyFileSync(src, dest[, flags])` | `xt_node_copy_file` | 复制文件；支持 `COPYFILE_EXCL` |
+| `cpSync(src, dest[, options])` | `xt_node_cp` | 递归复制；`recursive` / `force` / `errorOnExist` / `dereference` / `preserveTimestamps` |
+| `realpathSync(path)` | `xt_node_realpath` | 解析为绝对路径 |
+| `statSync(path)` | `xt_node_stat` | 文件元信息对象（跟随符号链接） |
+| `lstatSync(path)` | `xt_node_lstat` | 文件元信息对象（不跟随符号链接） |
+| `statfsSync(path)` | `xt_node_statfs` | 文件系统统计（`bsize` / `blocks` / `bfree` …） |
+| `accessSync(path[, mode])` | `xt_node_access` | 检查可访问性 |
+| `chmodSync(path, mode)` | `xt_node_chmod` | 修改权限 |
+| `lchmodSync(path, mode)` | `xt_node_lchmod` | 修改符号链接权限 |
+| `chownSync(path, uid, gid)` | `xt_node_chown` | 修改属主 |
+| `lchownSync(path, uid, gid)` | `xt_node_lchown` | 修改符号链接属主 |
+| `truncateSync(path[, len])` | `xt_node_truncate` | 截断文件 |
+| `utimesSync(path, atime, mtime)` | `xt_node_utimes` | 设置访问/修改时间（秒数或 `Date`） |
+| `lutimesSync(path, atime, mtime)` | `xt_node_lutimes` | 设置符号链接时间 |
+| `mkdtempSync(prefix)` | `xt_node_mkdtemp` | 创建唯一临时目录 |
+| `linkSync(existing, newPath)` | `xt_node_link` | 硬链接 |
+| `symlinkSync(target, path[, type])` | `xt_node_symlink` | 符号链接 |
+| `readlinkSync(path)` | `xt_node_readlink` | 读取符号链接目标 |
+| `opendirSync(path[, options])` | `xt_node_opendir` | 返回 `Dir`（`readSync` / `closeSync` / `read` / `close`） |
+| `globSync(pattern[, options])` | `xt_node_glob` | glob 匹配（`*` / `?` / `[...]` / `**`），`{ cwd, withFileTypes }` |
+| `openSync(path[, flags[, mode]])` | `xt_node_open` | 打开文件描述符 |
+| `closeSync(fd)` | `xt_node_close` | 关闭描述符 |
+| `readSync(fd, buffer, offset, length, position)` | `xt_node_read` | 读入 `Buffer` |
+| `writeSync(fd, data[, offset[, length[, position]]])` | `xt_node_write` | 写入字符串 / `Buffer` |
+| `readvSync(fd, buffers[, position])` | `xt_node_readv` | 分散读 |
+| `writevSync(fd, buffers[, position])` | `xt_node_writev` | 聚集写 |
+| `fstatSync(fd)` | `xt_node_fstat` | 描述符的 `stat` |
+| `fsyncSync(fd)` / `fdatasyncSync(fd)` | `xt_node_fsync` / `xt_node_fdatasync` | 刷新描述符 |
+| `ftruncateSync(fd[, len])` | `xt_node_ftruncate` | 截断描述符 |
+| `fchmodSync(fd, mode)` | `xt_node_fchmod` | 描述符的 `chmod` |
+| `fchownSync(fd, uid, gid)` | `xt_node_fchown` | 描述符的 `chown` |
+| `futimesSync(fd, atime, mtime)` | `xt_node_futimes` | 描述符的 `utimes` |
+| `watch(filename[, options][, listener])` | `xt_node_watch` | 返回发射器形态的 watcher（不会触发，见[未实现：`fs`](../../unimplemented/node/fs.md)） |
+| `watchFile(filename[, options], listener)` | `xt_node_watch_file` | 轮询形态的 `StatWatcher`（不会触发） |
+| `unwatchFile(filename[, listener])` | `xt_node_unwatch_file` | 停止监听 |
+| `constants` | `xt_fs_constants` | `F_OK` / `R_OK` / `W_OK` / `X_OK`、`COPYFILE_*`、`O_*`、`S_IF*`（宿主值） |
+| `promises` | `xt_fs_promises` | `fs/promises` 门面（见 [`fs/promises`](./fs-promises.md)） |
+
+## 编码支持
+
+`readFileSync` / `writeFileSync` / `appendFileSync` 的 `options` 可以是编码字符串，也可以是 `{ encoding: "..." }`：
+
+| 编码 | 读取 | 写入 |
+| --- | --- | --- |
+| 默认 / `utf8` / `utf-8` / `ascii` / `latin1` / `binary` | 原始 UTF-8 文本 | 按文本字节写入 |
+| `hex` | 小写十六进制字符串 | 解析十六进制后写入 |
+| `base64` | Base64 字符串 | 解析 Base64 后写入 |
+| `base64url` | Base64url 字符串 | 解析 Base64url 后写入 |
+| `utf16le` / `ucs2` | 按文本直接读取原始字节（不做 UTF-16 解码） | 按 UTF-8 文本写入 |
+
+> `readFileSync` 默认仍返回**字符串**而不是 `Buffer`（即使 `Buffer` 类已存在），这样 `console.log(readFileSync(p))` 仍打印文本。
+
+## `statSync` 返回结构
+
+返回普通对象，数值属性：`size`、`mode`、`uid`、`gid`、`dev`、`ino`、`nlink`、`rdev`、`blksize`、`blocks`、`atimeMs`、`mtimeMs`、`ctimeMs`、`birthtimeMs`。
+方法（原生闭包，可调用）：`isFile()`、`isDirectory()`、`isSymbolicLink()`、`isFIFO()`、`isSocket()`、`isBlockDevice()`、`isCharacterDevice()`。
+
+## 调用方式
+
+`fs` 的导出通过 `import` 引入（也可用 `node:fs` 别名），不再以裸全局标识符暴露：
+
+```ts
+import { readFileSync, writeFileSync, existsSync } from "fs";
+
+const text = readFileSync("examples/data.txt");
+writeFileSync("/tmp/out.txt", text);
+console.log(existsSync("/tmp/out.txt"));
+```
+
+## 错误处理
+
+失败时函数会**抛出** Node 形态的 `Error` 对象，带有 `name`（`Error`）、`message`、`code`（如 `ENOENT`）、`errno`（数值 `errno`）、`syscall` 与 `path`。`existsSync` 仍返回布尔值，不会抛出。
+
+```ts
+import { readFileSync } from "fs";
+try {
+  readFileSync("/does/not/exist");
+} catch (error) {
+  console.log((error as any).code); // ENOENT
+}
+```
+
+
+已知偏差见[未实现：`fs`](../../unimplemented/node/fs.md)。

package/doc/zh-CN/implemented/node/http.md

@@ -0,0 +1,17 @@
+# `http` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/http.md)
+
+实现位置：`src/extensions/node/http/index.ts`、`runtime/ext_node/http/http.c`
+
+服务端包裹一个 `net` 服务端：每个连接累积字节直到完整请求（请求行 + 头 + `Content-Length` body）可用，再以 `req`/`res` 调用 `request` 监听器。客户端包裹一个 `net` 套接字，写出 HTTP/1.1 请求并在连接关闭后解析响应。
+
+| API | 说明 |
+| --- | --- |
+| `http.createServer([requestListener])` | 创建 HTTP 服务端 |
+| `http.request(options[, cb])` | 创建 `ClientRequest`（`write` / `end` / `setHeader`） |
+| `http.get(url[, cb])` | 发起 GET |
+
+`IncomingMessage`（`req` / 响应）：`method`、`url`、`httpVersion`、`headers`、`statusCode`、`data` / `end` 事件、`setEncoding`。
+
+`ServerResponse`（`res`）：`writeHead(status[, message][, headers])`、`setHeader` / `getHeader` / `removeHeader` / `getHeaders`、`write(chunk)`、`end([chunk])`，事件 `finish` / `close`。响应固定带 `Connection: close`（不做 keep-alive）。

package/doc/zh-CN/implemented/node/net.md

@@ -0,0 +1,17 @@
+# `net` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/net.md)
+
+实现位置：`src/extensions/node/net/index.ts`、`runtime/ext_node/net/net.c`
+
+TCP 服务端与客户端，基于核心事件循环。
+
+| API | 说明 |
+| --- | --- |
+| `net.createServer([connectionListener])` | 创建 TCP 服务端（`Server` 构造函数等价） |
+| `net.connect(...)` / `net.createConnection(...)` | 连接（阻塞式 connect，之后注册事件循环） |
+| `net.isIP(s)` / `net.isIPv4(s)` / `net.isIPv6(s)` | 地址判定 |
+
+`Server`：`listen(port[, host][, cb])`、`close([cb])`、`address()`、`getConnections(cb)`，事件 `listening` / `connection` / `close`。
+
+`Socket`：`write(data[, cb])`、`end([data])`、`destroy()`、`address()`、`setEncoding(enc)`、`pause()` / `resume()`，事件 `data` / `end` / `close` / `connect` / `error`。

package/doc/zh-CN/implemented/node/os.md

@@ -0,0 +1,21 @@
+# `os` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/os.md)
+
+实现位置：`src/extensions/node/os/index.ts`、`runtime/ext_node/os/os.c`
+
+采用 `os.<name>(...)` 命名空间调用，降为 `xt_os_static(<name>, argc, argv)`。
+以命名空间方式导入（`import os from "os"`），或单独导入函数（`import { platform } from "os"`）。
+
+| 方法 | 说明 |
+| --- | --- |
+| `os.platform()` | `darwin` / `linux` / `win32` / ... |
+| `os.arch()` | `x64` / `arm64` / `ia32` / `arm` |
+| `os.type()` | `Darwin` / `Linux` / `Windows_NT` / ... |
+| `os.release()` | 内核版本 |
+| `os.endianness()` | `LE` / `BE` |
+| `os.homedir()` | 用户主目录 |
+| `os.tmpdir()` | 临时目录 |
+| `os.hostname()` | 主机名 |
+| `os.totalmem()` / `os.freemem()` | 总内存 / 可用内存（字节） |
+| `os.cpus()` | CPU 条目数组（`model` / `speed` 占位） |

package/doc/zh-CN/implemented/node/path.md

@@ -0,0 +1,26 @@
+# `path` 模块
+
+> 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/path.md)
+
+实现位置：`src/extensions/node/path/index.ts`、`runtime/ext_node/path/path.c`
+
+采用 `path.<name>(...)` 命名空间调用，编译器将其降为 `xt_path_static(<name>, argc, argv)`。结果在所有平台上都以 POSIX `/` 分隔符输出（Windows 也接受 `/`），但输入可以使用 Windows 原生分隔符：在 Windows 上 `/` 与 `\` 都被识别，并保留盘符前缀（`C:`），因此自举后的编译器能正确解析带盘符的路径。以命名空间方式导入（`import path from "path"` / `import * as path from "path"`），或单独导入方法（`import { join } from "path"`）。
+
+| 方法 | 说明 |
+| --- | --- |
+| `path.join(...parts)` | 拼接并规范化 |
+| `path.resolve(...parts)` | 解析为绝对路径 |
+| `path.normalize(path)` | 规范化 |
+| `path.dirname(path)` | 目录名 |
+| `path.basename(path[, ext])` | 文件名，可去掉扩展名 |
+| `path.extname(path)` | 扩展名 |
+| `path.isAbsolute(path)` | 是否绝对路径 |
+| `path.relative(from, to)` | 相对路径 |
+
+```ts
+import path from "path";
+import { basename } from "path";
+
+console.log(path.join("a", "b", "..", "c")); // a/c
+console.log(basename("/x/y/z.txt"));          // z.txt
+```