feat: improve torch-npu document writer and multi-version test runner skills-agent-skills-AtomGit

已合并

feat: improve torch-npu document writer and multi-version test runner skills #179

yi_jiabin创建于 8月5日从yi_jiabin/agent-skills： upgrade_doc_writer_skill_master 合入到 Ascend/agent-skills： master

feat: improve torch-npu document writer and multi-version test runner skills #179

已合并

yi_jiabin创建于 8月5日

从yi_jiabin/agent-skills upgrade_doc_writer_skill_master合入到Ascend/agent-skills master

yi_jiabin

8月5日

变更说明

持续优化 torch-npu-doc-writer、torch-npu-remote-runner 和 torch-npu-server-runner 三个技能，完善 Ascend torch-npu API 多版本测试适配中的证据分析、文档生成、远程测试编排、服务器执行、日志归档和结果报告流程。

三个技能保持职责分离并可串联使用：

torch-npu-doc-writer 基于本地 PyTorch Git 引用、torch-npu commit、测试文件和本轮日志，确定性生成 Issue 分析报告及逐版本 PR 描述。
torch-npu-remote-runner 在 Windows、Linux 或 macOS 本地通过 OpenSSH 免密连接完成测试扫描、上传、远端执行和日志下载。
torch-npu-server-runner 在已登录的 Linux 昇腾服务器或指定 Docker 容器内发现同名 conda 环境，执行多版本测试并写入本轮日志。

本次更新重点提升执行效率、版本隔离、证据可追溯性、Unicode 路径兼容性和失败结果的可诊断性，减少模型侧重复检索、历史日志污染及父子进程编码不一致造成的误判。

主要内容

torch-npu-doc-writer

引入统一的 config/versions.json 版本配置，集中维护启用版本、维护版本、各版本 PyTorch Git 引用以及 torch-npu master 资料目录映射。
建立 doc_pipeline.py prepare/render 两阶段流水线：准备阶段完成 commit 门禁并并行生成 PyTorch、commit 结构和完整日志证据；渲染阶段统一生成文档并执行确定性审计。
将 torch-npu commit 自动发现固化到预检脚本，按测试路径、文件名、blob 内容和 Git 拓扑识别版本归属；无法唯一确认时一次性要求补充对应版本 commit。
路径模式为每个文档分组生成一份六章 Issue，并为每个非维护版本生成一份独立 PR；特殊说明模式只生成 Issue，不再生成无版本 PR。
Issue 第一至第五章按证据签名和正文一致性自动归组，第六章保持逐版本结构；每份 PR 仅包含本版本的修改方案、资料变更、接口变更和功能验证。
功能验证只读取 manifest 唯一关联的本轮日志，逐行保留完整结果；渲染器核验日志哈希、原始/清理行数、测试表行数、资料适用版本和 PR 版本隔离。
增加严格 UTF-8 运行时，统一 CLI 标准输出、标准错误、Python 子进程和 Git 子进程的编码；禁止使用替换或忽略模式掩盖非法字节，修复 Windows 中文输出路径被误判为文件哈希无效的问题。
保持只读执行边界：不运行测试、不修改 PyTorch 或 torch-npu 工作树、不切换分支、不提交代码，也不创建或更新线上 Issue/PR。

torch-npu-remote-runner

保留“版本目录 + 用例在 torch-npu 仓库中的完整相对路径”，保证远程日志和后续文档 commit 定位可以准确关联测试来源。
使用一次非交互 SSH 连接完成免密登录、远端 Python、可选 Docker 容器和远程目录准备校验，不尝试密码或交互式认证。
使用 Python/PAX 归档经 SSH 标准流上传测试和内置 server runner，并只下载本轮预期日志；归档链路失败时自动回退到逐文件 SCP。
远程路径、日志清单和 runner 参数按 UTF-8 编码后封装为 ASCII 载荷，避免 Windows 代码页、本地 shell 和远端 shell 对中文、空格或特殊字符路径进行二次解释。
修正 SCP 回退路径的参数传递，不再对列表参数中的远程路径增加 shell 引号。
区分远程传输/环境错误和测试失败，校验下载日志完整性，并透传内置 server runner 的退出状态。
保留 --testBase、--serverIp、--containerName 旧参数别名，新命令统一使用 --localBase、--server 和 --dockerContainer。
实际测试启动后，只基于本轮下载日志生成本地 UTF-8 Markdown 验证报告，逐版本统计总数、通过、失败、跳过、xfail 和无法确认项。

