Endor / Aster VM

Rust 编写的 Endor 虚拟机实现。核心对象与对象存储位于独立 objects 包，core 专注 VM、执行帧与求值循环。当前具备 EndorObject、稳定对象分配、代际句柄、引用计数、显式循环回收，以及可执行语言函数的小型 wordcode VM。数字统一为无损表示优先的 Number。

Endor 采用平台解释执行模型；AST 到字节码的生成属于解释器内部准备步骤，使用者无需先构建独立程序。资源修订与依赖锁用于选择用户代码，解释器由平台统一升级；相关设计方向见 解释执行与平台资源版本，资源版本管理尚未实现。

独立 frontend 提供阅读器、字符 PEG lexer、token PEG parser、ASDL 生成的 AST 与编辑器接口。compiler 已连接名称／作用域分析、字节码生成和代码对象装载，CLI run／eval 可执行基础函数与表达式；可执行示例见 compiler/examples。VM 从空堆启动；Python type／元类体系、数值算术、源码闭包和完整异常传播尚未实现。数据库连接仅为需要数据库的特殊类保留；普通宿主不连接数据库；基础信息改用 host 包的 UTF-8 JSON 文件，不保存 VM 堆。当前边界见 系统架构。

从哪里读

要做的事	入口
查一个功能、设计或代码位置	文档总索引
看解释执行、资源修订、依赖锁和平台升级的关系	执行与版本模型
看核心对象与对象存储	objects
看源码目录与 crate 边界	crates
看字符串、流、文件与平台 URI 如何进入 lexer	Endor 阅读器
看 AST 根节点、ASDL、遍历与 JSON／编辑器接口	AST 模型
看源码词法、语法、AST 和解析命令	源码前端
看名称／作用域分析、源码编译与执行示例	编译链路
看指令、代码对象、执行帧和执行循环	字节码 VM
看 VM／帧／对象如何存活和销毁	生命周期
看基础信息文件和旧库迁移	宿主信息
看配置、UTF-8 与 locale 边界	配置
运行 CLI／HTTP 宿主	运行指南
看 ces-control CI 与 PostgreSQL 部署	部署
修改代码并同步文档	开发与文档维护

根目录内容

文件或目录	职责
Cargo.toml / Cargo.lock	工作区、包依赖、Rust 版本要求及依赖锁定；包名与目录一致：core、objects、frontend、compiler、storage、host、cli、server
crates/	core、objects、frontend、compiler、storage、host、cli、server 八个包，每个目录的 README 解释本目录
docs/	跨目录的架构、运行时契约、配置、运行、部署与维护说明
scripts/	指定远端环境中的检查、冒烟、CI 与部署脚本
.gitea/	Gitea Actions 工作流
Dockerfile	source、ci、build、runtime 多阶段镜像
docker-compose.yml	VM 宿主运行方案，保留原有数据卷
docker-compose.postgres.yml	VM 宿主与预置 PostgreSQL
docker-compose.ces-control.yml	ces-control 宿主与 PostgreSQL 资源部署
.env.example / .gitignore / .dockerignore	配置样例、Git 与 Docker 上下文排除规则
LICENSE	MIT 许可

本地不编译、不测试、不下载依赖；可做文档和静态文件检查。运行验证交给 ces-control；按用户约定不主动跟踪 CI／部署结果。命令和使用条件见 验证。

文档随代码版本更新：就地解释放各目录 README，跨目录契约放 docs，对外阅读副本以仓库文档为准。忽略的 work、target、data 和 Git 内部目录不属于需要维护 README 的源码目录。