xbintsc 0.5.22 → 0.5.31

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

@@ -30,7 +30,7 @@
 
 ## 其他表达式运算符
 
-- 逗号表达式 `,`
+- 逗号表达式 `,`（降级为 `SequenceExpression`：从左到右求值每个操作数，结果为最后一个）
 - `in` 运算符（`key in obj`，映射 `xt_in`）
 - `delete obj.key` / `delete obj[key]`（映射 `xt_delete`）
 - `instanceof`（映射 `xt_instance_of`，沿原型链判断）

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

@@ -10,7 +10,7 @@
 
 - 变量声明：`var` / `let` / `const`，支持多声明符 `const a = 1, b = 2;`
 - 函数声明、函数表达式和方法，含 `async` 修饰、生成器（`function*`、`yield`、`yield*`、`.next`/`.throw`/`.return`）与异步生成器（`async function*`、`for await...of`）
-- `class` 声明 / 类表达式（构造函数、字段、方法、`static`、`extends`）
+- `class` 声明 / 类表达式（构造函数、字段、方法、`static`、`static { ... }` 静态块、`extends`）
 - `if` / `else`
 - `while`、`do...while`
 - `for`（初始化、条件、增量均可省略）
@@ -27,8 +27,9 @@
 - 全部常见运算符及优先级 / 结合性（见[运算符](./operators.md)）
 - 赋值表达式与全部复合赋值（见[运算符](./operators.md)）
 - 条件（三元）表达式 `a ? b : c`
+- 逗号（序列）表达式 `a, b, c`（可用于 `for` 头、括号组与表达式语句）
 - 箭头函数 `() => expr` / `() => { ... }`（含类型参数、返回类型注解）
-- 函数表达式 `function () {}` 与命名函数表达式 `function g() {}`
+- 函数表达式 `function () {}` 与命名函数表达式 `function g() {}`（也支持 `async function` 表达式）
 - 调用表达式 `f(...)`、成员访问 `a.b`、元素访问 `a[i]`
 - 数组字面量 `[1, 2]`、稀疏数组 elision、展开 `[...a]`（也支持字符串、`Map`、`Set`）
 - 对象字面量 `{ a: 1 }`、简写属性 `{ a }`、方法简写 `{ m() {} }`、getter/setter 简写 `{ get x() {} }` / `{ set x(v) {} }`、计算属性名 `{ [expr]: 1 }`、对象展开 `{ ...obj }`

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

@@ -21,5 +21,7 @@ source.ts
 ```
 
 - 前端与后端、运行时、扩展完全解耦。
-- 流程由 `src/driver/compiler.ts` 串起：`读取 → 解析 → 绑定 → IR → 目标文件 → 链接`。前端位于 `src/driver/frontend.ts`，缓存键位于 `src/driver/build-key.ts`，运行时编译位于 `src/driver/runtime-objects.ts`，平台产物位于 `src/driver/app-artifacts.ts`。
+- 流程由 `src/driver/compiler.ts` 串起：`读取 → 解析 → 绑定 → 检查 → IR → 目标文件 → 链接`。前端位于 `src/driver/frontend.ts`，缓存键位于 `src/driver/build-key.ts`，运行时编译位于 `src/driver/runtime-objects.ts`，平台产物位于 `src/driver/app-artifacts.ts`。
+- [语义检查](./checker.md)（`src/checker/`）在绑定与代码生成之间运行，`--no-check` 可跳过。它把无需推断的检查（未定义名、重复声明、实参个数）与一个小型结构化类型模型结合起来（确定的可赋值性、属性形状、简单泛型与流收窄）；类型语法随后仍然被擦除。
 - **自举**：`xbintsc` 可编译自身前端。用编译器构建 `src/cli/main.ts` 可得到可用的 `xbintsc` 二进制，且该二进制再自编译时产出的 LLVM IR 逐字节一致（源码 ≡ 第 1 代 ≡ 第 2 代 ≡ 第 3 代）。运行时仍为手写 C。
+- **规范产物**：所有逐字节比较的产物在所有宿主上使用同一种编码。`src/canonical.ts` 定义 IR/调试信息/指纹的路径分隔符（`/`）与换行（LF），原生路径进入产物时用 `artifactPath()` 转换；运行时在渲染 `path` 结果与 `file://` URL 时使用 `XT_ARTIFACT_PATH_SEPARATOR`（`runtime/rt.h`）。面向用户的原生路径——诊断、`import.meta.filename`、`process.cwd()`——保留宿主分隔符，与 Node 一致。

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

