# 模块 5：共享资产的版本与兼容性

<div class="mt-6 text-sm">

Rule、任务上下文契约、Skill、自定义 Agent 和 MCP 契约一旦被共享使用，就会影响后续任务的判断与行为。

共享资产治理要明确资产变更后的可用范围、引用迁移与旧版本退出方式。

</div>

<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">版本</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">兼容</div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">迁移</div>
<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">回退</div>
</div>

<!--
逐字稿：第五天处理的是资产如何设计以及如何验证自身边界。第六天关心的是资产已经被共享使用后，发生变化时如何识别影响、处理引用、完成迁移和保留回退能力。它们的差别不在资产类型，而在验证对象和协作场景。

第五天已经解决“资产怎么写、怎么验证边界”。本模块只讨论资产进入共享使用后，内容变化如何作为工程改动被控制。
-->

---

# 哪些资产变更属于行为变更？

<div class="mt-5 text-xs">

| 资产 | 变更示例 | 可能改变的行为 |
|---|---|---|
| Rule | 增加必须检查的前置条件 | Agent 的允许范围和停止条件 |
| 任务上下文契约 | 删除一个必填输入字段 | 输出是否仍有足够事实基础 |
| Skill | 调整步骤或输出 Schema | 下游任务能否继续消费结果 |
| 自定义 Agent | 增加工具或修改默认指令 | 可访问的能力和风险边界 |
| MCP 契约 | 更改读写标识或错误语义 | 调用权限与失败后的处置 |

</div>

<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
只要会改变 Agent 的输入、判断、输出或权限，就不应把它当成普通文案修改。
</div>

<!--
逐字稿：判断资产改动是否需要认真控制，不看它是 Markdown 还是配置文件，而看它会不会改变任务行为。只要改动影响输入、判断顺序、输出结构、权限或停止条件，就属于行为变更。即使只删除一条输入要求，也可能让模型在事实不足时继续输出结论。

判断是否需要版本控制，不看文件格式，而看它是否改变运行时行为。即使只改一行任务上下文契约，也可能删除了关键证据约束。
-->

---

# 版本号应表达使用边界

<div class="mt-5 text-xs">

| 变更类型 | 使用建议 | 对既有调用方的要求 |
|---|---|---|
| 仅修正文案，不改变输入输出或约束 | 小版本 | 保持原有验证夹具通过 |
| 增加可选字段或补充反例 | 小版本，并说明新增行为 | 检查是否需要提供新材料 |
| 修改必填输入、输出结构、权限或停止条件 | 新版本边界 | 明确迁移方式和不兼容点 |
| 移除能力或结束支持 | 弃用版本 | 保留替代资产和退出期限 |

</div>

<!--
逐字稿：版本号的作用不是追求某种命名形式，而是帮助使用者判断能否直接替换。只改表达且不改变约束，可以在小版本内验证；一旦修改必填输入、输出结构、权限或停止条件，就必须明确新的使用边界和迁移方式。使用者最需要知道的是这次升级会不会破坏已有任务。

版本号的意义是帮助使用者判断能否直接替换。重点不是采用某一套固定命名规则，而是让不兼容变化有明确边界。
-->

---

# 兼容性说明的最小字段

<div class="mt-5 text-xs">

| 字段 | 要回答的问题 |
|---|---|
| 资产与版本 | 当前使用的是哪一份可识别资产？ |
| 适用范围 | 面向哪些项目、任务或技术栈？ |
| 行为变化 | 输入、输出、约束、工具权限中变了什么？ |
| 不兼容点 | 哪些旧引用、模板或 Agent 不能直接继续使用？ |
| 迁移方式 | 使用者需要替换什么、补充什么或调整什么？ |
| 回退条件 | 遇到何种结果时应回到哪个稳定版本？ |
| 验证证据 | 哪些夹具、测试或实际记录支持本次变化？ |

</div>

<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
兼容性说明服务于正确替换，不是为了增加文档数量。
</div>

<!--
逐字稿：每份共享资产都应附带最小兼容性说明。它要回答当前版本和适用范围是什么，行为变了什么，哪些旧引用不能继续使用，怎样迁移，以及异常时回退到哪里。没有这些信息，使用者无法判断升级风险，只能靠试错。

如果资产没有说明不兼容点和迁移方法，使用者无法安全升级。说明应与资产本身一起被审查和版本化。
-->

---

# 弃用不是删除旧文件

<div class="mt-5 text-xs">

| 需要保留的信息 | 目的 |
|---|---|
| 被替代的版本与适用范围 | 识别历史引用，不误用旧能力 |
| 替代资产及目标版本 | 提供明确迁移方向 |
| 不再适用的原因 | 防止未来又恢复同一错误做法 |
| 已知引用位置 | 便于逐项替换与复核 |
| 回退条件与稳定版本 | 变更异常时能够恢复已验证行为 |

</div>

<div class="mt-6 grid grid-cols-2 gap-3 text-sm">
<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">直接删除：历史引用失去解释</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">明确弃用：新旧边界仍可追溯</div>
</div>

<!--
逐字稿：弃用不是简单删除旧文件，而是停止把旧版本作为默认选择。旧版本的适用范围、替代资产、已知引用位置和稳定回退点仍要保留，才能解释历史任务并指导迁移。对于有引用关系的 Skill、Agent 和 MCP 契约，这些信息尤为关键。

弃用的重点是停止默认使用，而不是抹去历史。对于存在引用关系的 Skill、Agent 和 MCP 契约，替换目标和回退点尤其重要。
-->

---

# 版本发布前需要确认什么？

<div class="mt-5 text-xs">

| 确认项 | 要回答的问题 | 形成的版本结论 |
|---|---|---|
| 当前稳定版本 | 哪个版本仍可作为已知可用的回退点？ | 明确 source version |
| 目标版本边界 | 新版本改变了哪些使用前提与适用范围？ | 明确 target version |
| 使用者与引用 | 哪些 Rule、Skill、Agent、MCP 或模板仍依赖旧版本？ | 明确迁移清单 |
| 退出与回退 | 旧版本何时停止默认使用，异常时回到哪里？ | 明确弃用与恢复路径 |

</div>

<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
模块 5 解决“发布哪个版本、谁需要迁移、出现异常退回哪里”；单次资产 diff 的验证证据由模块 8 处理。
</div>

<!--
逐字稿：共享资产的版本治理，重点是版本选择和使用者迁移。发布前先识别当前稳定版本、目标版本的新边界、仍在引用旧版本的使用者，以及弃用和回退方式。这样可以决定谁能直接替换、谁必须迁移、异常时回到哪个稳定点。

这里不展开一条资产改动要怎样跑夹具或审查 diff。那是模块 8 的工作：它验证本次变化本身是否有充分的工程证据。两者的边界应当分清。
-->