torch-npu-server-runner

在宿主机或指定 Docker 容器内通过 conda env list --json 自动发现与版本目录同名的环境，不依赖调用进程预先执行 conda activate。
直接调用各版本环境的 Python 解释器执行测试；Docker 模式校验容器运行状态、测试目录同路径挂载及容器内解释器可用性。
支持按 TestClass.test_method 精确筛选测试；每个有测试文件的目标版本都必须匹配指定方法，避免静默漏测。
--maxWorkers 仅并行不同版本，同一版本内的测试文件保持顺序；默认并发数为 1，并逐项记录耗时、退出码和日志绝对路径。
测试标准输出直接写入 <localBase>/result_log/<version>/<完整相对路径>.log，不创建或依赖 run_manifest.json，结果分析范围由本轮标准输出中的任务和日志路径确定。
修正重复 conda 环境路径判断，并延长容器探测等环境检查的超时时间，降低慢环境下的误失败概率。
实际执行后生成服务器侧 UTF-8 Markdown 验证报告；失败时区分测试用例、API/NPU 实现、环境或执行问题以及证据不足，并提供最小重跑命令。

跨技能协作

torch-npu-remote-runner/scripts/torch_npu_server_runner.py 与 torch-npu-server-runner/scripts/torch_npu_server_runner.py 保持字节级一致。
remote runner 仅增加本地扫描、SSH 和文件传输编排，远端测试发现、conda 选择、Docker 执行、日志格式和退出码均复用内置 server runner。
runner 生成的“版本 + 完整测试相对路径 + 本轮日志”可直接作为 doc-writer 的路径模式输入，形成“执行测试 → 下载/整理日志 → 生成 Issue/PR 文档”的完整链路。

特性

文档分析从模型侧重复搜索转为脚本化、可签名、可复核的证据流水线，降低多版本任务的执行时间和推理开销。
版本生命周期由单一配置控制，输入中的维护版本和未激活版本自动过滤，避免错误进入 commit 门禁、日志和文档。
commit、PyTorch、日志三类证据与分析结果绑定；配置、commit 或日志发生变化后，旧 bundle 无法继续渲染。
Issue 支持跨版本结论归组，PR 保持严格版本隔离；相同方案只编写一次，由脚本展开为各版本文档。
本轮日志完整保留并进行哈希审计，不通过截断、摘要或历史日志推断测试结果。
remote/server runner 均支持宿主机和 Docker 模式、指定测试方法、版本级并发、逐项耗时和 --dryRun。
测试报告统一包含基本信息、逐版本汇总、失败明细和日志清单，并要求写入后复读核对。
中文、空格及常见特殊字符路径在本地文件、Python 子进程、SSH 参数、PAX 归档和 Markdown 输出链路中统一按 UTF-8 处理。

验证

python -B -m unittest discover -s torch-npu-remote-runner/tests -p "test_torch_npu_remote_runner.py" -v：37 个测试全部通过。
python -B -m unittest discover -s torch-npu-server-runner/tests -p "test_torch_npu_server_runner.py" -v：41 个测试全部通过。
已覆盖参数及旧别名校验、测试发现与方法筛选、非交互 SSH、SCP 回退、Unicode 路径、PAX 归档传输、安全解压、本轮日志完整性、宿主机/Docker 命令、conda 自动发现、解释器校验、dry-run、版本级并发、日志写入、逐项耗时和退出码透传。
跨技能一致性测试通过，两份 torch_npu_server_runner.py 的 SHA-256 均为 fa857c8dce065636939e0d96d448f42d2da81aabda8d1e204de8180687f6f35f。
已校验 torch-npu-doc-writer 的 6 个 CLI 脚本、版本配置、六章 Issue 模板、四章 PR 模板及严格 UTF-8 约束。
使用包含中文路径的真实多版本输入完成 doc-writer prepare 和 render，生成一份 Issue 与四份版本 PR，内置审计结果为 audit.valid=true；中文路径文件哈希复读、完整日志、测试表行数、资料版本和 PR 隔离均通过。

风险说明

