公开 API 稳定性¶
WorldForge 仍处于 1.0 之前的阶段，但已有若干表面足够公开，需要明确的变更策略。本策略设定了代码审查预期；这并非 1.0 的兼容性承诺。
API 层级¶
| 层级 | 示例 | 变更策略 |
|---|---|---|
| 稳定 | WorldForge、World、worldforge.models 中的领域模型、能力协议、WorldForgeError、WorldStateError、ProviderError、生成的提供方文档、已记录的 CLI 命令 |
在可行时保持源码兼容性。破坏性变更需要变更日志条目、迁移说明，以及至少一个发布周期的弃用通知，除非安全或正确性问题需要立即中断。 |
| 临时 | 评估报告模式、基准测试输入和预算模式、运行工作区清单、证据包、提供方工作台报告、可选宿主脚本 | 模式变更需要版本号递增或明确的迁移说明。在不保留无效状态的前提下，尽量保持旧字段可读。 |
| 实验性 | jepa-wms 直接构造候选、脚手架提供方预留、可选机器人封装器、已准备宿主实时冒烟测试、Rerun 可视化工件 |
变更可能更频繁，但文档必须如实说明能力和运行时所有权。实验性状态不允许密钥泄露或静默强制转换。 |
| 内部 | 私有辅助函数、生成的实现细节、仅供测试的夹具、未导出的解析器辅助函数、机器人案例展示 TUI 内部实现 | 可在不弃用的情况下变更。请勿在下游代码中导入这些符号。 |
稳定表面快照¶
当前稳定 Python 符号的权威列表位于
tests/fixtures/public_api/exports.json。
它记录了 worldforge、worldforge.testing、worldforge.observability、
worldforge.providers 和 worldforge.capabilities 的
__all__（或非下划线 dir()）的并集。
tests/test_public_api_snapshot.py 测试在上述任何模块偏离快照时——包括静默重命名或删除——会立即失败报警。
在同一提交中重新生成快照（与有意的表面变更同步）：
uv run python scripts/update_public_api_snapshot.py
# 或
WORLDFORGE_UPDATE_PUBLIC_API_SNAPSHOT=1 uv run pytest tests/test_public_api_snapshot.py
然后更新变更日志条目，并在添加、重命名或删除稳定符号时修订本页，确保稳定层描述保持准确。
弃用规则¶
当变更影响以下内容时，必须进行弃用处理：稳定的公开导入、构造函数参数、模型字段、异常族、CLI 命令或标志、提供方能力、提供方配置字段、工件模式或已记录的文件布局。在审查备注中，请将其明确标注为工件模式迁移。
每个弃用计划应包含：
- 旧表面和替换表面；
- 警告或文档通知首次出现的发布版本；
- 可能发生移除的最早发布版本；
- 在过渡期间证明新旧路径均可用的验证命令；
- 描述用户操作的变更日志条目。
仅在以下情况下允许立即移除：安全漏洞、持久化状态不一致、虚假的提供方能力声明，或无法在不损坏用户工件的情况下维护的行为。在此情况下，PR 必须说明原因、失败模式以及迁移命令或手动恢复步骤。
提供方与工件迁移¶
提供方变更必须保持如实的能力公告。移除或重命名能力、更改提供方配置状态或更改运行时所有权，需要在提供方页面和变更日志中添加迁移说明。脚手架适配器不得仅凭措辞晋级；晋级需要解析器测试、契约测试、运行时证据和文档更新。
工件模式在离开单个进程时必须保持 JSON 原生且带版本号。工件模式 所有权映射列出了当前公开和半公开的工件族、版本字段、所有者、验证表面及迁移规则。读取方应以明确错误拒绝格式异常或不支持的模式版本，而非静默强制转换无效状态。
变更日志预期¶
以下情况需要在变更日志中记录：
- 破坏性 API、CLI、提供方或工件模式变更；
- 新弃用及移除日期；
- 迁移命令或手动恢复步骤；
- 变更的验证门控；
- 变更的可选运行时要求。
细微的拼写修正和仅涉及内部的重构无需变更日志条目，除非它们影响公开文档、生成的工件或用户可见的命令。
贡献者检查清单¶
在合并公开 API 变更之前，请在 PR 中回答以下问题：
- 被触及的表面是稳定、临时、实验性还是内部的？
- 该变更是否需要弃用通知或模式版本号递增？
- 文档和变更日志是否解释了迁移方式？
- 在适用时，测试是否同时覆盖了旧的兼容路径和新行为？
- 提供方能力公告是否仍然如实？
- 格式异常的持久化/提供方状态是否被明确拒绝？