doca-upgrade

DOCA 升级

示例

• “我应该升级到下一个 DOCA 版本吗？” — 检测已安装的版本，报告差距，然后停止并询问。绝不自动升级。
• “apt upgrade 让我的 DOCA 软件包版本发生了偏移。” — 这是恢复操作，不是静默修复。检测、报告、询问，然后提供指导。

快速答复（根据此文件作答）

• 不更改版本（当前固定安装版本出现运行时错误）？此技能不适用：指出 doca-debug 并停止。

这里的两条答复已完整；只有在用户确认后，才打开 TASKS.md 获取升级指导。仅自行运行只读检测命令。软件包命令（sudo dpkg、apt、apt-get）需要 root 权限且会更改系统：提供给用户运行，然后停止；在 Agent shell 中，sudo 会等待密码输入，导致会话停滞。

• “我可以直接运行 apt upgrade 升级到下一个 DOCA 版本吗？” 绝不自动升级。使用 doca-version 的四来源链检测已安装版本（pkg-config --modversion doca-common、cat /opt/mellanox/doca/applications/VERSION、doca_caps --version，以及 BlueField 上的 BFB 版本），报告与目标版本的差距，然后停止并询问是否获得明确确认。BFB、固件或重启步骤遵循 doca-hardware-safety。
• “升级中途终止了，dpkg 报告事务中断。” 先恢复软件包数据库： 用户明确确认后（两条命令都会更改系统软件包状态），由用户运行 sudo dpkg --configure -a，然后运行 sudo apt-get -f install（Debian/Ubuntu）。不要首先重新运行升级；在决定下一步之前，使用 doca-version 重新检测版本。

说明

遵循下方的加载顺序。打开任务配套文件，完成检测 → 报告 → 询问 → 指导升级。打开功能配套文件，了解升级模式分类和拒绝自动升级规则。不要打开所有配套文件。

从何处开始： 此技能是整个软件包中关于 DOCA 升级或降级流程规范的唯一事实来源。用户想要执行升级相关操作时（检测差距、请求确认、逐步指导升级、验证升级，或诊断失败），打开任务配套文件；用户想了解升级具体包含什么时（主机 apt-upgrade 与 BFB 重刷、容器标签更新、降级／回滚模式之间的区别、绝不自动升级规则、确认关卡、版本弃用意识、错误分类以及升级专属安全补充要求），打开功能配套文件。

如何使用此技能。 阅读此文件，然后在配套文件中搜索问题所需的 ## <name> 标题，并阅读该完整章节。仅引用其中的符号和命令，从该章节完整作答。不要浏览文档；请使用 doca-public-knowledge-map 中的入口。将环境检查作为命令提供给用户，在其 DOCA 主机上运行。对于超出范围的请求，指出负责该事项的技能并停止。

对于计划中的版本升级，此技能要确保遵循的最重要规则是：检测 → 报告 → 询问 → 仅在此之后指导升级。绝不自动升级。 此技能会检测已安装的 DOCA 环境以及可用的新版本，清楚地报告版本差距，然后停止并请求用户明确确认。只有在用户明确回答“是”后，才会逐步指导升级。失败或部分完成的升级则进入恢复流程，而不会提出新的目标版本升级。两种流程中的所有硬件／固件／重启步骤都交由 doca-hardware-safety/SKILL.md 处理，绝不在此重新定义。版本检测本身由 doca-version/SKILL.md 负责；此技能会指引用户前往该文件，不会重复说明检测链。

此技能擅长回答的示例问题

此技能旨在回答的升级问题类别，每类都附有一个完整示例。Agent 应将类别视为核心内容——完整示例只是其中一个具体实例。

