endorphin-aster-vm/README.md

# Endor / Aster VM

Rust 编写的 Endor 虚拟机实现。当前具备 EndorObject、稳定对象分配、代际句柄、引用计数、显式循环回收，以及可执行语言函数的小型 wordcode VM。数字统一为无损表示优先的 Number。

独立 frontend 已提供 Endor 阅读器、手写 lexer、peg parser、基础函数／表达式 AST 与 cli parse 文件／stdin 入口。VM 从空堆启动；尚无 AST 到字节码编译器、Python type／元类体系、数值算术或完整异常传播。数据库连接仅为需要数据库的特殊类保留；普通宿主不连接数据库；基础信息改用 host 包的 UTF-8 JSON 文件，不保存 VM 堆。当前边界见 [系统架构](docs/architecture/README.md)。

## 从哪里读

| 要做的事 | 入口 |
| --- | --- |
| 查一个功能、设计或代码位置 | [文档总索引](docs/README.md) |
| 看源码目录与 crate 边界 | [crates](crates/README.md) |
| 看字符串、流、文件与平台 URI 如何进入 lexer | [Endor 阅读器](docs/runtime/reader.md) |
| 看源码词法、语法、AST 和解析命令 | [源码前端](docs/runtime/frontend.md) |
| 看指令、代码对象、执行帧和执行循环 | [字节码 VM](docs/runtime/bytecode.md) |
| 看 VM／帧／对象如何存活和销毁 | [生命周期](docs/runtime/lifecycle.md) |
| 看基础信息文件和旧库迁移 | [宿主信息](docs/operations/host-information.md) |
| 看配置、UTF-8 与 locale 边界 | [配置](docs/operations/configuration.md) |
| 运行 CLI／HTTP 宿主 | [运行指南](docs/operations/README.md) |
| 看 ces-control CI 与 PostgreSQL 部署 | [部署](docs/operations/deployment.md) |
| 修改代码并同步文档 | [开发与文档维护](docs/contributing/README.md) |

## 根目录内容

| 文件或目录 | 职责 |
| --- | --- |
| Cargo.toml / Cargo.lock | 工作区、包依赖、Rust 版本要求及依赖锁定；包名与目录一致：core、frontend、storage、host、cli、server |
| crates/ | core、frontend、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／部署结果。命令和使用条件见 [验证](docs/operations/validation.md)。

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