---
tags: [CANN]
doc_type: knowledge-note
abstract: "理解 Teams、Agents、Skills 分工，准备并校验开发环境。"
返回目录: "[[计算机系/昇腾与CANN/大模型与算子专题学习导航|大模型与算子专题学习导航]]"
专题目录: "[[计算机系/昇腾与CANN/CANNBot智能体与算子开发工作流|CANNBot智能体与算子开发工作流]]"
下一篇: "[[计算机系/昇腾与CANN/05 CANNBot开发流程与质量验证|05 CANNBot开发流程与质量验证]]"
前置知识: "[[计算机系/昇腾与CANN/Prompt、RAG、Skill与MCP的关系|Prompt、RAG、Skill与MCP的关系]]"
---

# 04 CANNBot架构与环境配置

理解 Teams、Agents、Skills 分工，准备并校验开发环境。

## 1. CANNBot解决什么问题

CANNBot 面向昇腾 CANN 开源社区，将领域知识、开发工具和智能体组织成可复用的研发流程。用户描述算子的数学语义、输入输出和目标平台后，系统围绕需求分析、方案设计、代码生成、测试、排障和性能验收开展工作。

算子开发需要同时理解 NPU 架构、存储层次、API 约束、Tiling 和数值精度。将这些知识封装为 Skills，可以减少重复查阅与配置；通过 Agent 分工和阶段验收，可以让设计、代码、测试结果及修改原因相互对应。

| 价值 | 具体做法 |
| --- | --- |
| 知识资产化 | 将文档、代码模板、失败案例和开发经验沉淀为技能及参考资产 |
| 流程工程化 | 以明确的输入输出、质量门禁和测试证据组织开发 |
| 平台可演进 | 在统一底座上扩展领域 Bot，逐步加入路由、隔离、观测、评测与发布机制 |

覆盖方向包括 Ascend C、PyPTO、TileLang、Triton、CATLASS 算子开发，以及模型训练与推理优化、图和运行时等领域。平台总体设计还涉及通信、编程语言和工具链。

技能数量与支持范围随版本变化，不能仅凭技能总数判断某条工作流是否完整。项目入口：[cann/cannbot-skills](https://gitcode.com/cann/cannbot-skills)。

## 2. 平台架构与三层分工

### 2.1 统一底座与领域Bot

平台设计采用“统一底座 + 多领域 Bot”。开发请求可以来自 CLI、IDE、社区 Issue/PR、CI/CD 流水线或 AI 框架。Router 拆解意图并路由任务，领域内部再由编排器安排 Agent 和 Skill。

![CANNBot平台架构](.assets/CANNBot/平台架构.png)

底座能力包括大模型、工具调用、Memory、日志、沙箱、策略管理、可观测性，以及注册和发布机制。领域 Bot 在共用底座上积累专业能力，避免每个领域重复实现基础设施。

这是一张总体架构蓝图。完整 Harness、多领域协同和持续进化需要分阶段落地，不能据此认为每个安装版本都已经具备全部能力。

### 2.2 Teams、Agents与Skills

![Teams、Agents与Skills三层架构](.assets/CANNBot/Teams-Agents-Skills.png)

| 层次 | 核心职责 | 例子 |
| --- | --- | --- |
| Teams：应用编排层 | 定义任务流程、阶段顺序及角色协作关系 | `ops-direct-invoke`、`pypto-op-orchestrator` |
| Agents：角色执行层 | 根据分工执行分析、开发、审查等任务 | `architect/analyst`、`developer`、`reviewer` |
| Skills：知识能力层 | 提供领域规则、方法、模板和工具使用知识 | NPU 架构、Tiling 设计、API 最佳实践、精度调试 |

**Team 组织流程，Agent 执行任务，Skill 提供执行所需的知识与方法。**一个 Agent 可以使用多个 Skills，同一 Skill 也可以供不同角色复用。

`ops-direct-invoke` 对应 Ascend C Kernel 直调开发。`ops-registry-invoke` 对应自定义算子开发编排，在这套架构中标为规划项；`perf-tuner/tester` 专门角色也标为规划项。已有相关技能与完整专门角色的交付状态需要分别判断。

### 2.3 按任务选择技能

| 任务 | 代表性Skills |
| --- | --- |
| 环境和架构确认 | `ascendc-env-check`、`cann-env-setup`、`ascendc-npu-arch` |
| 需求与规格 | `ops-spec-gen`、`ascendc-task-focus` |
| Tiling与代码实现 | `ascendc-tiling-design`、`ascendc-api-best-practices`、`ascendc-direct-invoke-template` |
| 文档检索与生成 | `ascendc-docs-search`、`ascendc-docs-gen` |
| 代码检视与测试 | `ascendc-code-review`、`ascendc-ut-develop`、`ascendc-st-design`、`ascendc-whitebox-design` |
| 精度与运行故障 | `ascendc-precision-debug`、`ascendc-runtime-debug`、`ascendc-crash-debug` |
| 性能采集与优化 | `ops-profiling`、`ascendc-performance-best-practices` |
| 直调和注册方式转换 | `ascendc-direct-invoke-to-registry-invoke`、`ascendc-registry-invoke-to-direct-invoke` |

其他技术栈也有对应流程：PyPTO 包括意图理解、Golden 参考实现、设计、开发、精度比较与调优；TileLang 包括编程模型、API、设计、开发和检视；Triton 包括任务提取、设计、代码生成、验证及延迟优化；CATLASS 包括内核设计、开发及调优。

模型推理技能涉及融合算子替换、图模式、KV Cache、并行、多流、预取、精度与运行时诊断。Torch 入图技能涉及自定义算子入图和 `npugraph_ex` 的模板、编译及运行故障诊断。GitCode 工具则辅助 Issue、PR 描述与仓库操作。技能名称和实际可用入口应与所用仓库版本对应。

## 3. 环境准备与安装

### 3.1 运行条件

这里的命令用于具备昇腾开发环境的 Linux 主机或云开发环境。

| 项目 | 示例环境要求 |
| --- | --- |
| NPU | Ascend 910及后续系列产品，具体算子需核对目标芯片支持 |
| CANN | 8.0.RC2及以上，并核对所用技能、API与芯片的兼容性 |
| 内存 | 建议16 GB以上 |
| 存储 | 建议50 GB可用空间 |
| 操作系统 | EulerOS 2.10、CentOS 7.6、Ubuntu 18.04+等示例环境；实际按目标CANN版本支持矩阵选择 |
| 客户端 | OpenCode、Claude Code、TRAE等，具体配置方式不同 |
| 网络 | 能访问GitCode仓库及所用模型服务 |

先确认设备信息可以正常查询：

```bash
npu-smi info
```

同时检查 CANN 版本、环境变量、编译依赖和客户端配置。CANN 社区云开发环境可以预置 NPU、CANN 和 OpenCode 等依赖，但仍应确认当前实例实际就绪。

### 3.2 脚本安装

克隆仓库后先进入仓库根目录，再进入直调工作流目录：

```bash
git clone https://gitcode.com/cann/cannbot-skills.git
cd cannbot-skills
cd skills/ops/teams/ops-direct-invoke
```

在该目录下，根据客户端与作用范围选择一条初始化命令：

| 范围 | OpenCode | Claude Code |
| --- | --- | --- |
| 项目级 | `bash init.sh project opencode` | `bash init.sh project claude` |
| 全局 | `bash init.sh global opencode` | `bash init.sh global claude` |

项目级配置适合隔离不同工程的开发规则。全局配置作用于用户环境，需要留意不同项目之间的配置影响。

初始化内容包括 Skills、Agents、`asc-devkit` 工具包，以及对应客户端配置。典型配置位置如下：

| 客户端 | 项目级目录 | 全局目录 |
| --- | --- | --- |
| OpenCode | `.opencode/` | `~/.config/opencode/` |
| Claude Code | `.claude/` | `~/.claude/` |

脚本帮助入口：

```bash
bash init.sh --help
```

更新技能可按初始化脚本的更新方式重新执行，但应先检查自定义配置是否会受影响。

### 3.3 手动配置与校验

手动配置适合自定义安装位置，主要工作是放置或链接 Skills、Agents，并准备客户端规则文件。它不等于完成全部工具链依赖安装。

符号链接的相对目标按**链接所在目录**解析。例如 `.opencode/skills` 指向 `../ops/skills` 时，要从 `.opencode/` 所在位置推算目标，不能仅凭终端当前目录判断。目录结构不同，应重新计算链接路径。

启动前确认：

- Skills和Agents目录存在，内容非空，链接目标有效。
- OpenCode所需的`AGENTS.md`、`opencode.json`等配置位于客户端能读取的位置。
- Claude Code配置采用相应的`CLAUDE.md`和目录结构。
- 当前工作目录确实属于已经初始化的项目。

在初始化目录启动 OpenCode：

```bash
opencode
```

`ascendc-env-check` 等名称表示供智能体调用的技能，不能直接把“技能名 + skill”当作通用 Shell 命令。