@cannbot-ai/install-helper 0.0.2-beta.11 → 0.0.2-beta.14

package/README.md

@@ -18,6 +18,22 @@ npx @cannbot-ai/install-helper
 
 交互式向导会自动检测已安装的 AI 编程工具（OpenCode / Claude Code / Trae / Cursor），通过箭头键选择场景即可完成安装。
 
+## 主要特性
+
+### 核心功能
+- **动态 Skill 发现**：自动扫描仓库中的 SKILL.md 文件，实时发现可用 Skills
+- **智能缓存机制**：扫描结果缓存 24 小时，大幅提升后续命令执行速度
+- **备份与恢复**：安装新插件时自动备份 AGENTS.md，支持一键恢复
+- **参数校验**：`--tool` 和 `--level` 参数支持校验，提供友好的错误提示（支持中英文）
+- **智能记忆**：记住上次选择的工具和安装级别，下次运行自动填充
+
+### 安装管理
+- **交互式向导**：箭头键选择，空格切换，回车确认
+- **插件安装**：支持 10 个官方插件，自动处理依赖
+- **Skill 安装**：支持 89 个 Skills，按 11 个类别组织
+- **智能卸载**：根据安装记录精确删除，自动清理空目录
+- **健康检查**：检测安装状态，自动修复常见问题
+
 ## 命令一览
 
 | 命令 | 说明 |
@@ -168,6 +184,10 @@ install-helper uninstall ops-direct-invoke --tool opencode
 
 ## 可用场景
 
+install-helper 支持 **10 个官方插件** 和 **89 个 Skills**（动态发现，数量可能随仓库更新而变化）。
+
+#### 官方插件
+
 | # | 场景 | ID | 别名 |
 |---|------|----|------|
 | 1 | AscendC Kernel 直调 | ops-direct-invoke | ops-direct, direct, kernel |
@@ -181,6 +201,23 @@ install-helper uninstall ops-direct-invoke --tool opencode
 | 9 | 代码检视 | ops-code-reviewer | code-review, reviewer |
 | 10 | torch.compile 图模式 | torch-compile | torch, compile |
 
+#### Skills 类别
+
+Skills 按 11 个类别组织（动态发现，数量可能随仓库更新而变化）：
+- 知识与参考
+- 环境与工具
+- 调试与诊断
+- 测试与质量
+- AscendC 开发
+- PyPTO 开发
+- TileLang 开发
+- Triton 开发
+- 模型推理优化
+- 图模式
+- 平台工具
+
+使用 `install-helper install --list` 查看完整的 Skills 列表。
+
 ## 前置条件
 
 - Node.js >= 18
@@ -192,17 +229,21 @@ install-helper uninstall ops-direct-invoke --tool opencode
 install-helper 是一个编排工具：
 
 1. **自动检测**已安装的 AI 编程工具
-2. **克隆或更新** cannbot-skills 仓库（缓存到 `~/.cannbot/repo/`）
-3. **调用**各插件的 `init.sh` / `install.sh` 脚本执行实际安装
-4. **追踪**安装状态（`~/.cannbot/config.yaml` + manifest）
+2. **动态扫描**仓库中的 SKILL.md 文件，发现可用 Skills
+3. **缓存扫描结果**到 `~/.cannbot/scan-cache.json`（24 小时有效）
+4. **克隆或更新** cannbot-skills 仓库（缓存到 `~/.cannbot/repo/`）
+5. **备份现有配置**（如果检测到已安装的 AGENTS.md）
+6. **调用**各插件的 `init.sh` / `install.sh` 脚本执行实际安装
+7. **追踪**安装状态（`~/.cannbot/config.yaml` + manifest）
 
 安装逻辑仍由各插件的 init.sh 脚本负责，install-helper 提供统一的交互式入口和状态管理。
 
 ## 配置文件
 
