get-available-resources

获取可用资源

对当前进程可用的资源做出保守评估。 将主机资源清单、进程亲和性、cgroup/容器限制、调度器分配和加速器运行时可用性分开处理。

安全约定

请遵循以下规则：

• 仅在用户请求检测或特定工作负载需要资源规划时运行检测。不要为每项科学任务都持久化指纹。
• 默认使用 stdout。仅在用户选择明确的通用本地文件名时才持久化。
• 不要运行压力测试、基准测试、大规模分配、写入探测、设备重置、驱动安装或时钟/电源设置更改。
• 不要转储环境变量。仅读取检测器实现中指定的 Slurm 和加速器变量。
• 不要报告主机名、绝对路径、cgroup 路径、作业 ID、设备 UUID、PCI 地址或原始可见性变量值。
• 将缺失的观测结果视为未知。绝不要将未知转换为无限制。
• 绝不要推断主机上可见的 CPU、内存池或 GPU 在调度器分配或容器内可用。

内置检测器仅使用固定的可执行文件/参数元组，不使用 shell；设置较短的超时时间，限制 stdout/stderr 输出长度，并对部分失败发出警告。

快速开始

从此技能目录运行。

临时 stdout 快照

python scripts/detect_resources.py

该命令仅向 stdout 输出 JSON。只有在普通 shell 权限可接受时才重定向输出。

明确指定的私有文件

python scripts/detect_resources.py --output resource-snapshot.json

显式输出仅允许使用当前目录中的一个 .json 文件名，并使用私有权限；拒绝符号链接和路径遍历；除非提供 --force，否则拒绝覆盖文件。

可选的 psutil 增强

标准库检测器无需安装即可工作。若要获得更全面的跨平台物理核心数、亲和性、可用内存、交换空间和磁盘信息：

uv pip install "psutil==7.2.2"

导入采用延迟方式。导入 psutil 失败时会发出警告，而不会导致致命错误。

跳过管理工具探测

python scripts/detect_resources.py --skip-accelerators

当不希望加速器发现过程产生延迟时使用此选项。检测器仍会汇总允许列表中的可见性变量是否存在及其状态，但不会返回其值。

必要解读

CPU

请将以下内容视为不同的信息：

• cpu.host.logical：系统可见的调度单元数。
• cpu.host.physical：物理拓扑；若未知则为 null，绝不根据逻辑核心数推断。
• cpu.process.affinity_logical：受支持时当前亲和性集合的大小。
• cpu.cgroup_v2.cpuset_logical：有效 cgroup cpuset 的大小。
• cpu.cgroup_v2.quota_cores：有限的 cpu.max 容量，可能是小数。
• scheduler.allocation.cpu_per_process：作用范围明确时，对 Slurm 每任务分配的有限解读。
• cpu.effective.capacity_cores：观测到的正值限制中的最小值。
• cpu.effective.worker_ceiling：CPU 进程工作器数量的保守上限。

配额 1.5 表示 CPU 时间容量，并不代表 1.5 个物理核心。亲和性和 cpuset 限制进程可运行的位置；配额限制 CPU 带宽。

内存

以下内容应分开处理：

• 主机总内存/可用内存；
• 当前 cgroup 用量、硬性 memory.max 限制及剩余层级容量；
• memory.high，它是压力/节流边界，而非硬性上限；
• 调度器内存分配及其作用范围；以及
• 保守估算的有效硬性限制和可用内存。

在 Apple silicon 上，memory.model 为 unified_cpu_gpu。不要将集成 GPU 内存计入 RAM，也不要将其描述为独立 VRAM。

加速器

每台设备都是一种后端候选项：

• NVIDIA GPU → CUDA 候选项；
• AMD GPU → ROCm 候选项；
• Apple 集成 GPU → Metal 候选项。

管理查询可见并不能证明以下事项：

1. 获得调度器/容器许可；
2. 可访问设备节点；
3. 驱动/运行时兼容；
4. 框架软件包兼容；或
5. 支持相应运算符/数据类型。

因此，runtime_usable_devices 保持为 null，每台设备的 runtime_compatibility 均为 not_tested。可见性/分配数量只是上限，不构成保证。

磁盘

capacity_bytes、文件系统的 free_bytes、用户可用的块数，以及非写入权限检查，是不同的概念。文件系统配额或项目配额可能会更严格。绝对工作路径始终会被脱敏。

调度器和容器

Slurm 变量描述分配范围，但实际限制取决于站点配置，例如任务亲和性或 cgroups。优先将亲和性和 cgroup 观测结果作为限制已生效的证据。

容器标记用于识别上下文；cgroup 控制项用于识别限制。没有有限 cgroup 值的容器仍可能看到主机清单；非根 cgroup 也不会自动被标记为容器。

平台规则详情请参阅 references/resource_semantics.md。

规划工作负载

规划器使用经过验证的快照，且不会执行任何工作：

