endorphin-aster-vm/docs/contributing/README.md

# 开发定位与文档维护

文档与代码使用同一 Git 版本，不按日期复制成多个相互竞争的说明。新增行为时更新其权威主题；删除或替换行为时直接改写／删除失效说明。文档中的当前契约须以实现为准；设计方向单独标明，历史背景需要时查 Git 历史。

## 开始修改前

从 [文档索引](../README.md) 按问题查到主题，再进入对应目录 README 找源文件。工作区边界见 [架构](../architecture/README.md)；本地禁测、远端验证与结果边界见 [验证](../operations/validation.md)。本地工作约定若有额外限制也须遵守；AGENTS.md 自身保持本地忽略，不将个人环境说明当成公开项目文档。

## 什么写到哪里

| 内容 | 唯一主要位置 | 同步入口 |
| --- | --- | --- |
| 目录职责、直接子文件／子目录、常见修改位置 | 该目录 README.md | 父目录 README |
| 各 crate 的依赖方向和系统边界 | [architecture/README](../architecture/README.md) | 根 README、docs 索引摘要 |
| 解释执行、资源修订／依赖锁、解释器升级与缓存方向 | [execution-and-versions.md](../architecture/execution-and-versions.md) | 根 README、架构、reader／frontend／bytecode、运行与交接 |
| 对象头、句柄、引用协议与 GC 算法 | [objects.md](../runtime/objects.md) | objects/src 文件表 |
| Number、String、Dict、Cell、函数环境和异常数据 | [builtins.md](../runtime/builtins.md) | objects/src、objects/tests 与 core/tests 文件表 |
| lexer 前的输入适配、SourceUnit 与来源诊断 | [reader.md](../runtime/reader.md) | frontend 的 reader／source、CLI 与读取检查 |
| Token、lexer.peg 词法／grammar.peg 语法规则、AST 与源码诊断 | [frontend.md](../runtime/frontend.md) | frontend 源码／测试／样例和 CLI |
| AST 节点／根模式、ASDL 生成、Visitor、位置与 JSON／编辑器接口 | [ast.md](../runtime/ast.md) | Endor.asdl、生成器、生成产物与 AST／CLI 检查 |
| 名称／作用域、源码编译、代码装载与执行示例 | [compiler.md](../runtime/compiler.md) | compiler 源码／检查／示例、CLI 与运行指南 |
| 指令编码、栈效果、调用协议与执行限制 | [bytecode.md](../runtime/bytecode.md) | instruction／code／frame／eval 文件职责 |
| 宿主基础信息、JSON 文件和旧库导入 | [host-information.md](../operations/host-information.md) | host、cli、server 与脚本 README |
| 地区与文本编码边界 | [text-encoding.md](../runtime/text-encoding.md) | 配置主题与实际 I/O 入口 |
| 数据库特殊类、显式连接和数据模型归属 | [database-objects.md](../runtime/database-objects.md) | storage 的源码与检查 README |
| VM／帧／对象的创建、错误退出与销毁 | [lifecycle.md](../runtime/lifecycle.md) | 对象与字节码主题链接 |
| 环境变量、默认值、优先级、UTF-8、locale 和配置边界 | [configuration.md](../operations/configuration.md) | 相关 crate README 链接 |
| 运行命令、端点和数据库连接边界 | [operations/README](../operations/README.md) | cli／server／storage README |
| 镜像、CI、部署、回退和数据目录 | [deployment.md](../operations/deployment.md) | scripts／工作流 README |
| 检查入口、覆盖范围、结果边界 | [validation.md](../operations/validation.md) | 各 tests README |
| 不可变研究表、聊天导出、临时脚本或构建产物 | 工作区外输出或忽略目录 | 不作为当前项目契约、不提交研究 HTML |

相同规则不要整段复制到多个 README。局部 README 解释本地内容并指向全局契约；全局主题用链接定位实现，不再维护第二份完整源文件表。

## 每次修改时同步

1. 新增、删除、重命名文件或目录：更新本目录和父目录 README 的文件表；新增受版本管理目录必须有 README。该规则不覆盖 .git、target、data、work、outputs 或其他忽略产物。
2. 修改 API、默认值、所有权、操作码或错误处理：同时修改上表对应主题、示例与相关检查；区分已实现行为和未来设计。
3. 改主题路径：修复仓库所有内部链接，更新 docs 总索引；失效旧页直接删除，不长久保留一份旧契约。
4. 改宿主配置／部署：同步配置表、运行命令和脚本 README；不把更换应用容器写成恢复 VM 堆或数据库回退。
5. 检查链接、目录覆盖、旧路径和差异空白；仅在指定远端运行行为测试。没有查询 CI 结果就写未核实，不能继承上次通过的结论。

不是每次提交都要给所有文档改日期或复制版本号；只有相关内容发生变化时更新相应文档。提交及代码审查描述说明目的和验证，文档保留长期可查询的当前行为。

## 当前实现边界

Objects 保持零依赖；Core 仅依赖本地 Objects，负责 VM、执行帧和求值循环。两者不引入 Python type／元类、源码前端或宿主库。句柄构造保持私有；非法句柄检查放堆内部单元测试，不能为测试开放非法构造器。容器更新须经过 ObjectStore 的引用事务，Vm 方法只委托；call／execute 对象结果持有根，借用读取仍须由使用方按需 retain。

Rust 实现依赖模块可见性、trait 和 rustfmt，不照搬 CPython C 符号命名规范。Objects 的对象定义与 ObjectStore 导出集中在 objects/src/lib.rs；Core 的 VM 导出与既有对象类型重导出集中在 core/src/lib.rs，Frontend 导出集中在 frontend/src/lib.rs，内部协作用 pub(crate) 或私有方法区分。当前基础源码解析契约在 frontend.md，尚无完整 Endor 源码风格规范或通用配置框架。

Endor 是由平台解释执行的语言，字节码生成是内部准备步骤。资源版本属于平台元数据，具体 URI 与持久化协议尚未定稿，不提前写进业务语法；首版暂不要求持久化字节码缓存，详见 [执行与版本模型](../architecture/execution-and-versions.md)。

AST 节点以 frontend/Endor.asdl 为唯一来源，Rust 类型／遍历器和 TypeScript／JSON Schema 为提交到 Git 的生成产物，不直接编辑；通过 scripts/generate_ast.py --write 更新，--check 做静态同步检查。生成器行为测试仅在指定远端执行。

独立 Frontend 提供阅读器、lexer/parser 和 ASDL AST；Compiler 已完成模块／函数名称分析、局部槽布局、最小字节码生成及代码装载。源码闭包、数值算术、迭代器等指令、类型检查与云服务机制仍待实现；语法可继续调整，范围见 [编译契约](../runtime/compiler.md)。

## 导出与迁移

旧 outputs 正文已融合入 runtime，输出目录已移除。以后只维护仓库正文，不保留同文入口文件；CPython 284 项研究 HTML／Markdown 和早期报告位于本地忽略的 work/research，不上传 Git。交接入口见 [handoff.md](handoff.md)。

旧平铺路径 docs/architecture.md、development.md、endor-object.md、endor-builtins.md、bytecode-vm.md、validation.md 已由新的多层主题替代；当前入口以 [文档索引](../README.md) 为准。