• “我安装的 DOCA 不是最新版吗？我落后了多少？”——完整示例：“pkg-config --modversion doca-common 显示 <installed X.Y.Z>；当前版本是什么？升级需要付出什么代价？”。通过 ## configure 中的检测并报告差距工作流回答，该工作流会将版本检测交给 doca-version/SKILL.md，并将当前版本查询交给 doca-public-knowledge-map/SKILL.md。
• “我应该直接运行 apt upgrade 来升级到下一个 DOCA 版本吗？”——完整示例：“我想要最新的 Flow 功能；现在可以直接升级吗？”。通过 ## Safety policy 中的绝不自动升级规则和确认关卡，以及 ## run 中的先询问再执行步骤回答——Agent 会报告差距，并在运行任何升级命令前停下，等待用户明确确认。
• “升级后，主机上的版本和 BlueField 上的版本不一致——发生了什么？”——完整示例：“升级后，pkg-config 报告的是新版本，但 bfver 仍报告旧版本”。通过 ## Error taxonomy 中的主机/BFB 版本不一致条目，以及 ## debug 中的升级失败诊断回答；该诊断会将检测重新交由 doca-version ## test。
• “升级中途终止了，现在 dpkg 卡住了——我该如何恢复？”——完整示例：“apt upgrade 被中断；dpkg 报告事务中断”。通过 ## Error taxonomy 中的升级未完成和事务中止条目，以及 ## debug 中的恢复步骤回答。
• “升级要求我重新刷写 BFB / 切换 BlueField 模式 / 重启——这样安全吗？”——完整示例：“目标版本要求使用新的 BFB；我现在可以重新刷写吗？”。通过 ## run 将每个硬件 / 固件 / 重启步骤交由 doca-hardware-safety/SKILL.md 处理；此技能绝不会重新定义重新刷写、模式切换或断电冷启动方面的操作规范。
• “我安装的组件即将停止维护——我应该继续基于它开发，还是迁移？”——完整示例：“我依赖 DOCA App Shield / DOCA Flow Inspector 服务；它们是否正处于弃用过程中？”。通过 ## Capabilities and modes 中对停止维护 / 弃用的关注来回答；该部分会引导用户通过 doca-public-knowledge-map/SKILL.md 查阅公开发行说明，以确认生命周期状态，而不是建议继续投入可能即将停止维护的组件。

何时加载此技能

只要升级或降级 DOCA 是核心关注点，就加载此技能——用户在询问是否有更新版本、是否应该升级、如何安全升级，或如何从失败的升级中恢复。必须在 Agent 撰写第一句话之前作出判断；下方的激活清单也在此处重复列出，确保每次查阅此技能时都能看到激活规则。对于计划中的升级或降级，它会报告差距，然后停下，等待用户明确确认。对于失败或未完成的升级，它会先进入 ## debug，以记录并稳定当前状态；绝不会在恢复时首先使用其他升级命令、重试升级，或在未获得明确确认的情况下发出新的升级命令。

Agent 激活检查清单 — 当以下任意单元格为 true 时，在回答开始时加载此技能

触发类别	提示词中的具体信号（任意一项都会触发此覆盖规则）
有意升级／降级	“有没有更新的 DOCA”、“我该升级到下一个版本吗”、“帮我升级到最新版”、“把我回滚到之前的 DOCA”、“为了复现 bug，降级到 3.1”
意外升级／版本漂移	“apt upgrade 拉取了更新的 DOCA 次要版本，导致我的构建失败”、“我的主机和 BlueField 现在运行不同版本”、“源通道是 latest，但我并不想升级”
升级失败／未完成	“升级中途终止了”、“事务中断后 dpkg 卡住了”、“升级已完成，但四方匹配不再成立”
容器标签更新	用户想将 NGC DOCA 容器部署从一个标签更新到较新的标签，或询问更新标签是否算升级
停用／弃用情况	用户询问其依赖的组件是否已弃用、即将停用，或是否值得继续投入

首先对请求进行分类。计划中的迁移（包括请求回滚）遵循 detect → report → ASK。失败、未完成或意外发生版本漂移的迁移已经属于诊断／恢复请求：加载此技能，采集当前四源状态，并进入 TASKS.md ## debug；不要询问是否可以执行已经失败的升级，也不要将再次执行升级命令作为首个恢复操作。

对于计划中的迁移，Agent MUST：