本次 runner 验证以本地单元测试为主，未连接真实 SSH 服务器、Docker 容器或昇腾 NPU 环境。真实执行结果仍受服务器网络、known_hosts 和密钥配置、目录权限、容器挂载、conda 环境、驱动/CANN、NPU 资源及 HCCL 状态影响。

torch-npu-remote-runner 和 torch-npu-server-runner 各保存一份 server runner。后续修改任一副本时必须同步另一份，并运行跨技能一致性测试；否则本地远程执行与服务器直接执行可能产生行为差异。

版本并发可能增加 NPU 显存、设备和 HCCL 资源争用风险，因此默认保持 --maxWorkers 1。只有确认设备隔离和资源充足后才建议提高并发数。

torch-npu-doc-writer 依赖本地 Git 引用、唯一 commit 和本轮日志作为证据，不访问线上仓库也不执行测试。严格 UTF-8 策略会主动拒绝非 UTF-8 文本或非法子进程输出，以避免乱码进入证据和文档；需要先修正输入编码后再重新执行。

路径模式现在按非维护版本分别生成 PR，特殊说明模式只生成 Issue。依赖旧版“一份 Issue + 一份 PR”输出约定的调用方需要同步适配新的文件数量和命名规则。

Pull Request已成功合入, 合并人@ascend-robot

（感谢 yi_jiabin 的贡献）

atomgit-bot

8月5日评论：

变更摘要

此 PR 对 torch-npu-doc-writer、torch-npu-remote-runner 和 torch-npu-server-runner 三个技能进行了大规模重构与优化，核心目标是建立一套确定性、可审计的 Ascend torch-npu API 多版本文档生成流水线。主要引入统一的 config/versions.json 版本配置、doc_pipeline.py 两阶段（prepare/render）流水线、以及 commit_evidence.py、log_evidence.py、pytorch_evidence.py 三个并行证据收集脚本，替代此前的模型侧推理搜索方式。同时通过 utf8_runtime.py 实现全链路严格 UTF-8 编码约束，修复 Windows 中文路径被误判为文件哈希无效等问题。runner 侧则强化了 conda 自动发现、Docker 容器支持、版本级并发控制以及 Unicode 路径的 SSH/PAX/SCP 传输兼容性。

主要改动

引入版本配置与两阶段文档流水线：新增 config/versions.json 统一维护启用版本、维护版本、各版本 PyTorch Git 引用及资料目录映射；新增 doc_pipeline.py 实现 prepare 阶段并行生成三类证据、render 阶段统一生成 Issue 与逐版本 PR 并执行确定性审计，Issue 第一至第五章按证据签名自动归组，第六章保持逐版本结构。
脚本化证据收集替代模型推理：新增 commit_evidence.py 通过 Git 拓扑分析（canonical_version_ref_evidence、branch_base_resolution 等）自动识别 commit 版本归属；新增 log_evidence.py 从 manifest 选定的本轮日志完整提取第六章证据并进行哈希审计；新增 pytorch_evidence.py 通过 AST 解析 (resolve_definition、definition_status) 收集 API 定义、社区测试和设备约束证据。
预检脚本增强自动发现与版本分类：evidence_preflight.py 新增 load_version_config 校验版本配置、canonical_version_ref_evidence/upstream_version_evidence/branch_base_resolution 多层 commit 归属判定逻辑，无法唯一确认时一次性返回 commit_required 状态并要求补充对应版本 commit，同时自动过滤维护版本与未激活版本。
渲染器支持多版本隔离与完整日志审计：render_docs.py 重写为按版本生成独立 PR（通过 build_issue_chapters/finalize_issue_chapters 归组与展开），新增 validate_manifest_versions 核验 manifest、PyTorch 证据、log 证据的 SHA-256 签名一致性，新增 audit_documents 逐版本检查日志完整行数、PR 版本隔离和测试表行数匹配。
全链路 UTF-8 编码统一：新增 utf8_runtime.py 提供 configure_utf8_stdio() 和 utf8_subprocess_env()，强制 CLI 标准输出/错误、Python 子进程和 Git 子进程均使用严格 UTF-8 编码，禁止替换或忽略模式，确保中文路径、空格及特殊字符在本地文件、SSH 参数、PAX 归档和 Markdown 输出中不产生乱码或误判。

不准确？

atomgit-bot

8月5日评论：

代码审查

审查总结

本次审查覆盖了全部 17 个变更文件（含 2 个已删除文件），共发现 4 个 P3 级问题，无 P0-P2 级问题。总体风险判定：低。

