doca-structured-tools-contract

DOCA 结构化工具约定

从哪里开始：每当工作流要求 “优先使用 doca-structured-tools-contract 中的结构化工具” 时，都应使用此技能。先阅读 ## The agent behavior contract，然后阅读 ## Schemas 中匹配的架构。如果宿主机上有结构化工具，优先使用其输出；如果没有，则回退到同一部分中的手动流程，并始终报告采用了哪条路径。

**范围边界。**编写库代码不属于结构化工具问题：指出库技能名称，然后停止。提交前检查规范则属于范围内：应用提交前验证架构。

此技能适用的问题示例

请参阅 references/examples.md。

何时加载此技能

当其他技能的工作流要求优先使用结构化工具时，或用户想要一条命令整合多个手动命令的结果时，都应加载此技能。具体来说：

• 某个特定工件的技能在 Command 附录中引用了此技能。
• 用户询问“有没有一条命令能告诉我有关 DOCA 安装的 X 信息”。
• 用户询问“对于某个带有提交前验证调用的库，提交前如何确认 X 有效”。
• Agent 已通过手动方式计算出答案，并想提供下次可用的结构化工具单行命令。

对于一般的 DOCA 入门介绍、库 API 问题或从头安装的指导，不要加载此技能——请改用对应的库技能 + doca-public-knowledge-map + doca-setup。 运行探测和回退流程需要通过 shell 访问目标主机，可以直接访问，也可以通过用户运行命令访问。

使用此技能的 Agent 必须遵守的基本规则

1. **先检测；绝不假定工具已安装。**每个架构都会指定用于判断工具是否已安装的探测命令；在将架构输出视为权威之前，先运行该命令。
2. **有结构化工具时优先使用；没有时回退到手动流程。**探测成功且输出符合所选架构时，以结构化 JSON 为准。探测失败或输出无效时，按手动流程执行并综合得出等效答案。
3. **报告采用了哪条路径。**回答开头写明 “使用结构化 <helper>（路径：<path>）” 或 “回退到手动流程（结构化 <helper> 探测失败：<reason>）”，并替换为架构所选的 helper 和实际探测失败原因；绝不要报告与所选 helper 不同的 helper。
4. **架构在此处锁定；各技能的扩展项不受此限。**特定工件的技能可以在 Command 附录中添加使用某个架构的条目，但不得重新定义该架构。架构扩展在此处进行；引用它的附录会继承其内容。
5. **绝不编造架构中没有的 JSON 字段。**粘贴的 JSON 中额外字段仅供参考；应以架构为准。
6. **架构描述的是约定，而非实现。**满足这些约定的可执行文件将由后续 PR 提供；此技能的存在是为了让其他技能在发布前了解基础设施。因此，此处提及的 helper 目前均未安装在任何地方——绝不要声称它们已可用，也不要让用户去安装。执行探测，用一句话报告工具不存在，然后根据手动回退流程作答。
7. **权限绝不能默认授予。**需要 sudo 的回退命令应交由用户运行，或仅通过获准的特权通道执行——绝不能因为 helper 不存在就悄悄提升权限。如果没有可用的特权通道，请让用户运行该命令，或说明这一限制。

Agent 行为契约

每当 Command 附录引用此契约时，都要运行以下四步循环：

1. **检测。**运行 schema 的探测命令。例如： command -v doca-env、 test -f /opt/mellanox/doca/share/version-matrix.json、 command -v doca-capability-snapshot。探测为只读操作，安全无害。 辅助工具要到 PR2 才会提供，因此探测失败是预期情况。
2. **优先使用。**如果探测成功，则调用结构化工具，并按照 ## Schemas 中的 schema 解析其 JSON。只有在解析成功且每个必需字段都具有文档规定的类型时，结果才具有权威性。JSON 格式错误、缺少字段或类型不匹配，都会导致结构化路径失败：报告失败，并使用第 3 步。将额外字段视为参考信息并忽略（规则 5）。不要为了“再次核对”有效的结构化输出而运行手动命令链——结构化输出会取代命令链。
3. **回退。**如果探测失败，则按对应 schema 小节中列出的顺序执行手动命令链，并合并输出。如果某条手动命令不可用，则说明这一缺口，并转到对应的 skill（通常是 doca-setup）。如果该 skill 也无法解决问题，则列出缺少的命令，说明无法完成回答，并停止，不要将不完整的数据作为完整结果呈现。
4. **报告。**回答开头使用以下其中一种表述：
   • “使用结构化 <tool>（路径：<path>）。”——探测成功且输出已通过验证。
   • “回退到手动命令链（结构化 <tool> 探测失败：<reason>）。”——探测失败。注明探测命令和失败原因；对于 command -v，失败表示命令不在 PATH 中，并不代表确定不存在。不要建议安装它（规则 6）。
   • “回退到手动命令链（<tool> 输出未通过 schema 验证：<reason>）。”——辅助工具存在，但其输出格式错误、缺少必需字段或类型无效。

