环境信息
操作系统：AlmaLinux 8.10
架构：aarch64
CANN 软件版本：8.5.0
安装的软件版本：torch、torch-npu 2.7.1~2.11.0

一、6 个 API 功能如下：

1. torch.distributed.elastic.agent.server.api.RunResult
RunResult 是 elastic agent 的运行结果数据结构，用于承载 worker group 的最终状态、返回值和失败信息。agent 运行结束后会根据该对象记录 metric、上报 worker 结果，并区分成功、失败、重试等状态。

2. torch.distributed.elastic.timer.configure
configure 用于配置当前进程默认的 timer client。后续调用 timer.expires() 时，如果没有显式传入 client，会使用 configure 配置的默认 client 完成超时请求注册。

3. torch.distributed.elastic.timer.expires
expires 是 elastic timer 的超时上下文管理器。进入上下文时会注册超时请求，退出上下文时会释放该请求，用于保护一段代码在指定时间后被 watchdog 处理。

4. torch.distributed.elastic.timer.TimerClient.acquire
TimerClient.acquire 是 timer client 的注册接口，用于向 timer backend 注册一个指定 scope 的超时请求。

5. torch.distributed.elastic.timer.TimerClient.release
TimerClient.release 是 timer client 的释放接口，用于在受保护代码块正常结束后清理对应 scope 的超时请求。

6. torch.distributed.elastic.timer.TimerRequest
TimerRequest 是 timer 请求的数据结构，包含 worker_id、scope_id、expiration_time 等字段，用于在 timer server 内部传递和处理超时请求。

二、社区用例对这 6 个 API 的验证完整性分析

本批 API 的主验证点主要分布在以下 3 个官方文件中：
- test/distributed/elastic/agent/server/test/api_test.py
- test/distributed/elastic/timer/api_test.py
- test/distributed/elastic/timer/local_timer_test.py

详细分析如下：

1. torch.distributed.elastic.agent.server.api.RunResult
主要验证点在 test/distributed/elastic/agent/server/test/api_test.py。

该文件中 SimpleElasticAgentTest.test_record_metrics_success_no_retries 和 SimpleElasticAgentTest.test_record_metrics_failed_no_retries 会直接构造 RunResult，分别覆盖成功和失败场景，然后调用 agent._record_metrics(group_result)，断言 metric 记录是否符合预期。

这两个用例直接消费了 RunResult.state、RunResult.return_values、RunResult.failures 等核心字段。整文件 api_test.py 在 2.7.1~2.11.0 均可执行通过，因此 RunResult 的社区验证是充分的。

2. torch.distributed.elastic.timer.TimerRequest
主要验证点在 test/distributed/elastic/timer/api_test.py。

该文件中的 TimerApiTest.test_run_watchdog 会直接构造多个 TimerRequest(worker_id, scope_id, expiration_time)，再通过 TimerServer._run_watchdog() 进入 register_timers、get_expired_timers、clear_timers 等真实路径。

该用例既验证了 TimerRequest 的构造，也验证了 TimerRequest 在 timer server 流程中的消费。整文件 api_test.py 在 2.7.1~2.11.0 均可执行通过，因此 TimerRequest 的社区验证是充分的。

3. torch.distributed.elastic.timer.configure
主要验证点在 test/distributed/elastic/timer/local_timer_test.py。

LocalTimerTest.test_no_client 会执行 timer.configure(None)，随后进入 timer.expires() 并断言抛出 RuntimeError，覆盖未配置 client 的异常路径。

LocalTimerTest.test_happy_path 会执行 timer.configure(timer.LocalTimerClient(self.mp_queue))，随后进入 timer.expires()，覆盖默认 client 配置后的正常路径。

4. torch.distributed.elastic.timer.expires
主要验证点在 test/distributed/elastic/timer/local_timer_test.py。

LocalTimerTest.test_no_client、LocalTimerTest.test_client_interaction、LocalTimerTest.test_happy_path 分别覆盖 expires 的异常路径、显式传入 client 的交互路径、配置默认 client 后的正常路径。expires 作为上下文管理器的进入、退出流程都有社区用例覆盖。

