codex-bot
483d9d1717
5.6 KiB
开发定位与文档维护
文档与代码使用同一 Git 版本，不按日期复制成多个相互竞争的说明。新增行为时更新其权威主题；删除或替换行为时直接改写／删除失效说明。当前文档只描述当前契约，历史背景需要时查 Git 历史。
开始修改前
从 文档索引 按问题查到主题，再进入对应目录 README 找源文件。工作区边界见 架构；本地禁测、远端验证与结果边界见 验证。本地工作约定若有额外限制也须遵守；AGENTS.md 自身保持本地忽略，不将个人环境说明当成公开项目文档。
什么写到哪里
| 内容 | 唯一主要位置 | 同步入口 |
|---|---|---|
| 目录职责、直接子文件／子目录、常见修改位置 | 该目录 README.md | 父目录 README |
| 各 crate 的依赖方向和系统边界 | architecture/README | 根 README、docs 索引摘要 |
| 对象头、句柄、引用协议与 GC 算法 | objects.md | core/src 文件表 |
| Number、String、Dict、Cell、函数环境和异常数据 | builtins.md | core/src 与 tests 文件表 |
| lexer 前的输入适配、SourceUnit 与来源诊断 | reader.md | frontend 的 reader／source、CLI 与读取检查 |
| token、PEG 规则、AST 与源码诊断 | frontend.md | frontend 源码／测试／样例和 CLI |
| 指令编码、栈效果、调用协议与执行限制 | bytecode.md | instruction／code／frame／eval 文件职责 |
| 宿主基础信息、JSON 文件和旧库导入 | host-information.md | host、cli、server 与脚本 README |
| 地区与文本编码边界 | text-encoding.md | 配置主题与实际 I/O 入口 |
| 数据库特殊类、显式连接和数据模型归属 | database-objects.md | storage 的源码与检查 README |
| VM／帧／对象的创建、错误退出与销毁 | lifecycle.md | 对象与字节码主题链接 |
| 环境变量、默认值、优先级、UTF-8、locale 和配置边界 | configuration.md | 相关 crate README 链接 |
| 运行命令、端点和数据库连接边界 | operations/README | cli／server／storage README |
| 镜像、CI、部署、回退和数据目录 | deployment.md | scripts／工作流 README |
| 检查入口、覆盖范围、结果边界 | validation.md | 各 tests README |
| 不可变研究表、聊天导出、临时脚本或构建产物 | 工作区外输出或忽略目录 | 不作为当前项目契约、不提交研究 HTML |
相同规则不要整段复制到多个 README。局部 README 解释本地内容并指向全局契约；全局主题用链接定位实现，不再维护第二份完整源文件表。
每次修改时同步
- 新增、删除、重命名文件或目录：更新本目录和父目录 README 的文件表；新增受版本管理目录必须有 README。该规则不覆盖 .git、target、data、work、outputs 或其他忽略产物。
- 修改 API、默认值、所有权、操作码或错误处理：同时修改上表对应主题、示例与相关检查；区分已实现行为和未来设计。
- 改主题路径：修复仓库所有内部链接，更新 docs 总索引；失效旧页直接删除，不长久保留一份旧契约。
- 改宿主配置／部署：同步配置表、运行命令和脚本 README；不把更换应用容器写成恢复 VM 堆或数据库回退。
- 检查链接、目录覆盖、旧路径和差异空白；仅在指定远端运行行为测试。没有查询 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。
旧平铺路径 docs/architecture.md、development.md、endor-object.md、endor-builtins.md、bytecode-vm.md、validation.md 已由新的多层主题替代；当前入口以 文档索引 为准。