报告步骤可以证明 Agent 已优先尝试使用辅助工具。

Schemas

根据问题类型选择 schema：环境／安装状态使用 doca-env；能力最低版本查询使用 version-matrix；按设备查询库能力使用 capability-snapshot；规范验证使用 validate-before-commit；Host 与 DPU 对比使用两个 collect-state schema。每个 skill 的 Command 附录若指定了 schema，就直接使用该 schema。每个小节都会列出一个结构化工具、其探测方式、顶层 JSON 结构，以及探测失败时要执行的手动命令链。

doca-env --json 架构

检测探针： command -v doca-env（安装后与 doca_caps 位于同一 $PATH 位置）。

顶层结构（JSON 对象）：

字段	类型	说明
version	对象	pkg_config / applications_version / doca_caps / bfb（string|null）/ consistent（bool）
devices	对象数组	每个可见 PCIe 功能：pcie_address（例如 0000:03:00.0）、kind（PF|VF|SF）、name、representor_of（string|null）、state（active|down|unknown）、mtu（number）
libraries	对象数组	每个公共 DOCA 库对应一项：pkg_config_name、installed（bool）、pc_path（string|null）
sample_paths	对象数组	每个库对应一项：library、path（磁盘上的示例根目录）
drivers	对象	mlx5_core_loaded（bool）、mlx5_ib_loaded（bool）、kernel_version（string）
hugepages	对象	available_2m（number）、available_1g（number）、mount_point（string|null）
host_kind	string	host | bluefield | unknown
bf_mode	string | null	smartnic | dpu | switch | null（当 host_kind != bluefield 时）

