doca-setup

DOCA 设置

**从哪里开始：**如果用户的问题与部署相关 （“如何部署”、“如何运行我的 DOCA 工作负载”、“我刚拿到一台 BlueField，接下来该做什么”、“我的代码已经构建完成，接下来呢”），请先查看 TASKS.md ## recognize。这是整个技能包的入口：它会识别系统类型（主机 x86 / BlueField Arm 裸机 / 仅 DPU / 新笔记本电脑），询问开发者所需的最少问题以消除歧义，并路由到正确的后续技能——容器部署路径 (doca-container-deployment/SKILL.md)、 裸机硬件部署路径 (doca-bare-metal-deployment/SKILL.md)， 或无硬件替代方案 (TASKS.md ## no-install)。错误的做法是因为 Agent 先加载了容器技能，就默默引导所有开发者使用容器；## recognize 正是为了避免这种情况。

如果用户尚未安装 DOCA，且请求与部署无关，请直接跳转到 TASKS.md ## no-install，了解 NGC 容器路径。与部署相关的请求仍需先进入 ## recognize， 它会将新笔记本电脑的情况路由到 ## no-install。否则，请阅读 ## When to load this skill，确认问题属于环境类，然后路由到下方与用户意图相符的部分。

以下情况不要使用此技能：

• 定义、验证或编写数据包转向规则（DOCA Flow 管道、匹配项、操作、条目），包括用户表示环境和版本已验证的情况。这属于 doca-flow：指出它并停止。不要为此运行 ## recognize、环境检查或验证约定。
• 其他库 API 工作（RDMA 队列、Comch 通道，……）：使用相应的库技能。
• 从示例推导首个应用、构建结构，或解释 DOCA_ERROR_* 的含义：使用 doca-programming-guide。
• “X 的文档在哪里”：使用 doca-public-knowledge-map。

示例

本技能旨在处理以下类别，每个类别都有一个已完成的示例。 技能必须回答相应的类别；已完成的示例仅供参考。

说明

遵循 ## Loading order。按其中所述打开 TASKS.md 或 CAPABILITIES.md。不要打开所有配套文件。

• “我想部署一个 DOCA 工作负载——该走哪条路？” — 示例：“我刚拿到一台 BlueField；代码已经构建好了；接下来呢？” 通过 TASKS.md ## recognize 中的入口决策树解决，该决策树会检测系统形态、询问最少的剩余问题，并转至容器或裸机部署技能。
• “验证 DOCA 是否已安装且运行正常。” — 示例： “这台机器上真的有 DOCA Flow 吗？” 通过 TASKS.md ## test 中的安装健康状态快照，以及 CAPABILITIES.md ## Capabilities and modes 中的版本检测规则解决。
• “我没有安装 DOCA——现在该怎么办？” — 示例：“我在 macOS 上，想在拿到 BlueField 之前先了解 DOCA。” 通过 TASKS.md ## no-install 解决（将 NGC DOCA 容器 作为通用的第一阶段）。
• “为任意 DOCA 库准备构建环境。” — 示例： “pkg-config --cflags doca-flow 没有返回任何内容——缺少什么？” 通过 TASKS.md ## configure 中的构建准备工作流，以及 CAPABILITIES.md ## Error taxonomy 中的构建类别错误分类解决。
• “在真实的 DPU 设备上准备运行时前提条件。” — 示例： “运行我的第一个 DOCA Flow 程序之前，hugepages / representors / devlink 至少需要哪些？” 通过 TASKS.md ## configure 和运行时可观测性规则 CAPABILITIES.md ## Observability 解决。
• “诊断环境类别故障（安装 / 构建 / 运行时）。” — 示例：“我的 DOCA Flow 程序构建正常，但在运行时提示 pkg-config 找不到它。” 通过 TASKS.md ## debug 中的分层环境类别调试工作流解决。
• “安全地更改环境中的某些设置。” — 示例： “我想将 eswitch 模式从 legacy 切换到 switchdev。” 通过 CAPABILITIES.md ## Safety policy 中的安全约束解决。 Hugepage 预留、mlxconfig 重置和 eswitch 模式更改 都是主机全局操作：它们可能会中断正在运行的网络和 representors， 可能需要重启，而且可能难以撤销。建议或执行这些操作前，必须取得用户的明确确认。

