jetson-diagnostic

Jetson 诊断

以统一且便于 Agent 使用的方式查看正在运行的 Jetson 设备。无需再记住 tegrastats、jtop、procrank、/sys/kernel/debug/nvmap、nvpmodel、free、swapon、df 和 systemctl list-units 分别提供哪部分信息。

用途

从 Jetson 主机采集只读健康快照，让 Agent 根据实时数据而非猜测，回答有关设备身份、内存、GPU、温度、电源、存储和服务状态的问题。

适用场景

在用户询问以下问题时启用：

• “这是什么 Jetson？属于哪个 SKU？内存有多大？”
• “这台 Jetson 目前在运行什么？”
• “我的 Jetson 为什么变慢了／发热了／内存不足了？”
• “给我一份 GPU／CPU／电源使用情况快照。”
• “我的 tegrastats 输出是什么意思？”
• “有哪些服务正在运行，可以关闭哪些？”
• 用户已安装 jetson-memory-audit、jetson-headless-mode、jetson-inference-mem-tune、jetson-llm-benchmark、jetson-llm-serve 或 jetson-package，并需要在运行它们之前进行基线测量。

不要使用此技能更改电源模式、清除缓存、停止服务、安装软件包、提供模型服务或调整推理标志。报告观察到的状态，然后交给面向操作的技能处理。

前提条件

• 在 Jetson 主机上运行，或在能够访问主机 Jetson 系统路径和进程数据的沙盒／容器中运行。

可用脚本

脚本	用途	参数
scripts/snapshot.sh	输出包含设备身份、内存、GPU、温度、电源、磁盘、占用最高的进程和候选服务的一体化 JSON 快照。	--human、--tegra-secs N、--top-procs N。
scripts/mem_summary.sh	输出简洁易读的 RAM／GPU／交换分区摘要。	--short、--watch、--interval N。
scripts/detect_jetson.sh	导出或打印此仓库使用的标准 Jetson SKU／代际／产品线字段。	无参数。

如果你的 Agent 运行时支持 run_script，请使用它运行 scripts/snapshot.sh 或 scripts/mem_summary.sh，并总结返回的输出。否则，请在仓库根目录下使用 bash 运行脚本。

操作说明

1. 运行 scripts/snapshot.sh，获取一体化 JSON 视图（默认首选）。
2. 如需快速查看易读的内存信息行，运行 scripts/mem_summary.sh。
3. 如需解释用户粘贴的单行 tegrastats 输出，请参阅 references/tegrastats-fields.md。
4. 如需解释 NvMap 客户端输出，请参阅 references/nvmap-clients.md。

报告指南

在总结设备状态前，先运行对应的辅助脚本，并且只报告该脚本返回的字段。如果运行时阻止直接执行，请运行 bash {baseDir}/scripts/<script-name>，不要尝试通过 chmod 修改文件权限。

• 对于“这是什么 Jetson”的问题，请引用 product_model 或 sku、variant、l4t_version 和 mem_total_gb。
• 对于“速度慢且发热”的问题，请运行 snapshot.sh，并总结症状的两方面：发热情况的 thermal_c，以及负载情况的 top_processes、gpu_processes、nvmap.top_clients 或 gpu_source。最后给出明确的后续处理建议，例如 jetson-memory-audit、jetson-headless-mode 或 jetson-inference-mem-tune。
• 对于“哪个进程正在使用内存”的问题，请运行 snapshot.sh，并将占用最高的进程列为 pid <number>、cmd 和其 pss_kb / MiB 值。如果 NvMap GPU 内存是相关信号，还要引用 gpu_source 以及排名最高的 nvmap.top_clients 或 gpu_processes 条目。

如果你的 Agent 运行时不会自动相对于此技能目录执行辅助脚本，请使用 AgentSkills {baseDir} 占位符解析脚本路径：

{baseDir}/scripts/snapshot.sh
{baseDir}/scripts/mem_summary.sh

除非运行时明确将技能注册为可调用工具，否则不要将 jetson-diagnostic 作为工具名称调用；Agent Skills 通常由说明和文件组成，而不是直接可调用的工具函数。

所有脚本都会从规范的平台检测器 skills/jetson-diagnostic/scripts/detect_jetson.sh 加载内容（导出 JETSON_SKU、JETSON_GENERATION、JETSON_PRODUCT_LINE、JETSON_VARIANT、JETSON_MEM_GB、JETSON_L4T_VERSION、JETSON_PRODUCT_MODEL）。其他技能可以加载此检测器，而不是重复编写 Jetson 识别逻辑。在非目标平台上会以状态码 2 退出，并显示修复建议。

限制

• 能看到此技能文件并不保证能够访问 Jetson 主机硬件。如果 NemoClaw/OpenClaw 沙盒内缺少 /proc/device-tree/model、/etc/nv_tegra_release、tegrastats、nvpmodel、nvidia-smi 或 /sys/kernel/debug/nvmap，请说明该沙盒无法查看 Jetson 主机，并让用户在 Jetson 主机上运行，或使用可查看主机的沙盒配置重新启动。
• NvMap debugfs 通常需要 root 权限，因此非特权运行可能会报告 gpu_source: "none" 或不完整的 nvmap 字段。
• 此技能只报告观察到的状态。如果工具缺失或无法访问，请勿编造内存、GPU、热状态、服务或回收数据。

错误处理