各文件审查结论：

文件	结论
`README.md`	2 个 P3：schema_version 示例与实际配置不一致；log_evidence.py 功能描述与实际实现不符
`SKILL.md`	无问题
`agents/openai.yaml`	无问题
`assets/templates/pr-template.md`	无问题
`config/versions.json`	无问题
`references/core-rules.md`	无问题
`references/path-mode.md`	无问题
`references/special-mode.md`	无问题
`references/document-rules.md`	（已删除）
`references/evidence-rules.md`	（已删除）
`scripts/commit_evidence.py`	无问题
`scripts/doc_pipeline.py`	无问题
`scripts/evidence_preflight.py`	无问题
`scripts/log_evidence.py`	1 个 P3：`focused_lines` 函数为死代码且与完整保留规则冲突
`scripts/pytorch_evidence.py`	无问题
`scripts/render_docs.py`	1 个 P3：重复的无操作 `render_issue` 调用
`scripts/utf8_runtime.py`	无问题
`torch-npu-remote-runner/SKILL.md`	无问题
`torch-npu-server-runner/SKILL.md`	无问题

4 个发现问题概况：

P3 × 4：均为文档描述不一致（README 中 schema_version 和 log_evidence 功能描述过时）或死代码（focused_lines 函数和重复的 render_issue 调用）。这些问题不影响运行时正确性，但可能误导用户或增加维护负担。

类型	数量
🔴 阻塞	0
🟡 建议	1

💬 仅评论

不准确？

ascend-robot成员

8月5日添加了label：ascend-cla/yes

ascend-robot成员

8月5日评论：

Thanks for your pull-request.
The full list of commands accepted by me can be found at here。
You can get sig-info at here

PR Approval Progress

✅ Congratulations! All modules have met the lgtm and approve requirements.

Module Approval Details

module	lgtm status	approve status
repo-Ascend/agent-skills	✅ 许涛, 曾浩龙, 占杰 (3/2)	✅ 许涛, 曾浩龙 (2/1)

💡 Tip:

Committer can comment /approve or /lgtm

Commenting /approve implies both code review (lgtm) and intent to merge (approve)

CLA Signature Pass

yi_jiabin, thanks for your pull request. All authors of the commits have signed the CLA. 👍

atomgit-bot8月5日进行代码检视3

official/PyTorch/torch-npu-doc-writer/scripts/doc_pipeline.py

已过期

317+ item = log_versions[version]

318+ chapter = item.get("chapter_6", "")

319+ ran = re.search(r"Ran\s+\d+\s+tests?", chapter)

320+ status = "OK" if re.search(r"(?m)^OK$", chapter) else "FAILED" if re.search(r"(?m)^FAILED", chapter) else "unknown"

atomgit-bot8月5日评论：

🟡 Medium Priority

changed line → doc_pipeline.py:320 的正则 (?m)^FAILED$ 要求行刚好是 FAILED 且立即结束。

affected behavior → 该表达式用于从本章日志（chapter_6）推断测试结果状态，写入 analysis_context 的 log_summary.status 字段，供模型参考。

failure mode → Python 标准 unittest 的输出格式为 FAILED (failures=N) 或 FAILED (errors=N)，行尾有空格和括号内容。^FAILED$ 不能匹配，导致 status 回退到 "unknown"。同文件中 log_evidence.py 的 SUMMARY_RE 使用了 ^\s*(?:OK|FAILED|PASSED)\b（词边界），可正确匹配，但此处未保持一致。 模型读取 analysis_context 时可能误判失败用例为"未知状态"，降低分析准确性。

suggested fix → 将 (?m)^FAILED$ 改为 (?m)^FAILED\b（词边界），与 log_evidence.py 的对等正则对齐。

建议：将正则 (?m)^FAILED$ 改为 (?m)^FAILED\b，使其能匹配 FAILED (failures=N) 格式，与 log_evidence.py 的 SUMMARY_RE 保持一致。

改动建议

320	- status = "OK" if re.search(r"(?m)^OK$", chapter) else "FAILED" if re.search(r"(?m)^FAILED", chapter) else "unknown"
320	+ status = "OK" if re.search(r"(?m)^OK$", chapter) else "FAILED" if re.search(r"(?m)^FAILED\b", chapter) else "unknown"