diff --git a/docs/HIGH_PRECISION_TYPES.md b/docs/HIGH_PRECISION_TYPES.md
new file mode 100644
index 00000000..c6d6e05b
--- /dev/null
+++ b/docs/HIGH_PRECISION_TYPES.md
@@ -0,0 +1,755 @@
+# AOT 编译器高精度类型使用教程
+
+本教程介绍 AOT 编译器中的三种高精度数值类型——**BigInt**（任意精度整数）、**Decimal**（任意精度十进制数）和 **BigFloat**（任意精度浮点数）——帮助你编写高精度、零开销的数值计算程序。
+
+## 目录
+
+1. [为什么需要高精度类型](#1-为什么需要高精度类型)
+2. [快速开始](#2-快速开始)
+3. [三种类型概览](#3-三种类型概览)
+4. [构造与声明](#4-构造与声明)
+5. [算术运算](#5-算术运算)
+6. [比较运算](#6-比较运算)
+7. [复合赋值](#7-复合赋值)
+8. [通用方法调用](#8-通用方法调用)
+9. [类型转换](#9-类型转换)
+10. [混合运算与类型提升](#10-混合运算与类型提升)
+11. [超长字面量自动识别](#11-超长字面量自动识别)
+12. [限制与注意事项](#12-限制与注意事项)
+13. [完整示例](#13-完整示例)
+
+---
+
+## 1. 为什么需要高精度类型
+
+PHP 的原生 `int` 是 64 位有符号整数，最大值为 `9223372036854775807`（约 9.22×10¹⁸）。超过这个范围的整数字面量会被 PHP 解析器静默转换为 `float`（double），丢失有效位数。
+
+PHP 的原生 `float`（IEEE 754 double）最多只能保证约 15–16 位有效数字。对于金融计算、科学计算、密码学等场景，这远远不够。
+
+```php
+// PHP 原生行为的精度问题
+$a = 123456789012345678901234567890;  // 30 位整数 → 被转为 float，精度丢失
+// 实际存储：1.2345678901234568E+29，末尾数字已经不可靠
+
+$b = 0.1 + 0.2;  // 0.30000000000000004 — 经典的浮点误差
+```
+
+AOT 编译器提供了三种高精度类型，底层基于成熟的 C/C++ 数学库，编译为本地机器码，**零运行时开销**：
+
+| 类型 | 底层库 | 特点 |
+|------|--------|------|
+| BigInt | GMP (`libgmp`) | 任意精度整数，不会溢出 |
+| Decimal | libmpdec | 十进制小数，约 50 位有效数字，无二进制浮点误差 |
+| BigFloat | MPFR (`libmpfr`) | 任意精度浮点数，可调精度 |
+
+---
+
+## 2. 快速开始
+
+使用高精度类型的前提条件：
+
+1. 文件头部声明 `declare(strict_types=1)`
+2. 导入原生类型声明 `use native_types`
+3. 系统已安装对应的 C++ 库（`libgmp-dev`、`libmpdec-dev`、`libmpfr-dev`）
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void {
+    // 你的高精度计算代码
+    $a = std::bigInt("123456789012345678901234567890");
+    $b = std::bigInt("987654321098765432109876543210");
+    $sum = $a + $b;
+    echo $sum->toString();
+}
+?>
+```
+
+编译运行：
+
+```bash
+php bin/compiler.php my_program.php -o my_program
+./my_program
+```
+
+> **提示**：和所有 native_types 一样，Big* 类型只能在 AOT 编译模式下使用，不能在普通 PHP 解释器中运行。AOT 编译器会对 `std::bigInt()` 等函数进行编译期求值，直接生成 C++ 代码。
+
+---
+
+## 3. 三种类型概览
+
+### BigInt — 任意精度整数
+
+适用于大整数计算，不会溢出，不会丢失精度。整数除法结果为整数（截断）。
+
+```php
+$a = std::bigInt("1234567890123456789012345678901234567890");  // 40 位
+$b = $a * 2;  // 80 位，不会溢出
+```
+
+### Decimal — 任意精度十进制数
+
+适用于金融计算等需要精确十进制表示的场景。`0.1 + 0.2` 精确等于 `0.3`，不存在二进制浮点误差。
+
+```php
+$price = std::decimal("19.99");
+$quantity = 3;
+$total = $price * $quantity;  // 59.97，精确
+```
+
+### BigFloat — 任意精度浮点数
+
+适用于科学计算等需要高精度浮点运算的场景。基于 MPFR，使用二进制浮点但精度远超 IEEE 754 double。
+
+```php
+$pi = std::bigFloat("3.141592653589793238462643383279502884197");
+$area = $pi * 100 * 100;  // 高精度 π × r²
+```
+
+---
+
+## 4. 构造与声明
+
+### 4.1 从字面量构造
+
+`std::bigInt()`、`std::decimal()`、`std::bigFloat()` 是**编译期函数**，在生成的 C++ 代码中直接构造对应的 C++ 对象，不产生运行时函数调用。
+
+```php
+// BigInt — 从 int 或字符串构造
+$a = std::bigInt(100);                                    // 普通整数
+$b = std::bigInt("123456789012345678901234567890");       // 超长整数，必须用字符串
+
+// Decimal — 建议从字符串构造以避免浮点精度丢失
+$c = std::decimal("123.456");                             // ✅ 推荐：精确字符串
+$d = std::decimal(42);                                    // ✅ 可行：从 int
+
+// BigFloat — 从 int、float 或字符串构造
+$e = std::bigFloat(100.5);                                // 从 float
+$f = std::bigFloat(42);                                   // 从 int
+$g = std::bigFloat("3.14159265358979323846");             // 从字符串（精确）
+```
+
+### 4.2 类型标注
+
+在 `use native_types` 下，Big* 类型变量自动获得原生 C++ 存储类型：
+
+```php
+use native_types;
+
+// 编译器自动推断类型为 php::BigInt / php::Decimal / php::BigFloat
+$a = std::bigInt(100);         // → C++: php::Variant(new BigInt(100))
+$b = std::decimal("100.50");   // → C++: php::Variant(new Decimal("100.50"))
+$c = std::bigFloat(3.14);      // → C++: php::Variant(new BigFloat(3.14))
+```
+
+> **关键细节**：Big* 类型是**不可变（immutable）**的。每次运算都返回新值，不会修改原变量。详见 [第 7 节：复合赋值](#7-复合赋值)。
+
+---
+
+## 5. 算术运算
+
+### 5.1 标准运算符
+
+所有标准二元运算符都可以直接用于 Big* 类型：
+
+```php
+$a = std::bigInt(100);
+$b = std::bigInt(200);
+
+$sum  = $a + $b;    // 加法
+$diff = $a - $b;    // 减法
+$prod = $a * $b;    // 乘法
+$quot = $a / $b;    // 除法（BigInt 为整数除法）
+$mod  = $a % $b;    // 取模
+$pow  = $a ** 10;   // 幂运算（BigInt 支持）
+
+// 一元取负
+$neg  = -$a;        // 取负
+```
+
+生成的 C++ 代码示例（`$a + $b`）：
+
+```cpp
+php::BigInt::add(a, b)      // BigInt 加法
+php::BigInt::sub(a, b)      // BigInt 减法
+php::BigInt::mul(a, b)      // BigInt 乘法
+php::BigInt::div(a, b)      // BigInt 除法
+php::BigInt::mod(a, b)      // BigInt 取模
+php::BigInt::pow(a, b)      // BigInt 幂运算
+```
+
+### 5.2 与 int / float 混合运算
+
+Big* 类型可以自由地与普通 int 和 float 混合运算，编译器自动进行类型提升：
+
+```php
+$a = std::bigInt(100);
+
+$b = $a + 50;       // BigInt + Int → BigInt
+$c = 200 + $a;      // Int + BigInt → BigInt
+$d = $a * 3.5;      // BigInt * Float → 编译错误！
+                    // 浮点数无法精确提升为 BigInt，
+                    // 应使用 Decimal 或 BigFloat
+```
+
+### 5.3 BigInt 除法注意事项
+
+`BigInt / BigInt` 是整数除法（截断），类似于 PHP 的 `intdiv()`：
+
+```php
+$a = std::bigInt(100);
+$b = $a / 3;  // 33（不是 33.333...）
+```
+
+如果需要精确的小数结果，先将操作数转换为 Decimal：
+
+```php
+$a = std::bigInt(100);
+$result = std::decimal($a->toString()) / std::decimal("3");
+// 33.333333333...
+```
+
+### 5.4 各类型支持的运算符汇总
+
+| 运算符 | BigInt | Decimal | BigFloat |
+|--------|--------|---------|----------|
+| `+` `-` `*` | ✅ | ✅ | ✅ |
+| `/` | ✅ 整数除法 | ✅ | ✅ |
+| `%` | ✅ | ✅ | ❌ |
+| `**` | ✅ | ❌ | ❌ |
+| `-` (一元取负) | ✅ | ✅ | ✅ |
+
+---
+
+## 6. 比较运算
+
+所有六种比较运算符均可用于 Big* 类型：
+
+```php
+$a = std::bigInt(100);
+$b = 200;
+
+// 比较运算返回 bool（需要 (int) 转换输出）
+echo (int)($a < $b);     // 1 (true)   → cmp(a,b) < 0
+echo (int)($a > $b);     // 0 (false)  → cmp(a,b) > 0
+echo (int)($a <= 100);   // 1 (true)   → cmp(a,b) <= 0
+echo (int)($a >= 100);   // 1 (true)   → cmp(a,b) >= 0
+echo (int)($a == 100);   // 1 (true)   → cmp(a,b) == 0
+echo (int)($a != 50);    // 1 (true)   → cmp(a,b) != 0
+
+// 太空船运算符
+$cmp = $a <=> $b;        // -1 ($a < $b)
+echo (int)$cmp;          // -1
+```
+
+生成的 C++ 代码示例：
+
+```cpp
+php::BigInt::cmp(a, b) < 0    // a < b
+php::BigInt::cmp(a, b) == 0   // a == b
+php::BigInt::cmp(a, b) != 0   // a != b
+php::BigInt::cmp(a, b)        // a <=> b（直接返回 -1/0/1）
+```
+
+---
+
+## 7. 复合赋值
+
+Big* 类型**支持** `+=`、`-=`、`*=`、`/=`、`%=` 等复合赋值运算符。
+
+### 7.1 工作方式
+
+Big* 类型是**不可变的**（immutable）。`$a += 50` 在编译时被展开为 `$a = BigInt::add($a, 50)`——创建一个新值然后赋值给原变量。
+
+```php
+$a = std::bigInt(100);
+$a += 50;          // → a = php::BigInt::add(a, php::newBigInt(50))
+echo $a->toString();  // "150"
+
+$a -= 30;          // → a = php::BigInt::sub(a, php::newBigInt(30))
+$a *= 5;           // → a = php::BigInt::mul(a, php::newBigInt(5))
+$a /= 3;           // → a = php::BigInt::div(a, php::newBigInt(3))
+$a %= 7;           // → a = php::BigInt::mod(a, php::newBigInt(7))
+```
+
+Decimal 和 BigFloat 同样支持：
+
+```php
+// Decimal 复合赋值
+$d = std::decimal("100.50");
+$d += 25.25;       // → d = php::Decimal::add(d, php::newDecimal("25.25"))
+$d -= 123.45;      // → d = php::Decimal::sub(d, php::newDecimal("123.45"))
+$d *= 2;           // → d = php::Decimal::mul(d, php::newDecimal(2))
+$d /= 4;           // → d = php::Decimal::div(d, php::newDecimal(4))
+$d %= 5.0;         // → d = php::Decimal::mod(d, php::newDecimal("5.0"))
+
+// BigFloat 复合赋值（不支持 %=）
+$bf = std::bigFloat(100.0);
+$bf += 50.0;
+$bf -= 30.0;
+$bf *= 2.0;
+$bf /= 3.0;
+```
+
+### 7.2 `++` / `--` 不可用
+
+由于 Big* 类型是不可变的，`++` / `--` 运算符在语义上不匹配。编译器会给出清晰的错误提示：
+
+```php
+$a = std::bigInt(100);
+$a++;  // ❌ 编译错误：Cannot use ++ on php::BigInt. Use += 1 instead.
+++$a;  // ❌ 编译错误：Cannot use ++ on php::BigInt. Use += 1 instead.
+--$a;  // ❌ 编译错误：Cannot use -- on php::BigInt. Use -= 1 instead.
+```
+
+正确的替代写法：
+
+```php
+$a += 1;   // ✅ 代替 $a++
+$a -= 1;   // ✅ 代替 $a--
+```
+
+---
+
+## 8. 通用方法调用
+
+Big* 类型支持通过 `$value->method()` 语法（通用方法/Universal Methods）调用方法。这些调用在编译时被翻译为对应的 C++ 静态函数，**零运行时开销**。
+
+### 8.1 BigInt 方法
+
+```php
+$a = std::bigInt("12345678901234567890");
+
+// 算术方法（均返回新的 BigInt）
+$b = $a->add(1);        // 加法：$a + 1
+$c = $a->sub(1);        // 减法：$a - 1
+$d = $a->mul(2);        // 乘法：$a * 2
+$e = $a->div(10);       // 除法：$a / 10
+$f = $a->mod(1000000);  // 取模：$a % 1000000
+$g = $a->pow(3);        // 幂运算：$a ** 3
+
+// 一元方法
+$h = $a->neg();         // 取负：-$a
+$i = $a->abs();         // 绝对值
+
+// 特殊方法
+$j = $a->gcd(15);       // 最大公约数：gcd($a, 15)
+
+// 比较方法
+$cmp = $a->cmp(100);    // 比较：返回 -1/0/1
+if ($a->cmp(100) > 0) { /* $a > 100 */ }
+
+// 类型转换方法
+echo $a->toString();    // 转字符串："12345678901234567890"
+echo $a->toInt();       // 转 int（可能截断）
+echo $a->toFloat();     // 转 float（可能丢精度）
+```
+
+### 8.2 Decimal 方法
+
+```php
+$d = std::decimal("123.456");
+
+// 算术方法
+echo $d->add(std::decimal("50.25"))->toString();  // "173.706"
+echo $d->sub(std::decimal("50.25"))->toString();  // "73.206"
+echo $d->mul(2)->toString();                      // "246.912"
+echo $d->div(3)->toString();                      // "41.152"
+echo $d->mod(std::decimal("5.0"))->toString();    // "3.456"
+
+// 一元方法
+echo $d->neg()->toString();   // "-123.456"
+echo $d->abs()->toString();   // "123.456"
+
+// 比较与转换
+echo $d->cmp(std::decimal("100")) > 0 ? "greater" : "less";  // "greater"
+echo $d->toInt();             // 123
+echo $d->toString();          // "123.456"
+```
+
+### 8.3 BigFloat 方法
+
+```php
+$bf = std::bigFloat(3.14159265);
+
+echo $bf->add(1.0)->toString();   // "4.14159265..."
+echo $bf->mul(2.0)->toString();   // "6.2831853..."
+echo $bf->div(2.0)->toFloat();    // 1.570796325
+echo $bf->neg()->toString();      // "-3.14159265..."
+echo $bf->abs()->toString();      // "3.14159265..."
+
+// 比较
+echo $bf->cmp(3.0);               // > 0（$bf > 3.0）
+```
+
+### 8.4 通用方法 vs 运算符
+
+运算符和方法调用在功能上等价，选择哪种取决于代码风格：
+
+```php
+$a = std::bigInt(100);
+$b = std::bigInt(50);
+
+// 两种等价写法
+$result1 = $a + $b;             // 运算符风格
+$result2 = $a->add($b);         // 方法调用风格
+
+// 方法调用支持链式调用
+$result3 = $a->add(10)->mul(2)->sub(5)->toString();  // "215"
+```
+
+---
+
+## 9. 类型转换
+
+### 9.1 Big* 之间的转换
+
+```php
+// BigInt → Decimal（精确，推荐方式）
+$big = std::bigInt("12345678901234567890");
+$dec = std::decimal($big->toString());
+
+// Decimal → BigInt（截断小数部分）
+$d = std::decimal("123.456");
+$i = std::bigInt($d->toInt());  // 123
+
+// Int → BigInt / Decimal / BigFloat
+$bi = std::bigInt(42);
+$dc = std::decimal(42);
+$bf = std::bigFloat(42);
+
+// Float → BigFloat（Float → Decimal 不推荐直接使用 float 字面量）
+$bf2 = std::bigFloat(3.14);
+
+// 任意类型 → BigFloat
+$bf3 = std::bigFloat($big->toString());
+```
+
+### 9.2 Big* 与普通类型的转换
+
+```php
+// BigInt → 普通类型
+$a = std::bigInt("99999999999999999999");
+$s = $a->toString();  // "99999999999999999999"
+$i = $a->toInt();     // PHP_INT_MAX（超出范围时截断）
+$f = $a->toFloat();   // 1.0E+20（可能丢失精度）
+
+// 普通类型 → BigInt（通过编译期函数）
+$b = std::bigInt(42);           // int → BigInt
+$c = std::bigInt("123456...");  // string → BigInt
+```
+
+### 9.3 跨类型隐式混合的限制
+
+编译器会阻止可能导致精度损失的跨类型隐式混合运算：
+
+```php
+$a = std::bigFloat(100.5);
+$b = std::bigInt(200);
+
+$c = $a + $b;  // ❌ 编译错误：Cannot mix BigFloat and BigInt implicitly.
+               //    Use std::bigFloat() to convert explicitly.
+
+// 正确的做法：显式转换
+$c = $a + std::bigFloat($b->toString());  // ✅
+```
+
+| 组合 | 是否允许 | 说明 |
+|------|---------|------|
+| BigInt + BigFloat | ❌ 编译错误 | 精密度量不同，需显式转换 |
+| BigInt + Decimal | ❌ 编译错误 | 精密度量不同，需显式转换 |
+| BigFloat + Decimal | ❌ 编译错误 | 精密度量不同，需显式转换 |
+| BigInt + Int | ✅ 自动提升 Int → BigInt | 无精度损失 |
+| BigInt + Float | ❌ 编译错误 | Float 无法精确提升为 BigInt |
+| Decimal + Int | ✅ 自动提升 Int → Decimal | 无精度损失 |
+| Decimal + Float | ✅ 自动提升 Float → Decimal | 可能有微小误差 |
+| BigFloat + Int | ✅ 自动提升 Int → BigFloat | 无精度损失 |
+| BigFloat + Float | ✅ 自动提升 Float → BigFloat | 无精度损失 |
+
+---
+
+## 10. 混合运算与类型提升
+
+当 Big* 类型与普通 Int/Float 混合运算时，编译器按优先级确定运算类型：
+
+```
+BigFloat  >  Decimal  >  BigInt  >  Float  >  Int
+```
+
+**规则**：
+
+1. 若任一操作数是 Var（非原生类型），则全部转为 Var，使用 ZendVM 运行时运算
+2. 若两操作数均为 Int/Float，则 Float 优先（Int → Float）
+3. 若任一操作数为 Big* 类型，则另一操作数自动提升为同类型（Int → BigInt 等）
+
+```php
+// 类型提升示例
+$a = std::bigInt(100);
+$b = 50;                // Int
+
+$c = $a + $b;           // BigInt + Int → BigInt
+                        // $b 自动提升为 BigInt
+
+$d = std::decimal("10.5");
+$e = $d + 3;            // Decimal + Int → Decimal
+                        // 3 自动提升为 Decimal
+
+$f = std::bigFloat(1.5);
+$g = $f + 2.0;          // BigFloat + Float → BigFloat
+                        // 2.0 自动提升为 BigFloat
+```
+
+---
+
+## 11. 超长字面量自动识别
+
+AOT 编译器会自动检测超出原生类型精度的数值字面量，并自动转为对应的 Big* 类型。你**不需要手动包装**。
+
+```php
+// 19 位以上整数 → 自动转为 BigInt
+$a = 12345678901234567890;
+echo $a->toString();  // "12345678901234567890"
+// 编译器自动处理：等同于 std::bigInt("12345678901234567890")
+
+// 16 位有效数字以上的小数 → 自动转为 Decimal
+$b = 3.14159265358979323846;
+// 编译器自动处理：等同于 std::decimal("3.14159265358979323846")
+```
+
+**识别规则**：
+
+- 纯数字，19 位及以上 → BigInt
+- 含小数点或指数，16 位有效数字以上 → Decimal
+- 禁用下划线 `_`（如 `1_234_567_890_123_456_789_0`）
+
+> **推荐做法**：对于关键精度，仍然建议显式使用 `std::bigInt("...")` 或 `std::decimal("...")`，确保意图明确。自动识别是一个便利特性，适用于快速原型开发。
+
+---
+
+## 12. 限制与注意事项
+
+### 12.1 不可变性
+
+所有 Big* 类型是**不可变的**。每次运算创建新值：
+
+```php
+$a = std::bigInt(100);
+$b = $a->add(50);    // $a 依然是 100，$b 是 150
+$c = $a + 50;        // $a 依然是 100，$c 是 150
+```
+
+### 12.2 `++` / `--` 不支持
+
+参见 [第 7.2 节](#72---不可用)。使用 `+= 1` / `-= 1` 代替。
+
+### 12.3 BigFloat 不支持 `%` 和 `**`
+
+```php
+$bf = std::bigFloat(10.0);
+$bf %= 3;   // ❌ 编译错误
+$bf ** 2;   // ❌ 编译错误
+```
+
+### 12.4 Decimal 不支持 `**`
+
+```php
+$d = std::decimal("10.5");
+$d ** 2;    // ❌ 编译错误
+```
+
+### 12.5 跨 Big* 类型不能隐式混合
+
+BigFloat、Decimal、BigInt 之间必须显式转换：
+
+```php
+$a = std::bigFloat(100.5);
+$b = std::bigInt(200);
+$c = $a + $b;  // ❌ 编译错误
+// 改为
+$c = $a + std::bigFloat($b->toString());  // ✅
+```
+
+### 12.6 不能在普通 PHP 解释器中运行
+
+Big* 类型是 AOT 编译器的专有特性，依赖编译期代码生成和 C++ 底层库。源码不能被 `php` 命令直接解释执行。
+
+### 12.7 启用 `use native_types`
+
+忘记添加 `use native_types` 会导致 Big* 变量被当作 Var（通用类型），失去原生类型的大部分性能优势。
+
+---
+
+## 13. 完整示例
+
+### 13.1 大整数阶乘
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+/**
+ * 计算 n 的阶乘，支持任意大的结果
+ */
+function factorial(int $n): void {
+    $result = std::bigInt(1);
+    for ($i = 2; $i <= $n; $i++) {
+        $result *= $i;
+    }
+    echo "{$n}! = " . $result->toString() . "\n";
+    echo "位数: " . strlen($result->toString()) . "\n";
+}
+
+function main(): void {
+    factorial(10);   // 10! = 3628800
+    factorial(50);   // 3041409320171337804361260816606476884...
+    factorial(100);  // 933262154439441526816992388562667004...
+}
+?>
+```
+
+### 13.2 金融计算：订单明细
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void {
+    // 使用 Decimal 精确表示金额
+    $price = std::decimal("19.99");
+    $quantity = 3;
+    $taxRate = std::decimal("0.08");
+
+    $subtotal = $price * $quantity;
+    $tax = $subtotal * $taxRate;
+    $total = $subtotal + $tax;
+
+    echo "单价: " . $price->toString() . "\n";
+    echo "数量: {$quantity}\n";
+    echo "小计: " . $subtotal->toString() . "\n";
+    echo "税额: " . $tax->toString() . "\n";
+    echo "总计: " . $total->toString() . "\n";
+}
+?>
+```
+
+输出：
+
+```
+单价: 19.99
+数量: 3
+小计: 59.97
+税额: 4.7976
+总计: 64.7676
+```
+
+### 13.3 高精度圆周率计算
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void {
+    // 使用 BigFloat 进行高精度数学运算
+    $pi = std::bigFloat("3.141592653589793238462643383279502884197");
+    $radius = 100;
+
+    // 圆面积
+    $area = $pi * std::bigFloat($radius * $radius);
+    echo "圆面积: " . $area->toString() . "\n";
+
+    // 圆周长
+    $circumference = $pi * std::bigFloat(2 * $radius);
+    echo "圆周长: " . $circumference->toString() . "\n";
+
+    // 比较
+    $earthRadius = 6371;
+    $earthArea = $pi * std::bigFloat($earthRadius * $earthRadius);
+    echo "如果半径是 {$earthRadius}km...\n";
+    echo "面积约: " . $earthArea->toInt() . " km²\n";
+}
+?>
+```
+
+### 13.4 综合示例：多种类型混合
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void {
+    // BigInt — 大整数运算
+    $big = std::bigInt("100000000000000000000");
+    $big += std::bigInt("99999999999999999999");
+    echo "BigInt: " . $big->toString() . "\n";
+
+    // 运算符 + 比较
+    $a = std::bigInt(100);
+    echo "BigInt + Int: " . ($a + 50)->toString() . "\n";
+    echo "BigInt * 5: " . ($a * 5)->toString() . "\n";
+    echo "BigInt > 50: " . (int)($a > 50) . "\n";
+    echo "a == 100: " . (int)($a == 100) . "\n";
+
+    // Unary minus
+    $neg = -$a;
+    echo "-a: " . $neg->toString() . "\n";
+
+    // Decimal — 精确十进制运算
+    $price = std::decimal("99.99");
+    $price *= 3;   // 复合赋值
+    echo "价格 × 3: " . $price->toString() . "\n";
+
+    // 比较
+    $d = std::decimal("100.25");
+    echo "d > 50: " . (int)($d > 50) . "\n";
+    echo "d != 100: " . (int)($d != 100) . "\n";
+
+    // BigFloat — 高精度浮点
+    $bf = std::bigFloat(3.14159);
+    $bf *= 2.0;
+    echo "pi × 2: " . $bf->toString() . "\n";
+
+    // 方法链式调用
+    $result = std::bigInt(100)
+        ->add(50)
+        ->mul(3)
+        ->sub(100)
+        ->toString();
+    echo "100 + 50 × 3 - 100 = " . $result . "\n";
+}
+?>
+```
+
+输出：
+
+```
+BigInt: 200000000000000000099
+BigInt + Int: 150
+BigInt * 5: 500
+BigInt > 50: 1
+a == 100: 1
+-a: -100
+价格 × 3: 299.97
+d > 50: 1
+d != 100: 1
+pi × 2: 6.2831800000000000
+100 + 50 × 3 - 100 = 350
+```
+
+---
+
+## 进一步阅读
+
+- **类型系统规范**：[`docs/NATIVE_TYPES.md`](NATIVE_TYPES.md) — 完整的类型提升规则、声明语法、C++ API 参考
+- **BigInt PHPT 测试**：[`tests/aot/bigint/`](../tests/aot/bigint/) — BigInt 各项功能的集成测试
+- **Decimal PHPT 测试**：[`tests/aot/decimal/`](../tests/aot/decimal/) — Decimal 各项功能的集成测试
+- **BigFloat 集成测试**：[`tests/aot/bigfloat_operators.phpt`](../tests/aot/bigfloat_operators.phpt) — BigFloat 运算符测试
+- **C++ 运行时头文件**：
+  - [`phpx/include/phpx_big_int.h`](../phpx/include/phpx_big_int.h) — BigInt C++ API
+  - [`phpx/include/phpx_decimal.h`](../phpx/include/phpx_decimal.h) — Decimal C++ API
+  - [`phpx/include/phpx_big_float.h`](../phpx/include/phpx_big_float.h) — BigFloat C++ API
diff --git a/docs/UNIVERSAL_METHODS.md b/docs/UNIVERSAL_METHODS.md
new file mode 100644
index 00000000..259fc224
--- /dev/null
+++ b/docs/UNIVERSAL_METHODS.md
@@ -0,0 +1,1112 @@
+# AOT 编译器通用方法（Universal Methods）使用教程
+
+本教程全面介绍 AOT 编译器的**通用方法（Universal Methods）**系统——一种在原生类型上通过 `$value->method()` 语法进行零开销方法调用的机制。
+
+## 目录
+
+1. [什么是通用方法](#1-什么是通用方法)
+2. [设计原理](#2-设计原理)
+3. [支持的类型一览](#3-支持的类型一览)
+4. [Int 整型方法](#4-int-整型方法)
+5. [Float 浮点型方法](#5-float-浮点型方法)
+6. [Bool 布尔型方法](#6-bool-布尔型方法)
+7. [String 字符串方法](#7-string-字符串方法)
+8. [Array 数组方法](#8-array-数组方法)
+9. [Stream 流方法](#9-stream-流方法)
+10. [Big* 高精度类型方法](#10-big-高精度类型方法)
+11. [方法链式调用](#11-方法链式调用)
+12. [可变方法 vs 不可变方法](#12-可变方法-vs-不可变方法)
+13. [Var 类型的方法查找](#13-var-类型的方法查找)
+14. [扩展方法：自动发现](#14-扩展方法自动发现)
+15. [完整示例](#15-完整示例)
+
+---
+
+## 1. 什么是通用方法
+
+通用方法（Universal Methods）允许你在 PHP 原生类型的变量上直接调用方法，就像在对象上调用一样。编译器在编译时将这些方法调用翻译为对应的 C 函数或 C++ 方法调用，**生成零开销的本地代码**。
+
+```php
+// 字符串上直接调用方法
+$s = "hello world";
+echo $s->length();          // → strlen($s) → 11
+echo $s->upper();           // → strtoupper($s) → "HELLO WORLD"
+echo $s->substr(0, 5);      // → substr($s, 0, 5) → "hello"
+
+// 数组上直接调用方法
+$arr = [1, 3, 5, 7, 9];
+echo $arr->count();         // → count($arr) → 5
+echo $arr->contains(3);     // → in_array(3, $arr) → true
+$arr->push(11);             // → array_push($arr, 11)
+
+// 整数上直接调用方法
+$a = 100;
+$a->add(50);                // → a += 50 → 150
+echo $a->toString();        // → "150"
+
+// 高精度类型上直接调用方法
+$big = std::bigInt("12345678901234567890");
+echo $big->mul(2)->toString();  // → "24691357802469135780"
+```
+
+> **关键理念**：所有通用方法调用在编译时全部消解为直接函数调用。不存在虚表查找、反射、或运行时类型检查——生成的 C++ 代码与手写 C 函数调用完全等价。
+
+---
+
+## 2. 设计原理
+
+### 2.1 编译期消解
+
+每个通用方法调用在编译时经过以下步骤：
+
+1. **类型推断**：编译器推断调用者（receiver）的类型（Int / Float / String / Array / Stream / BigInt / Decimal / BigFloat / Var）
+2. **方法查找**：在该类型的方法表中查找方法定义
+3. **参数校验**：检查参数个数是否在 `min_args` ~ `max_args` 范围内
+4. **代码生成**：根据 handler 类型生成对应的 C/C++ 调用代码
+
+### 2.2 Handler 类型
+
+通用方法系统支持五种内部 handler，各自适用于不同的场景：
+
+| Handler | 说明 | 示例 |
+|---------|------|------|
+| `calc_op` | 直接生成 C++ 运算符代码（仅 Int/Float） | `$a->add(1)` → `a + 1` |
+| `php_fn` | 调用 PHP 标准库函数 | `$s->length()` → `strlen(s)` |
+| `cpp_fn` | 调用 `phpx` C++ 静态方法 | `$big->add(1)` → `BigInt::add($big, 1)` |
+| `direct_method` | 调用 Variant 的 C++ 成员方法 | `$s->equals("x")` → `s.equals("x")` |
+| `convert_fn` | 类型转换 | `$a->toFloat()` → `php::toFloat(a)` |
+| `php_fn_ref` | 调用 PHP 函数并通过引用修改原值（仅 Array） | `$arr->push(1)` → `array_push($arr, 1)` |
+| `direct_method_mutate` | 调用 Variant 的变异成员方法 | `$arr->set(0, 1)` → `arr.set(0, 1)` |
+
+---
+
+## 3. 支持的类型一览
+
+| 类型 | 方法数量 | 主要分类 |
+|------|---------|---------|
+| **Int** | 26 | 算术、数学函数、类型转换 |
+| **Float** | 26 | 算术、数学函数、三角函数、类型转换 |
+| **Bool** | 2 | 类型转换 |
+| **String** | 70+ | 字符串操作、搜索、编码、Hash、多字节、序列化 |
+| **Array** | 50+ | 增删改查、排序、遍历、集合运算、序列化 |
+| **Stream** | 30+ | 读写、定位、锁、Socket、过滤 |
+| **BigInt** | 14 | 算术、比较、转换、GCD |
+| **Decimal** | 11 | 算术、比较、转换 |
+| **BigFloat** | 10 | 算术、比较、转换 |
+
+---
+
+## 4. Int 整型方法
+
+### 4.1 算数运算（返回 Int）
+
+```php
+$a = 100;
+
+$a->add(50);        // a += 50  → 150
+$a->sub(30);        // a -= 30  → 70
+$a->mul(2);         // a *= 2   → 200
+$a->div(4);         // a /= 4   → 25
+$a->mod(7);         // a %= 7   → 2
+
+$a->inc();          // a++  → 101
+$a->dec();          // a--  → 100
+```
+
+> **可变性**：`add`/`sub`/`mul`/`div`/`mod`/`inc`/`dec` **会修改原变量**（直接操作 C++ 原生 `int64_t`），同时返回新值。这与 Big* 类型的不可变语义不同。
+
+```php
+$a = 100;
+$b = $a->add(50);  // $a 变为 150，$b 也是 150（返回新值）
+```
+
+### 4.2 数学函数
+
+```php
+$a = -100;
+
+$a->abs();          // abs($a)         → 100
+$a->ceil();         // ceil($a)        → -100.0 (float)
+$a->floor();        // floor($a)       → -100.0 (float)
+$a->round();        // round($a)       → -100.0 (float)
+$a->sqrt();         // sqrt($a)        → NaN（负数无平方根）
+$a->pow(3);         // $a ** 3         → -1000000
+$a->log();          // log($a)         → NaN
+$a->log10();        // log10($a)       → NaN
+$a->exp();          // exp($a)         → 3.72e-44 (float)
+
+$a->max(50);        // max($a, 50)     → 50
+$a->min(50);        // min($a, 50)     → -100
+```
+
+> **注意**：`ceil`、`floor`、`round` 返回 **Float 类型**（PHP 标准行为）。`pow` 返回 **Var 类型**（因为幂运算结果可能溢出）。
+
+### 4.3 三角函数
+
+```php
+$a = 0;
+
+$a->sin();          // sin(0)     → 0.0
+$a->cos();          // cos(0)     → 1.0
+$a->tan();          // tan(0)     → 0.0
+$a->asin();         // asin(0)    → 0.0
+$a->acos();         // acos(1)    → 0.0
+$a->atan();         // atan(0)    → 0.0
+$a->atan2(1);       // atan2(0,1) → 0.0
+$a->deg2rad();      // deg2rad(0) → 0.0
+$a->rad2deg();      // rad2deg(0) → 0.0
+```
+
+### 4.4 类型转换
+
+```php
+$a = 42;
+
+$a->toFloat();      // (float) $a  → 42.0
+$a->toString();     // (string) $a → "42"
+$a->toBool();       // (bool) $a   → true
+```
+
+### 4.5 完整方法列表
+
+| 方法 | 参数 | 返回类型 | 说明 |
+|------|------|---------|------|
+| `add($x)` | 1 | Int | 加法（修改原值） |
+| `sub($x)` | 1 | Int | 减法（修改原值） |
+| `mul($x)` | 1 | Int | 乘法（修改原值） |
+| `div($x)` | 1 | Int | 除法（修改原值） |
+| `mod($x)` | 1 | Int | 取模（修改原值） |
+| `inc()` | 0 | Int | 自增（修改原值） |
+| `dec()` | 0 | Int | 自减（修改原值） |
+| `abs()` | 0 | Int | 绝对值 |
+| `ceil()` | 0 | Float | 向上取整 |
+| `floor()` | 0 | Float | 向下取整 |
+| `round()` | 0-2 | Float | 四舍五入 |
+| `sqrt()` | 0 | Float | 平方根 |
+| `pow($x)` | 1 | Var | 幂运算 |
+| `log()` | 0-1 | Float | 自然对数 |
+| `log10()` | 0 | Float | 以 10 为底的对数 |
+| `exp()` | 0 | Float | e 的指数 |
+| `sin()` | 0 | Float | 正弦 |
+| `cos()` | 0 | Float | 余弦 |
+| `tan()` | 0 | Float | 正切 |
+| `asin()` | 0 | Float | 反正弦 |
+| `acos()` | 0 | Float | 反余弦 |
+| `atan()` | 0 | Float | 反正切 |
+| `atan2($x)` | 1 | Float | 二参数反正切 |
+| `deg2rad()` | 0 | Float | 角度转弧度 |
+| `rad2deg()` | 0 | Float | 弧度转角度 |
+| `max($x)` | 1 | Int/Float | 取最大值 |
+| `min($x)` | 1 | Int/Float | 取最小值 |
+| `toFloat()` | 0 | Float | 转浮点 |
+| `toString()` | 0 | String | 转字符串 |
+| `toBool()` | 0 | Bool | 转布尔 |
+
+---
+
+## 5. Float 浮点型方法
+
+Float 的方法集与 Int 几乎完全相同，但返回类型为 Float（`ceil`/`floor`/`round`/三角函数等仍为 Float）。
+
+```php
+$f = 3.14;
+
+$f->add(1.0);       // f += 1.0  → 4.14
+$f->sub(1.0);       // f -= 1.0  → 2.14
+$f->mul(2.0);       // f *= 2.0  → 6.28
+$f->div(2.0);       // f /= 2.0  → 1.57
+
+$f->abs();          // abs(3.14) → 3.14
+$f->sqrt();         // sqrt(3.14) → 1.772...
+$f->sin();          // sin(3.14)  → 0.00159...
+$f->round(2);       // round(3.14, 2) → 3.14
+
+// Float 特有的转换
+$f->toInt();        // (int) $f   → 3
+$f->toString();     // (string) $f → "3.14"
+$f->toBool();       // (bool) $f  → true
+```
+
+Float 与 Int 方法的主要区别：
+- Int 有 `mod($x)`，Float 没有（浮点取模无意义）
+- 算术方法直接操作 C++ `double`，性能与手写 C 代码一致
+
+---
+
+## 6. Bool 布尔型方法
+
+Bool 类型仅有两个转换方法：
+
+```php
+$b = true;
+
+$b->toInt();        // (int) $b   → 1
+$b->toString();     // (string) $b → "1"
+```
+
+---
+
+## 7. String 字符串方法
+
+String 拥有最丰富的方法集，涵盖日常开发的大部分字符串操作需求。
+
+### 7.1 基本操作
+
+```php
+$s = "hello world";
+
+$s->length();           // strlen($s)         → 11
+$s->isEmpty();          // empty($s)          → false
+$s->upper();            // strtoupper($s)     → "HELLO WORLD"
+$s->lower();            // strtolower($s)     → "hello world"
+$s->upperFirst();       // ucfirst($s)        → "Hello world"
+$s->lowerFirst();       // lcfirst($s)        → "hello world"
+$s->upperWords();       // ucwords($s)        → "Hello World"
+
+$s->trim();             // trim($s)           → "hello world"
+$s->lTrim();            // ltrim($s)          → "hello world"
+$s->rTrim();            // rtrim($s)          → "hello world"
+$s->trim(" \t\n\r");    // trim($s, chars)
+```
+
+### 7.2 搜索与比较
+
+```php
+$s = "hello world";
+
+// 判断
+$s->startsWith("hello");    // str_starts_with(...)    → true
+$s->endsWith("world");      // str_ends_with(...)      → true
+$s->contains("lo wo");      // str_contains(...)       → true
+$s->compare("hello");       // strcmp(...)             → >0
+$s->iCompare("HELLO");      // strcasecmp(...)         → 0
+$s->isNumeric();            // is_numeric(...)         → false
+
+// 位置查找
+$s->indexOf("world");       // strpos($s, "world")     → 6
+$s->lastIndexOf("o");       // strrpos($s, "o")        → 7
+$s->iIndexOf("WORLD");      // stripos($s, "WORLD")    → 6
+$s->iLastIndexOf("O");      // strripos($s, "O")       → 7
+
+// 内容查找
+$s->find("world");          // strstr($s, "world")     → "world"
+$s->iFind("WORLD");         // stristr($s, "WORLD")    → "world"
+$s->lastCharIndexOf("o");   // strrchr($s, "o")        → "orld"
+```
+
+### 7.3 截取与替换
+
+```php
+$s = "hello world";
+
+// 截取
+$s->substr(0, 5);           // substr($s, 0, 5)        → "hello"
+$s->substr(6);              // substr($s, 6)           → "world"
+
+// 统计
+$s->substrCount("l");       // substr_count($s, "l")   → 3
+$s->wordCount();            // str_word_count($s)      → 2
+
+// 替换
+$s->replace("hello", "hi");        // str_replace("hello", "hi", $s)
+$s->iReplace("HELLO", "hi");       // str_ireplace(...)
+$s->substrReplace("hi", 0, 5);     // substr_replace($s, "hi", 0, 5)
+$s->stripTags();                   // strip_tags($s)
+$s->stripTags("<br><p>");          // strip_tags($s, tags)
+```
+
+### 7.4 拆分与连接
+
+```php
+$s = "hello world";
+
+// 拆分
+$words = $s->split(" ");            // explode(" ", $s) → ["hello", "world"]
+$words->count();                    // 2
+
+// 连接（在数组上操作）
+$words->join(", ");                 // implode(", ", $words) → "hello, world"
+
+// 重复
+$s->repeat(3);                      // str_repeat($s, 3) → "hello worldhello worldhello world"
+
+// 填充
+$s->pad(20, "-");                   // str_pad($s, 20, "-")
+```
+
+### 7.5 编码与转义
+
+```php
+$s = "hello world & <test>";
+
+$s->htmlEntityEncode();             // htmlentities($s)
+$s->htmlEntityDecode();             // html_entity_decode($s)
+$s->htmlSpecialCharsEncode();       // htmlspecialchars($s)
+$s->htmlSpecialCharsDecode();       // htmlspecialchars_decode($s)
+
+$s->urlEncode();                    // urlencode($s)       → "hello+world+%26+%3Ctest%3E"
+$s->urlDecode();                    // urldecode($s)
+$s->rawUrlEncode();                 // rawurlencode($s)
+$s->rawUrlDecode();                 // rawurldecode($s)
+
+$s->addSlashes();                   // addslashes($s)
+$s->stripSlashes();                 // stripslashes($s)
+$s->addCSlashes("A..z");            // addcslashes($s, "A..z")
+$s->stripCSlashes();                // stripcslashes($s)
+
+$s->base64Encode();                 // base64_encode($s)
+$s->base64Decode();                 // base64_decode($s)
+```
+
+### 7.6 Hash 与校验
+
+```php
+$s = "hello";
+
+$s->md5();          // md5($s)       → "5d41402abc4b2a76b9719d911017c592"
+$s->sha1();         // sha1($s)      → "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"
+$s->crc32();        // crc32($s)     → 907060870
+$s->hash("sha256"); // hash("sha256", $s) → "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+$s->hashCode();     // C++ std::hash → 哈希值 (int)
+```
+
+### 7.7 正则匹配
+
+```php
+$s = "hello world";
+
+// match(pattern) → 返回匹配数组
+$result = $s->match("/hello/");
+
+// matchAll(pattern) → 返回所有匹配结果
+$results = $s->matchAll("/[a-z]+/");
+```
+
+### 7.8 序列化
+
+```php
+$s = '{"name":"John","age":30}';
+
+$data = $s->jsonDecode();           // json_decode($s, true)  → ["name" => "John", ...]
+$obj = $s->jsonDecodeToObject();    // json_decode($s)        → stdClass
+
+$s = 'a:3:{i:0;s:3:"foo";i:1;s:3:"bar";i:2;s:3:"baz";}';
+$arr = $s->unserialize();           // unserialize($s)        → ["foo", "bar", "baz"]
+```
+
+### 7.9 多字节字符串（mbstring）
+
+以 `mb` 前缀开头的方法对应 PHP 的 `mb_*` 函数族：
+
+```php
+$s = "你好世界";
+
+$s->mbLength();                     // mb_strlen($s)          → 4
+$s->mbUpper();                      // mb_strtoupper($s)
+$s->mbLower();                      // mb_strtolower($s)
+$s->mbSubstr(0, 2);                 // mb_substr($s, 0, 2)    → "你好"
+$s->mbIndexOf("世界");              // mb_strpos($s, "世界")  → 2
+$s->mbFind("世");                   // mb_strstr($s, "世")
+$s->mbDetectEncoding();             // mb_detect_encoding($s)
+$s->mbConvertEncoding("UTF-8");     // mb_convert_encoding($s, "UTF-8")
+$s->mbConvertCase(MB_CASE_TITLE);   // mb_convert_case($s, MB_CASE_TITLE)
+$s->mbTrim();                       // mb_trim($s)
+$s->mbLTrim();                      // mb_ltrim($s)
+$s->mbRTrim();                      // mb_rtrim($s)
+```
+
+### 7.10 C++ 原生方法
+
+以下方法直接调用 `phpx::Variant` 的 C++ 成员函数，无 PHP 函数对应：
+
+```php
+$s = "hello";
+
+$s->equals("hello");        // C++ String.equals() —— 值比较
+$s->append(" world");       // C++ String.append() —— 追加（修改原值）
+```
+
+---
+
+## 8. Array 数组方法
+
+Array 方法分为**只读方法**和**变异方法**两类。变异方法会直接修改原数组变量。
+
+### 8.1 基本信息
+
+```php
+$arr = [1, 3, 5, 7, 9];
+
+$arr->count();          // count($arr)         → 5
+$arr->isEmpty();        // empty($arr)         → false
+$arr->isList();         // array_is_list($arr) → true
+```
+
+### 8.2 增删改查
+
+```php
+$arr = [1, 2, 3];
+
+// 变异方法（修改原数组）
+$arr->push(4);              // array_push($arr, 4)          → [1,2,3,4]
+$arr->push(5, 6, 7);        // 支持多个参数
+$arr->pop();                // array_pop($arr)              → 返回 7
+$arr->shift();              // array_shift($arr)            → 返回 1
+$arr->unshift(0);           // array_unshift($arr, 0)       → [0,...]
+$arr->set(0, 100);          // C++ Array.set(0, 100)        → [100,...]
+$arr->del(0);               // C++ Array.del(0)             → 删除索引 0
+$arr->clean();              // C++ Array.clean()            → []
+
+// 只读方法
+$arr = ['a' => 1, 'b' => 2, 'c' => 3];
+$arr->get('a');             // C++ Array.get('a')           → 1
+$arr->keyExists('a');       // array_key_exists('a', $arr)  → true
+$arr->contains(2);          // in_array(2, $arr)            → true
+$arr->search(2);            // array_search(2, $arr)        → "b"
+```
+
+### 8.3 遍历与聚合
+
+```php
+$arr = [1, 3, 5, 7, 9];
+
+$arr->sum();                // array_sum($arr)       → 25
+$arr->product();            // array_product($arr)   → 945
+$arr->all(fn($v) => ...);   // array_all($arr, fn)
+$arr->any(fn($v) => ...);   // array_any($arr, fn)
+
+$arr->map(fn($v) => $v * 2);// array_map(fn, $arr)   → [2,6,10,14,18]
+$arr->reduce(fn($c, $v) => $c + $v, 0);  // array_reduce($arr, fn, 0)
+$arr->filter(fn($v) => $v > 5);          // array_filter($arr, fn)
+$arr->walk(fn(&$v) => $v *= 2);          // array_walk($arr, fn)
+```
+
+### 8.4 排序
+
+```php
+$arr = [3, 1, 4, 1, 5, 9];
+
+$arr->sort();               // sort($arr)            → [1,1,3,4,5,9]
+$arr->sortDesc();           // rsort($arr)           → [9,5,4,3,1,1]
+$arr->keySort();            // ksort($arr)           → 按键排序
+$arr->valueSort();          // asort($arr)           → 按值排序（保持键）
+```
+
+所有排序方法都会**修改原数组**。
+
+### 8.5 集合运算
+
+```php
+$a = [1, 2, 3, 4, 5];
+$b = [4, 5, 6, 7, 8];
+
+$a->diff($b);               // array_diff($a, $b)   → [1,2,3]
+$a->intersect($b);          // array_intersect(...)  → [4,5]
+$a->merge($b);              // array_merge($a, $b)   → [1,2,3,4,5,4,5,6,7,8]
+$a->unique();               // array_unique($a)      → [1,2,3,4,5]
+$a->flip();                 // array_flip($a)        → {1:0, 2:1, 3:2, ...}
+$a->reverse();              // array_reverse($a)     → [5,4,3,2,1]
+$a->replace($b);            // array_replace($a, $b)
+$a->values();               // array_values($a)      → 重索引
+$a->combine($keys);         // array_combine($keys, $a)
+$a->fillKeys($value);       // array_fill_keys($a, $value)
+```
+
+> `diff`、`intersect`、`merge`、`replace` 等方法支持**可变参数**：`$a->merge($b, $c, $d)` 可以一次合并多个数组。
+
+### 8.6 提取与切片
+
+```php
+$arr = ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5];
+
+$arr->keys();               // array_keys($arr)         → ['a','b','c','d','e']
+$arr->slice(1, 3);          // array_slice($arr, 1, 3) → ['b'=>2, 'c'=>3, 'd'=>4]
+$arr->chunk(2);             // array_chunk($arr, 2)    → [[1,2],[3,4],[5]]
+$arr->column('name');       // array_column($arr, 'name')
+$arr->splice(1, 3, [6,7]);  // array_splice($arr, 1, 3, [6,7]) —— 修改原数组
+$arr->rand(2);              // array_rand($arr, 2)
+
+$arr->keyFirst();           // array_key_first($arr) → "a"
+$arr->keyLast();            // array_key_last($arr)  → "e"
+$arr->find(fn($v) => $v > 3);  // array_find($arr, fn)
+```
+
+### 8.7 字符串相关
+
+```php
+$arr = ["hello", "world"];
+
+$arr->join(", ");           // implode(", ", $arr) → "hello, world"
+$arr->replaceStr("hello", "hi");    // str_replace("hello", "hi", $arr)
+$arr->iReplaceStr("HELLO", "hi");   // str_ireplace(...)
+```
+
+### 8.8 序列化
+
+```php
+$arr = ["name" => "John", "age" => 30];
+
+$arr->serialize();          // serialize($arr)      → "a:2:{...}"
+$arr->marshal();            // serialize($arr) —— 别名
+$arr->jsonEncode();         // json_encode($arr)    → '{"name":"John","age":30}'
+```
+
+### 8.9 类型转换
+
+```php
+$arr = [1, 2, 3];
+
+$arr->toInt();              // (int) 非空数组 → 1
+$arr->toFloat();            // (float) 非空数组 → 1.0
+$arr->toBool();             // (bool) 非空数组 → true
+$arr->toString();           // → "Array"
+```
+
+### 8.10 完整方法分类表
+
+| 分类 | 方法 |
+|------|------|
+| 基本信息 | `count`, `isEmpty`, `isList` |
+| 增删改查 | `push`, `pop`, `shift`, `unshift`, `set`, `get`, `del`, `clean`, `keyExists`, `contains`, `search` |
+| 遍历聚合 | `sum`, `product`, `all`, `any`, `map`, `reduce`, `filter`, `walk` |
+| 排序 | `sort`, `sortDesc`, `keySort`, `valueSort` |
+| 集合运算 | `diff`, `diffAssoc`, `diffKey`, `intersect`, `intersectAssoc`, `merge`, `unique`, `flip`, `reverse`, `replace`, `values`, `combine`, `fillKeys` |
+| 提取切片 | `keys`, `slice`, `chunk`, `column`, `splice`, `rand`, `keyFirst`, `keyLast`, `find` |
+| 字符串 | `join`, `replaceStr`, `iReplaceStr`, `countValues`, `pad` |
+| 序列化 | `serialize`, `marshal`, `jsonEncode` |
+| 类型转换 | `toInt`, `toFloat`, `toBool`, `toString` |
+
+---
+
+## 9. Stream 流方法
+
+Stream 类型表示文件句柄或网络连接。通过 `fopen()` 等函数获取。
+
+### 9.1 读写
+
+```php
+$fp = fopen("test.txt", "w+");
+
+$fp->write("hello world\n");      // fwrite($fp, "hello world\n") → 写入字节数
+$fp->write("more data", 4);       // fwrite($fp, "more data", 4)  → 只写 4 字节
+
+$fp->seek(0);                     // fseek($fp, 0)   → 回到开头
+$content = $fp->read(1024);       // fread($fp, 1024)
+$content = $fp->getContents();    // stream_get_contents($fp)
+
+$char = $fp->getChar();           // fgetc($fp)      → 读取一个字符
+$line = $fp->getLine();           // fgets($fp)      → 读取一行
+$line = $fp->getLine(1024);       // fgets($fp, 1024)
+$line = $fp->getRecord(1024, "\n"); // stream_get_line($fp, 1024, "\n")
+```
+
+### 9.2 元数据与状态
+
+```php
+$fp->tell();                // ftell($fp)           → 当前位置
+$fp->eof();                 // feof($fp)            → 是否 EOF
+$fp->stat();                // fstat($fp)           → 文件状态数组
+$fp->getMetaData();         // stream_get_meta_data($fp)
+$fp->isLocal();             // stream_is_local($fp)
+$fp->isTTY();               // stream_isatty($fp)
+```
+
+### 9.3 控制操作
+
+```php
+$fp->truncate(0);           // ftruncate($fp, 0)    → 截断文件
+$fp->sync();                // fsync($fp)           → 同步到磁盘
+$fp->dataSync();            // fdatasync($fp)       → 同步数据
+$fp->close();               // fclose($fp)          → 关闭
+
+// 锁
+$fp->lock(LOCK_EX);         // flock($fp, LOCK_EX)
+$fp->lock(LOCK_SH);         // flock($fp, LOCK_SH)
+$fp->lock(LOCK_UN);         // flock($fp, LOCK_UN)
+
+// 缓冲设置
+$fp->setBlocking(true);     // stream_set_blocking($fp, true)
+$fp->setChunkSize(8192);    // stream_set_chunk_size($fp, 8192)
+$fp->setReadBuffer(8192);   // stream_set_read_buffer($fp, 8192)
+$fp->setWriteBuffer(8192);  // stream_set_write_buffer($fp, 8192)
+$fp->setTimeout(30);        // stream_set_timeout($fp, 30)
+$fp->supportsLock();        // stream_supports_lock($fp)
+```
+
+### 9.4 Socket 操作
+
+```php
+// 服务端
+$server = stream_socket_server("tcp://0.0.0.0:8080");
+$client = $server->accept();             // stream_socket_accept($server)
+$client->accept(30);                     // 超时 30 秒
+
+// 信息
+$client->getSocketName(true);            // stream_socket_get_name —— 远程地址
+$server->getSocketName(false);           // stream_socket_get_name —— 本地地址
+
+// 数据
+$client->sendTo("hello", 0, $addr);      // stream_socket_sendto(...)
+$client->recvFrom(1024);                 // stream_socket_recvfrom(...)
+$client->recvFrom(1024, 0, $addr);       // 带地址
+
+// 控制
+$client->enableCrypto(true);             // stream_socket_enable_crypto → 启用 TLS
+$client->shutdown(STREAM_SHUT_RDWR);     // stream_socket_shutdown(...)
+
+// 过滤器
+$fp->appendFilter("string.toupper");     // stream_filter_append(...)
+$fp->prependFilter("string.tolower");    // stream_filter_prepend(...)
+```
+
+### 9.5 流拷贝
+
+```php
+$src = fopen("source.txt", "r");
+$dst = fopen("dest.txt", "w");
+
+$src->copy($dst);                    // stream_copy_to_stream($src, $dst)
+$src->copy($dst, 4096);              // 指定缓冲区大小
+```
+
+---
+
+## 10. Big* 高精度类型方法
+
+### 10.1 BigInt 方法
+
+```php
+$a = std::bigInt("12345678901234567890");
+
+// 算术（均返回新 BigInt，原值不变）
+$b = $a->add(1);        // $a + 1
+$c = $a->sub(1);        // $a - 1
+$d = $a->mul(2);        // $a * 2
+$e = $a->div(10);       // $a / 10
+$f = $a->mod(1000000);  // $a % 1000000
+$g = $a->pow(3);        // $a ** 3
+
+// 一元方法
+$h = $a->neg();         // -$a
+$i = $a->abs();         // abs($a)
+
+// 特殊方法
+$j = $a->gcd(15);       // gcd($a, 15)
+
+// 比较
+$cmp = $a->cmp(100);    // -1/0/1
+
+// 类型转换
+$a->toString();         // → "12345678901234567890"
+$a->toInt();            // → int（可能截断）
+$a->toFloat();          // → float（可能丢精度）
+```
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `add($x)` | 1 | BigInt | 加法 |
+| `sub($x)` | 1 | BigInt | 减法 |
+| `mul($x)` | 1 | BigInt | 乘法 |
+| `div($x)` | 1 | BigInt | 整数除法 |
+| `mod($x)` | 1 | BigInt | 取模 |
+| `pow($x)` | 1 | BigInt | 幂运算 |
+| `neg()` | 0 | BigInt | 取负 |
+| `abs()` | 0 | BigInt | 绝对值 |
+| `gcd($x)` | 1 | BigInt | 最大公约数 |
+| `cmp($x)` | 1 | Int | 比较 |
+| `toString()` | 0 | String | 转字符串 |
+| `toInt()` | 0 | Int | 转整数 |
+| `toFloat()` | 0 | Float | 转浮点 |
+
+### 10.2 Decimal 方法
+
+```php
+$d = std::decimal("123.456");
+
+$d->add(std::decimal("50.25"));  // 加法
+$d->sub(std::decimal("50.25"));  // 减法
+$d->mul(2);                      // 乘法
+$d->div(3);                      // 除法
+$d->mod(std::decimal("5.0"));    // 取模
+$d->neg();                       // 取负
+$d->abs();                       // 绝对值
+$d->cmp(std::decimal("100"));    // 比较
+$d->toString();                  // → "123.456"
+$d->toInt();                     // → 123
+$d->toFloat();                   // → 123.456 (double)
+```
+
+### 10.3 BigFloat 方法
+
+```php
+$bf = std::bigFloat(3.14159265);
+
+$bf->add(1.0);          // 加法
+$bf->sub(1.0);          // 减法
+$bf->mul(2.0);          // 乘法
+$bf->div(2.0);          // 除法
+$bf->neg();             // 取负
+$bf->abs();             // 绝对值
+$bf->cmp(3.0);          // 比较 → >0
+$bf->toString();        // 转字符串
+$bf->toInt();           // → 3
+$bf->toFloat();         // → 3.14159265
+```
+
+> **不可变性**：与 Int/Float 不同，Big* 类型的所有方法都**返回新值**，不修改原变量。参见 [第 12 节](#12-可变方法-vs-不可变方法)。
+
+---
+
+## 11. 方法链式调用
+
+通用方法的返回值类型是编译时已知的，因此可以直接链式调用：
+
+```php
+// 字符串链式调用
+$result = "  Hello World!  "
+    ->trim()
+    ->lower()
+    ->substr(0, 5)
+    ->upper();
+echo $result;  // "HELLO"
+
+// Int 链式调用
+$result = 100
+    ->add(50)     // 150（修改原变量）
+    ->mul(3)      // 450
+    ->sub(100)    // 350
+    ->toString();
+echo $result;  // "350"
+
+// BigInt 链式调用（不可变，返回新值）
+$result = std::bigInt("100")
+    ->add(std::bigInt(50))
+    ->mul(std::bigInt(3))
+    ->toString();
+echo $result;  // "450"
+
+// 跨类型链式调用
+$sum = "123456789012345678901234567890"
+    ->length();     // String.length() → Int
+echo $sum;  // 30
+
+// 链式调用 + 最终转换
+$result = std::bigInt("99999999999999999999")
+    ->add(std::bigInt(1))
+    ->toString();
+echo "100000000000000000000 = " . $result;
+```
+
+> **注意**：Int/Float 的链式调用每步**都会修改原变量**。如果需要保留中间值，先用临时变量保存。Big* 类型不存在此问题，因为它们是不可变的。
+
+---
+
+## 12. 可变方法 vs 不可变方法
+
+不同类型的通用方法在可变性上有不同行为：
+
+### 12.1 可变方法（修改原值）
+
+**Int 和 Float** 的算术方法直接操作 C++ 原生变量，会**修改原值**：
+
+```php
+$a = 100;
+$b = $a->add(50);   // 这一步既修改了 $a（变为 150），又返回新值给 $b
+echo $a;   // 150 —— 已被修改
+echo $b;   // 150
+
+$a->inc();          // $a 变为 151
+$a->dec();          // $a 变为 150
+```
+
+**Array** 的变异方法会**修改原数组**：
+
+```php
+$arr = [1, 2, 3];
+
+$arr->push(4);      // 修改 $arr → [1,2,3,4]
+$arr->pop();        // 修改 $arr → [1,2,3]
+$arr->sort();       // 修改 $arr → [1,2,3]
+$arr->set(0, 100);  // 修改 $arr → [100,2,3]
+$arr->clean();      // 修改 $arr → []
+```
+
+### 12.2 不可变方法（返回新值）
+
+**BigInt、Decimal、BigFloat** 的所有方法都**不修改原值**，返回新创建的对象：
+
+```php
+$a = std::bigInt(100);
+$b = $a->add(50);   // $a 依然是 100，$b 是 150
+
+$a = std::bigInt(100);
+$a->add(50);        // 返回值被丢弃！$a 依然是 100
+```
+
+**String** 的大部分方法也返回新值：
+
+```php
+$s = "hello";
+$upper = $s->upper();  // $s 依然是 "hello"，$upper 是 "HELLO"
+```
+
+**例外**：`String.append()` 是变异方法（`direct_method_mutate`），会修改原字符串：
+
+```php
+$s = "hello";
+$s->append(" world");  // $s 变为 "hello world"
+```
+
+### 12.3 可变方法汇总
+
+| Handler 类型 | 影响类型 | 示例 |
+|-------------|---------|------|
+| `calc_op` | Int, Float | `add`, `sub`, `mul`, `div`, `mod`, `inc`, `dec` |
+| `direct_method_mutate` | String, Array | `append`, `set`, `del`, `clean` |
+| `php_fn_ref` | Array | `push`, `pop`, `shift`, `unshift`, `sort`, `sortDesc`, `splice`, `walk` |
+
+---
+
+## 13. Var 类型的方法查找
+
+当变量的类型为 `Var`（通用 PHP 类型）时，编译器会按以下顺序依次在方法表中查找：
+
+```
+String → Array → Int → Float → Bool → Stream → BigInt → Decimal → BigFloat
+```
+
+一旦找到匹配的方法名，就生成对应类型的调用代码。如果找不到，则退化为动态方法调用（通过 ZendVM）。
+
+```php
+// $x 的类型是 Var（来自函数返回值、数组提取等）
+$x = some_func_returning_var();
+
+// 编译器按顺序查找：
+// 1. 先在 String 方法表中找 length → 找到！→ strlen($x)
+echo $x->length();
+
+// 2. 先在 String 方法表中找 contains → 找到！→ str_contains($x, ...)
+echo $x->contains("test");
+```
+
+> **注意**：如果多个类型有同名方法，先匹配到的类型优先。例如 `toInt` 在多个类型中都存在——查找会停在第一个匹配的类型上。
+
+---
+
+## 14. 扩展方法：自动发现
+
+除了内置的通用方法外，编译器还支持**自定义扩展方法**。只要在当前项目中定义了命名符合约定的 PHP 函数，编译器就会自动将其发现为通用方法。
+
+### 14.1 命名约定
+
+格式：`{类型前缀}_{snake_case方法名}`
+
+| 类型 | 前缀 | 示例 |
+|------|------|------|
+| Int | `int_` | `int_is_prime` → `$a->isPrime()` |
+| Float | `float_` | `float_normalize` → `$f->normalize()` |
+| Bool | `bool_` | `bool_toggle` → `$b->toggle()` |
+| String | `str_` | `str_capitalize` → `$s->capitalize()` |
+| Array | `array_` | `array_flatten` → `$arr->flatten()` |
+| Stream | `stream_` | `stream_rewind` → `$fp->rewind()` |
+| BigInt | `bigint_` | `bigint_is_probable_prime` → `$a->isProbablePrime()` |
+| Decimal | `decimal_` | `decimal_round_to` → `$d->roundTo()` |
+| BigFloat | `bigfloat_` | `bigfloat_truncate` → `$bf->truncate()` |
+
+### 14.2 实现示例
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+/**
+ * 扩展方法：判断 Int 是否为素数
+ * 命名：类型前缀 int_ + snake_case 方法名 is_prime
+ */
+function int_is_prime(int $n): bool {
+    if ($n < 2) return false;
+    for ($i = 2; $i * $i <= $n; $i++) {
+        if ($n % $i == 0) return false;
+    }
+    return true;
+}
+
+/**
+ * 扩展方法：数组扁平化
+ * 命名：类型前缀 array_ + snake_case 方法名 flatten
+ */
+function array_flatten(array $arr): array {
+    $result = [];
+    array_walk_recursive($arr, function($v) use (&$result) {
+        $result[] = $v;
+    });
+    return $result;
+}
+
+function main(): void {
+    // 自动发现：int_is_prime → $n->isPrime()
+    $n = 97;
+    if ($n->isPrime()) {
+        echo "$n is prime\n";
+    }
+
+    // 自动发现：array_flatten → $arr->flatten()
+    $nested = [[1, 2], [3, [4, 5]], 6];
+    $flat = $nested->flatten();
+    var_dump($flat);  // [1, 2, 3, 4, 5, 6]
+}
+?>
+```
+
+### 14.3 注意事项
+
+- 函数**第一个参数**是接收者（receiver），从方法调用中自动传入
+- 扩展方法的返回类型固定为 `Var`
+- 需要先定义函数再调用——编译器在分析阶段发现函数，转换阶段使用它们
+- 方法的驼峰命名会**自动转为下划线命名**：`isPrime` → `is_prime`，`flattenNestedArray` → `flatten_nested_array`
+
+---
+
+## 15. 完整示例
+
+### 15.1 字符串处理管道
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void {
+    $raw = "  <h1>Hello World!</h1>  \n";
+
+    $processed = $raw
+        ->trim()                        // 去头尾空白
+        ->stripTags()                   // 去 HTML 标签
+        ->lower()                       // 转小写
+        ->upperWords();                 // 首字母大写
+
+    echo "原始: " . $raw->jsonEncode() . "\n";
+    echo "处理: " . $processed . "\n";
+    echo "长度: " . $processed->length() . "\n";
+    echo "是否为数字: " . (int)$processed->isNumeric() . "\n";
+}
+?>
+```
+
+### 15.2 数组数据处理
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void {
+    $data = [5, 2, 8, 1, 9, 3, 7];
+
+    echo "原始: " . $data->join(", ") . "\n";
+
+    // 排序
+    $data->sort();
+    echo "排序: " . $data->join(", ") . "\n";
+
+    // 统计
+    echo "数量: " . $data->count() . "\n";
+    echo "求和: " . $data->sum() . "\n";
+    echo "最小值: " . $data->get(0) . "\n";
+    echo "最大值: " . $data->get($data->count() - 1) . "\n";
+    echo "是否包含 5: " . (int)$data->contains(5) . "\n";
+
+    // 过滤与映射
+    $even = $data->filter(function($v) { return $v % 2 == 0; });
+    echo "偶数: " . $even->values()->join(", ") . "\n";
+
+    $doubled = $data->map(function($v) { return $v * 2; });
+    echo "翻倍: " . $doubled->join(", ") . "\n";
+
+    // 序列化
+    echo "JSON: " . $data->jsonEncode() . "\n";
+}
+?>
+```
+
+### 15.3 高精度计算与链式调用
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void {
+    // 大整数阶乘（使用复合赋值，更简洁）
+    $n = 50;
+    $result = std::bigInt(1);
+    for ($i = 2; $i <= $n; $i++) {
+        $result *= $i;
+    }
+    $digits = strlen($result->toString());
+    echo "{$n}! 有 {$digits} 位数字\n";
+
+    // 方法链：BigInt 算术 + 转换
+    $big = std::bigInt(1000);
+    $val = $big->mul(3)->add(200)->sub(50)->div(10)->toString();
+    echo "1000 * 3 + 200 - 50 / 10 = {$val}\n";
+
+    // Decimal 金融计算
+    $price = std::decimal("19.99");
+    $qty = 5;
+    $taxRate = std::decimal("0.08");
+    $total = $price * $qty * ($taxRate->add(std::decimal(1)));
+    echo "总价: " . $total->toString() . "\n";
+
+    // BigFloat 科学计算
+    $pi = std::bigFloat("3.14159265358979323846");
+    $area = $pi * 100;
+    echo "圆面积: " . $area->toString() . "\n";
+    echo "取整: " . $area->toInt() . "\n";
+}
+?>
+```
+
+### 15.4 文件处理
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void {
+    // 写入文件
+    $fp = fopen("data.txt", "w+");
+    $fp->write("Line 1\n");
+    $fp->write("Line 2\n");
+    $fp->write("Line 3\n");
+
+    // 回到开头并读取
+    $fp->seek(0);
+    while (!$fp->eof()) {
+        $line = $fp->getLine();
+        if ($line !== false) {
+            echo $line->trim();
+            echo " (长度: " . $line->trim()->length() . ")\n";
+        }
+    }
+
+    $fp->close();
+}
+?>
+```
+
+---
+
+## 进一步阅读
+
+- **高精度类型教程**：[`docs/HIGH_PRECISION_TYPES.md`](HIGH_PRECISION_TYPES.md)
+- **类型系统规范**：[`docs/NATIVE_TYPES.md`](NATIVE_TYPES.md)
+- **通用方法实现**：[`src/Php/UniversalMethodCall.php`](../src/Php/UniversalMethodCall.php)
+- **集成测试**：
+  - [`tests/aot/string_method/`](../tests/aot/string_method/) — String 通用方法测试
+  - [`tests/aot/array_method/`](../tests/aot/array_method/) — Array 通用方法测试
+  - [`tests/aot/stream_method/`](../tests/aot/stream_method/) — Stream 通用方法测试
+  - [`tests/aot/bigint/`](../tests/aot/bigint/) — BigInt 通用方法测试
+  - [`tests/aot/decimal/`](../tests/aot/decimal/) — Decimal 通用方法测试