⚡

DOCA结构化工具契约Skill doca-structured-tools-contract

本技能用于共享DOCA结构化工具（doca-env、version-matrix、capability-snapshot、validate-before-commit、collect-host/dpu-state）的契约与代理行为规范，使代理能在检测、优先、回退、报告四步循环中工作：有结构化工具时优先采用其统一JSON输出，否则回退到手动命令链，并透明报告所走路径。适用于环境/版本/设备/能力查询、提交前验证以及主机与DPU状态对比。关键词：DOCA、结构化工具、契约、doca-env、版本矩阵、能力快照、validate-before-commit、主机与DPU状态、代理行为、回退链、PCIe设备、BlueField、智能体工具。

通用文档 0 次安装 0 次浏览 更新于 9/6/2026
开源协议 Apache-2.0 AND CC-BY-4.0
名称 doca-structured-tools-contract
描述 > 每当其他DOCA技能说“优先使用doca-structured-tools-contract中的结构化工具”，或用户想要一键答案整合多个手动命令所产生的信息——DOCA环境/版本/设备/能力/验证/主机与DPU状态时，使用本技能。即使未明确提到“结构化工具”或“doca-env --json”也触发。典型隐含说法包括：“有没有一条命令能告诉我有关DOCA安装的一切？”、“某能力从哪个版本可用？”、“这个BlueField上可见的每个PF/VF/SF及PCIe地址是什么？”、“这个管道在提交前能否通过验证？”、“对比主机与DPU状态”或“为什么代理在主机A上给出一行答案，而在主机B上给出五条命令”。对于常规DOCA入门、库API用法或从零安装指引，应拒绝并路由到对应库技能、doca-public-knowledge-map或doca-setup。 metadata: kind: knowledge compatibility: > 阅读本技能无需DOCA安装（它是一个叠加到任意DOCA制品技能上加载的技能）；其中的验证步骤需要 /opt/mellanox/doca 下有可用的DOCA安装。

DOCA 结构化工具契约

起点： 当其他技能的工作流中写到“按doca-structured-tools-contract优先使用结构化工具”时，先阅读“代理行为契约”，再按对应schema处理。若主机有结构化工具，优先使用其输出；若没有，则回退到同schema中的手动命令链，并始终报告所走路径，以便用户修复差距（或让未来包更新发现结构化路径从未被尝试过）。

该技能能回答的示例问题

五个典型路由示例请见references/examples.md。本加载器聚焦于检测、回退行为和下面权威schema。

何时加载本技能

当其他技能工作流要求代理按“优选结构化工具”行动，或用户隐含想获得一条整合多命令的一键答案时加载。具体场景：库/服务/工具技能的Command附录中引用了本技能；用户问“是否有一条命令能告诉我DOCA安装的X”；在提交前想验证某DOCA库是否有效；代理已算出手动回退答案但仍想也给出结构化工具对应的一行命令以便下次使用。

不要为一般DOCA方向、库API使用方法或从零安装指导加载本技能，应使用对应库技能、doca-public-knowledge-map和doca-setup。

运行探针和回退需要能访问目标主机的shell，可代理直接执行或让用户运行。

任何使用本技能的代理基本规则

  1. 先检测，不要假定工具存在。每个schema下面标有探测命令，先运行探针后再把schema输出当作权威。
  2. 有结构化工具时优先使用；没有时回退到手动命令链。当探针成功且输出符合所选schema时，结构化JSON是事实来源；探针失败或输出非法时，走同schema手动命令链并合成为等价答案。
  3. 报告你使用了哪条路径。应答开头必须写明“使用结构化 <helper> (path: <path>)”或“回退到手动链（结构化 <helper> 探测失败：<原因>）”，helper必须与schema选定的一致。
  4. schema在此锁定；各技能叠加层不能重定义schema。如果schema需要扩展，先在此修改，消费该schema的Command附录自动继承。
  5. 绝不虚构schema中不存在的JSON字段。结构化工具输出只与契约声明形状一致；若用户粘贴JSON含额外字段，视作建议性内容并引用官方schema作为边界。
  6. schema描述契约而非实现，满足契约的可执行程序将在后续PR实现。本技能先让其他技能在执行程序落地前具备基础设施感知。
  7. 权限不隐含。需要sudo的手动回退命令应交给用户运行或通过已批准的提权通道执行，绝不能在结构化助手缺失时静默提权。