1. 将计划升级的版本检测转交给 doca-version ## configure。 对于失败或未完成的升级，从 doca-version ## debug 和

   debug 开始。请勿在此重述

   四源检测流程；此技能使用已检测到的状态和四方匹配结果。
2. 报告差异，然后停止并等待明确确认。 说明已安装的版本、可用的目标版本，以及迁移的代价（参见

   Version compatibility），

   然后询问用户是否确认。在用户明确同意之前，不得执行任何升级命令。
3. 将所有硬件／固件／重启步骤转交给 doca-hardware-safety/SKILL.md。此 技能说明升级流程中何时需要执行这类步骤；该技能说明如何安全地执行。

对于失败／未完成的迁移，Agent MUST 改为根据 CAPABILITIES.md ## Error taxonomy 对采集到的状态进行分类，委派唯一有文档说明的纠正操作，然后重新进入恢复流程。任何不受支持的 installed → target 跳转都必须安全失败：不得自行编造中间版本或命令；必须要求提供兼容性策略或发行说明中明确记录的升级路径。

在首次安装时（使用 doca-setup/SKILL.md）、仅涉及版本检测流程时（使用 doca-version/SKILL.md）， 或进行一般性了解时（使用 doca-public-knowledge-map/SKILL.md），不要加载此技能。

此技能提供的内容

这是一个精简加载器。正文仅保留用于选择下一份正确文件所需的指引。实质性的升级资料位于两个配套文件中：

• 功能配套文件——升级范围：升级模式分类（主机 apt 升级、BFB 重刷、容器标签升级，或降级／回滚）、绝不自动执行规则和确认门槛、日落／弃用意识事项、会重定向到 doca-version 的版本兼容性叠加层、错误分类（部分升级、apt 源漂移、主机／BFB 版本不一致、事务中止／dpkg 中断）、可观测性范围（用于证明升级已发生或未发生的命令），以及叠加在 doca-hardware-safety 之上的升级专属安全策略。
• 任务配套文件——适用动词的逐步工作流：configure（检测 + 发现目标 + apt 源预检查）、build 和 modify（路由占位内容——版本固定值变更由其他文件负责）、run（需经过确认门槛的引导式升级）、test（升级后的四路验证）、debug（诊断失败／部分升级），以及 Deferred task verbs 区块。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围（正在考虑或恢复升级／降级）。
2. 有关升级模式分类、绝不自动执行规则、日落意识事项、错误分类、可观测性和安全策略，请参阅功能配套文件。
3. 有关逐步工作流——检测并报告、需经过确认门槛的引导式升级、升级后验证和升级失败诊断，请参阅任务配套文件。

相关技能

• doca-version/SKILL.md——负责四来源检测链和四路匹配规则。此技能的检测步骤会转交至该技能，且不会重新定义版本检测；差距报告会使用检测到的版本。
• doca-setup/SKILL.md——负责首次安装、安装验证和 apt 源路径。此技能的 apt 源一致性预检查会在考虑任何 apt 形式的升级之前链接至该技能。
• doca-hardware-safety/SKILL.md——负责所有硬件／固件／重启步骤（mlxconfig、BFB 重刷、BlueField 模式切换、冷断电重启）。此技能的 ## Safety policy 会叠加该元策略，并仅添加升级专属内容（确认门槛、回滚优先、维护窗口）。
• doca-public-knowledge-map/SKILL.md——指向公开 DOCA 文档的路由表，包括发行说明和 Compatibility Policy。此技能会将当前发行版本是什么和此组件是否即将停止支持这两个问题路由至该技能；不会重复其路由内容。
• doca-debug/SKILL.md——跨领域的调试流程。若升级失败后的残留问题位于软件层，则在确认升级状态后转交至该技能。
• doca-programming-guide/SKILL.md——使用方在升级后重新构建所依据的构建模式。此技能会指出可能需要重新构建；构建机制则由该技能负责。
• doca-structured-tools-contract/SKILL.md——存在时 Agent 优先使用的 JSON 架构；若主机上有 doca-env，升级检测步骤会复用版本技能使用的同一项 doca-env 单次调用。