-配置保存在 `~/.cannbot/config.yaml`：
+配置保存在 `~/.cannbot/` 目录：
 
 ```yaml
+# config.yaml - 用户配置
 language: zh_CN           # 界面语言
 lastTool: opencode        # 上次使用的 AI 工具
 lastLevel: project        # 上次安装级别
@@ -211,6 +252,26 @@ installedPlugins:         # 已安装的插件列表
   - pypto-op-orchestrator
 ```
 
+```json
+// scan-cache.json - 扫描缓存（自动生成，24 小时有效）
+{
+  "skills": [...],
+  "timestamp": 1234567890,
+  "repoPath": "/path/to/repo"
+}
+```
+
+```json
+// installs/<plugin>.json - 安装记录（每个插件一个文件）
+{
+  "pluginId": "ops-direct-invoke",
+  "installTime": "2026-06-23T10:00:00Z",
+  "configRoot": "/path/to/config",
+  "files": [...],
+  "directories": [...]
+}
+```
+
 ## 开发
 
 ```bash

package/dist/index.js

@@ -682,6 +682,9 @@ function scanInstalled() {
       for (const manifest of manifests) {
         const plugin = plugins.find((p) => p.id === manifest.team);
         if (!plugin) continue;
+        if (!verifyPluginFilesExist(configRoot, manifest, tool, level)) {
+          continue;
+        }
         const alreadyAdded = installed.some(
           (p) => p.id === plugin.id && p.tool === tool && p.level === level
         );
@@ -701,6 +704,32 @@ function scanInstalled() {
   }
   return installed;
 }
+function verifyPluginFilesExist(configRoot, manifest, tool, level) {
+  const skillsDir = join3(configRoot, "skills");
+  const agentsDir = join3(configRoot, "agents");
+  if (manifest.installed_skills && manifest.installed_skills.length > 0) {
+    const hasAnySkill = manifest.installed_skills.some((skillId) => {
+      const skillPath = join3(skillsDir, skillId);
+      return existsSync3(skillPath);
+    });
+    if (!hasAnySkill) return false;
+  }
+  if (manifest.installed_agents && manifest.installed_agents.length > 0) {
+    const hasAnyAgent = manifest.installed_agents.some((agentId) => {
+      const agentPath = join3(agentsDir, agentId);
+      return existsSync3(agentPath);
+    });
+    if (!hasAnyAgent) return false;
+  }
+  let agentsMdPath;
+  if (tool === "opencode" && level === "project") {
+    agentsMdPath = join3(configRoot, "..", "AGENTS.md");
+  } else {
+    agentsMdPath = join3(configRoot, "AGENTS.md");
+  }
+  if (!existsSync3(agentsMdPath)) return false;
+  return true;
+}
 
 // src/utils/logger.ts
 import chalk from "chalk";
@@ -1096,7 +1125,7 @@ import { execa as execa2 } from "execa";
 
 // src/core/scanner.ts
 import { existsSync as existsSync5, readdirSync, readFileSync as readFileSync3, statSync, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
-import { join as join5 } from "path";
+import { join as join5, dirname } from "path";
 import { parse as parseYaml } from "yaml";
 var EXCLUDE_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
@@ -1779,7 +1808,13 @@ function removeSkillsFromRecord(skillIds, tool, level, installPath) {
 }
 function getInstalledSkills(tool, level, installPath) {
   const record = readSkillRecord();
-  return record[tool]?.[level]?.[installPath]?.skills || [];
+  const recordedSkills = record[tool]?.[level]?.[installPath]?.skills || [];
+  const configRoot = getConfigRoot(tool, level);
+  const skillsDir = join7(configRoot, "skills");
+  return recordedSkills.filter((skillId) => {
+    const skillPath = join7(skillsDir, skillId);
+    return existsSync7(skillPath) || isSymlink(skillPath);
+  });
 }
 
 // src/core/backup.ts
@@ -2159,7 +2194,7 @@ async function uninstallSkills(skillIds, tool, level) {
   }
   return results;
 }
-async function interactiveSkillSelect() {
+async function interactiveSkillSelect(tool, level) {
   const BACK3 = "__back__";
   const CANCEL3 = "__cancel__";
   const categories = getAllCategories();
@@ -2195,15 +2230,8 @@ async function interactiveSkillSelect() {
         const category = categories.find((c) => c.id === selectedCategoryId);
         if (!category) return [];
         printBoxTitle(t("wizard_step_4_skill_title").replace("{category}", category.name));
-        const tools = ["opencode", "claude", "trae", "cursor", "copilot"];
-        const levels = ["project", "global"];
-        const installedSkills = [];
-        for (const tk of tools) {
-          for (const l of levels) {
-            const path = l === "project" ? process.cwd() : getConfigRoot(tk, l);
-            installedSkills.push(...getInstalledSkills(tk, l, path));
-          }
-        }
+        const installPath = level === "project" ? process.cwd() : getConfigRoot(tool, level);
+        const installedSkills = getInstalledSkills(tool, level, installPath);
         const installedSet = new Set(installedSkills);
         const skillChoices = category.skills.map((skill) => {
           const isInstalled = installedSet.has(skill.id);
@@ -2536,7 +2564,7 @@ async function skillInstallFlow() {
         break;
       }
       case 2: {
-        const selectedSkills = await interactiveSkillSelect();
+        const selectedSkills = await interactiveSkillSelect(tool, level);
         if (selectedSkills === "back") {
           step = 1;
           break;
@@ -2807,20 +2835,22 @@ async function installCommand(names, options) {
       tool2 = validateTool(options.tool);
     } else {
       const detected = await selectToolWithDetection();
-      if (detected === "back") return;
+      if (detected === "back" || detected === "cancel") return;
       tool2 = detected;
     }
+    const level2 = options.level ? validateLevel(options.level) : "project";
     let step = 1;
     while (true) {
       switch (step) {
         case 1: {
-          const selectedSkills = await interactiveSkillSelect();
+          const selectedSkills = await interactiveSkillSelect(tool2, level2);
           if (selectedSkills === "back") {
             const redetected = await selectToolWithDetection();
-            if (redetected === "back") return;
+            if (redetected === "back" || redetected === "cancel") return;
             tool2 = redetected;
             break;
           }
+          if (selectedSkills === "cancel") return;
           if (selectedSkills.length === 0) {
             logger.info(t("install_no_skill_selected"));
             return;
@@ -2832,7 +2862,6 @@ async function installCommand(names, options) {
           const repoPath = await repoManager.ensureRepo();
           spinner.succeed("\u63D2\u4EF6\u6570\u636E\u52A0\u8F7D\u5B8C\u6210");
           logger.info(`${t("skill_install_progress")} ${chalk9.bold(names.length)} \u4E2A Skills...`);
-          const level2 = options.level ? validateLevel(options.level) : "project";
           const results = await installSkills(names, tool2, level2, repoPath);
           let successCount = 0;
           let failCount = 0;
@@ -2896,7 +2925,7 @@ async function installCommand(names, options) {
     tool = validateTool(options.tool);
   } else {
     const detected = await selectToolWithDetection();
-    if (detected === "back") return;
+    if (detected === "back" || detected === "cancel") return;
     tool = detected;
   }
   const level = options.level ? validateLevel(options.level) : "project";
@@ -3133,7 +3162,7 @@ async function updateCommand(pluginNames, options) {
     tool = validateTool(options.tool);
   } else {
     const detected = await selectToolWithDetection();
-    if (detected === "back") return;
+    if (detected === "back" || detected === "cancel") return;
     tool = detected;
   }
   const level = options.level ? validateLevel(options.level) : "project";
@@ -3295,7 +3324,7 @@ function createCLI() {
     setLanguage(config.language);
   }
   const program2 = new Command();
-  program2.name("install-helper").description("CANNBot Install Helper - Interactive installer for CANN operator development skills").version("0.0.2-beta.11");
+  program2.name("install-helper").description("CANNBot Install Helper - Interactive installer for CANN operator development skills").version("0.0.2-beta.14");
   program2.command("init", { isDefault: false }).description("Run interactive installation wizard").action(async () => {
     await initCommand();
   });