提案：一套可复用的 API 命名规则与评审清单

[TATP-233]

目标

把 #2434 API 命名规范化过程中验证过的做法，提炼成一组不依赖本次迁移背景的通用规则，供后续新 API 设计、跨模块协议、owner YAML/文档同步和 PR 评审复用。

这不是要重新讨论 #2434 的逐项裁决；那条 roadmap 已完成并关闭。这里希望沉淀的是：当一个 API 需要命名时，我们应该如何判断名字是否表达语义、边界和生命周期。

核心规则

1. 语义优先，实现其次。 公共 API 的名字描述“它承担什么角色/完成什么动作”，不描述当前恰好用什么库、什么设备或什么数据布局实现。
2. 类型/设备限定词是例外，不是默认。 只有同一作用域内确实存在两个真实并存实现时才加限定；需要限定时统一用 _tensor，不要引入 _torch、_device_tensor、cpu_、device_ 等平行写法。
3. 模块已经表达的限定，不再复制到符号名。 类型/命名空间可以承担上下文，例如模块名表达领域或表示形式，类/函数名不重复模块名。
4. 包内私有函数不加引擎/包名前缀。 依赖关系和模块路径已经说明归属；符号名保留给语义。
5. 跨模块消费的名字不带下划线前缀。 事实公共协议要么转正为公开 API，要么在文档中明确声明为 protected protocol；不能靠下划线隐式扩大使用面。
6. 一个意义只有一个公开名字。 不保留无约束条件的别名、临时兼容层或长周期 deprecation fallback。若确有外部契约必须兼容，需要 ADR/测试背书并写清退出条件。
7. 禁止用时间描述 API。 legacy、old、new、v2、tmp 等名字表达的是仓库历史，不是调用者可依赖的语义。
8. 动词选择要有领域约定。 例如组装对象/配置用 build_*，绑定回调或 adapter 用 bind_*，解析路径/配置用 resolve_*；重置钩子优先统一到 reset(mask) 一族，仅在阶段语义确实不同时刻意保留不同名字。
9. 命名风格跟随 API 形态。 函数 term 使用 snake_case，类 term 使用 CamelCase；同一注册表中不混排。
10. 改名是一次契约变更。 公共名变更必须同步所有调用点、owner YAML/注册表、测试和文档；迁移期不靠别名维持双路径。

评审清单

• 如果去掉名字中的类型/设备/引擎词，是否仍有歧义？有歧义才考虑限定。
• 是否存在同一语义的第二个公开入口？若有，是否应该删除而不是包装？
• 是否有带下划线前缀的名字被其他模块导入/调用？
• 是否用历史状态而非行为语义命名？
• 动词是否表达了真实生命周期阶段，而不是随便选了一个“创建类”动词？
• owner YAML、registry、tests、docs 和 checkpoint/config 兼容面是否与名字一起更新？
• 若需要例外，是否已经有 ADR、测试或明确的外部契约依据？

合理例外

• 第三方库或行业标准协议要求的名字。
• 序列化格式、checkpoint 字段、配置 schema 等稳定性优先于代码可读性的契约。
• 已经有 ADR 记录并写明退出条件的兼容层。
• 两个真实实现确实并存，且限定后能显著减少调用歧义。

建议的落地方式

• 新增 API 时按上述清单自检；评审时把它当作命名契约而非风格偏好。
• 对跨模块协议、backend adapter、RL runtime、环境契约等公共面，优先在 owner 模块或协议文件中固化命名约定。
• 发现平行 API 时优先提出一次性收敛 PR，而不是继续增加包装层。
• 需要例外时先写清约束和退出条件，再引入名字。

欢迎补充你们遇到的反例，尤其是：双实现何时值得命名区分、protected protocol 的文档边界、以及跨仓/外部稳定契约下是否需要放宽“不留别名”的要求。