004-step-02-runtime-model.md

第 2 步：运行时模型

状态

已完成。

这一阶段的目标，是先把 Lua 运行时最基础的几个概念稳定下来，为后续 VM、表、闭包、编译器提供统一的承载结构。

背景与参考

这一阶段主要参考这些官方资料：

• Lua 5.5 手册：https://www.lua.org/manual/5.5/
• references/lua-5.5.0/src/lobject.h
• references/lua-5.5.0/src/lstate.h
• references/lua-5.5.0/src/lfunc.h
• references/lua-5.5.0/src/lvm.h

这一阶段不追求把官方内部结构逐字段照搬到 C#。目标是先建立一组清楚、稳定、适合教学和后续演进的运行时抽象。

本步骤范围

本阶段先定义这些核心模型：

• LuaValueKind
• LuaValue
• LuaTable
• LuaClosure
• LuaThread
• LuaUserData
• LuaStack
• CallFrame
• LuaState

这些类型优先解决“如何表达运行时对象”和“VM 后续把状态放在哪里”两个问题。

设计原则

1. 值类型和引用类型分开表达

Lua 的运行时值需要同时容纳：

• nil
• 布尔
• 整数
• 浮点数
• 字符串
• 表
• 函数
• 线程
• userdata

这一步采用：

• LuaValueKind 表示种类
• LuaValue 表示一个统一运行时值

其中：

• 布尔、整数、浮点保存在结构体字段里
• 字符串按值语义比较
• 表、函数、线程、userdata 先按引用标识比较

2. 先保证状态容器清楚

VM 后续一定会依赖三个容器：

• 值栈
• 调用帧栈
• 整体运行时状态

所以这一步先定义：

• LuaStack
• CallFrame
• LuaState

这样第 3 步和第 4 步往下走时，就不用一边写 VM，一边临时拼状态结构。

3. 先做最小可用骨架

这一步不会把表、闭包、线程一次做满。

当前重点是：

• 类型边界稳定
• 行为足够测试
• 能支撑下一步 VM 骨架继续写

模型说明

LuaValue

职责：

• 表示任意一个 Lua 运行时值
• 提供工厂方法构造不同种类的值
• 提供安全的类型访问方法
• 提供明确的相等性规则

当前约定：

• nil 和 nil 相等
• 布尔按布尔值比较
• 整数按整数值比较
• 浮点按浮点值比较
• 字符串按 Ordinal 值比较
• 表、函数、线程、userdata 按引用身份比较

LuaStack

职责：

• 维护值栈
• 提供 Push、Pop、Peek
• 提供索引访问
• 提供 SetTop

SetTop 很重要，因为后续 VM 和调用协议会频繁调整栈顶。

CallFrame

职责：

• 表示一次 Lua 调用的执行上下文
• 记录当前闭包
• 记录栈基址
• 记录预期返回值数量
• 记录程序计数器

这一阶段先保留最少字段，后续再根据 VM 和调试需求扩展。

LuaState

职责：

• 聚合运行时栈
• 管理调用帧栈
• 暴露当前调用帧

后续标准库、协程和 VM 执行都会依赖它。

当前实现清单

• 编写本阶段文档
• 创建 Lua.Runtime 项目
• 定义基础运行时值模型
• 定义基础状态容器
• 创建 Lua.Runtime.Tests
• 为值、栈、调用帧、状态补基础测试

完成标准

本阶段完成时，应满足：

• Lua.Runtime 可以独立编译
• LuaValue 能稳定表达核心运行时值
• LuaStack 和 LuaState 可以支撑后续 VM 编写
• 测试覆盖最基本的值行为和容器行为
• 项目基线保持在 .NET 10

延后处理的内容

这些内容放到后续阶段继续展开：

• 完整的表实现
• 上值对象建模
• 原生函数和 Lua 函数的统一调用模型
• 协程调度细节
• 元表行为
• 指令执行循环

下一步

运行时模型落稳之后，下一步进入字节码加载与反汇编：

• 对齐 Lua 5.5 chunk 格式
• 读取 proto
• 建立指令元数据表
• 输出可读的反汇编结果