doca-version

DOCA 版本

示例

• “我实际安装的是哪个 DOCA 版本？” — 运行四源检测链，并要求四方匹配。
• “程序编译成功了，但网络上毫无动静。” — 在重写应用代码之前，先将混合安装漂移视为版本问题。

说明

遵循下方的加载顺序。打开任务配套文件，了解 detect / validate / diagnose；打开功能配套文件，了解四方匹配和 NGC 标签规则。不要打开所有配套文件。

从何处开始： 此技能是该套件中处理 DOCA 版本管理 的唯一事实来源。如果用户想要对版本执行操作（detect / validate / diagnose mismatch），请打开任务配套文件；如果问题是版本管理涵盖什么内容（四方匹配、检测链、NGC 语义、逐库覆盖模式），请打开功能配套文件。套件中其他涉及版本的技能都应转到此处——它们绝不能重新定义规则。

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

此技能旨在回答的版本管理问题类别，每类附一个实例。Agent 应将类别视为关键部分——实例只是单个具体情况。

• “我实际安装的是哪个 DOCA 版本？” — 实例：“文档说是 3.3，但我不确定这台主机上装的是什么。”通过 ## configure +

  Capabilities and modes

  中的事实来源表所列的规范检测链回答。
• “我的程序编译成功了，但网络上毫无动静——我的安装一致吗？” — 实例：“pkg-config --modversion 显示 3.3.0；doca_caps --version 显示 3.2.0。”通过

  Version compatibility

  中的四方匹配规则，以及

  debug

  中的部分安装诊断回答。
• “我使用的版本支持此 DOCA 功能 / API / 示例吗？” — 实例：“Flow 2.6.0 是否支持对称 RSS 哈希模式？”通过 ## test 中的版本矩阵查询流程回答（该流程使用 doca-structured-tools-contract/SKILL.md#schemas 中定义的 version-matrix.json 架构，并在必要时回退到通过 doca-public-knowledge-map/SKILL.md 查阅逐库文档）。
• “我能否用主机软件包版本 X 搭配 BFB 版本 Y 运行？” — 实例：“主机是 3.5.0 GA，BlueField BFB 是 3.2.3 LTS。”通过 ## Version compatibility 中所述的指引，查阅 DOCA Compatibility Policy。
• “我在 NGC DOCA 容器中——版本匹配是什么样的？” — 实例：“我是否仍需分别检查 pkg-config / applications/VERSION / doca_caps？”通过 ## Version compatibility 中的 NGC 容器规则，以及 ## configure 中的容器路径回答。
• “如何为新技能编写逐库版本兼容性章节？” — 实例：“将 doca-comch 加入套件时，它的 ## Version compatibility 应该是什么样的？”通过 ## Safety policy 中的逐库覆盖模式，以及 ## modify 中的实例模板回答。
• “我的 apt list 显示 DOCA 3.3.0109，但 /etc/apt/sources.list.d/doca.list 固定到了 latest / 另一个发行版——下一次执行 apt install doca-* 会不会悄悄升级？” — 实例：“我将 BFB 回滚到了 3.1.0105，但软件源仍指向 latest 通道。”通过 ## apt-source consistency 中的 APT 软件源一致性预检回答。该章节列举了配置 DOCA APT 软件源的三种合法形式（网络 URL、本地 file-repo、RHEL/OEL 等效形式），以及保护固定版本安装免受意外漂移影响的源与版本不匹配时禁止安装规则。

何时加载此技能

只要版本处理是关键关注点，就加载此技能。必须在 Agent 写下第一个句子之前做出判断——以下激活清单与 AGENTS.md ## Cross-cutting overlay activation triggers（bundle AGENTS.md#cross-cutting-overlay-activation-triggers）中引用的清单相同；此处再次列出，确保查阅此技能时能随时看到激活规则。

Agent 激活清单——以下任一条件成立时，在回答开始时加载此技能

触发类别	提示词中的具体信号（任一信号出现即触发此覆盖规则）
直接询问版本	“我用的是什么 DOCA 版本”、“X 是否一致”、“版本 Z 是否支持功能 Y”、“能否将主机软件包版本 A 与 BFB 版本 B 混用”、“我的 LTS 版本是否仍受支持”、“版本字符串是什么意思”
容器标签问题	任何提及特定 NGC 容器标签的提示词，或询问 latest 的提示词，或询问如何在 Dockerfile / pod 规范 / Compose 文件中固定标签的提示词。Agent 还必须引用 ## Safety policy 中的 “绝不凭记忆编造标签字符串，也绝不在未经确认的情况下引用 latest” 规则。
构建与运行时不一致	任何调试会话中出现以下症状：“程序构建正常，但运行时出现 DOCA_ERROR_NOT_SUPPORTED”、“未定义对文档中所述符号的引用”、“我的代码在线路上毫无动作”、“计数器没有递增”——这些都是典型的部分安装症状
升级 / 降级计划	用户计划在已经运行其他 DOCA 工作负载的主机上升级或降级 DOCA，或在已经连接到主机的 BlueField 对上刷新 BFB
按制品交叉引用	按制品划分的技能的 ## Version compatibility 部分在此处引用规则正文，或者 Agent 即将编写新的按制品划分的技能，需要使用覆盖模板

