企业官网建设流程全解析

oam-tools 仓库 Agent Skills 规划与全自动化开发流程指南

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools

oam-tools（Operations, Administration, and Maintenance）是华为 CANN 的运维工具集，为开发者提供故障定位与性能调优能力（故障信息收集、AI Core Error 分析、性能剖析、HCCL 性能测试等）。本文基于仓库.opencode/README_en.md的规划文档，系统讲解 oam-tools 为 AI Agent 设计的 Skills 清单、需要支持的完整开发流程、Skills 的安装与路径管理机制，并结合仓库源码给出实现细节。读完本文，你将掌握该仓库 Agent 自动化闭环（需求开发 → 编码 → UT/ST → 检视 → PR → 流水线监控 → 修复重提）的完整设计，以及如何在 oam-tools 目录下启动 Agent 时自动装配默认 Skills。

一、背景：为什么 oam-tools 需要 Agent Skills 规划

oam-tools 是典型的"多模块、多语言、强流程约束"的运维工具仓库，从 AGENTS.md 可以看到其四大核心能力：

• 故障信息收集（asys）：故障信息收集、软硬件信息展示、健康检查、综合检测等，源码位于 src/asys；
• AI Core Error 分析（msaicerr）：AI Core Error 问题分析、Dump 文件解析、环境检查等，源码位于 src/msaicerr；
• 性能调优（msprof）：采集分析昇腾 AI 处理器上 AI 任务各阶段关键性能指标，源码位于 src/msprof；
• HCCL 性能测试（hccl_test）：分布式场景下集合通信功能与性能测试，源码位于 src/hccl_test。

这样的仓库对 Agent 的诉求非常明确：让 Agent 在仓库内完成从需求到合入的完整闭环，而不是只做"单点问答"。为此，项目组在.opencode/README_en.md中规划了一整套 Skills 体系，并用一个插件实现启动时自动安装/更新。

说明：.opencode/README_en.md为英文规划文档，仓库内同时维护了中文版 .opencode/README.md，两份内容一一对应。

二、oam-tools 仓 Skills 清单

规划文档以清单形式列出了 9 个 Skill，其中[x]表示已就绪（ready），[ ]表示仍在规划中、尚未实现。以下完整保留原文档内容并补充说明：

从这张清单可以看出项目组的 Skill 分层设计思路：

• 平台层（gitcode-issue、gitcode-pr、gitcode-pipeline）：打通代码托管平台与 CI/CD 的核心操作，是自动化闭环的地基；
• 工程层（oam-tools-reviewer、oam-tools-dt-runner、oam-tools-tester）：面向仓库本身的代码质量与验证能力，直接对应当前仓库 test/ 下庞大的 UT/ST 用例体系；
• 能力层（superpowers、api-doc-generator、install-cann-toolkit）：提升 Agent 的开发、文档与部署能力。

与仓库现状的对照：Skills 已部分落地

规划文档中的 Skill 是"目标蓝图"，而当前仓库的 skills 目录已经实际沉淀了一批聚焦昇腾调优场景的 Skill，例如：

• cann-npu-perfanalysis/SKILL.md：分析 Ascend NPU Profiling 数据，覆盖迭代效率、算子热点、MFU、通信效率、设备空泡等 8 个性能维度，输出 Host/Device Bound 判定与 Markdown + HTML 双格式报告；
• cann-perf-breakdown、cann-perf-breakdown-to-ui-json、cann-perf-ui-json-report 等：围绕性能拆解、UI JSON 报告生成形成完整链路。

同时 AGENTS.md 在"开发规范"一节明确：gitcode pr/issue 操作引用.claude/skills/default-skills/SKILL.md，说明规划中的跨仓共享 Skill 将通过.claude/skills目录注入使用。规划文档与仓库现状互为印证：清单给出规划，skills 目录给出已实现的样例。

三、Agent 需要支持的四大流程

规划文档定义了 Agent 在 oam-tools 仓库必须支持的四种工作流，这是整个 Skills 体系的业务驱动：

1. 需求开发（Requirement Development）

完成从软件设计 → 编码 → 验证的完整流程：

1. 使用gitcode-pr提交 PR；
2. 个人检视代码；
3. 使用gitcode-pipeline触发流水线，并定时获取结果；
4. 若流水线失败，获取对应失败任务日志，本地修改代码，再次提交 PR 并持续监控流水线，直至通过。

2. 问题单修改（Issue Fix）

修改代码，后续 PR 提交流程与需求开发完全一致——即"改码容易，走完流程才是闭环"。

3. 解决 Issue（Solve Issue）

使用gitcode-issue读取 Issue 及评论；如果涉及修改代码或文档，后续流程同样与需求开发一致。

4. 执行测试用例或样例