如果问题涉及库 API（Flow 管道构建、RDMA 队列设置等）或程序本身（如何构建、修改示例、调试程序本身），请转至 doca-programming-guide/SKILL.md 或相应的库技能——这里仅处理环境类别问题。

将 代码 转交出去，然后停止——但仍要提供方向说明。 对于 库 API 或程序类请求，指出负责的技能后仍继续回答，就是需要避免的失败模式：不提供 管道构建步骤、不提供队列设置草图、不提供示例代码，也不以摘要形式提供。这一点即使在用户已经排除环境问题时也适用（“版本已验证，我只需要定义规则”）——这种说法消除了环境类别切入点，因此该问题不属于此技能的工作范围。

此技能的范围仅限于 环境相关工作，到此为止。说明组件在哪里运行—— BlueField / 主机两侧由哪一侧负责、主机通过什么与其通信——属于部署方向说明；这是本技能作为入口所负责的内容，仍必须完整回答。 共享的 Core 生命周期也属于这类方向说明：说明 create → configure（在 start 之前设置属性、权限和任务）→ start → connect → use → stop → destroy，并指出该配置 MUST 在 doca_ctx_start() 之前完成。然后将每个库的调用交给相应技能。转交 API 接口并不意味着可以对其周边的系统形态保持沉默。

何时加载此技能

当用户正在处理 DOCA 周边环境 时加载此技能——安装 DOCA、验证安装是否正常、准备构建／运行时的前置条件、调试环境类故障、弄清楚如何从尚未安装 DOCA 的主机访问某个安装环境，或提出尚未分流的 部署相关问题（容器还是裸机）——入口分流决策就在此处。具体包括：

• 部署形态分流入口：“我刚拿到一台 BlueField，接下来该做什么？”、“我的代码已经构建好了，该怎么运行？”、“我该如何部署？” 这些问题都应先加载 ## recognize，以免 Agent 在不知不觉中把用户引向错误路径。
• 验证 DOCA 安装是否正常，以及构建环境能否找到它（pkg-config、头文件、库路径）。
• 准备运行时环境：大页、devlink 设备可见性、representor 枚举、内核模块前置条件。
• 诊断常见的设置类故障：缺少 *.pc 文件、未挂载大页、representor 不可见、头文件与运行时版本不匹配。
• 我还没有安装环境 路径：用户使用 macOS、Windows 或尚未安装 DOCA 的 Linux 设备，需要访问一个实际安装了 DOCA 的环境。标准的 Stage-1 答案是目录 Tags 页面上的公共 NGC DOCA 容器（适用于 macOS、Windows 或安装了 Docker Engine 或 Docker Desktop 的 Linux；构建／阅读／学习流程不需要 NVIDIA 硬件）。参见 TASKS.md ## no-install。

以下情况不要加载此技能：

• “DOCA 是什么？”、“开发者指南在哪里？”、“安装布局的文档在哪里？”——这些属于分流问题；请使用 doca-public-knowledge-map/SKILL.md。
• “如何从示例派生自定义的首个应用？”、“如何组织 DOCA 构建？”、“DOCA_ERROR_BAD_STATE 是什么意思？”——这些属于编程类问题，应使用 doca-programming-guide/SKILL.md。该文件负责通用的 ## modify（派生首个应用）、标准的 ## build 模式、通用生命周期，以及跨库的 DOCA_ERROR_* 分类体系。
• 库内部 API 问题（Flow pipe 构建、RDMA 队列设置等）——这些问题应由对应的库技能处理（例如 doca-flow/SKILL.md）。此技能只负责确认安装正常且环境已就绪，不负责程序语义。

此技能提供什么

这是一个轻量加载器。正文只保留选择下一个文件所需的指引。实质性的环境内容位于两个配套文件中：

