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 索引摘要 |
| 对象头、句柄、引用协议与 GC 算法 | [objects.md](../runtime/objects.md) | core/src 文件表 |
| Number、String、Dict、Cell、函数环境和异常数据 | [builtins.md](../runtime/builtins.md) | core/src 与 tests 文件表 |
| lexer 前的输入适配、SourceUnit 与来源诊断 | [reader.md](../runtime/reader.md) | frontend 的 reader／source、CLI 与读取检查 |
| token、PEG 规则、AST 与源码诊断 | [frontend.md](../runtime/frontend.md) | frontend 源码／测试／样例和 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 结果就写未核实，不能继承上次通过的结论。

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

## 当前实现边界

Core 保持零外部依赖、不引入 Python type／元类、源码前端或宿主库。句柄构造保持私有；非法句柄检查放堆内部单元测试，不能为测试开放非法构造器。容器更新须经过 VM 的引用事务；call／execute 对象结果持有根，借用读取仍须由使用方按需 retain。

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

独立 Frontend 已提供 lexer/parser 和 AST；后续按实际需求接入名称／闭包分析和字节码编译、扩充迭代器等指令、宿主回调、错误传播和资源边界。语法可继续调整，AST 到字节码和云服务机制尚未实现，不写成既有功能。

## 导出与迁移

旧 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) 为准。