# cannbot-helper

> CANNBot Helper — CANNBot 交互式安装助手

[![npm version](https://img.shields.io/npm/v/cannbot-helper.svg)](https://www.npmjs.com/package/cannbot-helper)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)

## 快速开始

```bash
# 全局安装（推荐）
npm install -g cannbot-helper
cannbot-helper

# 或 npx 即用（无需安装）
npx cannbot-helper
```

交互式向导会自动检测已安装的 AI 编程工具（OpenCode / Claude Code / Trae / Cursor），通过箭头键选择场景即可完成安装。

## 命令一览

| 命令 | 说明 |
|------|------|
| `cannbot-helper` / `cannbot-helper init` | 交互式安装向导 |
| `cannbot-helper list` | 列出可用场景及安装状态 |
| `cannbot-helper install <name>` | 安装指定插件或 Skill（自动识别） |
| `cannbot-helper install --list` | 按类别列出所有可用 Skills |
| `cannbot-helper update [plugin]` | 更新已安装的 Skills |
| `cannbot-helper uninstall <plugin>` | 卸载指定场景 |
| `cannbot-helper status` | 查看已安装插件详情 |
| `cannbot-helper doctor` | 健康检查 |
| `cannbot-helper doctor --fix` | 健康检查 + 自动修复 |
| `cannbot-helper info <plugin>` | 查看插件详情 |
| `cannbot-helper lang show` | 显示当前语言 |
| `cannbot-helper lang set en_US` | 切换语言 |

> 短命令别名：`cbot` 等价于 `cannbot-helper`

## 命令详解

### 交互式安装向导

```bash
cannbot-helper
# 或
cannbot-helper init
```

向导会引导你完成：
1. 自动检测已安装的 AI 编程工具
2. 选择安装级别（project / global）
3. 多选要安装的场景（空格切换，回车确认）
4. 确认并执行安装

**智能记忆**：向导会记住你上次选择的工具和级别，下次运行无需重新选择。已安装的插件会自动标记并默认不勾选。

### 安装指定场景

```bash
cannbot-helper install ops-direct-invoke              # 安装单个
cannbot-helper install triton --tool claude           # 指定工具
cannbot-helper install ops-direct-invoke --yes        # 跳过确认
cannbot-helper install ops-direct-invoke --level global  # 全局安装
```

**重要说明**：

每个插件都有独立的 `AGENTS.md` 配置文件。如果在同一目录下安装多个插件，后安装的会覆盖前一个的配置文件。

**推荐做法**：
- 每个项目只安装一个插件
- 如需使用多个插件，在不同目录下分别安装

**示例**：
```bash
# 项目 A：使用 Kernel 直调
cd project-a
cannbot-helper install ops-direct-invoke --tool opencode

# 项目 B：使用 Triton
cd project-b
cannbot-helper install triton --tool opencode
```

> **注意**：每个插件有独立的 `AGENTS.md` 配置文件。同一项目目录下安装多个插件时，后安装的会覆盖前一个的 `AGENTS.md`。如需同时使用多个插件，建议分别在不同项目目录中安装。

### 安装单个 Skill（轻量模式）

如果只需要让 AI agent 掌握特定领域知识，不需要完整工作流，可以直接安装单个 Skill：

```bash
cannbot-helper install npu-arch                          # 安装 NPU 架构知识
cannbot-helper install ascendc-precision-debug           # 安装精度调试技能
cannbot-helper install model-infer-kvcache               # 安装 KVCache 优化技能
cannbot-helper install --list                            # 查看所有可用 Skills
```

Skills 按 11 个大类组织：知识与参考、环境与工具、调试与诊断、测试与质量、AscendC 开发、PyPTO 开发、TileLang 开发、Triton 开发、模型推理优化、图模式、平台工具。

`install` 命令自动识别输入是插件还是 Skill，无需区分。

**选项：**

| 选项 | 说明 |
|------|------|
| `--tool <tool>` | 指定 AI 工具（opencode, claude, trae, cursor, copilot） |
| `--level <level>` | 安装级别（project, global），默认 project |
| `--all` | 安装全部场景 |
| `--yes` | 跳过所有确认提示 |

**已装检测**：如果插件已安装，会提示是否覆盖安装。使用 `--yes` 可跳过提示直接覆盖。

### 更新已安装的 Skills

```bash
cannbot-helper update              # 更新所有已安装插件
cannbot-helper update triton       # 更新指定插件
```

更新流程：`git pull` 拉取最新 Skills 仓库 → 重新执行安装脚本 → 软链接自动指向最新内容。

### 查看插件详情

```bash
cannbot-helper info ops-direct-invoke
```

输出插件描述、包含的 Skills/Agents 列表、quickstart 文档路径、安装状态。

### 健康检查

```bash
cannbot-helper doctor              # 仅检测
cannbot-helper doctor --fix        # 检测 + 自动修复
```

检查项目：
- AI 工具安装状态
- 已安装插件状态
- 软链接完整性
- 配置文件存在性

`--fix` 会自动修复：清理失效软链接、重建缺失目录。

### 语言管理

```bash
cannbot-helper lang show           # 显示当前语言
cannbot-helper lang set zh_CN      # 设置为中文（默认）
cannbot-helper lang set en_US      # 设置为英文
```

语言设置保存在 `~/.cannbot/config.yaml`，重启后自动生效。

### 卸载

```bash
cannbot-helper uninstall ops-direct-invoke --tool opencode
```

卸载时根据安装记录（`~/.cannbot/installs/<plugin>.json`）精确删除所有安装产物：
- Skills 软链接
- Agents 软链接
- Workflows 链接
- 配置文件（AGENTS.md / CLAUDE.md）
- Manifest 文件
- 参考仓库链接（asc-devkit 等）
- 空目录清理

## 可用场景

| # | 场景 | ID | 别名 |
|---|------|----|------|
| 1 | AscendC Kernel 直调 | ops-direct-invoke | ops-direct, direct, kernel |
| 2 | AscendC Kernel 从零构建 | ops-direct-invoke-flash | flash |
| 3 | AscendC 算子注册调用 | ops-registry-invoke | ops-registry, registry |
| 4 | PyPTO 算子 | pypto-op-orchestrator | pypto |
| 5 | Triton 算子生成 | triton-op-generator | triton |
| 6 | TileLang 算子 | tilelang-op-orchestrator | tilelang |
| 7 | NPU 推理优化 | model-infer-optimize | model-infer, infer |
| 8 | Catlass 算子直调 | catlass-op-generator | catlass |
| 9 | 代码检视 | ops-code-reviewer | code-review, reviewer |
| 10 | torch.compile 图模式 | torch-compile | torch, compile |

## 前置条件

- Node.js >= 18
- 已安装至少一个 AI 编程工具（OpenCode / Claude Code / Trae / Cursor）
- Git（用于克隆 Skills 仓库）

## 工作原理

cannbot-helper 是一个编排工具：

1. **自动检测**已安装的 AI 编程工具
2. **克隆或更新** cannbot-skills 仓库（缓存到 `~/.cannbot/repo/`）
3. **调用**各插件的 `init.sh` / `install.sh` 脚本执行实际安装
4. **追踪**安装状态（`~/.cannbot/config.yaml` + manifest）

安装逻辑仍由各插件的 init.sh 脚本负责，cannbot-helper 提供统一的交互式入口和状态管理。

## 配置文件

配置保存在 `~/.cannbot/config.yaml`：

```yaml
language: zh_CN           # 界面语言
lastTool: opencode        # 上次使用的 AI 工具
lastLevel: project        # 上次安装级别
installedPlugins:         # 已安装的插件列表
  - ops-direct-invoke
  - pypto-op-orchestrator
```

## 开发

```bash
git clone https://gitcode.com/cann/cannbot-skills.git
cd cannbot-skills/packages/cannbot-helper

npm install
npm run dev          # watch 模式
npm run build        # 构建
npm link             # 全局注册
cannbot-helper list  # 测试
```