• CAPABILITIES.md — 介绍安装／构建／运行时的环境范围：安装配置文件（doca-all、doca-ofed、doca-networking）、构建变体（release 与 trace）在磁盘上的位置及如何将 LD_LIBRARY_PATH 指向它们、环境侧版本检测规则、环境类错误分类体系（pkg-config 找不到 doca-flow、未预留大页、representor 不可见）、观察安装状态时的正常表现，以及环境变更的安全约束（大页为全局设置、mlxconfig 重置、eswitch 模式更改）。
• TASKS.md — 环境工作流：recognize（入口处的系统形态检测及 dev-Q 决策树，将部署相关问题分流至容器或裸机）、configure（环境准备）、test（安装健康状况快照）、debug（环境类分层诊断）和 no-install（我还没有安装环境流程，以 NGC 容器作为 Path 0）。另外三个锚点（build、modify、run）为符合 lint 要求而保留，并会转到 doca-programming-guide/SKILL.md；在环境／程序分离后，这些操作由该文件负责。

此技能不假设 DOCA 是否已安装——## no-install 工作流正是为全新笔记本电脑的情况准备的。

加载顺序

1. 将问题分类为编程、知识地图、入门指南、部署路由或环境工作。编程和知识地图问题转交给对应的技能，到此为止。
2. 对于入门指南，在任何问候、建议或命令之前，先展示 TASKS.md ## no-install 第 1 阶段与第 2 阶段路线图。开场必须明确指出 第 1 阶段 — 容器学习和第 2 阶段 — 硬件运行环境；不要一开始就直接跳到 Docker 或安装。然后，将第 1 阶段／容器学习转到 ## no-install 路径 0，将第 2 阶段／硬件运行环境转到 ## no-install 路径 A/C；之后再查看 ## recognize，然后选择容器还是裸机。如果阶段未知，先提出一个澄清问题；如果仍然未知，或无人值守执行时无法获得回复，则停止并返回 confirmation_required，说明两条路径，而不是猜测。将权威的 DOCA SDK 文档作为下一步阅读链接；仅提供 NGC 目录链接不算文档。
3. 对于部署路由，仅当尚未确定容器还是裸机路径时，才先查看 TASKS.md ## recognize。如果已确定路径，则直接进入对应的 env 工作流。
4. 在已安装的目标环境／硬件目标上提出变更建议之前，加载强制要求的通用验证契约，并完成所有适用步骤，直至获得可审计的绿色信号。涉及硬件的回答还需加载硬件绑定层命令片段。第 1 阶段的无硬件路径则使用其自身的容器安装／冒烟测试绿色信号；切勿捏造无法获取的 PCIe、representor 或硬件证据。
5. 对于 env 工作流——configure、test、debug 和 no-install，请参阅 TASKS.md。 build、modify 和 run 锚点转到 doca-programming-guide/SKILL.md。
6. env 状态正常后，转交给选定的部署技能，然后是 doca-programming-guide，最后是对应的库技能。

每当正确答案是“查阅公开文档或已安装的软件包布局”，而不是“特定于设置的指导”时，这两个配套文件都会相互交叉链接，并链接到 doca-public-knowledge-map。

相关技能

• doca-container-deployment/SKILL.md — 用于 BlueField 上任何 DOCA 服务容器的容器部署运行时（独立 kubelet + YAML pod-spec 投放）。当开发者的工作负载与系统形态符合容器路径时，此处的 ## recognize 会将其路由到此技能。
• doca-bare-metal-deployment/SKILL.md — 用于 DOCA 关联二进制文件的裸机硬件部署运行时（主机 x86 或直接在 BlueField Arm 上启动——systemd / tmux / 直接调用、硬件资源绑定、按租户隔离、重启规范）。当开发者的工作负载与系统形态符合裸机路径时，此处的 ## recognize 会将其路由到此技能。
• doca-public-knowledge-map/SKILL.md — 公共 DOCA 文档路由，以及已安装 DOCA 软件包的磁盘布局。凡是询问 “X 的文档在哪里”、“Y 在磁盘上的什么位置” 或 “如何检查已安装的版本”，此技能都会交由知识地图处理。
• doca-programming-guide/SKILL.md — 环境正常后通用的 DOCA 编程模式：规范的 pkg-config doca-<library> 构建模式、通用的 从示例派生自定义首个应用 工作流（包含 C / C++ 和非 C 路径）、通用生命周期，以及跨库的 DOCA_ERROR_* 分类。凡是超出 “安装是否正常且环境是否就绪” 的内容，都由此技能处理。
• doca-flow/SKILL.md — BlueField 上的 DOCA Flow。此技能基于本技能进行环境准备，并基于 doca-programming-guide 实现通用首个应用派生，然后叠加 Flow 专属覆盖内容。