已合并
docs: add Ascend for PyTorch Agent Skills README #170
ID_G3创建于 7月21日
docs: add Ascend for PyTorch Agent Skills README #170
已合并
共 1 个文件变更+175-0
| @@ -0,0 +1,175 @@ | |||
| 1 | +<h1 align="center">Ascend for PyTorch Agent Skills</h1> | ||
| 2 | + | ||
| 3 | +<div align="center"> | ||
| 4 | +<p><b><span style="font-size:24px;">开发与维护的一站式 Agent Skills</span></b></p> | ||
| 5 | +</div> | ||
| 6 | + | ||
| 7 | +## ℹ️ 简介 | ||
| 8 | + | ||
| 9 | +Ascend for PyTorch Agent Skills 是专为 Ascend for PyTorch 社区及其核心组件 TorchNPU 的开发者打造的一站式可复用技能集合。它将 TorchNPU 方案设计、代码开发、问题定位、知识问答等流程沉淀为结构化工作流，帮助 Agent 在合适的场景下稳定执行并输出可复核的结果。 | ||
| 10 | + | ||
| 11 | +本技能集面向以下社区角色： | ||
| 12 | + | ||
| 13 | +- **开发者**：借助知识问答、问题定位和结构化开发流程，快速完成日常 TorchNPU 开发与调试任务。 | ||
| 14 | +- **贡献者**：按照现有流程、检查清单和交付模板完成算子接入、测试、文档与问题修复，降低参与社区贡献的门槛。 | ||
| 15 | +- **维护者**：依托方案分析、PR 审核和工程质量检查能力推进社区维护，减少遗漏关键证据、验证步骤或交付物。 | ||
| 16 | + | ||
| 17 | +每个顶层技能包都是一个独立目录，至少包含一个 `SKILL.md`，复杂技能包还会包含子技能、脚本、模板、参考资料和示例。下方清单按 **12 个可直接选择的顶层技能包** 组织；套件内部的子技能由总入口按任务自动路由，新用户通常不需要逐个调用。 | ||
| 18 | + | ||
| 19 | +## ✨ 能力介绍 | ||
| 20 | + | ||
| 21 | +| 场景 | 能力 | | ||
| 22 | +|---|---| | ||
| 23 | +| 算子开发 | 覆盖 CANN/aclnn 算子接入或修改、UT 与 FakeTensor 测试、API 文档和兼容性基线。 | | ||
| 24 | +| 问题定位与修复 | 覆盖 API 一致性工单、PyTorch 上游 UT 失败、分布式/HCCL、图模式、内存和缺失算子等场景。 | | ||
| 25 | +| 工程质量 | 覆盖当前改动文件的 CI 静态检查与受控修复，以及基于 whl 构建和测试的回归提交二分。 | | ||
| 26 | +| 源码与变更分析 | 覆盖 PyTorch/TorchNPU 源码设计分析、上游 PR 影响评估和 torch-npu PR 审核。 | | ||
| 27 | + | ||
| 28 | +## 🧩 技能总览 | ||
| 29 | + | ||
| 30 | +| Skill | 适用场景 | 典型输入 | 主要产出 / 依赖 | | ||
| 31 | +|---|---|---|---| | ||
| 32 | +| [`api-consistency`](./api-consistency/SKILL.md) | 处理 A2/A3/A5 上的 TorchNPU API 一致性问题，自动区分 ATK 与 `torchrun`、`python`、`pytest`、`bash` 等非 ATK 复现路径，也支持批量工单。 | DTS/问题描述、完整复现命令、ATK xlsx 或运行日志、可选远端环境信息。 | 复现记录、证据分析和结单文档；按场景需要 ATK、Python xlsx 解析、SSH 和可用的 NPU 环境。 | | ||
| 33 | +| [`ci-static-errors-fix`](./ci-static-errors-fix/SKILL.md) | 检查并安全修复当前 Git 工作区改动文件中的 `lintrunner`、FLAKE8、空白、格式和 CODESPELL 问题。 | 含未提交改动的 PyTorch 风格仓库。 | 低风险修复、残留问题和验证摘要；依赖 `lintrunner`、`uv`，FLAKE8 修复会临时使用 `autopep8`。 | | ||
| 34 | +| [`com-auto-binary-pr`](./com-auto-binary-pr/SKILL.md) | 已知 good/bad 范围时，通过反复构建 whl 和运行测试定位引入问题的提交。 | 二分范围、测试命令、容器/构建配置，或 `binary_config.json`。 | `binary_result.json`、构建与测试记录、可疑提交；依赖可用的 TorchNPU 构建和测试环境。 | | ||
| 35 | +| [`core-requirement-analyze`](./core-requirement-analyze/SKILL.md) | 基于 PyTorch 或 TorchNPU 源码分析模块、机制、算子、commit 或 diff，形成可用于修改和扩展代码的中文材料。 | 目标模块、源码路径、commit/diff，可选已有分析材料和输出要求。 | 带源码路径、调用链、扩展点和影响范围的需求/设计与实现分析文档。 | | ||
| 36 | +| [`npu-graph-skill`](./npu-graph-skill/SKILL.md) | 处理 NPUGraph/ACLGraph 的知识问答、代码导航、报错诊断、日志分析、性能分析和 MCP 配置。 | 图模式问题、错误堆栈、`TORCH_NPU_LOGS`、图 dump、性能现象或概念问题。 | 自动路由到 5 个子技能并输出分析/诊断报告；部分诊断与性能任务需要 TorchNPU、OpPlugin、CANN/NPU 环境。 | | ||
| 37 | +| [`op-adaptation`](./op-adaptation/SKILL.md) | 将新 CANN/aclnn 算子接入 TorchNPU，或修改已有算子的接口、变体、反向和实现。 | Create：算子 `.md` + `_def.cpp`；Modify：算子名 + 修改说明。 | YAML、C++、Meta、Derivatives、测试、文档、兼容性基线、CHECKLIST 和集成摘要；依赖 OpPlugin/TorchNPU 构建环境，并组合使用 `op-test` 与 `op-apidoc`。 | | ||
| 38 | +| [`op-apidoc`](./op-apidoc/SKILL.md) | 为 TorchNPU 自定义算子生成或补齐中文 API 参考文档。 | 算子名、YAML `func:`、参数与约束，或 `op-adaptation` 生成的 CHECKLIST。 | API Markdown、导航索引和 Python docstring 更新。 | | ||
| 39 | +| [`op-test`](./op-test/SKILL.md) | 为 TorchNPU 自定义算子或原生算子适配生成 UT 和 FakeTensor 测试，并在条件允许时执行。 | 算子实现、签名、参数约束，或 `op-adaptation` 的 CHECKLIST。 | 测试文件、参数覆盖矩阵和执行报告；无 NPU 时仍可生成测试，但会跳过上板执行。 | | ||
| 40 | +| [`pytorch-pr-analysis`](./pytorch-pr-analysis/SKILL.md) | 分析指定时间段内合入 PyTorch `main` 的 PR，评估其对 torch-npu 的兼容性影响。 | 起止日期。 | PR 明细、图模式/分布式深度分析和 Excel 报告；依赖 `GITHUB_TOKEN`、`requests`、`openpyxl`，飞书与外部深度分析能力按任务选配。 | | ||
| 41 | +| [`torch-npu-issue-pipeline-core`](./torch-npu-issue-pipeline-core/SKILL.md) | 端到端处理 Core 组 PyTorch 上游 UT 在 NPU 上的失败，覆盖准备、复现、诊断、修复、验证和交付。 | 完整参数化用例名、`issue_id`；首次使用还需仓库、分支范围和 GitCode 配置。 | 修复代码、复现/根因/验证报告、合入描述和 PR/MR；依赖 NPU、CANN、PyTorch/TorchNPU/OpPlugin 仓库及交付权限。 | | ||
| 42 | +| [`torch-npu-issue-pipeline-distributed`](./torch-npu-issue-pipeline-distributed/SKILL.md) | 处理分布式、HCCL 或图模式相关的上游 PyTorch UT 失败，按复现 → 诊断 → 验证推进。 | 完整参数化用例名、错误日志和环境说明。 | 复现报告、根因分析、修复验证报告和 PR 描述材料；图模式问题会检查 Inductor/Triton 调试产物。 | | ||
| 43 | +| [`torch-npu-pr-review`](./torch-npu-pr-review/SKILL.md) | 审核 Ascend/pytorch 的单个或多个 GitCode PR，支持 issue 入口、关联 PR 发现和跨分支对比。 | GitCode issue/PR 链接，可选目标分支和访问 token。 | 原始采集数据、`summary.json`、`data_report.md` 和审核报告；采集脚本仅依赖 Python 标准库，token 为可选增强项。 | | ||
| 44 | + | ||
| 45 | +### 常见选择 | ||
| 46 | + | ||
| 47 | +- **接入或修改一个算子**：从 `op-adaptation` 开始，它会在流程中组合 `op-test` 和 `op-apidoc`。 | ||
| 48 | +- **只补测试或文档**：分别直接使用 `op-test` 或 `op-apidoc`。 | ||
| 49 | +- **处理 API 一致性问题**：使用 `api-consistency`；没有 ATK 时也可以提供可执行脚本和完整日志。 | ||
| 50 | +- **修复 PyTorch 上游 UT**：普通 Core 交付流程使用 `torch-npu-issue-pipeline-core`；分布式、HCCL 或专项图模式问题使用 `torch-npu-issue-pipeline-distributed`。 | ||
| 51 | +- **咨询或排查 NPUGraph/ACLGraph**：使用 `npu-graph-skill`，由总入口选择知识、诊断、日志或性能子技能。 | ||
| 52 | +- **分析上游变更**：批量评估某个时间段的 PyTorch PR 使用 `pytorch-pr-analysis`；审核具体 torch-npu PR 使用 `torch-npu-pr-review`。 | ||
| 53 | + | ||
| 54 | +## 🚀 快速入门 | ||
| 55 | + | ||
| 56 | +### 1. 选择技能 | ||
| 57 | + | ||
| 58 | +先根据上方表格选择最接近任务的顶层技能。描述比较明确时，可以直接用自然语言交代任务，Agent 会根据 `SKILL.md` 中的触发条件匹配；存在多个相近技能时，建议明确写出技能名。 | ||
| 59 | + | ||
| 60 | +### 2. 确保运行环境可用 | ||
| 61 | + | ||
| 62 | +请根据所选 Skill 的 README 准备运行环境和依赖。 | ||
| 63 | + | ||
| 64 | +### 3. 提供最小必要上下文 | ||
| 65 | + | ||
| 66 | +为了让 Agent 能够直接开始工作，建议至少提供： | ||
| 67 | + | ||
| 68 | +- **任务目标**：希望分析、修改、测试还是生成文档。 | ||
| 69 | +- **工作目录或仓库**：例如 TorchNPU、OpPlugin 或 PyTorch 源码路径。 | ||
| 70 | +- **问题输入**：算子资料、完整用例名、复现命令、日志、PR 链接或时间范围。 | ||
| 71 | +- **环境信息**：目标分支、Python/PyTorch/TorchNPU/CANN 版本，以及 NPU 是否可用。 | ||
| 72 | +- **交付要求**：仅分析，还是需要修改代码、运行验证或准备 PR 材料。 | ||
| 73 | + | ||
| 74 | +### 4. 用任务语言触发 | ||
| 75 | + | ||
| 76 | +```text | ||
| 77 | +请使用 op-adaptation，把 ./aclnn_input/DynamicQuant 下的 | ||
| 78 | +aclnnDynamicQuant.md 和 dynamic_quant_def.cpp 接入当前 OpPlugin 仓库， | ||
| 79 | +完成签名校验、测试、API 文档和集成摘要。 | ||
| 80 | +``` | ||
| 81 | + | ||
| 82 | +```text | ||
| 83 | +请使用 torch-npu-issue-pipeline-distributed 处理这个 HCCL 社区用例失败： | ||
| 84 | +case_name=<完整参数化用例名> | ||
| 85 | +错误日志=<粘贴完整日志> | ||
| 86 | +``` | ||
| 87 | + | ||
| 88 | +```text | ||
| 89 | +请使用 torch-npu-pr-review 审核以下 PR，并比较它们在不同目标分支的差异： | ||
| 90 | +<PR 链接 1> <目标分支> | ||
| 91 | +<PR 链接 2> <目标分支> | ||
| 92 | +``` | ||
| 93 | + | ||
| 94 | +## 📦 安装指南 | ||
| 95 | + | ||
| 96 | +### 方式一：使用 Skills 管理工具 | ||
| 97 | + | ||
| 98 | +本仓托管在 GitCode，请使用完整仓库 URL： | ||
| 99 | + | ||
| 100 | +```bash | ||
| 101 | +# 查看仓库中可安装的 skills | ||
| 102 | +npx skills add https://gitcode.com/Ascend/agent-skills --list | ||
| 103 | + | ||
| 104 | +# 安装一个技能包 | ||
| 105 | +npx skills add https://gitcode.com/Ascend/agent-skills --skill npu-graph-skill | ||
| 106 | + | ||
| 107 | +# 算子接入建议同时安装三个协作技能 | ||
| 108 | +npx skills add https://gitcode.com/Ascend/agent-skills \ | ||
| 109 | + --skill op-adaptation \ | ||
| 110 | + --skill op-test \ | ||
| 111 | + --skill op-apidoc | ||
| 112 | +``` | ||
| 113 | + | ||
| 114 | +如需指定 Agent，可按管理工具支持的名称增加 `-a <agent>`；在 CI/CD 中可结合 `-g -y` 使用非交互安装。 | ||
| 115 | + | ||
| 116 | +### 方式二：克隆后从本地安装 | ||
| 117 | + | ||
| 118 | +```bash | ||
| 119 | +git clone https://gitcode.com/Ascend/agent-skills.git | ||
| 120 | +cd agent-skills | ||
| 121 | + | ||
| 122 | +npx skills add ./official/PyTorch --list | ||
| 123 | +npx skills add ./official/PyTorch --skill ci-static-errors-fix | ||
| 124 | +``` | ||
| 125 | + | ||
| 126 | +### 方式三：手动复制 | ||
| 127 | + | ||
| 128 | +Skills 本质上是包含 `SKILL.md` 及配套资源的目录。也可以把所需的**整个顶层技能目录**复制到目标 Agent 的 skills 搜索路径，不要只复制 `SKILL.md`，否则脚本、模板、参考资料和子技能会缺失。 | ||
| 129 | + | ||
| 130 | +| Agent | 常见项目级目录 | | ||
| 131 | +|---|---| | ||
| 132 | +| OpenCode | `.opencode/skills/` | | ||
| 133 | +| Claude Code | `.claude/skills/` | | ||
| 134 | +| TRAE | `.trae/skills/` | | ||
| 135 | +| Cursor | `.cursor/skills/` | | ||
| 136 | + | ||
| 137 | +以 `op-adaptation` 为例： | ||
| 138 | + | ||
| 139 | +```bash | ||
| 140 | +cp -r official/PyTorch/op-adaptation .claude/skills/ | ||
| 141 | +cp -r official/PyTorch/op-test .claude/skills/ | ||
| 142 | +cp -r official/PyTorch/op-apidoc .claude/skills/ | ||
| 143 | +``` | ||
| 144 | + | ||
| 145 | +## 📘 使用说明 | ||
| 146 | + | ||
| 147 | +### 运行原则 | ||
| 148 | + | ||
| 149 | +- 先阅读并调用顶层 `SKILL.md`。复杂套件会自行加载阶段技能、工具和参考资料。 | ||
| 150 | +- 保留完整目录结构；`references/`、`scripts/`、`templates/`、`examples/` 往往是工作流的一部分。 | ||
| 151 | +- 优先提供原始、完整、可追溯的输入，例如完整命令、日志、diff 和报告文件，不要只提供截图中的局部结论。 | ||
| 152 | +- 代码修改后应按技能要求执行最小必要验证；没有 NPU 或依赖缺失时，应明确记录跳过项和阻塞原因。 | ||
| 153 | +- Token、密码和私有凭证只通过安全的环境变量或本地配置提供，不要写入提示词、日志、报告或 Git 仓库。 | ||
| 154 | +- 涉及提交、推送、创建 PR/MR 等外部变更时，先确认目标仓库、分支和交付范围。 | ||
| 155 | + | ||
| 156 | +## 📂 目录结构 | ||
| 157 | + | ||
| 158 | +```text | ||
| 159 | +official/PyTorch/ | ||
| 160 | +├── README.md | ||
| 161 | +├── api-consistency/ | ||
| 162 | +├── ci-static-errors-fix/ | ||
| 163 | +├── com-auto-binary-pr/ | ||
| 164 | +├── core-requirement-analyze/ | ||
| 165 | +├── npu-graph-skill/ | ||
| 166 | +├── op-adaptation/ | ||
| 167 | +├── op-apidoc/ | ||
| 168 | +├── op-test/ | ||
| 169 | +├── pytorch-pr-analysis/ | ||
| 170 | +├── torch-npu-issue-pipeline-core/ | ||
| 171 | +├── torch-npu-issue-pipeline-distributed/ | ||
| 172 | +└── torch-npu-pr-review/ | ||
| 173 | +``` | ||
| 174 | + | ||
| 175 | +具体触发条件、输入约束、执行步骤和输出格式，请以各技能目录中的 `SKILL.md` 为准。 | ||