feat: add a generic package for Torch-NPU API static task analysis-agent-skills-AtomGit

已合并

feat: add a generic package for Torch-NPU API static task analysis #176

群青世界创建于 7月31日从Giotto0025/agent-skills： add_API_target_analyse 合入到 Ascend/agent-skills： master

feat: add a generic package for Torch-NPU API static task analysis #176

已合并

群青世界创建于 7月31日

从Giotto0025/agent-skills add_API_target_analyse合入到Ascend/agent-skills master

群

群青世界

7月31日

变更说明
新增 torch-npu-api-target-analyse 通用包，用于 Torch-NPU API 补齐前的静态证据采集、场景分类和任务分析报告生成。

主要内容
新增 SKILL.md：定义静态取证流程、人工判断字段、分类规则、交付边界和报告要求
新增 scripts/：提供 source 准备、证据采集、场景分类、报告生成、预检、配置初始化和临时目录清理能力
新增 references/：提供静态搜索、场景判断、交付矩阵和报告模板
新增 README.md：说明快速调用、参数配置、目录结构、执行流程和输出要求
新增本地仓库配置示例，支持本地 Git 仓库和 GitCode 默认源

特性
支持单个或多个完整 API 的批量分析
覆盖 v2.7.1、v2.9.0、v2.10.0、v2.11.0、v2.12.0 和 master
自动检索 PyTorch 定义、官方测试、torch-npu 适配 patch 和 native API 文档
支持本地仓库优先、GitCode 默认源后备
按确定性规则分类为 new-test、upstream-patch、issue-only 或 pending
生成并预检唯一对外交付文件 任务分析说明.md
不输出本机绝对路径、凭据、设备信息或原始证据
不修改源码，不运行 API、测试、NPU 或远程验证，不创建 Issue/PR

验证
Skill is valid!
python -m unittest discover -s scripts -p test_analysis_rules.py -v
规则单元测试 17/17 通过
已验证通用包不包含本地配置、缓存、产品专用元数据或机器相关信息
已验证 README、脚本目录和 ZIP 内容一致，SHA-256 校验通过

风险说明
在线取证依赖 GitCode 公开源及目标版本 ref 的可用性；本地仓库缺少对应 tag 或分支时可能回退到在线源。静态分析无法替代 API、NPU 和目标环境验证，无法确认的契约或测试结论将保持 pending，需在后续开发流程中验证。

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

（感谢群青世界的贡献）

atomgit-bot

7月31日评论：

变更摘要

此 PR 新增 torch-npu-api-target-analyse 通用包，用于 Torch-NPU API 补齐前的静态证据采集、场景分类和任务分析报告生成。该包通过 Git 命令在六个目标版本（v2.7.1、v2.9.0、v2.10.0、v2.11.0、v2.12.0、master）上自动检索 PyTorch 定义、官方测试、torch-npu 适配 patch 及 native API 文档，按确定性规则将各版本分类为 new-test、upstream-patch、issue-only 或 pending，并生成唯一的对外交付文件 任务分析说明.md。整个过程不修改源码，不运行 API、测试或 NPU 验证，不输出本机绝对路径或凭据。

主要改动

证据采集脚本 collect_evidence.py：新增约 1046 行，实现六个版本的源码准备、API 符号检索（基于 AST 的 import 别名解析与精确引用匹配）、官方测试搜索（含两级调用链扩展）、设备/张量标记检测、契约候选项提取及父对象核心覆盖自动判定，生成 schema v4 的 JSON 证据账本。
场景分类脚本 decide_scenario.py：新增约 244 行，按固定首条命中规则对六个 target 执行确定性分类，综合官方测试状态、核心覆盖、patch 状态、NPU 适配必要性及 native API 资料证据，输出主场景和逐版本分类结果，并收集阻塞项。
报告生成脚本 generate_task_analysis.py：新增约 1093 行，对输入 JSON 执行严格校验（枚举值、路径隐私、中文要求、子 API 点名禁止、契约矩阵完整性），调用分类规则后生成标准 Markdown 报告，包含 API 功能、外部开发者任务清单（区分 code PR 与 docs PR）、测试覆盖场景矩阵、质量要求和执行建议，且外部章节不暴露内部场景名称。

预检脚本 preflight_report.py：新增约 214 行，对最终报告执行 UTF-8 编码、目录纯净性、标准章节完整性、隐私路径、英文句检测、内部场景名泄露检查、以及 PR 勾选项与质量要求一致性验证等多重门禁。
配套脚本与配置：prepare_sources.py 支持本地仓库优先、GitCode 在线回退的源码准备；init_config.py 通过交互式或命令行参数生成本地仓库配置文件；cleanup_analysis.py 安全删除 workspace 内的临时目录；单元测试 test_analysis_rules.py 覆盖 17 条确定性规则验证。

不准确？

atomgit-bot

7月31日评论：