python scripts/plan_workload.py resource-snapshot.json \
  --workload cpu \
  --tasks 100 \
  --memory-per-worker-mib 2048

可选控制项：

• --workers N：显式设置上限。
• --reserve-memory-mib N：将此内存留在工作进程预算之外。
• --workload cpu|mixed|io：选择一个有界的工作进程启发式策略。
• --accelerator none|any|cuda|rocm|metal：请求候选后端决策，但不声称其可用。
• --output plan.json：显式指定本地私有输出；默认输出到 stdout。

对于 CPU 或混合型工作，请同时使用 suggested_workers 和 threads_per_worker。进程工作进程数乘以 BLAS/OpenMP 原生线程数，可能会超出分配限额。

I/O 规划允许有限度地超额配置（最多 32），但会将其标记为启发式策略。仅针对真实且有代表性的工作负载进行基准测试，并遵守调度器/容器限额。

验证或比较快照

验证：

python scripts/snapshot_tools.py validate resource-snapshot.json

比较资源状态，同时忽略 observed_at：

python scripts/snapshot_tools.py diff before.json after.json

使用 --include-volatile 可包含时间戳。输入必须是常规的非符号链接 JSON 文件，且大小不超过 1 MiB。差异输出有界。

架构以及 null/零值的含义记录在 references/snapshot_schema.md 中。

可选加速器诊断计划

生成计划，但不执行任何诊断：

python scripts/accelerator_diagnostics.py resource-snapshot.json \
  --backend auto

结果包含固定的只读管理查询参数列表，以及分别针对可见性、权限和运行时兼容性的检查门。仅在将实际执行工作负载的确切环境中运行框架官方的可用性检查。不要自动安装或更改驱动程序。

部分故障和来源信息

单项探测失败不得抹去成功的观测结果。请检查：

• completeness；
• 带有稳定代码的排序后 warnings；
• 排序后的 provenance 来源/状态记录；以及
• null 字段。

子进程 stderr 和原始异常文本不会复制到快照中，因为其中可能包含标识符或路径。

平台说明

• **Linux：**仅读取有界的 /proc 和 cgroup v2 文件。会考虑祖先级 CPU 和内存限制。
• **macOS：**使用固定的 sysctl 键，以及有界的 system_profiler SPDisplaysDataType -json 查询。Apple 芯片采用统一内存。
• **Windows：**可选的 psutil 可改进物理核心数、亲和性、可用内存和交换空间的观测结果。处理器组范围可能导致主机计数与进程计数不同。
• **Slurm：**读取允许列表中的分配变量。绝不会输出作业、节点、提交主机、GPU ID 或路径值。
• **NVIDIA/AMD：**管理 CLI 为可选项。缺少 CLI 属于正常情况；超时、截断、解析失败和运行时不确定性都会明确标示。

打包文件

• scripts/detect_resources.py — 脱敏快照收集器。
• scripts/plan_workload.py — 确定性工作进程／内存规划器。
• scripts/snapshot_tools.py — 架构验证器和有界结构差异工具。
• scripts/accelerator_diagnostics.py — 不执行操作的只读诊断计划。
• 仓库根目录下的 tests/get-available-resources/ — 无网络的 Linux、macOS、Windows、cgroup、Slurm 和加速器测试用例。
• references/resource_semantics.md — 解读方式和平台详情。
• references/snapshot_schema.md — 架构 1.1 契约。
• references/sources.md — 按日期整理的官方来源清单。

官方文档已于 2026-07-23 更新；更改语义或依赖项固定版本前，请查阅 references/sources.md。

Agent 操作流程

1. 检查环境。 确认 Python 环境和库版本（python -c "import pkg; print(pkg.__version__)"），并检查数据的结构、类型和缺失值。
2. 确定输入。 根据数据或用户提供的信息确认格式、标识符和参数。对于任何会影响结果的取值，不要猜测，应先询问。
3. 先运行小规模版本。 先在样本或单个折上运行，并检查运行时间和内存。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 使用留出数据、固定随机种子和适当的指标；检查是否存在数据泄漏；报告不确定性（置信区间、不同随机种子的标准差）。
6. 报告。 说明运行内容（版本、命令、参数）、检查内容，以及仍不确定的事项。

如果发生这种情况	请执行以下操作
内存不足或运行非常缓慢	进行子采样，使用分块或惰性计算，或者减小模型规模，并告知用户所做的更改。
已安装版本中没有这些说明里提到的函数、标志或端点	查看已安装版本自身的文档（help()、--help、官方文档），进行调整并告知用户。切勿捏造 API。
必需的输入、标识符或参数含糊不清	询问用户，或在运行前明确说明所作假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证，须如实说明。
• 切勿报告本次会话中未计算的指标；应展示生成每个数值的代码路径。
• 此处与特定版本相关的细节可能已经过时：请对照已安装版本的官方文档进行确认。
• 对于涉及费用、占用共享 GPU 或云配额、接触个人或患者数据，或无法撤销的操作，必须事先征得用户同意。