002-step-01-foundation.md

第 1 步：基础基线与规范对齐

状态

已完成。

这份文档定义了新实现路线里的第一个正式阶段。

为什么先做这一步

在写 VM、解析器、编译器之前，必须先把目标版本和项目规则定死。

如果跳过这一步，后面很容易把不同阶段的设计目标和不同层级的职责混在一起，最终让实现边界越来越模糊。

规范依据

本项目以官方 Lua 5.5 资料为准，优先级如下：

• 手册：https://www.lua.org/manual/5.5/
• 发布说明和变更：https://www.lua.org/manual/5.5/readme.html
• 官方测试集：https://www.lua.org/tests/
• 官方源码：https://www.lua.org/source/5.5/

如果仓库里的实现和官方 Lua 5.5 资料不一致，以官方资料为准。

另外，仓库里保留一份本地官方源码副本：

• references/lua-5.5.0/

本步骤范围

这一步还不进入 VM 实现。

这一阶段只做基础基线的确定，包括：

• 目标 Lua 版本
• 工具链版本
• 模块边界
• 测试策略
• 命名规则

已确定的决策

1. 只对齐一个目标版本

当前只对齐 Lua 5.5.0。

最终兼容性目标是：

• 能接受并运行官方 Lua 5.5 编译器能够接受的 Lua 源码

工具链基线为：

• SDK：.NET 10
• Target Framework：net10.0

2. 新模块边界要明确

后续要逐步往下面这几个模块靠拢：

• Lua.Runtime
• Lua.Bytecode
• Lua.Syntax
• Lua.Compiler
• Lua.StandardLib
• Lua.Cli

不要求现在立刻把所有模块都建好，但新增代码必须考虑这些边界，不要继续往模糊的大项目里堆。

3. 核心库保持纯净

核心项目不应该直接写 Console。

格式化输出、调试信息、命令行展示都应放在专门的工具层或测试辅助层，不应该混进运行时和数据模型。

4. 测试分三层

后续测试按三层组织：

1. 单元测试，验证局部行为
2. 夹具测试，验证源码、chunk 和 golden 输出
3. 兼容性测试，基于官方 Lua 5.5 材料

遇到语义不够明确的地方，优先顺序如下：

1. 官方手册
2. 官方源码的实际行为
3. 本地显式测试

建议的测试目录

建议逐步整理成下面的结构：

• test/Lua.Runtime.Tests
• test/Lua.Bytecode.Tests
• test/Lua.Syntax.Tests
• test/Lua.Compiler.Tests
• test/Lua.Compatibility.Tests

建议的夹具目录：

• test/fixtures/lua55/source
• test/fixtures/lua55/chunks
• test/fixtures/lua55/golden

本步骤交付物

这一阶段完成时，仓库里至少应该有：

• 一份明确写明 Lua 5.5 目标的文档
• 一份说明模块边界的文档
• 一份说明测试策略的文档

实现清单

• 在 docs/ 中写总路线图
• 在 docs/ 中写基础基线文档
• 把官方 Lua 5.5.0 源码拉到 references/
• 在 docs/ 中写官方源码参考策略文档
• 调整解决方案结构，使其更接近新的模块边界
• 建立 Lua 5.5 的源码和 chunk 夹具目录
• 补一份简短的贡献说明，明确“先文档、后实现”的工作方式

完成标准

这一步完成时，应满足下面几点：

• 新加入的人在一分钟内就能看明白目标版本是什么
• 新加入的人能快速知道运行时、语法、编译器、标准库代码应该放哪里
• 不需要额外口头说明，也能理解新项目的方向
• 下一步实现开始之前，不需要重新讨论“到底对齐哪个 Lua 版本”

后续阶段处理的内容

下面这些内容会在后续阶段展开：

• VM 指令执行
• 字节码解码实现
• AST 设计细节
• 解析器实现
• 编译器实现
• 标准库行为实现

下一步

这份文档之后，应该进入第 2 步： 先定义运行时值模型，以及 VM 会依赖的状态、调用帧和栈抽象。