• 如果辅助脚本因检测到非目标平台而退出，请报告当前环境不是 Jetson 主机或无法查看主机；不要用通用 Linux 值替代。
• 如果 tegrastats、nvpmodel、nvidia-smi 或 NvMap debugfs 不可用，请保留 JSON 中对应的 null、false 或空字段，并说明受限的信号。
• 如果 snapshot.sh 输出格式错误的 JSON，请报告原始故障，并在修复辅助脚本输出后重新运行；不要手动编辑并伪造设备快照。

snapshot.sh 的输出约定

{
  "sku": "orin-nano",
  "generation": "orin",
  "product_line": "orin-nano",
  "variant": "orin-nano-8gb",
  "mem_total_gb": 8,
  "l4t_version": "36.4.0",
  "product_model": "nvidia jetson orin nano developer kit",
  "memory_kb": { "total": 8123456, "available": 4123456, "swap_total": 0, "swap_free": 0, "cached": 1234567 },
  "tegrastats_sample": "RAM 4011/8138MB (lfb 8x4MB) ...",
  "thermal_c": { "CPU": 52.3, "GPU": 49.0, "AO": 47.0 },
  "power": { "nvpmodel_id": 0, "nvpmodel_name": "MAXN" },
  "disk": [ { "mount": "/", "used_pct": 41 } ],
  "gpu_source": "nvmap:iovmm-clients",
  "gpu_devices": [],
  "gpu_processes": [],
  "nvmap": {
    "readable": true,
    "total_kb": 654321,
    "stats_total_bytes": 669985280,
    "top_clients": [ { "pid": 1234, "cmd": "vlm-server", "kb": 524288 } ]
  },
  "top_processes": [ { "pid": 4321, "cmd": "vllm", "pss_kb": 4000000 } ],
  "candidate_services": { "gdm3": { "active": "inactive", "enabled": "disabled" } }
}

gpu_source 指明此技能用于归因每个进程 GPU 内存的具体数据来源，让调用方准确了解这些数值代表什么：

• "nvidia-smi:compute-apps" — 来自 nvidia-smi --query-compute-apps 的每进程 used_memory 值。用于统一的 nvidia.ko 堆栈（目前为 Thor 系列）。注意：在此堆栈上，某些 BSP 的 nvidia-smi 设备级 memory.used 查询会返回 [N/A]，因此此技能会汇总每进程列表，而不是读取顶层总量。汇总总量显示在 gpu_processes[*].used_mib 中。
• "nvmap:iovmm-clients" — 来自 /sys/kernel/debug/nvmap/iovmm/clients 的每进程大小。用于 nvgpu 堆栈（目前为 Orin 系列）；在该堆栈上，nvidia-smi 是一个存根，对所有计算/内存查询都返回 [N/A]。每进程条目显示在 nvmap.top_clients 中；内核侧总量位于 nvmap.total_kb，以及（可读取时）nvmap.stats_total_bytes。
• "none" — 无法访问权威数据源。通常出现在无特权运行于 nvgpu 堆栈的 Jetson 上（/sys/kernel/debug/nvmap 下的 debugfs 需要 sudo）；请使用 sudo 重新运行，以填充 nvmap 字段。

Agent 应向用户呈现关键信息（SKU、可用内存、按 gpu_source 确定的 GPU 最大内存占用者、温度最高的区域、电源模式），并提出可进一步查看具体信息（top_processes、gpu_processes / nvmap、services）。

安全性

此技能为只读。它不会更改 nvpmodel、不会运行 jetson_clocks，也不会修改服务。如需根据发现采取行动，请转交给：

• jetson-memory-audit — 专项内存快照 + drop_caches 验证循环
• jetson-headless-mode — 禁用 GUI 和辅助守护进程（安全、可逆）
• jetson-inference-mem-tune — 选择运行时和内存标志（vLLM / SGLang / llama.cpp / TensorRT Edge-LLM）
• jetson-llm-serve — 使用 Jetson 默认设置的 vLLM 和相关 GHCR 镜像
• jetson-llm-benchmark — 可复现的延迟 / 吞吐量基准测试
• jetson-package — GHCR + Jetson AI Lab PyPI 索引与通用 ARM 轮子

跨平台行为

系列	技能可识别的变体	tegrastats	nvidia-smi	nvpmodel	NvMap debugfs
Jetson Thor	thor-t5000、thor-t4000	是	是（完整支持）	是	是（需要 root）
Jetson AGX Orin	orin-agx-64gb、orin-agx-32gb、orin-agx-industrial	是	是（存根，nvgpu）*	是	是（需要 root）
Jetson Orin NX	orin-nx-16gb、orin-nx-8gb	是	是（存根，nvgpu）*	是	是（需要 root）
Jetson Orin Nano	orin-nano-8gb、orin-nano-4gb	是	是（存根，nvgpu）*	是	是（需要 root）

* 在 GPU 由内核树内 nvgpu 内核驱动程序驱动的 Jetson 上，虽然存在 nvidia-smi 二进制文件，但大多数字段（Memory-Usage、功耗、利用率、计算进程表）会报告 Not Supported / N/A。为判断运行时应信任哪个数据源，脚本会进行能力探测：nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits。只有当此查询返回有效整数时，才会使用 nvidia-smi 获取每个进程的 GPU 内存。如果未返回有效整数，脚本会改用 /sys/kernel/debug/nvmap/iovmm/clients。对于采用 nvgpu 堆栈的 Jetson，这是权威的逐进程 GPU 内存数据源。

脚本会妥善处理各工具是否存在的情况；对于无法访问的工具，会报告 null / false（例如 Agent 未以访问 /sys/kernel/debug 所需的权限运行时）。变体检测会首先读取 /proc/device-tree/model 字符串（识别 T5000 / T4000 等名称）；如果型号字符串较为通用，则会改用内存大小启发式判断。