refactor!: 错误码体系重构删除特殊平台语境残留

BREAKING CHANGE: 错误码编号全部变更, 外部依赖旧编号的代码需按映射表更新 - 删除 10 个从未使用的错误码: JSON/MCP 系列(5001/5002/5006/5007/5008) + 其余死码(5004/5009/5013/5018/5021) - 重排为连续 5001~5016 - 宏前缀 NAPI_(鸿蒙 NAPI 语境残留) 改为 LUAERR_ - 同步更新: errors.h / bridge.cj getErrorMessage+typed抛出点 / lua_runner_test.cj 断言 / api.md 对照表 / README.md / GTest 宏名 - 清理注释残留: 鸿蒙 el2 沙盒路径 TODO / 沙盒内路径描述 - 版本号 0.2.1 -> 0.2.2 验证: GTest 44/44 通过; cjpm build 成功; 独立程序运行时 9/9 通过 (含新编号 5016/5013 错误路径)
2026-09-19 16:42:48 +00:00 · 2026-08-25 09:29:48 +08:00
parent 237aab3f36
commit 4af121c1f3
4 changed files with 105 additions and 61 deletions
--- a/README.md
+++ b/README.md
@ -5,7 +5,7 @@
 [![Cangjie](https://img.shields.io/badge/Cangjie-SDK-orange)](https://cangjie-lang.cn/)
 [![AI-Assisted](https://img.shields.io/badge/🤖_AI_Assisted-20%25-orange)](README.md#ai-%E8%BE%85%E5%8A%A9%E7%BC%96%E7%A8%8B%E6%A0%87%E8%AF%86)  
 ![AigcAssets.png](https://raw.atomgit.com/user-images/assets/9445015/a1976a82-4d44-493a-8efd-fb12a104268e/AigcAssets.png "AigcAssets.png")
-**v0.2.1版本更新**：新增doString方法，可执行单句lua，新增loadFunction/callFunction预加载能力（AI辅助），更新了文档布局与readme优化了文档布局。
+**v0.2.2版本更新**：新增 typed interop（原始类型直通：Int64/Float64/Bool 与 Lua 直接互转，不经过字符串序列化），新增 `callFunctionInt/Num/Bool`、`runScriptInt/Num/Bool`、`resultType` API，扩展错误码 5016（结果类型不支持）。补充AI辅助编程标识。

 ---

@ -17,9 +17,10 @@

 | 模块 | AI 辅助程度 | 说明 |
 | :--- | :--- | :--- |
+| `typed interop`（`callFunctionInt/Num/Bool`、`runScriptInt/Num/Bool`、`resultType` 及 C 层 typed 函数） | 高（AI 主写，人工审查） | 原始类型直通映射：仓颉 Int64/Float64/Bool 与 Lua integer/number/boolean 直接互转，带类型标记的结果读取与严格校验（错误码 5016） |
 | `loadFunction`/`callFunction`/`unloadFunction` | 高（AI 主写，人工审查） | 预加载函数能力：加载文件→顶层执行一次→返回函数存入 Registry→可多次调用 |
-| 单元测试（新增部分） | 中（AI 主写，人工修正） | 预加载相关 GTest / 仓颉单测 |
-| 文档（新增部分） | 低（AI 起草，人工定稿） | README / api.md 预加载部分 |
+| 单元测试（新增部分） | 中（AI 主写，人工修正） | 预加载与 typed interop 相关 GTest / 仓颉单测 |
+| 文档（新增部分） | 低（AI 起草，人工定稿） | README / api.md 预加载与 typed interop 部分 |

 ---

@ -33,6 +34,7 @@ Lua Runner for Cangjie 是一个专为仓颉语言设计的轻量级、高性能
 ## 特性

 - **轻量级集成**：基于 Lua 5.4，通过 FFI 直接与仓颉语言交互，性能损耗小。
+- **原始类型直通**：`Int64`/`Float64`/`Bool` 与 Lua `integer`/`number`/`boolean` 直接互转，支持 typed 参数与结果（`callFunctionInt/Num/Bool`、`runScriptInt/Num/Bool`），整数可跨 `2^53` 保真，无需字符串往返。
 - **栈式管道模式**：支持脚本间基于栈的数据隐式传递，实现类似函数式管道的调用链。
 - **预加载函数**：提供 `loadFunction`/`callFunction`/`unloadFunction`，预加载一次 Lua 函数到内存（Registry），顶层代码仅执行一次，后续可多次调用，与管道模式互不干扰。
 - **doString**：直接执行 Lua 代码字符串，无需写入文件。
@ -76,8 +78,8 @@ main(): Int64 {

 ## 当前局限性

- **数据类型限制**：当前版本在仓颉与 Lua 交互层仅支持**字符串**类型。虽然 Lua 内部可以处理复杂数据结构，但传递给仓颉或从仓颉传入时必须进行序列化/反序列化（如 JSON）。
- **容量限制**：内部使用固定数组管理加载的库，上限为 **20 个**，超过将报错 `5016`。
+- **数据类型限制**：跨语言交互层从**仅字符串**扩展为**原始类型直通**（Int64/Float64/Bool 作为参数与返回值直接映射，不经过字符串序列化），复杂数据结构（表/嵌套）仍需序列化（如 JSON）。
+- **容量限制**：内部使用固定数组管理加载的库，上限为 **20 个**，超过将报错 `5008`。
 - **I/O 性能**：I/O 重定向依赖于文件系统交换，相对于纯内存交互存在微小的性能开销。

 ## 第三方组件与合规说明
--- a/cjpm.toml
+++ b/cjpm.toml
@ -1,6 +1,6 @@
 [package]
 name = "luaRunner"
-version = "0.2.1"
+version = "0.2.2"
 description = "Lite and High performance LuaRunner"
 cjc-version = "1.1.0"     
 license = "LGPL-3.0-or-later"
--- a/doc/api.md
+++ b/doc/api.md
@ -23,6 +23,13 @@ Lua 虚拟机的主要管理类。
 | `load(path: String, name: String): This` | **块压栈**。加载 Lua 文件、编译成 chunk、压入虚拟栈并记录栈位置。`name` 仅作为内部标识。与管道模式配套使用。 | 实例本身 (`This`) |
 | `loadFunction(path: String, name: String): This` | **预加载函数到内存**。加载文件 → 执行顶层代码（仅执行一次） → 捕获返回的函数对象 → 存入 Lua Registry。与 `load` 完全独立的两套存储（不共用 `pkgs` 栈），被加载的 Lua 文件顶层必须 `return` 一个函数。 | 实例本身 (`This`) |
 | `callFunction(name: String, arg: String): String` | **按名称调用预加载的函数**。从 Registry 取出函数后 `pcall`，**不消耗该函数**，可多次重复调用。与管道模式互不干扰。 | 函数执行的字符串结果 |
+| `callFunctionInt(name: String, val: Int64): Int64` | **typed 直通调用**。传 Int64 参数（映射为 Lua integer），返回整数结果。结果非数值时抛 5016。 | 整数结果 |
+| `callFunctionNum(name: String, val: Float64): Float64` | **typed 直通调用**。传 Float64 参数（映射为 Lua number），返回浮点结果。结果非数值时抛 5016。 | 浮点结果 |
+| `callFunctionBool(name: String, val: Bool): Bool` | **typed 直通调用**。传 Bool 参数（映射为 Lua boolean），返回布尔结果。结果为 nil/string 时抛 5016。 | 布尔结果 |
+| `runScriptInt(path: String, val: Int64): Int64` | 运行脚本并传 Int64 参数，返回整数结果。独立调用（执行后弹出返回值、保持虚拟栈清洁），非管道模式。 | 整数结果 |
+| `runScriptNum(path: String, val: Float64): Float64` | 同上，Float64 版本。 | 浮点结果 |
+| `runScriptBool(path: String, val: Bool): Bool` | 同上，Bool 版本。 | 布尔结果 |
+| `resultType(): Int32` | 获取最近一次调用的结果类型：`0`=nil `1`=bool `2`=int `3`=num `4`=str | 类型常量 |
 | `unloadFunction(name: String): This` | 卸载预加载的函数（释放 Registry 引用）。 | 实例本身 (`This`) |
 | `unload(name: String): This` | 从内部栈中卸载由 `name` 标识的块（仅适用于 `load` 加载的块）。 | 实例本身 (`This`) |
 | `runScript(path: String, arg: String): String` | **核心执行方法**。  - 若 `path` 非空：加载并执行该脚本，`arg` 作为单参数传入。  - 若 `path` 为空：触发**管道模式**，调用栈顶函数，并按内部栈布局自动计算参数数量。 | 脚本执行的字符串结果 |
@ -42,36 +49,28 @@ Lua 虚拟机的主要管理类。

 ### 错误码对照表

+错误码连续编号 `5001~5016`，宏前缀为 `LUAERR_`。
+
 | 错误码 | 宏定义 | 描述 |
 | :----- | :--------------------- | :------------------------------------------------------- |
-| 5001 | `NAPI_JSON_LOAD_FAIL` | JSON 文件加载失败。 |
-| 5002 | `NAPI_MALLOC_FAIL` | 内存分配失败。 |
-| 5003 | `NAPI_LOAD_FILE_ERROR` | 文件加载错误，包含路径、权限以及脚本编译期语法错误。 |
-| 5004 | `NAPI_SCRIPT_RUNNER_INVALID` | 脚本运行器初始化失败或实例无效。 |
-| 5005 | `NAPI_LUA_STATE_ERROR` | Lua 状态机初始化失败或已损坏。 |
-| 5006 | `NAPI_JSON_RESOLVE_FAIL` | JSON 解析错误，可能是格式问题。 |
-| 5007 | `NAPI_JSON_FORMATE_ERROR` | JSON 格式错误，不符合 MCP 常见格式。 |
-| 5008 | `NAPI_MISSING_JSON_ARG` | 无法从 JSON 中解析到所需参数。 |
-| 5009 | `NAPI_LUA_STACK_NOSPACE` | Lua 栈空间不足。 |
-| 5010 | `NAPI_SCRIPT_ERROR` | 脚本内部错误，请通过 `result()` 获取详细信息。 |
-| 5011 | `NAPI_SCRIPT_BAD_RET` | 脚本返回值错误，当前版本仅支持字符串返回。 |
-| 5012 | `NAPI_UNLOADLIB_FAIL` | 尝试卸载未加载的库。 |
-| 5013 | `NAPI_LUAFUN_NOFOUND` | 调用不符合单输入单输出约定。 |
-| 5014 | `NAPI_LUA_STACK_ERROR` | 函数调用时栈大小小于最小约定大小。 |
-| 5015 | `NAPI_LUA_INITFAIL` | Lua 状态机初始化错误。 |
-| 5016 | `NAPI_LUALIB_LOAD_OVER_STACK` | 加载的库数量超过上限（最大 20 个）。 |
-| 5017 | `NAPI_LUA_CLASS_LOST` | 底层 LuaRunner 对象丢失。 |
-| 5018 | `NAPI_LUA_MISS_REDIRECT` | 缺少用于重定向的文件路径。 |
-| 5019 | `NAPI_RESET_INPUT_FILE_ERROR` | 重置输入文件失败，可能导致输入污染。 |
-| 5020 | `NAPI_ERROR_FUNCS` | 回调函数执行过程中发生错误（含 `doString` 语法错误）。 |
-| 5021 | `NAPI_CHDIR_ERROR` | 切换工作目录失败，可能导致包搜索错误，日志写入路径错误等。 |
-| 5022 | `NAPI_NOCHUNK_FOUND` | 没有找到待调用的函数。 |
-| 5023 | `NAPI_FUNCTION_NOT_FOUND` | `callFunction` 调用时未找到指定名称的预加载函数。 |
-| 5024 | `NAPI_LOAD_FUNCTION_OVER` | 预加载函数数量超过上限（最大 20 个）。 |
-| 5025 | `NAPI_FUNCTION_NOT_VALID` | 预加载的文件顶层返回的不是函数。 |
+| 5001 | `LUAERR_LOAD_FILE` | 文件加载错误，包含路径、权限以及脚本编译期语法错误。 |
+| 5002 | `LUAERR_LUA_STATE` | Lua 状态机初始化失败或已损坏。 |
+| 5003 | `LUAERR_SCRIPT_ERROR` | 脚本内部错误，请通过 `result()` 获取详细信息。 |
+| 5004 | `LUAERR_SCRIPT_BAD_RET` | 脚本返回值类型不符合要求（如返回非字符串且无法转换）。 |
+| 5005 | `LUAERR_UNLOADLIB_FAIL` | 尝试卸载未加载的库。 |
+| 5006 | `LUAERR_LUA_STACK` | 函数调用时栈布局与约定不符。 |
+| 5007 | `LUAERR_INIT_FAIL` | Lua 状态机初始化错误。 |
+| 5008 | `LUAERR_LIB_OVERFLOW` | 加载的库数量超过上限（最大 20 个）。 |
+| 5009 | `LUAERR_CLASS_LOST` | 底层 LuaRunner 对象丢失。 |
+| 5010 | `LUAERR_RESET_INPUT_FILE` | 重置输入文件失败，可能导致输入污染。 |
+| 5011 | `LUAERR_CALLBACK` | 回调函数执行过程中发生错误（含 `doString` 语法错误）。 |
+| 5012 | `LUAERR_NOCHUNK_FOUND` | 没有找到待调用的函数。 |
+| 5013 | `LUAERR_FUNCTION_NOT_FOUND` | `callFunction` 调用时未找到指定名称的预加载函数。 |
+| 5014 | `LUAERR_FUNC_OVERFLOW` | 预加载函数数量超过上限（最大 20 个）。 |
+| 5015 | `LUAERR_FUNCTION_INVALID` | 预加载的文件顶层返回的不是函数。 |
+| 5016 | `LUAERR_RESULT_TYPE` | typed interop 中请求的结果类型与实际返回类型不兼容（如将 string 读作 int）。 |

 ## 预加载函数模式 (Preload Function Mode)
-
 与管道模式不同，预加载模式适合“加载一次、多次调用”的场景。

 ### 调用规范
@ -117,6 +116,56 @@ println(runner.callFunction("counter", "c")) // arg=c count=3
 runner.unloadFunction("counter")
 ```

+## 类型化交互 (Typed Interop) — v0.2.2
+
+除字符串形式外，仓颉侧的 `Int64`/`Float64`/`Bool` 可与 Lua 的 `integer`/`number`/`boolean` **直接互转**，不经过字符串序列化。
+
+### 支持的类型映射
+
+| 仓颉 | Lua | 说明 |
+| :--- | :--- | :--- |
+| `Int64` | `integer` | 64 位整数，可跨 `2^53` 保真 |
+| `Float64` | `number` | 64 位浮点 |
+| `Bool` | `boolean` | 布尔 |
+| `String` | `string` | 原 callFunction/runScript 路径 |
+
+### 调用规范
+
+```cangjie
+let runner = LuaRunner()
+
+// 预加载：inc.lua 顶层返回 function(n) return n + 1 end
+runner.loadFunction("./scripts/inc.lua", "inc")
+
+// typed 调用：参数与结果均为整数，不转字符串
+let n = runner.callFunctionInt("inc", 41)  // n == 42 (Int64)
+let d = runner.callFunctionNum("mul", 4.0) // Float64
+let b = runner.callFunctionBool("neg", true) // Bool
+
+// 脚本直通：脚本直接返回入参（如 return (...) ）
+let r = runner.runScriptInt("./scripts/echo.lua", 777) // 777
+
+// 查询结果类型：0=nil 1=bool 2=int 3=num 4=str
+let t = runner.resultType()
+```
+
+### 类型校验规则
+
+- `callFunctionInt`/`runScriptInt`：接受 Lua `integer`（CJT_INT）与 `number`（CJT_NUM）结果；其余（nil/string/bool/table）抛 **5016**。
+- `callFunctionNum`/`runScriptNum`：同上，接受 int/num 结果。
+- `callFunctionBool`/`runScriptBool`：接受 bool/int/num 结果；nil 与 string 抛 **5016**。
+- 现有字符串 API（`callFunction`/`runScript`）行为不变；每次调用都会同步更新类型化结果字段，因此 `callFunction("x", "10")` 之后 `resultType()` 返回 `4`（str）。
+
+### 与管道模式的关系
+
+`runScriptInt/Num/Bool` 是**独立调用**：执行后弹出返回值、保持虚拟栈清洁，不参与管道链。管道模式请继续使用字符串版 `runScript(path, arg)`（其结果留在栈上供下一节点消费）。
+
+### 内部实现
+
+- C 层新增 `callfunction_int/num/bool/void`、`run_int/num/bool/void`、`result_type/int/num/bool` 共 11 个 FFI 函数。
+- C++ 层 `Lua_runner` 新增 `last_result_type/int/num/bool` 字段，`capture_result()` 读取 Lua 栈顶并记录类型，`finish_call()` 计算 `lua_pcall` 实际返回值数量（`nres = post_top - pre_top + nargs + 1`）以正确处理无返回值场景。
+- typed 结果同时同步到字符串缓冲区 `self->result`，因此 `result()`/`getresult` 与 typed getter 可以混用。
+
 ## 管道模式 (Pipeline Mode)

 这是该引擎的核心特性，允许数据在多个脚本间自动流转，无需在仓颉层进行手动传递。
@ -146,7 +195,7 @@ runner.unloadFunction("counter")
 ### 运行时语义说明

 - 当 `path` 非空时，脚本会先完成编译并压入内部栈，再进入执行阶段。
- 若脚本在编译阶段发生语法错误，当前实现返回 `NAPI_LOAD_FILE_ERROR`，详细信息可通过 `result()` 获取。
+- 若脚本在编译阶段发生语法错误，当前实现返回 `LUAERR_LOAD_FILE` (5001)，详细信息可通过 `result()` 获取。
 - 在 `require` / `package.path` 场景下，`runScript` 返回当前 Lua 栈顶字符串结果；若栈顶内容是模块解析路径，则会直接返回该路径字符串。

 ### 管道模式示例
@ -198,6 +247,6 @@ println(res2) // 输出: 42
 ### 注意事项

 - `doString` 要求代码执行后栈顶必须是**字符串类型**的返回值
- 若代码不返回字符串（如返回 `nil`、数字或无返回值），将抛出 `NAPI_SCRIPT_BAD_RET` (5011) 错误
- 若代码存在语法错误，将抛出 `NAPI_ERROR_FUNCS` (5020) 错误
+- 若代码不返回字符串（如返回 `nil`、数字或无返回值），将抛出 `LUAERR_SCRIPT_BAD_RET` (5004) 错误
+- 若代码存在语法错误，将抛出 `LUAERR_CALLBACK` (5011) 错误
 - `doString` 与 `runScript` 共享同一个 Lua 状态机，全局变量和已加载的模块可互相访问
--- a/lib/errors.h
+++ b/lib/errors.h
@ -1,30 +1,23 @@
 #ifndef ERRORS
 #define ERRORS
-//用于定义napi中所有可能出现的错误，便于错误传递
-#define NAPI_JSON_LOAD_FAIL 5001 //json文件加载错误
-#define NAPI_MALLOC_FAIL 5002 //内存分配错误
-#define NAPI_LOAD_FILE_ERROR 5003    //文件加载错误，可能为权限或路径问题
-#define NAPI_SCRIPT_RUNNER_INVALID 5004 //脚本运行器初始化错误，脚本运行器异常
-#define NAPI_LUA_STATE_ERROR 5005 //lua状态机初始化错误或损坏
-#define NAPI_JSON_RESOLVE_FAIL 5006 //json解析错误，可能为格式错误等
-#define NAPI_JSON_FORMATE_ERROR 5007 //json格式错误（与mcp常见格式不符)
-#define NAPI_MISSING_JSON_ARG 5008 //无法从json中解析到参数
-#define NAPI_LUA_STACK_NOSPACE 5009 //lua状态机栈空间不足
-#define NAPI_SCRIPT_ERROR 5010 //脚本内部错误,取result获取更多信息
-#define NAPI_SCRIPT_BAD_RET 5011 //脚本返回值错误
-#define NAPI_UNLOADLIB_FAIL 5012 // 释放的库未被加载
-#define NAPI_LUAFUN_NOFOUND 5013 //调用不符合规定，没有遵守单入参单出参约定
-#define NAPI_LUA_STACK_ERROR 5014 //函数调用时，栈大小小于约定最小大小
-#define NAPI_LUA_INITFAIL 5015 //lua状态机初始化错误
-#define NAPI_LUALIB_LOAD_OVER_STACK 5016 //加载太多lib
-#define NAPI_LUA_CLASS_LOST 5017 //luarunner对象丢失
-#define NAPI_LUA_MISS_REDIRECT 5018 //漏传用于重定向的文件路径
-#define NAPI_RESET_INPUT_FILE_ERROR 5019 //重置输入文件失败，可能造成输入污染
-#define NAPI_ERROR_FUNCS 5020 //函数调用错误
-#define NAPI_CHDIR_ERROR 5021 //切换工作目录失败，可能导致包搜索错误，日志写入路径错误等
-#define NAPI_NOCHUNK_FOUND 5022 //没有找到待调用的函数
-#define NAPI_FUNCTION_NOT_FOUND 5023 //通过callfunction调用时未找到指定函数
-#define NAPI_LOAD_FUNCTION_OVER 5024 //预加载函数数量超过上限
-#define NAPI_FUNCTION_NOT_VALID 5025 //预加载文件顶层执行后返回的不是函数
+// LuaCangjia_api 统一错误码体系：5001~5016 连续编号，C++ 层与仓颉层共用。
+// 仓颉侧 LuaError.code 与此处数字一一对应，修改时需同步 src/bridge.cj 的
+// getErrorMessage 与 doc/api.md 的错误码对照表。
+#define LUAERR_LOAD_FILE 5001          //文件加载错误，可能为权限、路径或编译期语法问题
+#define LUAERR_LUA_STATE 5002          //lua状态机初始化错误或损坏
+#define LUAERR_SCRIPT_ERROR 5003       //脚本内部错误，取result获取更多信息
+#define LUAERR_SCRIPT_BAD_RET 5004     //脚本返回值类型不符合要求
+#define LUAERR_UNLOADLIB_FAIL 5005     //释放的库未被加载
+#define LUAERR_LUA_STACK 5006          //函数调用时，栈布局与约定不符
+#define LUAERR_INIT_FAIL 5007          //lua状态机初始化失败
+#define LUAERR_LIB_OVERFLOW 5008       //加载的库数量超过上限
+#define LUAERR_CLASS_LOST 5009         //luarunner对象丢失
+#define LUAERR_RESET_INPUT_FILE 5010   //重置输入文件失败，可能造成输入污染
+#define LUAERR_CALLBACK 5011           //回调函数执行错误（含doString语法错误）
+#define LUAERR_NOCHUNK_FOUND 5012      //没有找到待调用的函数
+#define LUAERR_FUNCTION_NOT_FOUND 5013 //callfunction时未找到指定函数
+#define LUAERR_FUNC_OVERFLOW 5014      //预加载函数数量超过上限
+#define LUAERR_FUNCTION_INVALID 5015   //预加载文件顶层执行后返回的不是函数
+#define LUAERR_RESULT_TYPE 5016        //结果类型不支持（如将string读作int）

 #endif