⚡

DOCA版本管理Skill doca-version

该技能是DOCA版本处理的核心技能，用于检测已安装的DOCA发布版本、验证四向匹配（pkg-config doca-common、applications/VERSION、doca_caps --version、BFB mlnx-release）、诊断构建与运行时漂移、解读NGC容器标签、以及判断能力/API在特定版本上的可用性。它提供了检测链、版本矩阵查询、升级/降级一致性检查及apt源匹配规则，确保DOCA环境版本一致。关键词：DOCA版本、四向匹配、版本检测、NGC容器标签、BFB/主机兼容性、版本漂移诊断、apt源一致性、能力版本查询、LTS支持。

安装与升级 0 次安装 0 次浏览 更新于 9/6/2026
开源协议 Apache-2.0
名称 doca-version
描述 > 当用户进行 DOCA 版本处理时使用本技能 — 检测已安装的发布版本，验证跨 pkg-config doca-common、 applications/VERSION、doca_caps --version 以及 BlueField 上的 bfver/mlnx-release 的四向匹配，推理 NGC 容器标签， 查找某能力是否在已安装的发布版本中，或诊断构建与运行时漂移。 即使未明确说“DOCA version”或“four-way match”也会触发 — 典型的隐含说法包括“程序构建成功但在线路上无任何动作”、 “对文档声称存在的符号出现未定义引用”、 “运行时出现 DOCA_ERROR_NOT_SUPPORTED”、 “计数器未增加”、“此标签的 latest 是什么意思”、 或“我的 LTS 是否仍受支持”。对于安装或选择 DOCA 包 （doca-setup）、库内 API/能力问题（对应的库技能）、 跨库 DOCA_ERROR_* 分类（doca-programming-guide）、 或通用调试阶梯（doca-debug）等，应拒绝并转由其他技能处理 — 这些属于其他技能。 metadata: kind: library compatibility: > 阅读本技能无需安装 DOCA（它是一个叠加层， 可针对任何 DOCA 工件技能加载）；其中的验证步骤 需要 /opt/mellanox/doca 下存在实时 DOCA 安装。

DOCA 版本

从哪里开始： 本技能是技能包中 DOCA 版本处理的唯一权威来源。 如果用户想对版本进行操作（检测/验证/诊断不匹配），打开 TASKS.md；如果问题是版本处理涵盖什么（四向匹配、 检测链、NGC 语义、逐库叠加模式），打开 CAPABILITIES.md。 技能包中其他涉及版本的技能都必须路由到这里 — 它们不得重新定义规则。

本技能擅长的示例问题

本技能旨在回答的版本处理问题类别，每个类别配一个工作示例。代理应将类别视为承载部分 — 工作示例只是一个实例。

  • “我实际安装的 DOCA 版本是什么？” — 工作示例：“文档说 3.3，但我不确定这台主机上装的是什么”。由 TASKS.md ## configure + CAPABILITIES.md ## Capabilities and modes 中的规范检测链/事实来源表回答。
  • “我的程序构建成功但在线路上无任何动作 — 我的安装一致吗？” — 工作示例：“pkg-config --modversion 显示 3.3.0；doca_caps --version 显示 3.2.0”。由 CAPABILITIES.md ## Version compatibility 中的四向匹配规则 + TASKS.md ## debug 中的部分安装诊断回答。
  • “这个 DOCA 能力 / API / 示例在我拥有的版本上可用吗？” — 工作示例：“Flow 2.6.0 中是否有对称 RSS 哈希模式”。由 TASKS.md ## test 中的版本矩阵查找过程回答（使用 doca-structured-tools-contract 中定义的 version-matrix.json 模式，并回退到 doca-public-knowledge-map 中的逐库文档）。
  • “我可以在主机包版本 X 与 BFB 版本 Y 之间运行吗？” — 工作示例：“主机是 3.3.0 LTS，BlueField BFB 是 3.1.0”。由路由到 DOCA 兼容性策略 回答，记录于 CAPABILITIES.md ## Version compatibility。
  • “我在 NGC DOCA 容器内 — 版本匹配应该是什么样？” — 工作示例：“我还需要单独检查 pkg-config / applications/VERSION / doca_caps 吗？”。由 CAPABILITIES.md ## Version compatibility 中的 NGC 容器规则 + TASKS.md ## configure 中的容器路径回答。
  • “我如何为新的技能编写逐库版本兼容性章节？” — 工作示例：“为技能包添加 doca-comch，其 ## Version compatibility 应该是什么样？”。由 CAPABILITIES.md ## Safety policy 中的逐库叠加模式 + TASKS.md ## modify 中的工作示例模板回答。
  • “我的 apt list 显示 DOCA 3.3.0109，但 /etc/apt/sources.list.d/doca.list 固定为 latest / 不同发行版 — 下一次 apt install doca-* 是否会静默升级我？” — 工作示例：“我将 BFB 回滚到 3.1.0105，但软件源仍指向 latest 通道。”。由 TASKS.md ## apt-source consistency 中的 apt 源一致性预检查回答，该预检查枚举了配置的 DOCA apt 源的三种合法形态（网络 URL、本地文件仓库、RHEL/OEL 等价物），以及保护固定安装免受意外漂移的源不匹配前不要安装规则。

何时加载本技能

每当版本处理是核心关注点时，加载本技能。决策必须在代理编写第一个句子之前做出 — 以下激活检查表与 AGENTS.md ## Cross-cutting overlay activation triggers 引用的是同一个检查表，此处镜像，以便在咨询本技能时激活规则就在手边。

