LuaCangjia_api/doc/ADAPTATION-lua32.md

# Lua 3.2 分支移植评估（ADAPTATION.md）

> 本分支已 vendor Lua 3.2 官方源码到 `lib/lua/`（include/ 头文件 + src 平铺）。
> **桥接层尚未适配**——Lua 3.x 是"前 lua_State 时代"的 API，与本项目桥接层不兼容。

## 当前状态

- ✅ Lua 3.2 源码就位（18 个 .c）
- ❌ `lib/lua_runner.cpp` / `lib/lua_cj_api.cpp` 未适配
- ❌ 构建系统未适配（CMakeLists 需按 3.2 文件集重写）

## 移植要点

Lua 1.0~3.2 均为**全局唯一状态机**设计：

| 能力 | Lua 5.4 桥接实现 | Lua 3.2 | 改造方案 |
|---|---|---|---|
| 状态机 | `luaL_newstate()` 返回句柄，可多实例 | `lua_open(void)` 全局单例，`lua_close(void)` | **多实例语义丧失**：仓颉侧多个 LuaRunner 共享同一状态机；handle 退化为哑指针 |
| 加载执行 | `luaL_loadfile` + `lua_pcall` | `lua_dofile(char*)` / `lua_dostring(char*)` 一步式 | run()/doString 重写；无编译/执行分离 → 管道模式（块压栈）不可实现 |
| 函数引用 | `luaL_ref` + Registry | `lua_ref(lua_Object)` / `lua_getref` | loadFunction 可映射，但 lua_Object 是 unsigned int 句柄 |
| 栈模型 | 显式虚拟栈索引操作 | 隐式"对象栈"，`lua_getparam(n)` 取参 | 整个 pkgs[] 栈布局逻辑推倒重写 |
| 数据传递 | 栈上多值 | 单返回值 `lua_getresult` | typed interop 仅剩 string/number |
| I/O 重定向 | extraspace/Registry 存 iopath | 无对应机制，print 劫持需用 tag method 或改 lbuiltin.c 源码 | 成本高 |

## 结论

**不建议移植**。理由：
1. 全局单例状态机与本项目"多 runner 实例"的核心抽象冲突
2. 无编译/执行分离，管道模式（项目核心特性）无法实现
3. 1999 年的 API，无 integer 类型、无保护调用、tag method 机制与现代完全不同
4. 实际收益趋近于零——没有现存应用依赖 Lua 3.x 嵌入

本分支仅作为源码存档。若确需支持，建议以 `lua_dofile`+全局单例为边界
做一个极简 doString-only 的独立桥接，而非复用现有 Lua_runner 抽象。