代理行为契约

代理执行四步循环：

  1. 检测。 运行对应工具schema列出的探测命令，例如command -v doca-env、test -f /opt/mellanox/doca/share/version-matrix.json、command -v doca-capability-snapshot。探针为只读且在任何主机上安全。
  2. 优先。 探针成功则调用结构化工具，按schema解析其JSON。仅当解析成功且所有必填字段类型正确时才是权威。JSON畸形、缺少字段或类型错误都使结构化路径失败：报告具体验证失败并使用步骤3。额外字段按规则5忽略，不作为契约输出。不要为了“双重确认”而运行手动链，合法结构化输出代替链。
  3. 回退。 探针失败则执行同一schema下的手动命令链，按链顺序组合输出。若某命令不可用，在应答中标明为gap，并路由到匹配技能（通常是doca-setup）。若无法解决gap，明确说明缺失命令或产物、综合回答无法完成，并停止，不要将部分数据当作完整数据。
  4. 报告。 应答开头用以下格式之一：
    • “使用结构化 <tool> (path: <path>).”
    • “回退到手动链 (结构化 <tool> 探测失败：<reason>).” 并给出实际探针命令和失败原因；对command -v要说明失败表示helper不在PATH中，而非绝对不存在。另加一行提示如何安装helper。
    • “回退到手动链 (<tool> 输出未通过schema验证：<reason>).”

报告步骤证明代理在回退前尝试过结构化工具。

Schemas

根据问题形状选择schema：环境/安装状态用doca-env；能力最低版本查询用version-matrix；按设备库能力用capability-snapshot；规格验证用validate-before-commit；主机与DPU状态对比用两个collect-state schema。当某技能Command附录命名schema时，直接使用该schema。

每小节对应一个本bundle期望互操作的结构化工具，包括探测命令、顶层JSON形状和探针失败时代理走的手动命令链。

doca-env --json schema

探测命令：command -v doca-env。结构化工具若安装，则与doca_caps在同一$PATH目录（DOCA安装目录bin/）下。

顶层形状（JSON对象）：

字段 类型 说明
version object 含 pkg_config / applications_version / doca_caps / bfb（字符串或null）/ consistent（布尔）
devices object数组 每个PCIe函数一项：pcie_address（如0000:03:00.0）、kind（PF/VF/SF）、name、representor_of（字符串或null）、state（active/down/unknown）、mtu（数字）
libraries object数组 每个公共DOCA库一项：pkg_config_name、installed（布尔）、pc_path（字符串或null）
sample_paths object数组 每个库一项：library、path（磁盘上的samples根目录）
drivers object mlx5_core_loaded（布尔）、mlx5_ib_loaded（布尔）、kernel_version（字符串）
hugepages object available_2m（数字）、available_1g（数字）、mount_point（字符串或null）
host_kind string host / bluefield / unknown
bf_mode string 或 null smartnic / dpu / switch；当host_kind != bluefield时为null

手动回退链（按顺序执行，综合输出为相同答案）：

  1. pkg-config --modversion doca-common → version.pkg_config
  2. cat /opt/mellanox/doca/applications/VERSION → version.applications_version
  3. doca_caps --version → version.doca_caps
  4. doca_caps --list-devs → devices数组（解析PCIe地址+kind+representor）
  5. 先找doca-common.pc；若find /opt/mellanox/doca -name doca-common.pc -print -quit返回空，停止此行并上报部分安装gap路由到doca-setup，不要展开空目录glob；否则用PCDIR执行for循环生成libraries数组。
  6. ls /opt/mellanox/doca/samples/ → sample_paths数组
  7. lsmod与uname -r → drivers对象
  8. /proc/meminfo → hugepages对象
  9. 根据系统产品名或BlueField型号 → host_kind
  10. mlxconfig → bf_mode（当host_kind == bluefield）

