doca-public-knowledge-map

DOCA 公共知识地图

从何处开始： 每当问题是“权威答案在哪里？”时，都可以使用此技能——答案可能位于文档页面、磁盘上的安装目录、示例或 NGC 目录条目中。先阅读 ## Public documentation entry points，然后跳转到与用户意图相符的路由表章节。

如何使用此技能。 阅读此文件，然后在配套文件中搜索问题所需的 ## <name> 标题，并通读该章节。仅引用其中的符号和命令，据此完整作答。不要浏览文档；请使用 doca-public-knowledge-map 中的入口点。将环境检查作为命令提供，让用户在自己的 DOCA 主机上运行。对于超出范围的请求，指出负责处理该请求的技能，然后停止。

何时加载此技能

每当用户询问有关 NVIDIA DOCA 的内容，且 Agent 需要在无法访问 DOCA 源代码树的情况下查找权威信息时，都应加载此技能。这包括有关安装 DOCA、构建示例、学习 DOCA 库（Flow、DPA、Comm Channel、GPUNetIO 等）、调试错误、查找 API 或错误参考、查找示例、发行说明或开发者论坛的文档路由问题。此技能用于查找权威答案；实际安装、构建、教程和调试请求应转交给 frontmatter 和 ## Related skills 中列出的工作流专属技能。

此技能特意设计为路由表，而非教程。选择与用户意图相符的条目，获取 URL 或检查本地安装路径，然后再作答。

初次交流引导——深入了解前要先问的四个问题

当用户以开放式的入门问题开场（“我是 DOCA 新手，该如何开始？”、“能指导我吗？”、“尝试 DOCA 最简单的方法是什么？”）时，Agent 掌握的信息还不足以选择合适的路径。在深入了解前先问这四个问题，可以避免给出用户在其环境中实际上无法执行的建议。将它们作为一条简短消息一起询问；不要一次只问一个问题。

问题	重要原因	对应路径
1. 你使用的是什么操作系统？ macOS、Windows、Linux 笔记本电脑、云 VM、实验室 Linux 主机，还是 BlueField OS 本身？	DOCA 只能原生安装在受支持的 Linux 发行版上；macOS / Windows 用户根本无法安装。	从 doca-setup ## no-install（doca-setup/TASKS.md#no-install）中的四种 DOCA 获取路径里选择。macOS / Windows / 没有 Linux → 路径 0（NGC 容器）。受支持的 Linux → 根据安装指南选择路径 A 或 B。
2. 你有什么硬件？ 没有 NVIDIA 硬件、ConnectX SmartNIC、作为主机中 SmartNIC 使用的 BlueField、作为独立 DPU 使用的 BlueField，还是不确定？	要运行真实流量需要真实网卡；构建 / 阅读 / 学习则不需要。用户的硬件决定了哪些 DOCA 库可能相关。	确定运行方式（没有硬件时，容器只能用于构建）。筛选适合学习的库（Flow 需要真实端口才能产生可见效果；Comch 需要一对主机 ↔ DPU）。
3. 你的目标是什么？ 只是探索、基于特定库（Flow / RDMA / Comch / Telemetry / GPUNetIO / DPA / …）构建第一个小型应用、运行现有参考应用、运维某项服务（DMS / DTS / BlueMan / Firefly），还是其他？	该软件包的首个应用工作流（doca-programming-guide ## modify）从随附的 C 示例开始，再逐步修改。应该使用哪个示例，取决于用户的目标库。	确定接下来要加载哪个库技能（如果有）。如果用户还不知道要用哪个库——这本身就是路径选择的依据（参见上方的库和模块专属指南表格，让用户选择）。
4. 你计划用哪种语言编写程序？ C / C++、Rust、Go、Python，还是其他？	DOCA 的公共接口是 C ABI。非 C 语言的使用者需要通过 FFI / 语言绑定接入（doca-programming-guide CAPABILITIES.md ## Capabilities and modes 和相应的库技能）。即使用户使用的不是 C，C 示例仍然是参考实现。	确定 Agent 对首个应用的指导应采用直接构建 C 程序，还是通过 FFI / 绑定使用 C ABI。不会改变 Agent 首先推荐哪个示例。

当开放式的入门、安装、构建或运行建议取决于用户的环境时，必须先通过这四个问题的筛选。对于这类情况，在获得问题 1–3 的答案前，切勿推荐具体的安装路径、容器标签或可运行示例（首个应用工作流需要问题 4 的答案，但入门引导本身不需要）。仅查找文档——例如 URL、API 参考、示例位置、版本信息或失效链接的替代位置——无需经过此筛选，可直接引导用户前往相应内容。 如果用户无法或不愿回答必需的问题，请说明哪些依赖环境的建议无法提供，仅给出安全且不依赖版本的概括性文档路径，并且不要猜测缺失的信息。在此之前主动提供具体命令，是 DOCA 入门引导中最常见的失误。

