doca-comm-channel-admin

DOCA Comm Channel Admin Tool

示例

• “当前可以看到哪些 comch 服务和连接？” — 这属于本工具的范围。请留在管理 CLI 中；不要通过此技能 打开新的 comch 通道。
• “程序报告 CONNECTED，但管理工具列出的通道数为零。” — 在重写 comch 应用之前，先交叉核对 representor 绑定。

说明

请遵循下文的加载顺序。打开任务配套文件，了解运行 / 调试。打开功能配套文件，了解表格列和 错误层级。不要打开所有配套文件。

实际二进制文件契约。 doca_comm_channel_admin 是一项 不接受应用参数、只读的扫描并打印操作。 它通过 resourcedump（MFT）扫描当前侧每个支持 comch 的 doca_dev， 并打印 SERVERS 和 CONNECTIONS 表格。 它没有 list、inspect、设备范围限定、drain、restart 或其他 应用操作。本技能不会使用虚构的命令名称保留概念性 工作流。

从何处开始： 这是一个用于调用 DOCA Comm Channel Admin Tool 的工具技能——它是与 doca-comch/SKILL.md 库对应的只读清单 CLI。 随附的 doca_comm_channel_admin 二进制文件除了 ARGP 默认参数 （--help、--version、--log-level、 --sdk-log-level、--json）之外不接受任何参数， 且每次调用只执行一次清单扫描：它会遍历此侧的每个 doca_dev，筛选出支持 comch 的设备， 对每台设备调用 resourcedump（MFT），并打印两个 ASCII 表格（SERVERS 和 CONNECTIONS）。 它没有 list 子命令、没有 inspect 子命令、没有 drain 标志，也没有 restart 标志——这些都不属于 该工具的功能范围。打开任务配套文件，从 ## run 开始了解单次调用方式；如果用户报告工具看到的通道集合 与程序不同，则从 ## debug 开始。 如果用户询问的是打印出的表格实际表示什么以及哪些内容不在 此工具的范围内，请打开功能配套文件。如果用户尚未安装 DOCA， 请先转到 doca-setup/SKILL.md；如果用户需要 MFT（PATH 中有 resourcedump，并具备已安装版本文档所述的权限），则由 doca-setup + doca-public-knowledge-map 介绍相关内容。如果用户手上的是 提及“Comm Channel”的 2.5 之前文档，请转到 doca-comch/SKILL.md 了解更名规则。如果用户想要更改通道 状态，请转到 doca-comch/SKILL.md 中的程序端 重连生命周期，或转到 doca-setup/SKILL.md + doca-hardware-safety/SKILL.md 了解 BlueField 模式 / 驱动程序重载——不要 转到此工具。

此技能擅长回答的示例问题

此技能旨在回答的管理工具问题类别，每类各有一个完整示例。类别是关键所在；完整示例只是其中一个实例。

• “目前可以看到哪些 comch 服务器和连接？” — 完整示例：“打印此端可见的每一行服务器和连接”。由 capabilities 配套文档中的扫描并打印功能
  • tasks 配套文档中的单次调用回答。
• “工具对这个服务器或连接报告了什么？” — 在 SERVERS 或 CONNECTIONS 表中找到匹配的行； 不需要再按通道单独查询。由 capabilities 配套文档
  • tasks 配套文档回答。
• “我怎么知道管理工具看到的内容与我的 Comch 程序看到的内容一致？” — 完整示例：“程序报告 CONNECTED，但管理工具列出的通道数为零”。由 tasks 配套文档中的交叉核对模式，以及 capabilities 配套文档中的 representor 绑定层回答。
• “我的已安装 DOCA 版本是否包含此管理工具，它是否 与 comch 库版本匹配？” — 完整示例：“此工具在 DOCA 2.4 上是否可用”。由 capabilities 配套文档中的补充说明回答，该说明会跳转到规范的 doca-version/SKILL.md 规则，并补充 Comm Channel Admin Tool 的具体说明。
• “工具没有打印任何内容——是安装出问题了，还是确实 没有通道？” — 完整示例：“在一个已知 Comch 客户端正常 工作的主机上，list 返回了空结果”。 由 tasks 配套文档中的空输出解读规则 + capabilities 配套文档回答。

受众

此技能面向需要从外部盘点主机到 DPU 的 comch 通道的 外部操作员和 AI Agent——他们已使用 doca-comch/SKILL.md 库从程序中创建通道。具体包括：

• 在 BlueField 上运行使用 Comch 的服务，并需要在宣布 服务就绪之前确认通道运行正常的平台操作员。
• 遇到 DOCA_ERROR_AGAIN 或程序端无响应的 Comch 消费者 开发者，他们希望从程序外部读取通道状态，而不是凭猜测。
• 在建议更改程序端代码或生命周期之前，先捕获外部服务器／连接 行的 AI Agent。