5. torch.distributed.elastic.timer.TimerClient.acquire
主要验证点在 test/distributed/elastic/timer/local_timer_test.py。

LocalTimerTest.test_client_interaction 会用 MagicMock 包裹 timer client 的 acquire 方法，再进入 with timer.expires(..., client=timer_client)，最后断言 acquire 被正确调用并校验参数。该用例直接覆盖 expires -> TimerClient.acquire 的调用链。

6. torch.distributed.elastic.timer.TimerClient.release
主要验证点在 test/distributed/elastic/timer/local_timer_test.py。

LocalTimerTest.test_client_interaction 同样会用 MagicMock 包裹 timer client 的 release 方法，退出 expires 上下文后断言 release 被正确调用。该用例直接覆盖 expires -> TimerClient.release 的调用链。

三、NPU 适配

3.1 API 适配

这 6 个 API 全部属于 elastic agent / elastic timer 的控制面逻辑，统一特征是：
纯 Python 框架层逻辑，不涉及 NPU 算子、NPU kernel 或计算图构建；
不需要 .npu() 张量迁移；
不依赖 CANN runtime 分支；
核心行为是 Python 对象构造、metric 记录、上下文管理器、timer 请求注册和释放。
因此，本批 API 本体不需要任何 NPU 适配修改，不需要提交 API 修复 PR。

3.2 测试用例适配

(1) test/distributed/elastic/agent/server/test/api_test.py
该文件完全硬件无关，不需要做任何修改，可以整文件直接运行。

(2) test/distributed/elastic/timer/api_test.py
该文件完全硬件无关，不需要做任何修改，可以整文件直接运行。

(3) test/distributed/elastic/timer/local_timer_test.py
2.7.1、2.8.0、2.9.0 中，该文件未屏蔽 ARM64，整文件可以直接运行通过，不需要 patch。
2.10.0、2.11.0 中，该文件通过 IS_ARM64 guard 屏蔽了 LocalTimerTest、MultiprocessingRequestQueueTest、LocalTimerServerTest 等测试类。当前环境为 aarch64，如果不去掉该 guard，整文件执行结果为 Ran 0 tests，无法作为有效验证。
因此 2.10.0、2.11.0 需要提交 test_upstream patch，去掉 local_timer_test.py 中的 IS_ARM64 屏蔽。该 patch 只恢复已有社区用例在 ARM64/NPU 环境的可执行性，不修改 API 实现，不改变测试断言语义。

重点说明：上游通过IS_ARM64过滤arm环境，是因为社区 CI 环境里的 ARM64 节点不稳定（调度抖动、虚拟化差异），属于防御性屏蔽。但对于昇腾来说，ARM64 上跳过，等于主动放弃对这部分的兼容性验证。而且我已在实体 ARM 服务器上跑通了，说明昇腾 ARM下这些测试是稳定的，上游的过度保守限制对昇腾场景不适用。

3.3 文档修改

检查当前文档基线 docs/zh/native_apis/torch-distributed-elastic.md，以下 6 个 API 均已存在支持项：

torch.distributed.elastic.agent.server.api.RunResult
torch.distributed.elastic.timer.configure
torch.distributed.elastic.timer.expires
torch.distributed.elastic.timer.TimerClient.acquire
torch.distributed.elastic.timer.TimerClient.release
torch.distributed.elastic.timer.TimerRequest

因此本批 API 不需要 docs PR。

四、运行日志

以下日志均为运行整个 py 文件，不使用 -v 选择性执行测试点。

1、test/distributed/elastic/agent/server/test/api_test.py，2.7.1 2.8.0 2.9.0 2.10.0 2.11.0 全部运行通过，日志如下：

cd official_pytorch_versions/pytorch-v2.11.0/test/distributed/elastic/agent/server/test
python -m unittest api_test.py