使用oam-tools-tester在**真实环境（带 NPU）**中执行用例。这与仓库 examples 目录（asys、msaicerr、msprof 各组件均有 run.sh 样例）以及 test 目录（UT/ST 用例）直接呼应——Agent 不仅写代码，还要能跑真实的昇腾环境验证。

四、oam-tools 仓 Skills 路径管理机制

规划层面的路径规则

• 项目组共享：期望做到启动 Agent 时默认安装或更新Skills；
• 仓库私有 Skill：仅在 oam-tools 仓使用的 Skills 可直接提交到 oam-tools 仓的.claude/skills目录；
• 跨仓共享 Skill：多个仓库共用的 Skills，源码存放在公共仓，启动 Agent 时会自动下载或更新到.claude/skills目录。

注意：gitcode-issue、gitcode-pr等跨仓共享 Skills 不在 oam-tools 仓的.claude/skills目录中维护，其源码存放在公共仓；在 oam-tools 目录下启动 Agent 后会自动下载并安装到本地.claude/skills目录。

实现层面的自动安装插件

"启动 Agent 自动安装/更新"并非停留在规划，仓库提供了实际实现：.opencode/plugins/install-default-skills.ts。从源码结构可以梳理出该插件的核心机制：

1. 定位仓库根目录：通过findGitRoot从当前目录向上逐级查找.git目录，确保在子目录启动也能正确找到仓库根；
2. Windows 平台降级处理：检测process.platform === 'win32'，若是 Windows 则跳过自动安装，改为提示用户输入"安装默认skill"指令手动触发；
3. 执行安装脚本：调用.claude/skills/default-skills/scripts/install-default-skills.sh完成下载/更新；
4. MD5 变更检测：安装前后分别对gitcode-pr、gitcode-issue两个 Skill 的SKILL.md计算 MD5 哈希，比对beforeStates与afterStates：
   • 文件从不存在变为存在 → 判定"新安装"；
   • 文件存在但哈希变化 → 判定"已更新"；
   • 只有当发生变化时，才延迟 1 秒提示"重启 opencode 才能完全生效"，避免打扰；
5. 失败兜底：安装出错时写日志到install_error.log，并在仓库根目录生成错误标记文件.opencode_skills_error，提示用户输入"安装默认skill"重试。

此外，.opencode/opencode.json 中的插件配置还声明了superpowers@git+https://github.com/obra/superpowers.git插件依赖，与规划清单中"superpowers（需求开发）"一项对应，说明需求开发能力通过插件体系接入。

五、Agent 辅助流程（完整 Mermaid 图）

规划文档给出了一张完整的辅助流程图，清晰展示了从入口到结束的决策与执行路径，原文如下：

流程要点解读

入口分流：

• 需求开发（A1）直接进入设计判断 B2——需求开发必须先确认是否需要设计阶段；
• 问题单修改（A2）与Issue 处理（A3）进入代码修改判断 B1。

两级判断：

• B2（是否需要设计阶段）：需求开发需要 → 产出"软件设计/需求规格"（C1）后再编码；不需要 → 直接编码（D1）；
• B1（是否需要代码修改）：问题单/Issue 需要改代码 → 编码（D1）；不需要改代码 → 直接流程结束（H1）。

编码验证阶段（D1→D4）：编码完成后依次执行 UT/ST（D2）、由 oam-tools-reviewer 检视代码（D3）、由 oam-tools-tester 在真实环境本地验证（D4），全部通过后才进入 PR 流程。

PR 闭环（E1→E4→F1）：创建 PR（E1）→ 个人代码检视（E2）→ 触发流水线（E3）→ 定时获取结果（E4）。流水线通过则结束（H1）；失败则获取失败任务日志（F2）→ Agent 本地修复（F3）→ 通过 gitcode-pr 重新提交代码（I1）→ 再次触发流水线（E3），形成"失败-修复-重提-再验"的循环，直到流水线通过。

六、总结

oam-tools 的 Agent Skills 规划是一个典型的仓库级 Agent 自动化闭环设计：以 gitcode-issue / gitcode-pr / gitcode-pipeline 三个平台类 Skill 为骨架打通开发全链路，以 oam-tools-reviewer / oam-tools-dt-runner / oam-tools-tester 保障代码质量与真实环境验证，以 superpowers、api-doc-generator、install-cann-toolkit 补齐设计与部署能力；同时通过.opencode/plugins/install-default-skills.ts插件实现"启动即安装、变更即更新"的默认 Skills 装配机制。规划文档中已就绪的两个 Skill（gitcode-issue、gitcode-pr）与仓库 skills 目录中已沉淀的昇腾调优 Skill 相互印证，表明该体系正从规划稳步走向落地。

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools