用途:为 Agent Framework Python 代码库提供包与功能生命周期规范,区分包级生命周期(整个包的成熟度)与功能级生命周期(包内具体 API 或功能的成熟度)。包阶段是包内所有内容的默认值,功能阶段装饰器仅用于功能落后于包默认阶段的例外情况,不要因为包处于实验或候选发布阶段就给每个类或函数加装饰器。
四个阶段:实验(不稳定,可能变更或移除,使用 @experimental(feature_id=ExperimentalFeature.X),会向 docstring 添加警告块、记录元数据并在首次使用时发出运行时警告);候选发布(接近稳定,使用 @release_candidate(feature_id=ReleaseCandidateFeature.X),添加说明但不发实验警告);已发布(稳定 GA,不加功能阶段装饰器,也不在枚举中登记);弃用(仍存在但不建议新代码使用,使用 @deprecated("..."),并说明替代方案,不再叠加功能阶段装饰器)。
功能枚举:ExperimentalFeature 与 ReleaseCandidateFeature 是当前阶段功能的清单,每个概念功能用一个全大写成员,相关 API 复用同一 ID,功能离开该阶段时移除成员;这些枚举不是稳定的消费者内省 API。消费者应将 feature_stage 与 feature_id 视为可选元数据,用 getattr 读取,缺失即表示无显式标注;警告过滤匹配字面 feature ID 字符串。
阶段迁移:实验到候选发布需移动枚举成员并替换装饰器;实验或候选发布到已发布需移除装饰器与枚举成员,不加替代装饰器;任意阶段到弃用需移除阶段装饰器与枚举成员,改用 @deprecated。功能不必经过每个阶段,可按实际就绪度提升,包升级时不要自动提升所有功能。
限制:资料未提供具体安装命令、版本号或平台信息。