DOCA 结构化工具契约
用统一的结构化输出汇总 DOCA 环境、设备、能力、验证及主机与 DPU 状态。
技能明确要求先探测、优先结构化工具、使用只读探针并报告实际路径，未见恶意行为、凭据窃取或隐蔽外传；但涉及硬件/系统状态、sudo flint及可能暴露拓扑信息，缺少用户确认、敏感输出处理、回滚说明和结构化工具依赖的安全边界，因此扣分。
四步流程、JSON schema、手工回退链和异常缺口提示较清楚；但核心结构化可执行文件明确延期，部分手工命令存在权限、平台和工具可用性假设，且评测材料称收集状态回退包含 lspci，而本技能对应 schema 未列出，存在不一致。静态证据不足，按上限保守评分。
触发形状、适用场景和明确的非适用范围较完整，覆盖环境、版本、设备、能力和校验问题；但依赖其他 DOCA 技能、live DOCA 安装或未来工具，未说明中文交互支持，也未充分界定不同发行版/权限环境，故未满分。
文档结构清晰，采用行为契约、schema 和渐进式说明，包含依赖、限制、评测摘要及维护路线；但 SKILL.md 许可证与 skill-card 的双许可证表述不一致，缺少作者、明确版本/changelog、维护责任人和稳定更新路径，且评测报告记录缺少 Instructions/Examples。
对需要统一 DOCA 状态查询和手工回退的代理具有直接路由价值，字段和报告格式也较可用；但结构化工具尚未实现，回退链仍需多命令合并，版本矩阵还依赖其他技能和外部文档，输出完整性与相对手工替代方案的收益缺少充分验证，因此限制在静态上限内。
技能提供锁定的 schema、命令链、评测断言和 benchmark 摘要，具备一定审计线索；但评测数据集不可用，未提供覆盖该技能关键路径的真实 CI/测试套件，且外部文档来源未在本技能中逐项绑定，无法独立复现，故仅给有限分。
- 结构化工具实现尚未交付，实际使用很可能退回多命令流程；不要把契约 schema 当作已安装功能。
- 执行 flint、mlxconfig、dmidecode 等命令前应确认权限、主机范围和输出是否包含敏感硬件信息；技能没有明确的确认和脱敏策略。
- benchmark 的部分回退命令与 SKILL.md schema 不一致，发布前应统一并补充可复现的 CI/测试数据。
- SKILL.md、skill-card 和仓库许可证表述应统一，并补充作者、版本、变更记录和维护联系人。
这个 Skill 能做什么，适合哪些场景？
这是 NVIDIA Agent Skills 集合中的一个 DOCA 知识型技能，定义了结构化工具与手动命令链之间的统一契约。它适用于需要一次性汇总 DOCA 安装信息、设备能力、版本可用性、提交前验证或主机与 DPU 状态差异的场景。技能会先探测对应助手，优先使用并校验结构化 JSON；助手不可用或输出无效时，才使用记录在相应模式中的手动链。该技能本身不提供这些可执行助手，相关实现被留给后续 PR。
读取技能定义的探测命令结果，选择 doca-env、version-matrix、capability-snapshot、validate-before-commit 或主机/DPU 状态收集模式。它可指导代理运行 doca_caps、pkg-config、uname、lsmod、ip、lspci、devlink、mlxconfig、flint 等命令，或读取 DOCA 安装目录中的版本、样本和矩阵文件。代理随后按固定字段合并结构化或手动结果，并明确报告采用了结构化路径还是手动回退路径。涉及固件查询或其他特权命令时，技能要求通过已批准的特权渠道执行，不能隐式提权。
- DOCA 工程师想用一个命令汇总安装版本、可见 PCIe 函数、库、驱动和 hugepage 状态。
- BlueField 运维人员需要列出 PF、VF、SF、代表端口、PCIe 地址及设备状态。
- 开发者想确认某个 DOCA 能力从哪个版本开始可用，并与当前安装版本交叉核对。
- 提交或创建 DOCA 规格前，工程师需要执行安全的验证流程并区分失败与无法验证。
- 排障人员需要分别收集主机和 DPU 状态，再比较版本、固件、内核、模块和设备差异。
这个 Skill 有哪些优点和局限？
- 为环境、版本、设备能力、验证和跨侧状态比较定义了明确 JSON 契约。
- 强制先探测、校验输出并报告实际路径，降低误报风险。
- 覆盖 host、BlueField、PF/VF/SF、版本矩阵和特权操作等 DOCA 运维细节。
- SKILL.md 明确说明配套可执行助手尚未随技能提供，结构化探测通常会失败。
- 验证步骤需要位于 /opt/mellanox/doca 的实时 DOCA 安装；部分手动命令还需要已批准的特权渠道。
- 它是检测、回退和模式契约，不是通用 DOCA 入门、库 API 教程或从零安装指南。
如何安装这个 Skill？
使用仓库 README 中的 skills CLI 安装指定技能：
npx skills add nvidia/skills --skill doca-structured-tools-contract --yes
README 未说明该技能的具体本地安装目录；CLI 会提示选择安装目标。
如何使用这个 Skill？
安装后，在相关任务中提出例如“有没有一个命令能告诉我 DOCA 安装的全部信息？”或“比较主机和 DPU 的 DOCA 状态”。代理应先运行所选模式的探测命令；成功且 JSON 符合契约时使用结构化结果，否则报告实际探测失败原因并执行同一模式的手动命令链。