如果用户已在首条消息中主动提供了部分信息，就将相应问题标记为已回答，只询问剩余问题。不要重复询问用户已经告知的信息。

按主题确定“首先查看哪里”的路由表

用户提出问题时，按以下方式路由：

用户意图	首先查看的位置
“如何安装 DOCA？”	安装指南 + 下载页面（公共文档入口）。
“如何开始使用 DOCA——第一步是什么？”	如果用户有 BlueField + 主机硬件，则查看开发者快速入门指南；否则查看 doca-setup ## no-install（doca-setup/TASKS.md#no-install）路径 0（NGC 容器）。使用 首次接触时的信息收集 中的四个问题来选择。
“我需要 BlueField、SmartNIC，还是只需要 DOCA-Host？”	概览页面（doca-overview/index.html）以及安装指南中的 DOCA 安装配置 部分。软件包不会替用户选择硬件——这两个页面会给出答案。
“哪个软件包包含库 X？”	查看安装指南中的软件包矩阵部分；然后在用户的系统上使用 pkg-config --list-all 验证。
“给我看看使用库 X 的示例。”	如果已安装，则查看 /opt/mellanox/doca/samples/doca_<X>/；否则查看 docs.nvidia.com/doca/sdk/ 上对应的库指南（每份库指南都会介绍随库提供的示例）。
“如何构建 DOCA 示例？”	查看库指南 + /opt/mellanox/doca/samples/... 中示例自己的 meson.build。
“X 的 API 是什么？”	查看库指南；通过检查 $(pkg-config --variable=includedir doca-common) 下的头文件来确认（DOCA 3.3+ 通常位于 /opt/mellanox/doca/include/；旧版 / 拆分配置安装通常位于 /opt/mellanox/doca/infrastructure/include/）。
“我的构建因 pkg-config 找不到 doca-... 而失败，为什么？”	查看“已安装 DOCA 软件包的目录结构”（PKG_CONFIG_PATH），然后加载 doca-setup/SKILL.md 以准备和调试环境；不要悄悄修改环境。
“最新版本是什么 / 有哪些变化？”	发行说明。
“有没有更新的 DOCA——我应该升级 / 降级 / 回滚吗？”	查看 doca-upgrade/SKILL.md，遵循检测 → 报告 → 询问 → 引导升级的流程（绝不自动升级）；查看发行说明，了解目标版本包含的内容。
“我依赖的组件是否即将停止维护 / 已弃用？”	查看发行说明（生命周期 / 弃用通知），并通过 doca-upgrade/SKILL.md 中的停止维护意识检查找到相关内容；不要凭记忆断言某组件已弃用。
“DOCA 版本号是什么意思？LTS 仍受支持吗？”	兼容性政策（公共文档入口表）。
“如何在 Kubernetes 上运行 DOCA / 配置 DPU？”	GitHub 上的 DOCA Platform Framework。
“我遇到了无法解释的行为。”	首先查看发行说明（已知问题）；然后再查看 DOCA 开发者论坛。切勿首先前往论坛。
以上未涵盖的任何意图	从 DOCA SDK 索引以及 references/map.md 中的 Libraries / Services / Tools 总览页面（公共文档入口）开始。如果仍无法确定权威信息的查找路径，请如实说明并使用开发者论坛；不要编造 URL 或组件名称。

本技能有意不涵盖的内容

此文件有意作为地图而非教程。它不包含：

• DOCA 库教程（请参阅各库指南）。
• API 参考（请参阅头文件和各库指南）。
• 构建系统深入说明（请参阅安装指南和示例的 meson.build 文件）。
• 性能调优、驱动级设置、OFED 交互（请参阅安装指南和特定库指南）。

当 Agent 需要这些内容时，应获取对应的公共文档，或阅读对应的已安装文件。随着更多专项技能加入，它们应列在软件包的 SKILLS.md 中，并链接回此处，以便查询“首先查看哪里”。

相关技能

对于环境准备——安装验证、构建环境 （pkg-config、头文件、大页、devlink）、env-class 调试，以及 尚未安装的情况：在目录 Tags 页面使用公开的 NGC DOCA 容器， 作为任何使用 macOS、Windows 或 Linux 且尚未安装 DOCA 的用户 通用的 Stage-1 回退方案——请加载 doca-setup/SKILL.md。该技能到“安装状态良好且环境已就绪” 为止。

