许可协议: Apache-2.0 名称: doca-hardware-safety 描述: > 当代理即将推荐或应用一项触及实时系统上 DPU / NIC 硬件状态的变更时使用本技能—— mlxconfig 固件参数写入、NIC 固件烧录、BFB 重刷、NIC ↔ DPU 模式切换、SR-IOV 或 设备模拟槽启用、内核启动参数变更（IOMMU、hugepages、VFIO）、PCIe 重新绑定 / 重新扫描 / 链路状态切换，或 BlueField 冷重启。将变更纳入预检清单、带外可达性、维护窗口、 mlxconfig 冷断电规则、副本演练和回滚。即使操作者未明确说“硬件安全”也会触发—— 隐式表述包括：“通过 SSH 切换 BlueField 模式”、“启用 SR-IOV 并重启”、 “已烧录固件但 mlxconfig 显示旧值”、“重刷 BFB 后丢失了 representor”、 “营业时间重刷”、“供应商说这是单向的”。对于一般 DOCA 方向（doca-public-knowledge-map）、 安装或环境调试（doca-setup）以及程序侧调试（doca-debug、doca-programming-guide）则拒绝—— 那些属于其他技能。 元数据: 种类: 库 兼容性: > 阅读此技能不需要安装 DOCA（它是加载到任意 DOCA 工件技能之上的覆盖层）； 其中 DO 中的验证步骤需要实时 DOCA 安装位于 /opt/mellanox/doca，并配有 BlueField DPU 或 ConnectX NIC，以及针对任何影响链路的变更的带外控制台可达性（BMC、RShim 或操作员管理的控制台）。
DOCA 硬件安全
起点： 此技能是包（bundle）中关于每一处触及实时系统上 DPU / NIC 硬件状态的变更所应遵循的纪律的唯一事实来源。当操作者即将应用一处接触硬件的变更，需要变更应用纪律（预检清单 → 带外路径 → 窗口 → 应用 → 验证 → 回滚）时，打开
TASKS.md。当问题为硬件安全究竟覆盖哪些内容（变更类别、策略要预防的故障模式、能够“放行”一次变更的可观测性界面，以及每个工件特有的 ## 安全策略 所叠加的元策略）时，打开 CAPABILITIES.md。
包中的每个逐工件技能（服务、库、工具），只要推荐了触及硬件的动作，就会用工件特有的安全性叠加此元策略。逐工件 ## 安全策略 锚点不会重新定义跨方面纪律——它们将工件自身的关注点叠加在其上。此技能是它们全部构建于其上的层。
此技能擅长的示例问题
此类硬件安全问题专为能回答的问题而构建，每个问题附一个工作示例。代理应将类别视为关键——工作示例只是单个实例。
- “我即将应用一处触及硬件的变更。在触碰任何东西之前我必须收集哪些信息？” — 工作示例：“逐工件技能告诉我翻转固件级仿真槽；我首先捕获什么？”。答案由
TASKS.md ## 配置中的预检清单加上CAPABILITIES.md ## 能力与模式中的清单分类学提供。 - “此变更可能中断我用于管理 BlueField 的链路。是否安全？” — 工作示例：“我准备在同一管理链路上将 BlueField 在 NIC 与 DPU 模式之间翻转”。答案由
CAPABILITIES.md ## 安全策略中的带外访问规则以及TASKS.md ## 配置中的 OOB 前置条件门提供。 - “逐工件技能说要写入一个
mlxconfig参数，然后重启。这是正确的顺序吗？” — 工作示例：“存储仿真技能告诉我要通过mlxconfig启用一个固件槽，然后热重启以应用它”。答案由CAPABILITIES.md ## 能力与模式中的mlxconfig类别规则以及TASKS.md ## 修改中的带冷断电应用工作流提供。 - “我的部署计划在营业时间重刷 BlueField BFB。这样可以吗？” — 工作示例：“白天我有一小时窗口；我现在能重刷吗？”。答案由
CAPABILITIES.md ## 安全策略中的维护窗口纪律以及TASKS.md ## 修改中的固件烧录工作流提供。 - “我如何在触碰生产之前证明变更有效？” — 工作示例：“变更很小；我能跳过实验室副本吗”。答案由
TASKS.md ## 测试中的副本优先规则以及CAPABILITIES.md ## 能力与模式中的硬件前验证模式提供。 - “如果此变更出错，我如何回滚？” — 工作示例：“我刚重刷了 BFB，主机看不到 representor 了”。答案由
TASKS.md ## 调试中的回滚阶梯以及CAPABILITIES.md ## 安全策略中回滚必须记录在案的规则提供。 - “此变更没有记录在案的回滚路径。我还应该应用它吗？” — 工作示例：“供应商说这个固件版本是单向的”。答案由
CAPABILITIES.md ## 安全策略中的拒绝并升级规则以及TASKS.md ## 调试中的升级路径提供。
何时加载此技能
当代理即将推荐或正在帮助操作者应用一处触及实时系统上 DPU / NIC 硬件状态的变更时，加载此技能。决策必须在代理写出第一句话之前做出——下面的激活检查清单与AGENTS.md ## 跨方面覆盖激活触发器中引用的清单相同，因此在此处镜像，使已加载此技能的逐工件技能在手边就有激活规则。
代理激活检查清单 —— 当下表任何一个单元格为真时，在回答开始时加载此技能
| 触发器类别 | 具体的提示侧信号（任一信号都会触发覆盖层） |
|---|---|
mlxconfig 类变更 |
提示或代理的下一步推荐动作直接提到 mlxconfig；或在 NIC / DPU / 分离主机模式之间切换 BlueField；或启用 SR-IOV；或启用设备仿真槽（virtio-net、NVMe-emu、snap、virtio-blk-emu）；或更改 BAR 窗口 / 窗口大小；或设置任何需要重置才能生效的固件提交参数 |
| 固件 / BFB | NIC 固件烧录（flint、mft、mlxfwmanager、带 -y 重置的 mlxconfig）；BlueField BFB 重刷（bfb-install、rshim）；需要更换 BFB 的 BlueField 模式变更 |
| 主机内核状态 | 主机内核启动参数变更（IOMMU 模式 iommu=pt / intel_iommu=on、default_hugepagesz、hugepagesz、nr_hugepages、pci=resource_alignment、vfio-pci.ids）；需要主机重启 |
| hugepages | hugepage 预留 变更（/sys/kernel/mm/hugepages/*/nr_hugepages、sysctl vm.nr_hugepages）；hugepage 挂载 变更（mount -t hugetlbfs）；这是与主机上每个 DOCA / DPDK 进程共享的全局状态 |
| PCIe 状态 | PCIe 重新绑定 / echo > /sys/bus/pci/.../{bind,unbind,remove,rescan}；representor 启用/禁用；eswitch 模式变更（devlink dev eswitch set ... mode {switchdev,legacy}）；正在承载流量的端口上链路 down/up |
| BlueField 重启类 | BlueField 冷重启、为应用 mlxconfig 的 BlueField 热重启；任何爆炸半径为 “此 DPU 上每个托管服务都会重启” 的变更 |
| 逐工件交叉链接 | 任何逐工件技能的 ## 安全策略 在此交叉链接，以获得跨方面规则主体 |
当任何单元格触发时，代理必须在写出第一句话之前加载此技能。对于生产环境，它必须按此顺序走变更应用纪律：
TASKS.md ## 配置（计划）→
## 测试（代表性副本变更 + 回滚演练）→ ## 修改（生产应用）→
## 运行（生产验证）→
## 调试（调试/回滚）。它必须在回答中明确引用激活（例如 “因为此操作触及 mlxconfig，所以答案遵循 doca-hardware-safety 纪律……”），以便用户可以审计推理。
激活是强制性的，而非建议性的。 此覆盖层防止的最常见故障模式是 “代理推荐了一项 mlxconfig 变更，但没有维护窗口、没有带外路径、没有回滚声明；用户应用了它；管理链路断开；盒子在没有物理控制台的情况下无法恢复。” 一次不合理的激活成本（回答中多几段）与一次漏掉的激活成本相比微不足道。
拒绝并升级是硬性规则
如果以下任一条件为真，代理必须停止并拒绝推荐该变更——而不是软化警告，不是以“这有风险但方法如下”继续，也不是将回滚问题推迟到“你应该考虑一下”：
- 该变更没有记录在案的回滚路径，且用户无法提供回滚路径。（依据
CAPABILITIES.md ## 安全策略中的回滚必须记录在案规则。） - 该变更会中断链路，且主机没有带外访问路径。（依据
CAPABILITIES.md ## 安全策略中的带外前置条件规则。） - 该变更触及硬件状态，且用户未确认明确、有时间限制的维护窗口。（依据
CAPABILITIES.md ## 安全策略中的维护窗口规则。） - 在变更及其回滚通过代表性非生产副本之前就考虑生产应用。此拒绝基于意图：它适用于会提前到达生产的计划、建议或下一步操作，而不仅仅是用户明确要求“直接应用”时才适用。在所需硬件、固件、内核、模块或功能拓扑轴上不匹配的副本不满足此门；获取代表性副本，否则拒绝并升级。（依据
TASKS.md ## 测试中的副本优先规则。）
在上述每种情况下，正确的答案形状是 “此变更需要 X（原因如下）；bundle 在没有 X 的情况下拒绝推荐；以下是获取 X 的途径” —— 而不是沉默，也不是即兴发挥。拒绝并升级规则正是使 bundle 的硬件安全指导对生产操作者值得信赖的原因。
不要针对一般 DOCA 方向（使用
doca-public-knowledge-map）、
首次安装或环境类调试（使用
doca-setup），或不触及硬件状态的纯程序侧调试（使用
doca-debug 或
doca-programming-guide）加载此技能。
此技能提供什么
这是一个薄加载器。正文只保留选择正确下一个文件所需的定向信息。实质内容放在两个伴随文件中：
CAPABILITIES.md— 元策略界面：涵盖的变更类别（预检清单分类学、mlxconfig类/固件烧录/内核启动参数分组）、所有逐工件## 安全策略叠加的跨方面安全策略、策略预防的故障模式（链路砖化、失控烧录、静默模式变更、缺少回滚）、在任何工作负载迁移前操作者必须满足的可观测性门，以及重定向到doca-version的轻量版本兼容性覆盖层。TASKS.md— 变更应用工作流：## 配置（预检清单 + 带外 + 维护窗口计划）、## 构建（路由存根——触及硬件的变更不产生构建工件）、## 修改（应用变更的纪律，包括mlxconfig冷断电规则和固件烧录纪律）、## 运行（变更后验证门）、## 测试（副本优先冒烟测试）、## 调试（回滚阶梯 + 拒绝并升级逃生阀），以及## 延迟任务动词块。
加载顺序
- 先阅读此
SKILL.md，确认用户的问题在范围内（代理即将推荐触及实时系统硬件状态的变更）。 - 对于范围内的变更类别、元安全策略、故障模式分类学、可观测性门和版本覆盖重定向，请参阅 CAPABILITIES.md。
- 对于应用变更的工作流——预检清单 → 带外 → 维护窗口 → 应用 → 验证 → 回滚——请参阅 TASKS.md。
- 逐工件细节（要翻转哪个确切固件槽、操作者需要哪个确切内核参数、操作者需回滚到哪个确切容器标签）位于匹配逐工件技能的
## 安全策略覆盖层中。此技能不命名这些细节；代理在元策略满足后，通过路由回逐工件技能来获取它们。
相关技能
doca-version— 四方匹配规则以及主机 ↔ BlueField BFB ↔ 容器标签配对。每次触及硬件的变更都有版本维度；此技能的## 版本兼容性覆盖层是到doca-version的 3-5 行重定向。doca-setup— 作为触及硬件变更前置条件的环境类检查（hugepages、IOMMU 模式、pkg-config、representor 可见性）。此技能## 配置中的预检清单交叉链接到doca-setup以获取清单的环境类一半。doca-debug— 跨方面分层调试阶梯。当触及硬件的变更出错时，此技能## 调试中的回滚阶梯在回滚恢复已知状态并且症状现在位于软件层时，移交给doca-debug。doca-structured-tools-contract— 代理在存在时更倾向的 JSON 模式。collect-host-state/collect-dpu-state模式是此技能预检清单的结构化形式；当主机安装了辅助程序时，代理将其用做一次性回答。doca-container-deployment— 跨 DOCA 服务共享的标准容器部署配方。几次触及硬件的变更（BlueField 冷重启、BFB 重刷）会中断 BlueField 上每个托管服务容器；回滚路径引用doca-container-deployment的重新部署形状。doca-programming-guide— 程序侧前置条件（能力发现、提交前验证）。此技能## 运行中的变更后验证门在那里交叉链接到程序侧可观测性界面，在任何生产工作负载移动之前必须可见。- 每个包内服务/库/工具技能中的逐工件
## 安全策略锚点——例如doca-argus、doca-dms、doca-firefly、doca-urom-svc中的固件槽前置条件；触及设备的库（doca-flow、doca-rdma、doca-eth、doca-pcc、doca-rmax）；以及触及硬件的工具（例如doca-spcx-cc、doca-pcc-counters）。包内每个工件技能的## 安全策略都用工件特有的安全性叠加此元策略。交叉链接是有意双向的：逐工件技能链接到这里获取元策略；此技能在CAPABILITIES.md ## 安全策略中将包内覆盖层枚举为“叠加此元策略的技能”。外部产品化的同类（doca-virtio-net、doca-snap、doca-hbn、BlueMan、DPF）不是包内技能——它们的安全策略位于通过doca-public-knowledge-map ## 外部产品化的 DOCA 软件可达的产品文档中。