🤖 AI Code Review

⚠️ 审查未能完成

本次代码审查未能完成，可能是临时性故障。

你可以在评论区输入 /ai review 重新发起审查。若多次失败，请联系管理员并附上下方追踪 ID。

追踪 ID: task-142353-run-136527

不准确？

ascend-robot成员

7月31日添加了label：ascend-cla/yes

ascend-robot成员

7月31日评论：

CLA Signature Pass

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

ascend-robot成员

7月31日评论：

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	✅ 许涛, 何宇航 (2/2)	✅ 许涛 (1/1)

💡 Tip:

Committer can comment /approve or /lgtm

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

CLA Signature Pass

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

群

群青世界

8月3日评论：

/ai review

atomgit-bot

8月3日评论：

代码审查

审查结论

发现统计

P0：0 个
P1：0 个
P2：1 个 — cleanup_analysis.py 未实现 README/SKILL 承诺的“最终任务目录外”安全门禁，存在误删唯一交付物 任务分析说明.md 的风险
P3：3 个 — 多 API 模式下无点号 API 触发未捕获 IndexError；PRIVATE_PATH 的 // 分支误伤合法官方 URL；decide()/docs_delivery_decision() 高风险分支缺少回归测试

各文件审查结果

README.md — 发现问题：第 143 行关于清理脚本安全性的承诺与 cleanup_analysis.py 实际行为不符（见 P2 发现）；其余内容无安全/误用指引
SKILL.md — no issues（只读取证约束、无危险命令）
references/delivery-matrix.md — no issues
references/local-upstream-search.md — no issues（git 命令均为只读）
references/report-template.md — no issues
references/scenario-decision.md — no issues
scripts/cleanup_analysis.py — 发现问题：缺少“最终任务目录外”校验（P2）
scripts/collect_evidence.py — 发现问题：无点号 API 的 IndexError（P3）；已逐一核对 staging/output 校验、patch 状态推导、docs 分类与 decide_scenario/generate_task_analysis 的字段契约，无其他缺陷
scripts/decide_scenario.py — no issues（分类优先级、master 排除、blocker 逻辑与 SKILL 规则一致；仅缺测试覆盖见 P3）
scripts/generate_task_analysis.py — 发现问题：PRIVATE_PATH 正则误伤 URL（P3）；校验链与 collect_evidence 输出契约核对一致
scripts/init_config.py — no issues
scripts/preflight_report.py — no issues（章节/勾选/隐私检查与生成器输出一致）
scripts/prepare_sources.py — no issues（clone/本地解析与回退逻辑正确）
scripts/test_analysis_rules.py — 发现问题：高风险分支缺回归测试（P3）
torch-npu-api-target-analyse.local.example.json — no issues（键名 schema_version/local_pytorch_root/local_torch_npu_root 与 init_config.py、prepare_sources.py 完全一致）

总体风险判断

该 PR 是一次完整的新工具包交付，代码量大（3805 行）但内部字段契约（collect → decide → generate → preflight）经核对基本自洽，单元测试 17 项覆盖了主要分类规则。未发现 P0/P1 级别的崩溃、注入或数据一致性缺陷；主要风险集中在破坏性清理命令的安全门禁缺失（P2，可能导致交付物被误删）以及若干边界输入与文档/代码不一致的低风险问题。整体可接受，但建议在合入前修复 P2 项，并补充 P3 项中的回归测试。

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

💬 仅评论

不准确？

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

official/PyTorch/torch-npu-api-target-analyse/scripts/cleanup_analysis.py

已过期

28+ try:

29+ path.relative_to(workspace)

30+ except ValueError as exc:

31+ raise ValueError("临时目录必须位于 workspace 内") from exc

atomgit-bot8月3日评论：

🟡 Medium Priority

变更行：cleanup_analysis.py 第 23-35 行 cleanup()，其中第 28-31 行是唯一的安全检查。
受影响的契约：README.md 第 143 行明确承诺“临时分析目录必须处于成果根目录内、最终任务目录外，才能通过清理脚本的安全检查”，SKILL.md 第 119 行也要求用该脚本删除 staging/evidence 临时目录。但 cleanup() 只调用 path.relative_to(workspace) 校验 path 位于 workspace 内，没有任何“处于最终任务目录外”的判断——而 collect_evidence.py 的 task_directory()（第 51-52 行）正是把最终任务目录 workspace/test_<API短名> 创建在 workspace 内，临时目录 .analysis/<任务名> 也在 workspace 内，二者对该检查一视同仁。
失败模式：用户按 README 流程误将 <成果根目录>/test_<API短名>（最终任务目录，仅含唯一对外交付物 任务分析说明.md）传给 cleanup_analysis.py，脚本会静默 shutil.rmtree 删除整个成果目录，且 README 声称的“安全检查”不会拦截，导致唯一交付物被不可恢复地删除。