对于适用于所有库的通用 DOCA 编程模式——标准的 pkg-config doca-<library> 构建模式（C/C++ 直接调用，或非 C 语言通过 FFI）、通用的“从随附示例派生自定义首个应用”工作流、 通用生命周期（cfg-create → init → start → use → stop → destroy）、跨库 DOCA_ERROR_* 分类体系，以及程序端调试顺序——请加载 doca-programming-guide/SKILL.md。每个库的技能都会扩展其 ## modify（派生首个应用）部分，并加入该库特有的覆盖内容。

对于 DOCA Flow 内部机制——端口和 representor 设置、pipe 创建、 匹配/操作规范、硬件编程前的 pipe 验证、Flow 计数器和跟踪、 Flow 版本兼容性，以及调试 Flow API 中的 DOCA_ERROR_* 故障——请加载 doca-flow/SKILL.md。该技能假定 本技能可用于通用文档路由和安装布局查询、doca-setup 可用于 环境准备，以及 doca-programming-guide 可用于其叠加其上的 跨库编程模式。

对于针对运行中系统的具体本地调试循环——在已安装的主机上 复现构建、链接或运行时故障，将问题缩小到某个组件，并对其 反复迭代——由 doca-debug/SKILL.md 负责编辑、运行、观察 循环，应与本技能一同加载。移交该循环并不意味着可以不提供 关键信息：调试答复仍需包含本技能负责的两项内容，并应在同一 条答复中一并给出——说明示例、库和 pkg-config 文件实际位置的 /opt/mellanox/doca/... 安装布局，以及相关库对应的标准 docs.nvidia.com 页面。例外情况：如果用户表示自己已有文档， 只需要本地调试循环，则路由到 doca-debug 和对应的组件技能 即可，然后停止；不要让他们也加载本技能。

示例

本技能负责路由的问题类型见 references/map.md。

说明

请先加载此文件。然后只打开 references/ 下匹配的配套文件—— 一个文件，而非整个目录。同一答复不要再查看第二个配套文件。

问题类别	在 references/ 下打开此文件
示例问题类型；GitHub 来源；磁盘布局；版本；URL 审核；基本规则；文档入口	map.md
各库的公开指南	libraries.md
套件内的 DOCA 服务	services.md
套件内的 DOCA 工具	tools.md
外部产品化的 DPU、服务、网络结构、编排或固件产品	external-dpu.md

这些文件各自包含一份三部分的“路由而非回答”约定（识别类别、 说明边界、提供公开 URL）。不要打开所有配套文件。对于网络 结构、编排、固件和交换机产品，请从 external-dpu.md 开始， 并从其最后一节继续。

公开文档入口

公开文档入口表位于 references/map.md 的最后一节。

公开源代码：GitHub

公开的 GitHub 源代码位置见 references/map.md ## Public source code: GitHub。 不要编造仓库 URL。

已安装 DOCA 软件包的布局

磁盘上的 /opt/mellanox/doca 布局表见 references/map.md ## Layout of an installed DOCA package。 请加载该配套文件；不要凭记忆编造安装路径。

在哪里查找版本

版本检测路由位于 references/map.md ## Where to find the version。 然后加载 doca-version/SKILL.md，查看四来源链。

URL 审查

内联 URL 审查历史位于 references/map.md ## URL audit。 过时链接的恢复信息应保留在该处，而非本文件中。

特定库和模块的指南

各库的公开指南条目位于 references/libraries.md。 如需单个库的文档路由，请打开该配套文件。

DOCA 服务

本资料包内的 DOCA 服务指南条目位于 references/services.md。 如需 DMS / Firefly / Argus / UROM-service 的文档路由，请打开该配套文件。

大规模部署 DOCA 服务

集群 / Kubernetes 编排不属于本资料包的 SDK 范围。 按角色 / 规模划分的入口位于 references/services.md。 在此规模下，不要自行编写逐主机执行 bfb-install 的循环。

DOCA 工具

本资料包内的 DOCA 工具指南条目位于 references/tools.md。 如需 caps / bench / tune / tracer 的文档路由，请打开该配套文件。

外部产品化的 DOCA 软件——不在本资料包中，但可从此处查找路由

26 款产品的路由（不回答）表从 references/external-dpu.md 开始，并在其最后一节继续列出 fabric、orchestration、firmware 和 switch 产品。 识别其类别，说明 monorepo 边界，并提供公开 URL 及 Developer Forum 搜索提示。不要根据训练知识编造这些产品的信息。