@@ -13,7 +13,7 @@
 ## 对象
 
 - `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`，对象展开 `{...obj}`。
-- `Object.defineProperty` / `getOwnPropertyDescriptor(s)` —— 数据属性与访问器属性；属性标志会被报告，但后续写入/枚举尚未强制执行。
+- `Object.defineProperty` / `defineProperties` / `getOwnPropertyDescriptor(s)` —— 数据属性与访问器属性，可单个也可批量定义；属性标志会被报告，但后续写入/枚举尚未强制执行。
 - `Object.freeze` / `is_frozen` / `from_entries`、`Object.getPrototypeOf`。
 - `Object.prototype`：`hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`；`Object.getPrototypeOf({}) === Object.prototype`。
 - 一等公民内建构造器（`const A = Array`、`new A(...)`、`A.isArray`、`x instanceof A`）见[代码生成](./codegen.md)。
@@ -30,6 +30,7 @@
 - 数字格式化与强制转换与 Node 一致：`toFixed` / `toPrecision` / `toExponential`、十六 / 八 / 二进制解析，以及完整的 `+` / 关系运算 `ToPrimitive` 规则。这些由差分测试覆盖。
 - `BigInt` 字面量与值：任意精度算术、位运算与移位、比较、`toString(radix)`、`BigInt()`、`BigInt.asIntN` / `BigInt.asUintN`。
 - `Math`：完整函数与常量。
+- `Math` 同时是一等对象：`const cos = Math.cos`、`[1, 2].map(Math.max)`、`const { sqrt, PI } = Math` 都能按值读取成员（`xt_math_object()` 为每个函数缓存一个原生闭包，读取开销仍然很低）。
 - `Number` 静态与 `Number()` 转换；`parseInt` / `parseFloat` / `isNaN` / `isFinite`。
 
 ## JSON

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

@@ -2,9 +2,11 @@
 
 > 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/tests.md)
 
-实现位置：`tests/`（`lexer` / `parser` / `binder` / `codegen` / `driver` / `extensions` / `cli` / `e2e`）
+实现位置：`tests/`（`lexer` / `parser` / `binder` / `checker` / `codegen` / `driver` / `extensions` / `cli` / `conformance` / `e2e`）
 
 - 各模块单元测试与源码树一一对应。
 - `tests/e2e/` 会真正编译并运行二进制；缺少 `clang` 时自动跳过，而不是静默通过。
 - `tests/e2e/differential-*.test.ts` 让同一份源码同时经 `xbintsc` 与 Node 运行并逐字节比较输出。语义变化时应新增差分用例，而不是手写期望字符串。
