扩展成熟度
每个 x/* 包都在 module.yaml 中声明其成熟度。本页说明这些声明对于决定是否依赖某个扩展的团队意味着什么。
要读的两个字段
Section titled “要读的两个字段”打开任意 x/*/module.yaml，查找以下两个字段：
status: experimental # 模块级成熟度stability_tiers: # 可选的子包细分 stable: - provider - session experimental: - orchestration - semanticcache大多数扩展只有 status: experimental，没有 stability_tiers 块。少数（如 x/ai）发布了更细粒度的分类，因为其子包的成熟速度不同。
各状态的含义
Section titled “各状态的含义”| 状态 | 语义版本保证 | API 变更策略 | 生产建议 |
|---|---|---|---|
| beta | API 在 minor release refs 之间冻结 | 破坏性变更需要主版本号升级；删除前提供弃用通知 | 可在生产中使用并锁定 minor 版本；升级前审查 changelog |
| beta surface | 仅覆盖指定子包 | 与 beta 相同；父 family 仍可能是 experimental | 依赖具体子包；用应用本地 adapter 隔离，并检查 module.yaml |
| experimental | 尚未覆盖 | API 可能在没有弃用期的情况下更改 | 按用例评估；锁定精确版本并在升级时审查 changelog |
当前 beta 家族
Section titled “当前 beta 家族”以下扩展 family 处于 beta 状态。它们的 API 在 minor release refs 之间冻结，并由连续两个 release refs、导出的 API snapshot 和 owner sign-off 支撑。
| Family | 晋升版本 | 证据 |
|---|---|---|
x/gateway | v0.2.0 | beta 证据 |
x/observability | v0.2.0 | beta 证据 |
x/rest | v0.2.0 | beta 证据 |
x/websocket | v0.2.0 | beta 证据 |
x/tenant | v1.1.0 | beta 证据 |
x/frontend | v1.1.0 | beta 证据 |
x/messaging | v1.1.0（app-facing service） | beta 证据 |
已选 beta surface
Section titled “已选 beta surface”有些 family 的根层级仍是 experimental，但其中的特定子包已经积累了自己的 release 证据并完成 beta sign-off。父 family 的形态仍可能变化，但命名子包的 surface 是稳定的。
| Surface | 父 family | 晋升版本 | 覆盖范围 |
|---|---|---|---|
x/ai/provider | x/ai（experimental） | v1.1.0 | Provider 接口和具体构造函数 |
x/ai/session | x/ai（experimental） | v1.1.0 | Session 生命周期和状态管理 |
x/ai/streaming | x/ai（experimental） | v1.1.0 | Streaming response 协调 |
x/ai/tool | x/ai（experimental） | v1.1.0 | Tool 注册和调用 |
x/data/file | x/data（experimental） | v1.1.0 | 文件 helper 和元数据契约 |
x/data/idempotency | x/data（experimental） | v1.1.0 | Idempotency key store 契约 |
依赖这些 surface 前，请检查 module.yaml 的 stability_tiers。列在 stable: 下的子包已覆盖；列在 experimental: 下或未列出的子包尚未覆盖。
依赖前如何检查
Section titled “依赖前如何检查”grep -E "^status:|stability_tiers:" x/<module>/module.yaml对于有子包细分的 x/ai：
cat x/ai/module.yaml | grep -A 12 "stability_tiers:"Experimental 在实践中意味着什么
Section titled “Experimental 在实践中意味着什么”Experimental 状态意味着：
- 构造函数签名、接口方法或配置字段名称可能在 minor 版本之间更改。
- 子包可能在达到 stable 层级之前被拆分、合并或移除。
- 团队正在生产服务中积极使用它，因此回归会被快速发现 — 但 API 形态仍在完善中。
Experimental 不意味着：
- 代码未经测试或存在问题
- 在生产中运行不安全
- 即将被移除
子包从 experimental 晋升到 stable 的条件：
- 公共 API 已在多个服务中使用，无需破坏性变更。
- 接口契约已记录在
module.yaml中。 - 经评审确认当前路线图中没有计划中的破坏性变更。
在晋升之前，将 module.yaml 视为权威记录。如果 module.yaml 在 stable: 下列出某子包，你可以像对待稳定根一样依赖其 API。如果它不在 stability_tiers 中或列在 experimental: 下，请锁定版本并在升级时审查。
稳定根有所不同
Section titled “稳定根有所不同”九个稳定根包 — core、router、contract、middleware、security、store、health、log、metrics — 在模块层面受语义版本覆盖。它们没有 x/* 依赖，其 API 在主版本号升级之前不会更改。可以自由使用，无需锁定 patch 版本。