update runner docs and align tests

README.md

@@ -83,7 +83,7 @@ Lua 虚拟机的主要管理类。
 | :--- | :--- | :--- |
 | `load(path: String, name: String): This` | 加载指定路径的 Lua 文件，编译后以 `name` 为标识压入内部栈。 | 实例本身 (`This`) |
 | `unload(name: String): This` | 从内部栈中卸载由 `name` 标识的模块。 | 实例本身 (`This`) |
-| `runScript(path: String, arg: String): String` | **核心执行方法**。  - 若 `path` 非空：加载并执行该脚本，`arg` 作为参数传入。  - 若 `path` 为空：触发**管道模式**，调用栈顶函数，并将栈顶数据作为参数传入。 | 脚本执行的字符串结果 |
+| `runScript(path: String, arg: String): String` | **核心执行方法**。  - 若 `path` 非空：加载并执行该脚本，`arg` 作为单参数传入。  - 若 `path` 为空：触发**管道模式**，调用栈顶函数，并按内部栈布局自动计算参数数量。 | 脚本执行的字符串结果 |
 | `clear(): This` | 清理 Lua 状态机，清空全局变量和所有加载的库，恢复到初始状态。 | 实例本身 (`This`) |
 | `result(): String` | 获取最近一次 `runScript` 成功执行的返回值。 | 字符串 |
 | `error(): String` | 获取最近一次错误的原始描述信息。 | 字符串 |
@@ -103,7 +103,7 @@ Lua 虚拟机的主要管理类。
 | :----- | :--------------------- | :------------------------------------------------------- |
 | 5001 | `NAPI_JSON_LOAD_FAIL` | JSON 文件加载失败。 |
 | 5002 | `NAPI_MALLOC_FAIL` | 内存分配失败。 |
-| 5003 | `NAPI_LOAD_FILE_ERROR` | 文件加载错误，可能由路径错误或权限不足引起。 |
+| 5003 | `NAPI_LOAD_FILE_ERROR` | 文件加载错误，包含路径、权限以及脚本编译期语法错误。 |
 | 5004 | `NAPI_SCRIPT_RUNNER_INVALID` | 脚本运行器初始化失败或实例无效。 |
 | 5005 | `NAPI_LUA_STATE_ERROR` | Lua 状态机初始化失败或已损坏。 |
 | 5006 | `NAPI_JSON_RESOLVE_FAIL` | JSON 解析错误，可能是格式问题。 |
@@ -144,9 +144,15 @@ Lua 虚拟机的主要管理类。
      3. `runner.load("A.lua", "A")`
 3. **触发执行**：
    
-   - 首先执行初始脚本，将其返回值压入栈顶。
-   - 然后调用 `runScript("", "")`，引擎将自动调用栈顶下方的函数（即最后加载的脚本 `B`），并将栈顶数据作为参数传入。
-   - `B` 执行完毕后的返回值成为新的栈顶，等待下一次 `runScript` 调用。
+- 首先执行初始脚本，将其返回值压入栈顶。
+- 然后调用 `runScript("", "")`，引擎将自动调用栈顶下方的函数（即最后加载的脚本 `B`），并将栈顶数据作为参数传入。
+- `B` 执行完毕后的返回值成为新的栈顶，等待下一次 `runScript` 调用。
+
+### 运行时语义说明
+
+- 当 `path` 非空时，脚本会先完成编译并压入内部栈，再进入执行阶段。
+- 若脚本在编译阶段发生语法错误，当前实现返回 `NAPI_LOAD_FILE_ERROR`，详细信息可通过 `result()` 获取。
+- 在 `require` / `package.path` 场景下，`runScript` 返回当前 Lua 栈顶字符串结果；若栈顶内容是模块解析路径，则会直接返回该路径字符串。
 
 ### 管道模式示例