smart
67837df8d0
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
7.2 KiB
7.2 KiB
模块 5：共享资产的版本与兼容性
Rule、任务上下文契约、Skill、自定义 Agent 和 MCP 契约一旦被共享使用，就会影响后续任务的判断与行为。
共享资产治理要明确资产变更后的可用范围、引用迁移与旧版本退出方式。
版本
兼容
迁移
回退
哪些资产变更属于行为变更？
| 资产 | 变更示例 | 可能改变的行为 |
|---|---|---|
| Rule | 增加必须检查的前置条件 | Agent 的允许范围和停止条件 |
| 任务上下文契约 | 删除一个必填输入字段 | 输出是否仍有足够事实基础 |
| Skill | 调整步骤或输出 Schema | 下游任务能否继续消费结果 |
| 自定义 Agent | 增加工具或修改默认指令 | 可访问的能力和风险边界 |
| MCP 契约 | 更改读写标识或错误语义 | 调用权限与失败后的处置 |
只要会改变 Agent 的输入、判断、输出或权限，就不应把它当成普通文案修改。
版本号应表达使用边界
| 变更类型 | 使用建议 | 对既有调用方的要求 |
|---|---|---|
| 仅修正文案，不改变输入输出或约束 | 小版本 | 保持原有验证夹具通过 |
| 增加可选字段或补充反例 | 小版本，并说明新增行为 | 检查是否需要提供新材料 |
| 修改必填输入、输出结构、权限或停止条件 | 新版本边界 | 明确迁移方式和不兼容点 |
| 移除能力或结束支持 | 弃用版本 | 保留替代资产和退出期限 |
兼容性说明的最小字段
| 字段 | 要回答的问题 |
|---|---|
| 资产与版本 | 当前使用的是哪一份可识别资产？ |
| 适用范围 | 面向哪些项目、任务或技术栈？ |
| 行为变化 | 输入、输出、约束、工具权限中变了什么？ |
| 不兼容点 | 哪些旧引用、模板或 Agent 不能直接继续使用？ |
| 迁移方式 | 使用者需要替换什么、补充什么或调整什么？ |
| 回退条件 | 遇到何种结果时应回到哪个稳定版本？ |
| 验证证据 | 哪些夹具、测试或实际记录支持本次变化？ |
兼容性说明服务于正确替换，不是为了增加文档数量。
弃用不是删除旧文件
| 需要保留的信息 | 目的 |
|---|---|
| 被替代的版本与适用范围 | 识别历史引用，不误用旧能力 |
| 替代资产及目标版本 | 提供明确迁移方向 |
| 不再适用的原因 | 防止未来又恢复同一错误做法 |
| 已知引用位置 | 便于逐项替换与复核 |
| 回退条件与稳定版本 | 变更异常时能够恢复已验证行为 |
直接删除：历史引用失去解释
明确弃用：新旧边界仍可追溯
版本发布前需要确认什么？
| 确认项 | 要回答的问题 | 形成的版本结论 |
|---|---|---|
| 当前稳定版本 | 哪个版本仍可作为已知可用的回退点？ | 明确 source version |
| 目标版本边界 | 新版本改变了哪些使用前提与适用范围？ | 明确 target version |
| 使用者与引用 | 哪些 Rule、Skill、Agent、MCP 或模板仍依赖旧版本？ | 明确迁移清单 |
| 退出与回退 | 旧版本何时停止默认使用，异常时回到哪里？ | 明确弃用与恢复路径 |
模块 5 解决“发布哪个版本、谁需要迁移、出现异常退回哪里”；单次资产 diff 的验证证据由模块 8 处理。