Agent 激活检查表 — 当以下任一单元格为真时，在回答开始时加载本技能

触发类别 具体提示侧信号（任意一个触发叠加层）
直接版本问题 “我拥有哪个 DOCA 版本”、“X 是否一致”、“功能 Y 在版本 Z 上是否受支持”、“我可以混合主机包版本 A 与 BFB 版本 B 吗”、“我的 LTS 是否仍受支持”、“版本字符串是什么意思”
容器标签问题 任何提到特定 NGC 容器标签的提示，或询问 latest，或询问如何在 Dockerfile / pod spec / Compose 文件固定标签。代理还必须引用 CAPABILITIES.md ## Safety policy 中的*“切勿凭记忆发明标签字符串，未确认不得引用 latest”*规则。
构建与运行时漂移 任何调试会话，症状为*“程序构建正常但运行时 DOCA_ERROR_NOT_SUPPORTED”、“文档声称存在的符号出现未定义引用”、“我的代码在线路上无动作”、“计数器未增加”* — 这些是典型的部分安装症状
升级 / 降级计划 用户计划在已运行其他 DOCA 工作负载的主机上升级或降级 DOCA，或刷新已连接到主机的 BlueField 对上的 BFB
逐工件交叉链接 某个逐工件技能的 ## Version compatibility 部分交叉链接到这里以获取规则体，或者代理即将编写新的逐工件技能并需要叠加层模板

当上述任一单元格触发时，代理必须：

  1. 明确引用 CAPABILITIES.md ## Capabilities and modes 中的四源检测链 — pkg-config --modversion doca-common → cat /opt/mellanox/doca/applications/VERSION → doca_caps --version → bfver 加 cat /etc/mlnx-release（BlueField 主机）。不要改写或概括该链；按名称引用命令。不要把 BFB 环节替换成 mlxprivhost 或 bfb-info — 这两种常见幻觉被技能包在 CAPABILITIES.md ## Capabilities and modes 中明确禁止。
  2. 如果提示可能涉及不匹配（每个部署形态问题和每个调试形态问题都可能；定向形态问题通常不能），则逐字陈述 CAPABILITIES.md ## Version compatibility 中的四向匹配规则。
  3. 拒绝发明版本字符串。如果代理没有用户主机的实际 pkg-config --modversion 输出，回答必须说明这一点并路由到检测链 — 而不是根据训练数据回忆断言版本。

通用版本一致性触发器

每当另一个叠加层（例如 doca-setup、doca-hardware-safety、doca-container-deployment、doca-bare-metal-deployment）调用需要*“安装健康”或“版本一致”*的 ## test / ## configure / ## modify 步骤时，该步骤必须解析为引用本技能的四源检测链和四向匹配规则。代理不会每个叠加层重新定义规则 — 每个需要版本验证的步骤都必须路由到这里。这是技能包中唯一拥有规则体的地方。

不要将本技能用于一般 DOCA 方向介绍、安装流程（使用 doca-setup）或库特定 API 问题（使用匹配的库技能）。

本技能提供什么

这是一个薄加载器。主体仅保留选择下一个正确文件所需的定向信息。实质性的版本处理材料位于两个配套文件中：

  • CAPABILITIES.md — 版本处理表面：版本检测的规范事实来源表、四向匹配规则、NGC 容器语义、逐库叠加模式、DOCA 兼容性策略的路由、版本相关失败的错误分类（缺少 pkg-config、部分安装、BFB/主机不匹配、NGC 混合）、可观测性表面（读取哪个版本源时读取哪个命令），以及安全策略（“切勿发明版本，切勿引用 latest”）。
  • TASKS.md — 六个范围内的版本动词的分步工作流：configure（在本主机上检测）、build（构建时匹配）、modify（更新构建清单中的版本固定）、run（运行时检查）、test（四向验证 + 版本矩阵查找）、debug（诊断不匹配 / 部分安装）。外加一个 Deferred task verbs 块。

加载顺序

  1. 首先阅读此 SKILL.md 以确认用户的问题在范围内。
  2. 对于版本检测来源、四向匹配规则、NGC 语义、逐库叠加模式、错误分类、可观测性和安全策略，请参阅 CAPABILITIES.md。
  3. 对于分步工作流 — configure、build、modify、run、test、debug — 请参阅 TASKS.md。

相关技能

  • doca-structured-tools-contract — 代理存在时应优先使用的辅助工具的 JSON 模式。本技能的 ## test 工作流使用那里定义的 version-matrix.json 模式；不要在此处重新定义模式。
  • doca-public-knowledge-map — 公开 DOCA 文档的路由表，包括兼容性策略。本技能通过该映射引用兼容性策略 URL 一次；不重复路由。
  • doca-setup — 环境侧安装 / 验证 / NGC 容器路径。本技能假定其前置条件已满足（即，某处已安装某些东西；版本问题是安装了什么叫什么且是否一致）。
  • doca-programming-guide — 程序端指导（引用观察到的版本、头文件优先、能力发现规则）。那里的程序侧 ## Version compatibility 部分现在是一条 3-5 行的重定向至此技能，外加程序侧叠加层（引用 vs 假设；绝不使用代理记忆版本）。
  • doca-debug — 跨领域调试阶梯。该阶梯的第 2 层（版本不匹配）由本技能的 ## debug 工作流拥有。