docs: 补全 Aster 中文调用链、控制流与生命周期注释 #3

2026-11-15T12:08:13Z

codex-bot commented

2026-11-15 12:08:13 +00:00

目标与结果

为后续本地 Nexus runtime 抽取补全 Aster 的中文源码说明，方便沿调用链阅读和维护。覆盖 objects、core、frontend、compiler 的实现、测试、示例和生成脚本；说明函数调用方、变量用途、控制分支、对象根/内部边、委托及失败清理。

实际改动

对象层：载荷协议、Store/Heap、数值、字节码验证、类型/能力、原生上下文、契约和效果查询的详细注释。
执行器与编译器：帧/协程/只读切片、参数及返回检查、栈根转交、名称分析、模板加载和跳转布局说明。
前端：读取/来源/诊断、词法与 PEG 语法、AST/Visitor/JSON 校验说明；中文说明保存在生成器并写入 Rust/TypeScript，重新生成不会丢失。
16 份集成测试及所有示例逐文件复核，说明断言覆盖、辅助函数和生命周期；修正与实际场景不符的旧说明。
修正 AST 指南中条件/循环尚未实现的过时描述。按用户明确选择保留 Endor.asdl 原文，中文解释放在生成源码中，避免改变包含注释/空白的协议哈希。

检查结果

代码清单 62/62 核对完成；61 个文件直接补充注释，ASDL 采用上述保留方案。
58 个 Rust/TypeScript/Endor/PEG 文件的非注释代码与基线完全一致。
全部 Rust/PEG 的 rustfmt --check、完整分支 git diff --check、shell 语法检查通过；shell 可执行命令及 Python 回归脚本 AST 未改变。
AST 生成同步检查通过；4 项纯 Python 生成器测试通过。真实 schema、增加操作符、可选递归节点三种输入下，生成代码的非注释内容与 JSON Schema 均保持一致。
原始 ASDL 和 JSON Schema 字节与基线一致，协议标识未变。

验证边界与后续

用户暂不使用 CI/CD，且未授权本机编译；没有执行 Rust/TypeScript 编译、Cargo test/clippy 或 VM 行为测试。上述静态检查证明注释与生成说明的修改范围，不代表运行验证通过。

复核记录中的既有运行时问题（对象真值读取依赖、调用图分析的算术模拟分支）留待独立行为修复与回归，不混入本次注释交付。Nexus 尚未抽取，也没有创建 Nexus 远程仓库。

请用户查看后手动合并到 main；bot 不代为合并。

## 目标与结果为后续本地 Nexus runtime 抽取补全 Aster 的中文源码说明，方便沿调用链阅读和维护。覆盖 objects、core、frontend、compiler 的实现、测试、示例和生成脚本；说明函数调用方、变量用途、控制分支、对象根/内部边、委托及失败清理。 ## 实际改动 - 对象层：载荷协议、Store/Heap、数值、字节码验证、类型/能力、原生上下文、契约和效果查询的详细注释。 - 执行器与编译器：帧/协程/只读切片、参数及返回检查、栈根转交、名称分析、模板加载和跳转布局说明。 - 前端：读取/来源/诊断、词法与 PEG 语法、AST/Visitor/JSON 校验说明；中文说明保存在生成器并写入 Rust/TypeScript，重新生成不会丢失。 - 16 份集成测试及所有示例逐文件复核，说明断言覆盖、辅助函数和生命周期；修正与实际场景不符的旧说明。 - 修正 AST 指南中条件/循环尚未实现的过时描述。按用户明确选择保留 Endor.asdl 原文，中文解释放在生成源码中，避免改变包含注释/空白的协议哈希。 ## 检查结果 - 代码清单 62/62 核对完成；61 个文件直接补充注释，ASDL 采用上述保留方案。 - 58 个 Rust/TypeScript/Endor/PEG 文件的非注释代码与基线完全一致。 - 全部 Rust/PEG 的 rustfmt --check、完整分支 git diff --check、shell 语法检查通过；shell 可执行命令及 Python 回归脚本 AST 未改变。 - AST 生成同步检查通过；4 项纯 Python 生成器测试通过。真实 schema、增加操作符、可选递归节点三种输入下，生成代码的非注释内容与 JSON Schema 均保持一致。 - 原始 ASDL 和 JSON Schema 字节与基线一致，协议标识未变。 ## 验证边界与后续用户暂不使用 CI/CD，且未授权本机编译；没有执行 Rust/TypeScript 编译、Cargo test/clippy 或 VM 行为测试。上述静态检查证明注释与生成说明的修改范围，不代表运行验证通过。复核记录中的既有运行时问题（对象真值读取依赖、调用图分析的算术模拟分支）留待独立行为修复与回归，不混入本次注释交付。Nexus 尚未抽取，也没有创建 Nexus 远程仓库。请用户查看后手动合并到 main；bot 不代为合并。

codex-bot added 62 commits 2026-11-15 12:08:14 +00:00

docs: explain builtin payload ownership and VM consumers a7078adc54

docs(objects): explain builtin store operations and ownership 523ab6c745

docs(objects): explain store lifecycle and payload protocols 6be33467c8

docs(objects): explain heap tracking and reference lifecycle 9861a6d586

docs(objects): explain change notifications and shared errors 717eab6d32

docs(objects): explain wordcode operations and codec boundaries b793bac407

docs(objects): explain executable layout and bytecode verification 6d8a5a8fe6

docs(objects): explain native contracts and scoped root transfers fce5ccf883

docs(objects): explain numeric representations and operation budgets c25cb6756e

docs(objects): explain snapshot call effect analysis 58ec874dc0

docs(objects): explain method substitution contracts c05d60cbc9