09 · Versioning & Release (Core + Apps + Schemas + Prompts) (v0.5)
v0.4 已定义 Core/App 的 SemVer 与 requiredCoreVersion，并增加 Event Envelope、Schema、RulePack 的版本化。
v0.5 在此基础上，增加 Prompt Template 的版本化。
1. Core 版本（SemVer）
v0.4 已定义，v0.5 保持不变。
- MAJOR：破坏性变更（包括 EventEnvelope 字段语义变更、API 破坏）
- MINOR：新增能力（新增字段保持兼容；新增 action/rule 能力）
- PATCH：修 bug
v0.5 版本：0.5.0
2. Event Envelope 版本（强制，v0.4 已有）
v0.4 已定义，v0.5 保持不变。
EventEnvelopeV1作为协议版本- 若将来需要破坏性变更：引入
EventEnvelopeV2 - Ingest API 必须声明支持的 envelope 版本（Header 或字段）
3. Event Schema 版本（强制，v0.4 已有）
v0.4 已定义，v0.5 保持不变。
- schemaRef 使用 SemVer（例如 @1.0.0）
- 兼容规则：
- PATCH/MINOR：只能"向后兼容"（新增可选字段、放宽约束）
- MAJOR：破坏性变更（字段改名/类型变化/必填变化）
4. RulePack 版本（建议，v0.4 已有）
v0.4 已定义，v0.5 保持不变。
- RulePack 自身也用 SemVer
- RulePack 内部引用 schemaRef 的具体版本（避免运行时歧义）
- App 升级时：
- 允许覆盖同 id 的 RulePack（需要 audit 记录：rulepack_upgraded）
5. Prompt Template 版本（v0.5 新增）
5.1 Prompt ID 格式
- 格式：
<appId>.<name>@<version> - 示例：
project-mngt.task_decomposition@1.0.0 - 版本建议：SemVer（例如 1.0.0）
5.2 版本兼容规则
- PATCH/MINOR：只能"向后兼容"
- 新增可选变量
- 放宽 output_schema 约束（例如允许更多类型）
- 更新模板内容（但不改变输出结构）
- MAJOR：破坏性变更
- 删除变量
- 改变 output_schema 结构
- 改变变量语义
5.3 PromptPack 版本
- PromptPack 自身也用 SemVer
- PromptPack 内部引用 Prompt 模板的具体版本（避免运行时歧义）
- App 升级时：
- 允许覆盖同 id 的 PromptPack（需要 audit 记录：promptpack_upgraded）
6. App 版本与兼容（v0.4 已有，v0.5 更新）
v0.4 已定义，v0.5 更新 requiredCoreVersion。
- App 必须声明
requiredCoreVersion - v0.5 App 应设置为
">=0.5.0,<0.6.0" - App 安装器在 install/upgrade 时校验：
- Core 版本是否满足
- schema/rulepack/promptpack/sourceTemplates 是否符合 Core 的 contract
7. 契约测试（CI 必做，v0.4 已有，v0.5 扩展）
7.1 Core CI（v0.4 已有，v0.5 扩展）
- 安装一组示范 App：
- project-mngt（传统实体事件 + AI 功能）
- os-assistant（外部事件 + rulepack + AI 功能）
- 跑 e2e：
- ingest → rule → alert → AI action → audit
- 测试两个最小闭环（Alert → AI Summary、Meeting → AI Minutes → Draft）
7.2 App CI（v0.4 已有，v0.5 扩展）
- 校验 app.yaml
- 校验 schemas 是合法 JSON Schema 且 $id/schemaRef 符合命名空间
- 校验 RulePack 引用的 eventType/schemaRef 存在
- v0.5 新增：校验 PromptPack 格式正确
- v0.5 新增：校验 Prompt 模板的 output_schema 是合法 JSON Schema
8. 版本升级策略（v0.5 新增）
8.1 Prompt 模板升级
场景 1：App 升级 PromptPack
- 如果版本号相同，跳过（不覆盖）
- 如果版本号更高，更新
- 如果版本号更低，跳过（不降级）
场景 2：手动更新 Prompt 模板
- 通过 API 更新 Prompt 模板
- 必须提供新版本号
- 旧版本标记为 deprecated，但保留（用于审计追溯）
8.2 AI Actions 版本兼容
规则中的 Prompt 引用：
- 规则可以使用
prompt_template: "project-mngt.task_decomposition@1.0.0"（固定版本） - 或使用
prompt_template: "project-mngt.task_decomposition@latest"（使用最新版本，不推荐）
推荐做法：
- 规则中固定 Prompt 版本，确保行为可预测
- Prompt 升级时，需要更新 RulePack 版本
文档版本: v1.0
最后更新: 2025-12-17