.........<string>:19: DeprecationWarning: WorkerSpec.fn will be deprecated, please use WorkerSpec.entrypoint instead
..W0425 22:08:54.682000 83444 torch/distributed/elastic/agent/server/api.py:739] Received 15 death signal, shutting down workers
..........................
----------------------------------------------------------------------
Ran 37 tests in 1.769s

OK

各版本整文件运行结果：

2.7.1  Ran 30 tests in 1.740s  OK
2.8.0  Ran 31 tests in 1.738s  OK
2.9.0  Ran 31 tests in 1.747s  OK
2.10.0 Ran 37 tests in 1.765s  OK
2.11.0 Ran 37 tests in 1.769s  OK

2、test/distributed/elastic/timer/api_test.py，2.7.1 2.8.0 2.9.0 2.10.0 2.11.0 全部运行通过，日志如下：

cd official_pytorch_versions/pytorch-v2.11.0/test/distributed/elastic/timer
python -m unittest api_test.py

E0425 22:09:07.343000 83590 torch/distributed/elastic/timer/api.py:205] Error reaping worker=[3]. Will retry on next watchdog.
.
----------------------------------------------------------------------
Ran 1 test in 0.006s

OK

各版本整文件运行结果：

2.7.1  Ran 1 test in 0.006s  OK
2.8.0  Ran 1 test in 0.006s  OK
2.9.0  Ran 1 test in 0.006s  OK
2.10.0 Ran 1 test in 0.011s  OK
2.11.0 Ran 1 test in 0.006s  OK

说明：api_test.py 中会主动构造 _reap_worker() 抛异常场景，用于验证 timer server 异常兜底逻辑，因此日志中的 Error reaping worker=[3] 属于社区用例预期日志，不代表失败。

3、test/distributed/elastic/timer/local_timer_test.py，2.7.1 2.8.0 2.9.0 2.10.0 2.11.0 全部运行通过，日志如下：

2.7.1、2.8.0、2.9.0 原生社区用例无需 patch，可直接整文件运行通过。

cd official_pytorch_versions/pytorch-v2.9.0/test/distributed/elastic/timer
python -m unittest local_timer_test.py

..............
----------------------------------------------------------------------
Ran 14 tests in 12.149s

OK

2.10.0、2.11.0 应用 test_upstream patch 去掉 IS_ARM64 guard 后，整文件运行通过。

cd official_pytorch_versions/pytorch-v2.11.0/test/distributed/elastic/timer
python -m unittest local_timer_test.py

..............
----------------------------------------------------------------------
Ran 14 tests in 11.237s

OK

各版本整文件运行结果：

2.7.1  Ran 14 tests in 11.702s  OK
2.8.0  Ran 14 tests in 11.542s  OK
2.9.0  Ran 14 tests in 12.149s  OK
2.10.0 Ran 14 tests in 10.323s  OK
2.11.0 Ran 14 tests in 11.237s  OK

五、验证结论

1. torch.distributed.elastic.agent.server.api.RunResult 在 PyTorch 社区已有整文件测试覆盖，2.7.1~2.11.0 均整文件运行通过。

2. torch.distributed.elastic.timer.TimerRequest 在 PyTorch 社区已有整文件测试覆盖，2.7.1~2.11.0 均整文件运行通过。

3. torch.distributed.elastic.timer.configure、torch.distributed.elastic.timer.expires、torch.distributed.elastic.timer.TimerClient.acquire、torch.distributed.elastic.timer.TimerClient.release 在 test/distributed/elastic/timer/local_timer_test.py 中已有社区覆盖。

4. 2.7.1、2.8.0、2.9.0 的 local_timer_test.py 可原样整文件运行通过，不需要 patch。

5. 2.10.0、2.11.0 的 local_timer_test.py 需要去掉 IS_ARM64 guard，否则整文件只会 Ran 0 tests，无法作为有效验证。去掉 guard 后整文件运行通过，因此需要向这两个版本提交 test_upstream patch PR。

6. 本批 API 本体无需修改，不需要 API 修复 PR。

7. 文档已包含这 6 个 API，不需要 docs PR。