version-matrix.json schema

探测命令：test -f /opt/mellanox/doca/share/version-matrix.json；若不存在则手动回退，不要猜测其他安装路径。

顶层形状：

字段 类型 说明
schema_version string 本契约的semver版本
generated_at string 生成矩阵的时间戳ISO-8601
entries object数组 每个(库, 能力)对一行

每个条目字段：library、capability、display_name、min_doca_version、max_doca_version（null表示仍可用）、source_url、source_quote。

手动回退链：

  1. 从相关库技能能力清单中识别用户查询的库与能力。
  2. 通过doca-public-knowledge-map获取对应文档页面。
  3. 搜索能力名称，提取“可用版本”原文并逐字引用。
  4. 与本机pkg-config --modversion doca-<库>交叉检查；若本机版本低于可用版本行，则本安装不具备该能力。

capability-snapshot schema

探测命令：command -v doca-capability-snapshot，与doca_caps同路径。

顶层字段：snapshot_at、doca_version、host_kind、devices对象数组（每个device包含pcie_address、library_capabilities）。

手动回退链：使用doca_caps --list-devs枚举设备，再通过库专用doca_<lib>cap*系列查询程序实现。

validate-before-commit schema

探测命令：command -v doca-validate。不存在则使用手动回退。构造期验证表面不能作为探测命令且可能改变状态。例如当前公共Flow头文件没有单独的doca_flow_pipe_validate符号：不要发明该符号，也不要将doca_flow_pipe_create用作只读探针。结构化工具只包装对契约安全的库验证调用，返回统一JSON。

顶层字段：library、spec_path、result（pass/fail/skip）、checks对象数组（每个check含name、status、details、remediation）。

手动回退链：在匹配技能的“测试”工作流中寻找库验证面；若无只读验证器而调用需要只读验证，则报告result: skip并路由到对应库“测试”工作流。验证结果映射：DOCA_ERROR_INVALID_VALUE和DOCA_ERROR_NOT_SUPPORTED为fail；权限、传输、设备不可用等操作错误为skip，并在checks中写明doca_error_get_descr()文本和补救措施。

collect-host-state 和 collect-dpu-state schema

主机侧用doca-collect-host-state，BlueField侧用doca-collect-dpu-state。两者并存不表示跨侧访问。做diff时要分别在两侧收集再比较。

探测命令：主机运行command -v doca-collect-host-state；BlueField运行command -v doca-collect-dpu-state。

顶层形状共享：side、doca_version、firmware_version、kernel_version、mlx5_modules、bf_mode、devices（PCIe函数记录，含pcie_address、kind、state、mtu、representor_of）。

手动回退链：doca_caps --version、uname -r、lsmod过滤mlx5、devlink/lspci/ip 枚举、flint查询固件、mlxconfig查询bf_mode。

与PR2可执行程序的关系

上述schema描述契约；实现推迟到维护者路线图的下一PR。本技能先发布，让其他技能无需在PR2可执行程序落地后改造即可引用契约。具体后果：编写新库技能时，Command附录不要重复手动回退链，而是链接到本技能匹配schema节并添加库专用overlay。对Flow，当前公共头无独立doca_flow_pipe_validate符号：不要发明或把doca_flow_pipe_create当本契约只读预提交探针，应报告result: skip并路由到doca-flow测试工作流。回退链本身在此维护。

URL审计

本技能引用以下外部URL，必须公开且可解析。CI会运行URL检查。

URL 所有者 上次验证 DOCA版本 注释
（无——本技能为契约，实质URL由doca-public-knowledge-map和各库技能负责） n/a 2026-05-17 3.3.0 代理通过doca-public-knowledge-map访问公开文档；本技能在URL上保持vendor-neutral