此技能不适用于调试管理工具本身的用户，不能替代 当前公开的 DOCA Comm Channel Admin Tool 指南， 也不适合学习 comch API 的用户——此类用户应使用 doca-comch/SKILL.md。

此工具以 CLI 二进制文件的形式随附于 /opt/mellanox/doca/tools/ 下，并非供你链接的库。此 技能采用与套件其余部分相同的 kind: tool 三文件结构， 以确保 Agent 的任务动词约定 （configure / build / modify / run / test / debug）在 库、服务和工具之间保持一致。

何时加载此技能

当用户需要在安装了 DOCA 的真实主机或 BlueField Arm 上 调用 DOCA Comm Channel Admin Tool 时（或在已正确直通设备的公开 NGC DOCA 容器内调用时），请加载此技能。具体包括：

• 列出主机或 DPU 上当前活跃的 comch 通道。
• 从完整的无参数扫描结果中读取某个指定服务器或连接的行。
• 当管理工具的视图与程序端连接回调状态看起来不一致时， 对两者进行交叉核对。
• 捕获无副作用的通道快照，作为后续跨越程序／ 通道／驱动层的调试会话的前置证据。

一般 DOCA 介绍、comch 编程 API、库安装或 comch 协议设计，请勿加载此技能。对于这些内容，请转到 doca-public-knowledge-map/SKILL.md、 doca-comch/SKILL.md 或 doca-setup/SKILL.md。

此技能提供的内容

这是一个轻量加载器。实质性内容位于两个配套文件中：

• 功能配套文件——Comm Channel Admin Tool 报告的内容：两个只读表格、会跳转至 doca-version/SKILL.md 的版本可用性覆盖层、分层错误分类（工具未安装 / 设备绑定 / 通道发现 / 通道状态卡住 / 权限 / 版本 / 跨领域）、该工具作为 doca-comch/SKILL.md 调试会话的可观测性基础工具的角色，以及只读安全策略。
• 任务配套文件——适用任务动词的分步工作流：configure（转到安装流程）、build（转到安装流程）、modify（拒绝）、run（扫描并打印一次）、test（交叉核对打印的行）、debug（分层诊断流程），以及一个 Deferred task verbs 部分和一个遵循此工具包 doca-structured-tools-contract/SKILL.md 前言要求的 Command appendix。

此技能假定主机或 BlueField 已安装 DOCA（或者正在运行已正确直通设备的公开 NGC DOCA 容器），并且操作员拥有公开 DOCA Comm Channel Admin Tool 指南要求的所有权限。

此技能有意不提供的内容

此技能是面向 Agent 的指导，不是示例或脚本工具包。为明确边界，此技能有意不包含以下内容，拉取请求也不应添加：

• 逐字列出的标志、子命令名称或输出列名称。 docs.nvidia.com 上的公开 DOCA Comm Channel Admin Tool 指南与用户所用版本中安装的 --help 共同构成权威信息源；在此处复制这些内容会把技能固定到某个版本，并在工具演进时悄然过时。此技能会引导 Agent 查阅这些信息源。
• 预先准备的示例输出。 输出因安装情况、版本和通道状态而异。捕获的示例可能会误导使用不同平台 / 状态的操作员。
• 以任何语言编写的包装器、解析器或脚本，用于处理管理工具的输出。输出格式已有文档说明；若用户希望据此编写脚本，应阅读最新版指南，并针对其安装版本编写解析器。
• samples/ 或 reference/ 子目录。 这是一个用于文档化 CLI 的轻量加载器；实质性内容位于公开页面和 --help 中。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围（用户想从外部盘点 comch 通道，而不是了解 comch API）。
2. 有关该工具报告的内容、版本可用性、分层错误表面、可观测性和安全态势，请参阅功能配套文件。
3. 有关单次调用和交叉核对工作流——configure、build、modify、run、test、debug，以及 Command appendix——请参阅任务配套文件。

相关技能

• doca-comch/SKILL.md — 此工具盘点其通道的库。 每次故障排查都应将两者配合使用：程序端的连接回调和 管理工具中的通道状态共同构成了完整图景。
• doca-public-knowledge-map/SKILL.md — 用于跳转到公开的 DOCA Comm Channel Admin Tool 指南，以及 其他公开 DOCA 文档。
• doca-version/SKILL.md — DOCA 版本处理的权威规则。能力配套文档中的 ## Version compatibility 部分是精简的补充说明，正文请参阅此处。
• doca-structured-tools-contract/SKILL.md — 此套件针对结构化辅助工具的 detect → prefer → fall back → report 合约。任务配套文档中的 Command 附录遵循此合约。
• doca-setup/SKILL.md — 环境准备、 安装验证、representor 可见性检查，以及使用公开 NGC DOCA 容器的 我还没有安装 流程。使用此技能前，须先满足其前置条件。
• doca-debug/SKILL.md — 跨领域的 调试步骤。Comm Channel Admin Tool 位于 运行时 层，在建议修改代码前提供只读盘点界面。