+- `tests/conformance/` 是“支持子集”的可执行定义：它运行一份固定版本、随仓库分发的 [test262](https://github.com/tc39/test262) 子集（`tests/conformance/test262/cases/` 下的原始文件），逐个编译并执行受支持用例。不支持用例是 xbintsc 目前仍会拒绝的合法 JavaScript，以实际诊断码固定。[`doc/support-matrix.md`](../support-matrix.md) 由同一份目录生成（`npm run docs:matrix`），提交的表格过期时测试会失败。固定版本与 harness 适配见 [`tests/conformance/test262/SOURCE.md`](../../../tests/conformance/test262/SOURCE.md)。
+- `tests/checker/` 固化检查器：未定义名、同作用域重复声明、实参个数、结构化可赋值性、属性形状与必须保持合法的收窄场景。
 - 本目录的各功能页记录受支持的行为，测试是这份契约的可执行形式。提交前的门禁（`npm run typecheck && npm run lint && npm test`）见[参与贡献](../../ai/contributing.md)。

package/doc/zh-CN/implemented.md

@@ -16,6 +16,7 @@
 - [词法分析](./implemented/lexer.md) —— token、字面量、关键字、词法诊断
 - [语法分析](./implemented/parser.md) —— 语句、表达式、类型语法、ASI
 - [名字绑定与作用域](./implemented/binder.md) —— 作用域、符号、闭包捕获
+- [语义检查](./implemented/checker.md) —— 可关闭的未定义名、重复声明与实参个数检查
 
 ### 语义与代码生成
 
@@ -51,6 +52,7 @@
 | 分词器、字面量、关键字 | [词法分析](./implemented/lexer.md) |
 | 语句 / 表达式 / 类型语法 | [语法分析](./implemented/parser.md) |
 | 作用域、符号、捕获 | [名字绑定](./implemented/binder.md) |
+| 检查器诊断（未定义名、重复声明、实参个数） | [语义检查](./implemented/checker.md) |
 | 运算符、赋值降级 | [运算符与赋值](./implemented/operators.md) |
 | 值表示、函数 ABI | [值模型](./implemented/value-model.md) |
 | 控制流、表达式降级、类、`main` | [代码生成](./implemented/codegen.md) |

package/doc/zh-CN/npm-package.md

@@ -0,0 +1,391 @@
+# 通过 npm 包使用 xbintsc
+
+> 语言 / Language：[English](../npm-package.md) | **简体中文**
+
+`xbintsc` 已经发布到 npm。你可以在任意 Node 项目里安装它，把这个项目的
+TypeScript 直接编译成独立的原生二进制——不需要源码检出，不需要下载发布压缩包，
+也不需要全局安装。
+
+本文是面向 npm 包使用者的指南。编译参数与配置字段见
+[CLI 参考](../ai/zh-CN/cli.md)；各平台的工具链要求见[使用前置要求](./requirements.md)。
+
+## 快速开始
+
+```bash
+npm install --save-dev --save-exact xbintsc
+npx xbintsc doctor                  # "status : ok" 表示 clang 可用
+npx xbintsc build src/main.ts --out build
+./build/main                        # Windows 上是 .\build\main.exe
+```
+
+后文会解释环境要求、首次构建成本、CI 用法以及与普通 Node 构建的差异。
+
+## 给 AI 代理的说明
+
+如果你是被要求构建一个已经依赖 `xbintsc` 的项目的 AI 代理：
+
+1. 运行 `npx xbintsc doctor`。如果退出码非零，报告工具链问题；不要为了绕过
+   缺失或过旧的 clang 去修改程序。
+2. 找入口文件：`xbintsc.config.json` 里的 `entry`、调用 `xbintsc` 的 package
+   脚本，或项目的主 TypeScript 文件（通常是 `src/main.ts`）。有配置文件时，
+   `npx xbintsc build` 不需要位置参数。
+3. 用 `npx xbintsc build <entry> --out build` 构建。如果程序导入了 Node 内置
+   模块，加 `--ext node`；诊断信息会指出缺失的扩展。
+4. 运行产物（`./build/<name>`，Windows 上是 `.exe`），并报告其路径。
+5. 如果构建报不支持的语法，阅读安装包里的子集指南
+   `node_modules/xbintsc/doc/ai/language-support.md`；不要假设 Node 能跑的
+   TypeScript 就一定能编译。首次构建还会编译 C 运行时，请预留比增量构建更多的
+   时间。
+
+不要在 `node_modules/xbintsc` 里运行 `npm install`，也不要用 `tsc`/`esbuild`
+代替 xbintsc：原生产物必须由 `npx xbintsc` 生成。`xbintsc` 不读取
+`tsconfig.json`；请使用相对导入或包导入。
+
+## npm 包里有什么
+
+这个包包含：
+
+- 编译器 CLI（`bin/xbintsc.js` 以及 `dist/` 里编译后的 JavaScript）；
+- C 运行时**源码**（`runtime/`），其中包括 `node` 扩展的源码；
+- 项目配置 schema 与文档。
+
+它通过 Node.js 运行编译器。产出的二进制仍然是独立的：不嵌入 Node、V8 或
+TypeScript 编译器。
+
+这个包**不包含**：
+
+- C 编译器——构建机器需要 clang 16+；
+- 预编译的运行时归档（`runtime/lib/<os>-<arch>/core.a`）。驱动会在首次使用时
+  从随包发布的源码编译 C 运行时并缓存目标文件，所以第一次构建会更慢
+  （见[首次构建与缓存](#首次构建与缓存)）；
+- GUI/media 的原生归档（`gui.a`、`media.a`）。如果你需要 `--ext gui` 或
+  `--ext media`，请使用 Linux/macOS 的发布压缩包，或从源码检出中构建这些归档。
+
+## 环境要求
+
+| 要求 | 原因 |
+| --- | --- |
+| Node.js **22+** | 用来运行编译器本身。产出的二进制不需要 Node。 |
+| clang / LLVM **16+** | xbintsc 生成 LLVM IR，再交给 clang 编译和链接。 |
+| 平台链接器 / SDK | macOS：Xcode Command Line Tools。Linux：clang + lld。Windows：LLVM + Visual Studio C++ 生成工具（MSVC ABI）。 |
+
+首次构建前先确认：
+
+```bash
+node --version          # v22.x 或更高
+npx xbintsc doctor      # "status : ok" 表示工具链可用
+```
+
+`doctor` 还会报告解析到的编译器、运行时目录和运行时库目录。Windows 上，如果
+解析到的 clang 自己找不到 MSVC/SDK 头文件，请在 **x64 Native Tools Command
+Prompt for VS 2022**（Windows on ARM 用 **ARM64 Native Tools**）中运行构建。
+如果发行版默认的 `clang` 低于 16（例如 Ubuntu 22.04 或 Debian 12），请从该
+发行版的 LLVM 软件源安装更新的 LLVM，并用 `xbintsc_CLANG` 指向那个二进制。
+完整的分平台说明见[使用前置要求](./requirements.md)。
+
+## 在项目里安装
+
+在将要执行构建的 Node 项目里，把它装成开发依赖：
+
+```bash
+npm install --save-dev --save-exact xbintsc
+```
+
+`--save-exact` 会把编译器版本固定到 `package.json`；lockfile 则会为其他人和 CI
+锁定同一版本。固定版本很重要：编译器版本是增量缓存 key 的一部分，而且新版本
+可能产出不同的二进制。
+
+其他包管理器的等价命令是 `pnpm add -D xbintsc` 和 `yarn add -D xbintsc`。
+本文其余部分使用 npm 与 `npx`。
+
+验证本地安装：
+
+```bash
+npx xbintsc version
+npx xbintsc doctor
+```
+
+`npx` 会优先使用 `node_modules/.bin/xbintsc`。如果项目没有本地安装，`npx`
+可能会转而下载最新版本——偶尔用一次很方便，但不可复现。在 CI 中，要么先安装
+依赖，要么使用 `npx --no-install xbintsc …`，让缺失安装直接失败，而不是静默
+拉取另一个版本的编译器。
+
+### 不添加依赖的一次性运行
+
+```bash
+npx --yes xbintsc@latest build src/main.ts --out build
+```
+
+如果产物必须可复现，请把 `latest` 换成确切版本。这个命令会把包下载到 npm 的
+`_npx` 缓存，所以常规构建还是推荐使用项目依赖。
+
+### 全局安装（不推荐）
+
+```bash
+npm install --global xbintsc
+xbintsc build src/main.ts --out build
+```
+
+全局安装适合临时试验，但所有项目会共享当前全局的那一个版本。项目级开发依赖
+才能保证构建可复现。
+
+## 一个完整的最小项目
+
+```text
+my-app/
+├── package.json
+├── xbintsc.config.json
+└── src/
+    └── main.ts
+```
+
+`src/main.ts`：
+
+```ts
+const greeting: string = "Hello from xbintsc";
+console.log(greeting);
+```
+
+`xbintsc.config.json`：
+
+```json
+{
+  "entry": "src/main.ts",
+  "outDir": "build"
+}
+```
+
+在 `package.json` 里加一个构建脚本——npm 会把 `node_modules/.bin` 放进
+`PATH`，所以脚本里可以直接调用 `xbintsc`：
+
+```json
+{
+  "scripts": {
+    "build:native": "xbintsc build"
+  }
+}
+```
+
+然后：
+
+```bash
+npm install --save-dev --save-exact xbintsc
+npm run build:native
+./build/main          # Windows 上是 .\build\main.exe
+```
+
+预期输出（首次构建还会编译 C 运行时）：
+
+```text
+xbintsc: wrote /absolute/path/my-app/build/main
+Hello from xbintsc
+```
+
+`xbintsc build` 不带位置参数时会从 `xbintsc.config.json` 读取 `entry`，所以脚本
+可以写得很短。没有配置文件时，显式传入文件：`xbintsc build src/main.ts --out build`。
+
+## 首次构建与缓存
+
+运行时目标文件按源码/头文件内容哈希缓存。默认缓存目录是**执行命令时所在目录**下
+的 `.xbintsc/`（不一定是配置文件所在目录）；可以用 `xbintsc_CACHE_DIR` 改到别处。
+
+npm 包只带运行时的 C 源码，不带预编译的 `core.a`，所以第一次构建会逐个编译
+运行时的翻译单元。这次构建会明显比后续构建慢。`--time` 可以看到时间花在哪里：
+
+```bash
+npx xbintsc build src/main.ts --out build --time
+# xbintsc: timing (frontend 4ms, codegen 7ms, clang 1089ms, runtime 37770ms, link 1966ms)
+```
+
+之后的构建会复用目标文件和增量构建记录：
+
+```bash
+npx xbintsc build src/main.ts --out build
+# xbintsc: wrote /absolute/path/build/main (cached)
+```
+
+实际使用中的建议：
+
+- 把 `.xbintsc/` 加进 `.gitignore`；
+- 在 CI 里保留 `.xbintsc/`（或把 `xbintsc_CACHE_DIR` 指向持久目录），避免每次
+  都重新编译运行时；
+- 删除 `.xbintsc/` 是安全的——下一次构建会重新生成；
+- `--force` 只忽略构建新鲜度记录，已缓存且内容哈希相同的运行时目标文件仍会复用。
+  如果要强制完整重编 C 运行时，请删除 `.xbintsc/`。
+
+## 常用命令
+
+以下命令都假设已经安装了项目依赖，因此 `npx` 能找到本地包。
+
+| 任务 | 命令 |
+| --- | --- |
+| 构建可执行文件 | `npx xbintsc build src/main.ts --out build` |
+| 指定确切的输出路径 | `npx xbintsc build src/main.ts -o dist/app` |
+| 编译后立即运行 | `npx xbintsc run src/main.ts -- --flag value` |
+| 给程序传参数 | 放在 `--` 之后；它们不是编译器参数 |
+| 只检查、不链接（不需要 clang） | `npx xbintsc check src/main.ts` |
+| 打印 LLVM IR（不需要 clang） | `npx xbintsc emit src/main.ts > main.ll` |
+| 只产出目标文件 | `npx xbintsc build src/main.ts --emit obj --out build` |
+| 优化 | `npx xbintsc build src/main.ts -O3 --out build` |
+| 使用 Node 内置模块 | `npx xbintsc build src/main.ts --ext node --out build` |
+| 监听变化并重新构建 | `npx xbintsc watch src/main.ts` |
+| 查看工具链 | `npx xbintsc doctor` |
+| 查看完整帮助 | `npx xbintsc help` |
+
+`--out <dir>` 是目录：输出文件名沿用入口文件的基本名。`-o <path>` 是确切的输出
+路径。优化级别默认是 `-O2`。
+
+完整参数、项目配置字段和环境变量见 [CLI 参考](../ai/zh-CN/cli.md)。
+
+## 编译产物里的 Node 内置模块与 npm 依赖
+
+从 npm 安装 `xbintsc` **并不**意味着编译产物运行在 Node 上。产物是独立的原生
+二进制，因此有两条规则：
+
+1. **Node 内置模块需要显式开启。** `node:fs` 或 `fs` 这样的导入需要 `node` 扩展：
+
+   ```bash
+   npx xbintsc build src/main.ts --ext node --out build
+   ```
+
+   或者永久写进 `xbintsc.config.json`：
+
+   ```json
+   {
+     "entry": "src/main.ts",
+     "outDir": "build",
+     "extensions": ["node"]
+   }
+   ```
+
+2. **第三方 npm 包在构建期打包。** 裸导入会从项目的 `node_modules` 解析，并把
+   源码合并进二进制。运行时没有包查找。ESM 和 CommonJS 包都支持；循环依赖、
+   动态 `require(<表达式>)`，以及依赖 `__dirname` 等 Node 全局变量的包不支持。
+
+   ```bash
+   npm install ms
+   ```
+
+   ```ts
+   import ms from "ms";
+   console.log(ms(60000));
+   ```
+
+完整规则与限制见[扩展](../ai/zh-CN/extensions.md#第三方-npm-包)。
+
+## 在 Node 构建脚本里调用
+
+npm 包只提供 ESM，并暴露了编程 API；当另一个 Node 构建脚本需要产出二进制时
+很方便：
+
+```js
+// scripts/build-native.mjs
+import { build } from "xbintsc";
+
+const result = build("src/main.ts", { outDir: "build", optimize: "2" });
+if (result.diagnostics.some((diagnostic) => diagnostic.category === "error")) {
+  process.exitCode = 1;
+} else {
+  console.log(`wrote ${result.outputPath}${result.cached ? " (cached)" : ""}`);
+}
+```
+
+用 `node scripts/build-native.mjs`（或 `package.json` 脚本）运行。注意：
+
+- 使用 `.mjs` 或 `"type": "module"`，因为 `require("xbintsc")` 没有导出，会以
+  `ERR_PACKAGE_PATH_NOT_EXPORTED` 失败；
+- `build` 返回 `{ outputPath, irPath?, cached, diagnostics, … }`，源码错误通过
+  `diagnostics` 报告；clang 自身失败时会**抛出** `ToolchainError`；
+- `compileString(source)` 是纯 IR 生成调用，不需要 clang；
+- 子路径 `xbintsc/driver` 暴露驱动内部能力（缓存、工具链、配置、图标、macOS
+  bundle 助手）。
+
+完整 API 见 [CLI 参考](../ai/zh-CN/cli.md#编程-api)。
+
+## 在 CI 中使用
+
+下面是一个发布 Linux 二进制的 GitHub Actions 示例：
+
+```yaml
+name: native
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: sudo apt-get update && sudo apt-get install -y clang lld
+      - run: npm ci
+      - run: npx xbintsc doctor
+      - uses: actions/cache@v4
+        with:
+          path: .xbintsc
+          key: xbintsc-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - run: npx xbintsc build src/main.ts --out build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: my-app-linux-x64
+          path: build/main
+```
+
+- `npm ci` 默认安装 devDependencies，所以 `xbintsc` 可用。如果流水线使用
+  `npm ci --omit=dev`，请在裁剪依赖前完成构建，或把 `xbintsc` 放进
+  `dependencies`。
+- `.xbintsc` 的缓存 key 包含 lockfile，而 lockfile 固定了编译器版本；缓存里的
+  目标文件名是内容哈希，因此旧缓存不会污染新构建。
+- xbintsc 只为**宿主**平台构建，不是交叉编译器：要给多个平台产出产物，请使用
+  CI matrix（每个 OS/arch 一个 job）。
+- macOS runner 已经带有 Xcode Command Line Tools；Windows runner 需要安装 LLVM
+  与 MSVC 生成工具，产物是 `build\main.exe`。
+
+## npm 包还是发布压缩包？
+
+| | npm 包（`xbintsc`） | 预编译发布压缩包 |
+| --- | --- | --- |
+| 需要 Node.js | 是，22+ | 否 |
+| 首次构建 | 从源码编译 C 运行时 | 直接链接预编译运行时 |
+| GUI / media 扩展 | 不包含 | Linux/macOS 压缩包包含 |
+| 安装方式 | `npm install` + lockfile / provenance | 下载、校验 `.sha256`、解压 |
+| 编程 API | 有 | 无（仅 CLI） |
+| 交叉编译 | 否——只构建宿主平台 | 否——只构建宿主平台 |
+| 适合 | Node 项目与 CI，沿用熟悉的 npm 流程 | 没有 Node 的机器、首次构建要快、GUI 应用 |
+
+如果只需要核心运行时和 `node` 扩展，npm 包最方便。如果需要最快的冷启动构建，
+或者需要 GUI/media 归档，请使用发布压缩包（开发时也可以从源码构建）。
+
+## 与普通 Node 构建的差异
+
+- **不会读取 `tsconfig.json`。** xbintsc 使用自己的 `xbintsc.config.json` 指定
+  入口、输出目录和构建参数。TypeScript 的 `paths` 别名以及其他 `tsconfig.json`
+  设置不会生效；请使用相对导入或真实的包导入。
+- **项目的 `package.json` `"type"` 不决定源码方言。** 写 ESM 的
+  `import`/`export`；自己源码里的 `require()` 会被拒绝。
+- **类型会先检查、再擦除。** 默认检查器能发现确定的类型不匹配，但没有完整的
+  类型推断与 strict-null 模式。只有确实需要跳过语义检查时才使用 `--no-check`。
+- **只支持 TypeScript 的一个子集。** 不支持的语法会给出诊断并失败，而不是被
+  近似实现。见[语言支持范围](../ai/zh-CN/language-support.md)。
+- **产物与平台、架构绑定。** 请在最终运行它的平台上构建。
+
+## 排错
+
+诊断信息末尾的提示使用仓库相对路径，例如 `doc/ai/troubleshooting.md`。如果项目是
+通过 npm 安装的 xbintsc，请到 `node_modules/xbintsc/doc/ai/` 下读同一个文件。
+
+| 现象 | 原因 / 处理 |
+| --- | --- |
+| `npx xbintsc` 用了意料之外的版本 | 运行 `npx --no-install xbintsc version` 和 `npm ls xbintsc`；在 `package.json` 中固定版本，CI 用 `npm ci`。 |
+| `requires Node.js 22` / engine 错误 | 升级 Node；编译器使用了较新的 Node API。 |
+| `No C compiler found` 或 `requires clang 16 or newer` | 安装 clang 16+，运行 `npx xbintsc doctor`；需要时用 `xbintsc_CLANG` 指定 clang。 |
+| 第一次构建很慢 | 正常：正在编译并缓存运行时 C 源码。后续构建会复用 `.xbintsc/`；`--time` 可确认。如果冷启动必须快，请使用发布压缩包。 |
+| 写 `.xbintsc/` 权限错误 | 用 `xbintsc_CACHE_DIR` 指向可写目录，或在可写目录中运行。 |
+| `module 'fs' is provided by the 'node' extension` | 加 `--ext node`，或在配置里写 `"extensions": ["node"]`。 |
+| `GUI native library not found` / `media native library not found` | npm 包不包含 `gui.a`/`media.a`；请使用 Linux/macOS 发布压缩包，或从源码检出构建。 |
+| `require("xbintsc")` 失败 | 包只提供 ESM；使用 `import`（或动态 `import()`）。 |
+| Windows 链接时报缺少 MSVC 库 | 在 Native Tools 命令提示符中运行，安装 VS C++ 生成工具，并检查 `npx xbintsc doctor`。 |
+| `npm ci --omit=dev` 后构建找不到 `xbintsc` | 在构建阶段安装 devDependencies，或把 `xbintsc` 移到 `dependencies`。 |
+
+更多错误信息与修复方式见[排错](../ai/zh-CN/troubleshooting.md)。

package/doc/zh-CN/post/announce.md

@@ -1,47 +1,47 @@
-# 兄弟们 typescript可以编译成原生二进制了
-
-## 缘由
-2019年的时候研究过一段时间编译器，当时写了一个迷你的JS编译器，只支持function和number类型，但别小看就这两个类型，差不多花费了两周时间去实现，所以编译器是需要大量的时间和精力去做这个事情，当时就感叹可能我这辈子都不太可能能撸出一个相对完整的编译器了。
-
-2026年9月的某个下午，群里有人聊到了前端/js/ts永远都只能在鄙视链的最底端，因为它不能像C++和rust一样生成二进制文件。
-
-## 触发
-这件事就像触发了我的底层代码一样，脑子里疯狂出现了一个念头，然后回过头去翻了翻当年写的编辑器文章，不！不对！如果用AI的话，现在可能真的有可能可以实现，然后我开始列出了我的思路，写了第一个文档 DESIGN.md，接下来打开pi，开撸！
-
-很快不到一个小时，就出现第一个原型，我看完何其丑陋和简单，甚至不如我当年写的demo，于是我觉得自己重写把整个框架重新写一遍，若干天，总算是达到了我想要的水平，然后我开启了第二次尝试，这次我继续启动pi，这次发现虽然AI在架构上表现一般，但是架构完善后，它完成功能的速度不是一般的快，于是我开始了急速的迭代过程。
-
-## 核心进展
-
-* 绝大部分的js/ts语法以及node.js的主流方法(可选包)
-* 支持了C++和rust扩展,用户可以自由扩展
-* 实现了自举，即自己编译了自己
-* 实现无GNU依赖运行
-
-当然未实现的在这里：
-[unimplemented.md](https://github.com/zy445566/xbintsc/blob/main/doc/unimplemented.md)
-[node-unimplemented.md](https://github.com/zy445566/xbintsc/blob/main/doc/node-unimplemented.md)
-
-当然对于实现二进制编译最大的优势主要是两点：
-* 包体积巨小，编译后的二进制文件低至200KB (--ext node 300KB)，且可以直接运行，不再需要再捆绑几十MB的node.js运行时了
-* 冷启动速度巨快，本机实测比node.js原生大概快了120-200倍左右
-
-## 使用方法
-在 [releases页面](https://github.com/zy445566/xbintsc/releases) 下载zst压缩包解压后，运行即可,下面以windows作为案例
-```
-# 编译
-.\xbintsc-win32-x64\bin\xbintsc.exe build .\hello.ts --out .\build
-# 运行
-.\build\hello.exe
-```
-
-# 附录
-Github 地址： [https://github.com/zy445566/xbintsc](https://github.com/zy445566/xbintsc)
-兄弟们 有兴趣可以一起研究 `;)`
-
-
-
-
-
-
-
-
+# 兄弟们 typescript可以编译成原生二进制了
+
+## 缘由
+2019年的时候研究过一段时间编译器，当时写了一个迷你的JS编译器，只支持function和number类型，但别小看就这两个类型，差不多花费了两周时间去实现，所以编译器是需要大量的时间和精力去做这个事情，当时就感叹可能我这辈子都不太可能能撸出一个相对完整的编译器了。
+
+2026年9月的某个下午，群里有人聊到了前端/js/ts永远都只能在鄙视链的最底端，因为它不能像C++和rust一样生成二进制文件。
+
+## 触发
+这件事就像触发了我的底层代码一样，脑子里疯狂出现了一个念头，然后回过头去翻了翻当年写的编辑器文章，不！不对！如果用AI的话，现在可能真的有可能可以实现，然后我开始列出了我的思路，写了第一个文档 DESIGN.md，接下来打开pi，开撸！
+
+很快不到一个小时，就出现第一个原型，我看完何其丑陋和简单，甚至不如我当年写的demo，于是我觉得自己重写把整个框架重新写一遍，若干天，总算是达到了我想要的水平，然后我开启了第二次尝试，这次我继续启动pi，这次发现虽然AI在架构上表现一般，但是架构完善后，它完成功能的速度不是一般的快，于是我开始了急速的迭代过程。
+
+## 核心进展
+
+* 绝大部分的js/ts语法以及node.js的主流方法(可选包)
+* 支持了C++和rust扩展,用户可以自由扩展
+* 实现了自举，即自己编译了自己
+* 实现无GNU依赖运行
+
+当然未实现的在这里：
+[unimplemented.md](https://github.com/zy445566/xbintsc/blob/main/doc/unimplemented.md)
+[node-unimplemented.md](https://github.com/zy445566/xbintsc/blob/main/doc/node-unimplemented.md)
+
+当然对于实现二进制编译最大的优势主要是两点：
+* 包体积巨小，编译后的二进制文件低至200KB (--ext node 300KB)，且可以直接运行，不再需要再捆绑几十MB的node.js运行时了
+* 冷启动速度巨快，本机实测比node.js原生大概快了120-200倍左右
+
+## 使用方法
+在 [releases页面](https://github.com/zy445566/xbintsc/releases) 下载zst压缩包解压后，运行即可,下面以windows作为案例
+```
+# 编译
+.\xbintsc-win32-x64\bin\xbintsc.exe build .\hello.ts --out .\build
+# 运行
+.\build\hello.exe
+```
+
+# 附录
+Github 地址： [https://github.com/zy445566/xbintsc](https://github.com/zy445566/xbintsc)
+兄弟们 有兴趣可以一起研究 `;)`
+
+
+
+
+
+
+
+

package/doc/zh-CN/requirements.md

@@ -9,7 +9,10 @@ xbintsc 不再自带编译器，因此每个平台都需要安装一个兼容 cl
 | 要求 | 最低版本 | 说明 |
 | --- | --- | --- |
 | clang / LLVM | **16** | 生成的 IR 使用不透明指针，而 LLVM 16 起不透明指针是唯一的指针表示。 |
-| Node.js | **22** | 仅用于从源码运行或构建编译器；发布二进制是独立的，不需要 Node。 |
+| Node.js | **22** | 用于从 npm 或源码运行编译器；发布二进制是独立的，不需要 Node。 |
+
+如果通过 npm 安装编译器而不是使用发布压缩包，Node.js 22+ 会直接运行编译器本身；
+见[通过 npm 包使用 xbintsc](./npm-package.md)。
 
 clang 15 及更旧版本会在任何程序的第一个字符串字面量处失败：