出现上述任一条件时，Agent 必须：

1. 在回答中明确引用 ## Capabilities and modes 中的四来源检测链——pkg-config --modversion doca-common → cat /opt/mellanox/doca/applications/VERSION → doca_caps --version → bfver 加上 cat /etc/mlnx-release（BlueField 主机）。不得转述或概括此检测链；须按名称引用这些命令。不得用 mlxprivhost 或 bfb-info 替代 BFB 环节——这两种替代方式是常见的幻觉内容，且此 bundle 在 ## Capabilities and modes 中明确禁止使用。
2. 如果提示词可能涉及不匹配（所有部署类问题和调试类问题都有可能；概述类问题通常不会），则须逐字说明 ## Version compatibility 中的四项匹配规则。
3. 拒绝编造版本字符串。如果 Agent 没有用户主机上实际运行 pkg-config --modversion 的输出，回答必须明确说明这一点，并引导用户执行检测链——不得根据训练数据中的记忆断言版本。

通用版本一致性触发条件

每当其他覆盖规则（例如 doca-setup/SKILL.md、doca-hardware-safety/SKILL.md、doca-container-deployment/SKILL.md、doca-bare-metal-deployment/SKILL.md）调用某个要求*“安装状态正常”或“版本一致”*的 ## test / ## configure / ## modify 步骤时，该步骤必须引用此技能的四来源检测链和四项匹配规则。Agent 不得在每个覆盖规则中重新定义此规则——所有需要验证版本的步骤都必须指向此处。这是整个 bundle 中唯一规定该规则正文的地方。

一般性的 DOCA 概述、安装流程（使用 doca-setup/SKILL.md） 或特定库的 API 问题（使用对应的库技能），均不得加载此技能。

此技能提供的内容

这是一个轻量加载器。正文只保留了选择下一个合适文件所需的指引。实质性的版本处理内容位于两个配套文件中：

• capabilities 配套文件 — 版本处理范围：版本检测的权威事实来源表、四向匹配规则、NGC 容器语义、按库叠加模式、指向 DOCA Compatibility Policy 的路由、版本相关故障的错误分类（缺少 pkg-config、部分安装、BFB/主机不匹配、NGC 混用）、可观测性范围（针对每个版本来源应查看哪个命令），以及安全策略（“绝不臆造版本，绝不引用 latest”）。
• tasks 配套文件 — 涵盖六个范围内版本动词的分步工作流：configure（检测此主机上的版本）、build（构建时匹配）、modify（更新构建清单中的版本固定值）、run（运行时检查）、test（四向验证 + 版本矩阵查询）、debug（诊断不匹配 / 部分安装）。另有一个 Deferred task verbs 块。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其范围。
2. 有关版本检测来源、四向匹配规则、NGC 语义、按库叠加模式、错误分类、可观测性和安全策略，请参阅 capabilities 配套文件。
3. 有关分步工作流 — configure、build、modify、run、test、debug — 请参阅 tasks 配套文件。

相关技能

• doca-structured-tools-contract/SKILL.md — 规定 Agent 在有可用辅助工具时应优先使用的 JSON 架构。此技能的 ## test 工作流使用其中定义的 version-matrix.json 架构；请勿在此处重新定义该架构。
• doca-public-knowledge-map/SKILL.md — 指向公开 DOCA 文档的路由表，其中包括 Compatibility Policy。此技能通过该映射仅引用一次 Compatibility Policy URL；不会重复路由信息。
• doca-setup/SKILL.md — 环境侧的安装 / 验证 / NGC 容器路径。此技能假定其前提条件已满足（即某处已安装了某些内容；版本问题关注的是安装了什么，以及版本是否一致）。
• doca-programming-guide/SKILL.md — 程序侧指南（引用观察到的版本、以头文件为准、能力发现规则）。其中程序侧的 ## Version compatibility 部分现已简化为 3-5 行，重定向至此技能及程序侧叠加内容（引用还是假定；绝不使用 Agent 记忆中的版本）。
• doca-debug/SKILL.md — 跨领域的 调试阶梯。该阶梯的第 2 层（版本不匹配）由此技能的 ## debug 工作流负责。