get-available-resources

获取可用资源

构建一个关于当前进程可用资源的保守图景。 将主机清单、进程亲和性、cgroup/容器限制、调度器 分配以及加速器运行时可用性分开对待。

安全约定

遵循以下规则：

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

捆绑的检测器仅使用固定的可执行文件/参数元组，不使用 shell， 超时时间短，stdout/stderr 有界，并给出部分失败警告。

快速开始

从本 skill 目录运行。

临时 stdout 快照

python scripts/detect_resources.py

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

显式私有文件

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

显式输出仅限于当前目录中的一个 .json 文件名， 在 POSIX 上使用 0600 模式，拒绝符号链接和路径遍历，并且 除非提供 --force，否则拒绝覆盖。强制输出还会拒绝 硬链接和非普通文件。Windows 隐私还取决于 目录 ACL。

可选的 psutil 增强

标准库检测器无需安装即可工作。如需更广泛的 跨平台物理核心、亲和性、可用内存、交换分区和磁盘 覆盖：

uv run --no-project --with "psutil==7.2.2" python scripts/detect_resources.py

导入是惰性的。导入 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 约束放置；配额约束带宽。

内存

将以下各项分开对待：

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

在 Apple 芯片上，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。可见性/分配计数约束的是观测到的管理记录，而不是框架设备的数量。MIG 与 AMD 分区枚举可能不同。 AMD reported_total_bytes 是设备报告的内存池；其与 主机 RAM 的关系尚未确立，因此永远不会被计入 RAM 预算。

磁盘

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

磁盘快照仅覆盖工作文件系统，与 psutil 的路径特定语义一致。 如果暂存、缓存和最终输出使用不同的文件系统，请从各自的目标目录分别检查，并按用途标注报告。为同时存在的临时副本和最终副本预留预算；输入文件系统上的可用空间并不能确立 输出文件系统上的空间。

调度器与容器

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

容器标记识别的是上下文；cgroup 限制识别的是限额。一个 没有有限 cgroup 值的容器仍可能看到主机清单，而 非 root 的 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：保留在 worker 预算之外的内存。
• --workload cpu|mixed|io：选择有界的 worker 启发式规则。
• --accelerator none|any|cuda|rocm|metal：请求一个候选后端 决策，但不声称其可用性。
• --output plan.json：显式的私有本地输出；默认输出到 stdout。

已知的内存预算若无法容纳一个 worker，则返回零个 worker 以及 recommendation.status: insufficient_memory；不要启动该计划。未知的 CPU 或可用内存会产出 review_required。正数计数是 暂定估算，并非预留。

对于 CPU 或混合型工作，请将 suggested_workers 和 threads_per_worker 结合使用。进程 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。对比结果是有界的。

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

可选的加速器诊断计划

生成一个不执行任何诊断的计划：

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

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

部分失败与来源

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

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

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

平台说明

• Linux： 仅读取有界的 /proc 与 cgroup v2 文件。通过 cgroup2 挂载点可见的 祖先 CPU 与内存限制会被纳入考量。隐藏的祖先以及 cgroup v1 限制不会被测量； 无法读取的 v2 成员关系会报告为未知，而不会用挂载根目录替代。
• macOS： 使用固定的 sysctl 键以及有界的 system_profiler SPDisplaysDataType -json 查询。Apple 芯片内存为统一内存。
• Windows： 可选的 psutil 可改进物理核心、亲和性、可用 内存与交换空间的观测。处理器组作用域可能导致主机与 进程计数不一致。
• Slurm： 读取分配变量的允许列表。它绝不输出作业、 节点、提交主机、GPU-ID 或路径值。
• NVIDIA/AMD： 管理 CLI 为可选项。缺失属正常情况；超时、 截断、解析失败与运行时不确定性仍会明确呈现。

附带文件

• scripts/detect_resources.py —— 脱敏快照采集器。
• scripts/plan_workload.py —— 确定性 worker/内存规划器。
• scripts/snapshot_tools.py —— schema 校验器与有界结构化差异比较。
• scripts/accelerator_diagnostics.py —— 不执行任何操作的只读诊断 计划。
• 仓库根目录下的 tests/get-available-resources/ —— 无需网络的 Linux、macOS、Windows、cgroup、Slurm 与加速器测试用例。
• references/resource_semantics.md —— 解释与平台细节。
• references/snapshot_schema.md —— schema 1.1 契约。
• references/sources.md —— 带日期的官方来源台账。

官方文档与源码已于 2026-10-01 更新；在更改语义或 依赖版本锁定之前，请查阅 references/sources.md。

引用 Scientific Agent Skills

本 skill 属于 K-Dense 的 Scientific Agent Skills。如果它对某篇 稿件、报告、演示或代码发布有实质性贡献，请将该论文加入参考文献或 软件部分，并告知用户你已这样做：

Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065

请始终引用当前版本。DOI 与 https://arxiv.org/abs/2609.00065 均解析到 最新的 arXiv 版本，因此切勿附加诸如 v1 之类的版本后缀。当网络访问 可用时，在撰写参考文献之前先获取 https://arxiv.org/abs/2609.00065（或 http://export.arxiv.org/api/query?id_list=2609.00065），并从中 记录作者列表、年份与版本。如果该记录列出了期刊参考文献 或出版商 DOI，请改为引用已发表版本。