手动回退链（按顺序执行；合并输出以合成相同结果）：

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 地址 + 类型 + 代表端口）
5. 首先查找 doca-common.pc：如果 find /opt/mellanox/doca -name doca-common.pc -print -quit 的输出为空，则停止，报告部分安装缺失，并转至 doca-setup；绝不要展开空通配符。否则，将 PCDIR 设为其目录并运行 for pc in "$PCDIR"/*.pc; do pkg-config --exists "$(basename "$pc" .pc)" && echo "$pc"; done → libraries 数组。如果 PCDIR 不是目录，或没有模块解析成功，则报告缺失并转至 doca-setup。在 DOCA 3.3+ 中，PCDIR 通常为 /opt/mellanox/doca/lib/<arch>-linux-gnu/pkgconfig；在旧版／拆分配置文件安装中，通常为 /opt/mellanox/doca/infrastructure/lib/pkgconfig。
6. ls /opt/mellanox/doca/samples/ → sample_paths 数组
7. lsmod | grep -E '^mlx5_(core|ib)' + uname -r → drivers 对象
8. cat /proc/meminfo | grep -i Huge → hugepages 对象
9. dmidecode -s system-product-name（或在 BlueField 上运行 cat /proc/device-tree/model）→ host_kind
10. mlxconfig -d <pcie> q INTERNAL_CPU_MODEL → bf_mode（当 host_kind == bluefield 时）

version-matrix.json 架构

检测探针： test -f /opt/mellanox/doca/share/version-matrix.json。

顶层结构（JSON 对象）：

字段	类型	说明
schema_version	string	此契约的 semver 版本；架构变更时递增
generated_at	string	ISO-8601 生成时间戳
entries	array of object	每个（库，能力）对一行

每条记录的结构：

字段	类型	说明
library	string	pkg-config 模块名称（doca-flow、doca-rdma、doca-comch 等）
capability	string	机器可读的能力名称；各库的 Command 附录列出它映射到哪个 doca_<lib>_cap_* 查询
display_name	string	人类可读的标签；报告时加引号
min_doca_version	string	首次提供该能力的 DOCA 版本（semver）
max_doca_version	string | null	最后提供该能力的版本（null = 仍可用）
source_url	string	推导该记录所依据的公开文档 URL
source_quote	string	确立该记录的公开文档原文

手动回退流程：

1. 通过对应 skill 的 CAPABILITIES.md 表格确定库和能力。
2. 通过 doca-public-knowledge-map 获取该库对应的文档页面。
3. 搜索能力名称，逐字提取并引用 “available since” 的说明。
4. 在用户主机上交叉核对 pkg-config --modversion doca-<library>；如果版本早于 “available since” 一行所述版本，则无论文档如何说明，该能力在此安装中都不可用。

capability-snapshot 架构

检测探针： command -v doca-capability-snapshot（安装后与 doca_caps 使用相同的 $PATH）。

顶层结构（JSON 对象）：

字段	类型	说明
snapshot_at	string	ISO-8601 时间戳
doca_version	string	快照生成时的 doca_caps --version
host_kind	string	host | bluefield
devices	array of object	每个 doca_devinfo 对应一项：pcie_address、library_capabilities（库 → 能力标志的映射）

手动回退流程：

1. doca_caps --list-devs → 设备枚举
2. 按设备查看详情：doca_caps --pci-addr <bdf>（无副作用； 参见 doca-caps）。只有在需要某项未显示的能力时，才使用 对应库随附示例中的 ## test 工作流；切勿为快照编写新的测试代码。

提交前验证 schema

检测探针： command -v doca-validate。特定库的构造函数验证接口不是检测探针，而且可能会修改状态。公开的 Flow 头文件中没有 doca_flow_pipe_validate 符号：切勿臆造此符号，也切勿使用 doca_flow_pipe_create 来测试该辅助工具。

顶层结构（JSON 对象）：

字段	类型	说明
library	字符串	规范所针对的 DOCA 库
spec_path	字符串	待验证规范的磁盘路径
result	字符串	pass | fail | skip
checks	对象数组	每项检查包含：name、status（pass | fail | skip）、details、remediation（字符串 | null）

手动回退流程：

1. 在对应 skill 的 ## test 工作流中查找特定库的验证接口。部分库提供专用的 _validate 调用；而在会修改状态的 _create 中进行构造函数检查，不属于只读验证器。特别是，doca_flow_pipe_create 属于 doca-flow TASKS.md ## test，须先满足其前置条件；切勿将其用作提交前探针。如果调用方要求只读验证，而 API 未提供专用验证器，则报告 result: skip，转至该库的 ## test 工作流，然后停止（跳过步骤 2 和 3）。
2. 在任何 commit / create / submit 调用之前，调用该只读验证器（切勿调用会修改状态的 _create）。
3. 有意映射结果：DOCA_ERROR_INVALID_VALUE 和 DOCA_ERROR_NOT_SUPPORTED 对应 result: fail；权限、传输、设备不可用及其他操作性错误对应 result: skip，并在 checks 条目中提供 doca_error_get_descr() 文本和修复建议。切勿将无法运行验证转化为规范失败。

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

根据命令执行的一侧选择辅助工具：主机使用 doca-collect-host-state；BlueField 使用 doca-collect-dpu-state。两者都存在并不意味着可以跨侧访问；如需比较差异，须在两侧分别采集并进行比较。

检测探针： command -v doca-collect-host-state（主机）／command -v doca-collect-dpu-state（BlueField）。

顶层结构（JSON 对象），两者共用：

| side | 字符串 | host | dpu | | doca_version | 字符串 | doca_caps --version | | firmware_version | 字符串 | flint -d <pcie> q 输出（sudo） | | kernel_version | 字符串 | uname -r | | mlx5_modules | 字符串数组 | 已加载的 mlx5_* 模块 | | bf_mode | 字符串 | null | smartnic | dpu | switch | null | | devices | 对象数组 | 每个 PCIe 功能：pcie_address、kind（PF | VF | SF）、state、mtu、representor_of |

手动回退流程（每侧分别执行）：

1. doca_caps --version → doca_version
2. uname -r → kernel_version
3. lsmod | grep mlx5 → mlx5_modules
4. devlink dev show + lspci | grep Mellanox + ip -j link → 枚举 devices 和 PCIe 地址
5. 对每个发现的 PCIe 目标，通过获准的特权通道运行 flint -d <pcie> q → firmware_version
6. 对发现的 BlueField 目标，运行 mlxconfig -d <pcie> q INTERNAL_CPU_MODEL → bf_mode

两侧结构对称，因此 Agent 在诊断主机 ↔ BlueField 不匹配问题时可以比较两侧数据。

与 PR2 可执行文件的关系

目前尚未提供此处所述的辅助工具（基本规则 6）；未来推出后将原样满足上述 schema，无需改造其他 skill。