heflc-skill 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# heflc-skill
+
+> 一条命令安装 AI Skill 到所有编辑器。
+
+## 安装
+
+```bash
+npm install -g heflc-skill
+```
+
+或不安装直接用：
+
+```bash
+npx heflc-skill <command>
+```
+
+## 使用
+
+```bash
+# 查看可用的 Skill
+heflc-skill list
+
+# 安装指定 Skill
+heflc-skill install tech-branding
+
+# 安装全部 Skill
+heflc-skill install --all
+
+# 更新已安装的 Skill
+heflc-skill update
+
+# 查看本机编辑器和已安装状态
+heflc-skill doctor
+
+# 卸载指定 Skill
+heflc-skill uninstall tech-branding
+```
+
+## 支持的编辑器
+
+自动检测本机安装的编辑器，将 Skill 注入全局配置：
+
+| 编辑器 | Skill 路径 |
+|--------|-----------|
+| Claude Code | ~/.claude/skills/&lt;name&gt;/SKILL.md |
+| Cursor | ~/.cursor/skills/&lt;name&gt;/SKILL.md |
+| Trae | ~/.trae/skills/&lt;name&gt;/SKILL.md |
+| Gemini | ~/.gemini/antigravity/skills/&lt;name&gt;/SKILL.md |
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| GITHUB_TOKEN | GitHub API token（可选，提高速率限制） | 无 |
+| HEFLC_SKILL_OWNER | 覆盖仓库拥有者 | {owner} |
+| HEFLC_SKILL_REPO | 覆盖仓库名 | {repo} |

package/bin/heflc-skill.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+// bin/heflc-skill.js
+// CLI 入口，注册所有命令
+
+import { Command } from 'commander';
+import { listCommand } from '../src/commands/list.js';
+import { installCommand } from '../src/commands/install.js';
+import { uninstallCommand } from '../src/commands/uninstall.js';
+import { updateCommand } from '../src/commands/update.js';
+import { doctorCommand } from '../src/commands/doctor.js';
+
+const program = new Command();
+
+program
+  .name('heflc-skill')
+  .description('下载并安装 AI Skill 到本机编辑器')
+  .version('1.0.0');
+
+program
+  .command('list')
+  .description('列出所有可用的 Skill')
+  .action(listCommand);
+
+program
+  .command('install [name]')
+  .description('安装指定 Skill 到所有检测到的编辑器')
+  .option('-a, --all', '安装全部 Skill')
+  .action(installCommand);
+
+program
+  .command('uninstall <name>')
+  .description('从所有编辑器中卸载指定 Skill')
+  .action(uninstallCommand);
+
+program
+  .command('update [name]')
+  .description('更新已安装的 Skill（不指定名称则更新全部）')
+  .action(updateCommand);
+
+program
+  .command('doctor')
+  .description('检查编辑器检测状态和已安装的 Skill')
+  .action(doctorCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "heflc-skill",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "CLI tool to install AI Skills into editors (Claude Code, Cursor, Trae, Gemini)",
+  "bin": {
+    "heflc-skill": "./bin/heflc-skill.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["ai", "skill", "cli", "claude", "cursor", "trae"],
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ora": "^8.0.0"
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,44 @@
+// src/commands/doctor.js
+// 诊断本机编辑器和已安装的 skill 状态
+
+import chalk from 'chalk';
+import { detectEditors, listInstalledSkills } from '../editors.js';
+
+/**
+ * 执行 doctor 命令
+ */
+export async function doctorCommand() {
+  const editors = detectEditors();
+
+  // 打印编辑器检测结果
+  console.log('编辑器检测：\n');
+  for (const editor of editors) {
+    if (editor.detected) {
+      console.log(`  ${chalk.green('✓')} ${editor.name}  ${chalk.gray(`(${editor.detectFullPath})`)}`);
+    } else {
+      console.log(`  ${chalk.gray('✗')} ${chalk.gray(editor.name)}  ${chalk.gray('(未检测到)')}`);
+    }
+  }
+
+  // 打印已安装的 skill
+  const activeEditors = editors.filter((e) => e.detected);
+  if (activeEditors.length === 0) {
+    console.log(chalk.yellow('\n未检测到任何支持的编辑器。'));
+    return;
+  }
+
+  console.log('\n已安装的 Skill：\n');
+  for (const editor of activeEditors) {
+    const skills = listInstalledSkills(editor);
+    console.log(`  ${chalk.bold(editor.name)}:`);
+    if (skills.length === 0) {
+      console.log(`    ${chalk.gray('(无)')}`);
+    } else {
+      for (const skill of skills) {
+        console.log(`    ${chalk.green('✓')} ${skill}`);
+      }
+    }
+  }
+
+  console.log(`\n使用 ${chalk.green('heflc-skill list')} 查看可安装的 Skill。`);
+}

package/src/commands/install.js

@@ -0,0 +1,93 @@
+// src/commands/install.js
+// 安装 skill 到所有检测到的编辑器
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { listRemoteSkills, downloadSkill } from '../github.js';
+import { detectEditors, writeSkillFile, getSkillFilePath } from '../editors.js';
+
+/**
+ * 打印编辑器检测结果
+ * @param {Array} editors - detectEditors() 返回值
+ */
+function printEditorStatus(editors) {
+  console.log('检测到以下编辑器：');
+  for (const editor of editors) {
+    if (editor.detected) {
+      console.log(`  ${chalk.green('✓')} ${editor.name}`);
+    } else {
+      console.log(`  ${chalk.gray('✗')} ${chalk.gray(editor.name)}  ${chalk.gray('(未检测到)')}`);
+    }
+  }
+  console.log();
+}
+
+/**
+ * 安装单个 skill 到所有检测到的编辑器
+ * @param {string} skillName - skill 名称
+ * @param {Array} activeEditors - 已检测到的编辑器列表
+ */
+async function installOne(skillName, activeEditors) {
+  const spinner = ora(`正在下载 ${skillName} ...`).start();
+
+  try {
+    const content = await downloadSkill(skillName);
+    spinner.succeed(`已下载 ${chalk.cyan(skillName)}`);
+
+    for (const editor of activeEditors) {
+      try {
+        writeSkillFile(editor, skillName, content);
+        const filePath = getSkillFilePath(editor, skillName);
+        console.log(`  ${chalk.green('✓')} ${filePath}`);
+      } catch (err) {
+        console.log(`  ${chalk.red('✗')} ${editor.name}: ${err.message}`);
+      }
+    }
+  } catch (error) {
+    spinner.fail(chalk.red(`${skillName}: ${error.message}`));
+  }
+}
+
+/**
+ * 执行 install 命令
+ * @param {string|undefined} name - skill 名称，undefined 时需要 --all
+ * @param {object} options - 命令选项
+ */
+export async function installCommand(name, options) {
+  // 检测编辑器
+  const editors = detectEditors();
+  printEditorStatus(editors);
+
+  const activeEditors = editors.filter((e) => e.detected);
+  if (activeEditors.length === 0) {
+    console.log(chalk.yellow('未检测到任何支持的编辑器，无法安装。'));
+    process.exit(1);
+  }
+
+  // 确定要安装的 skill 列表
+  let skillNames;
+  if (options.all) {
+    const spinner = ora('正在获取所有 Skill ...').start();
+    try {
+      skillNames = await listRemoteSkills();
+      spinner.succeed(`找到 ${skillNames.length} 个 Skill`);
+    } catch (error) {
+      spinner.fail(chalk.red(error.message));
+      process.exit(1);
+    }
+  } else if (name) {
+    skillNames = [name];
+  } else {
+    console.log(chalk.red('请指定 skill 名称，或使用 --all 安装全部。'));
+    console.log(`用法: heflc-skill install <name>`);
+    console.log(`      heflc-skill install --all`);
+    process.exit(1);
+  }
+
+  // 逐个安装
+  for (const skillName of skillNames) {
+    await installOne(skillName, activeEditors);
+  }
+
+  console.log(chalk.green('\n安装完成！'));
+}

package/src/commands/list.js

@@ -0,0 +1,35 @@
+// src/commands/list.js
+// 列出集中仓库中所有可用的 skill
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { listRemoteSkills } from '../github.js';
+
+/**
+ * 执行 list 命令
+ */
+export async function listCommand() {
+  const spinner = ora('正在获取可用的 Skill 列表...').start();
+
+  try {
+    const skills = await listRemoteSkills();
+
+    if (skills.length === 0) {
+      spinner.warn('集中仓库中暂无可用的 Skill。');
+      return;
+    }
+
+    spinner.succeed(`找到 ${skills.length} 个可用的 Skill：\n`);
+
+    for (const name of skills) {
+      console.log(`  ${chalk.cyan(name)}`);
+    }
+
+    console.log(
+      `\n使用 ${chalk.green('heflc-skill install <name>')} 安装指定 Skill。`
+    );
+  } catch (error) {
+    spinner.fail(chalk.red(error.message));
+    process.exit(1);
+  }
+}

package/src/commands/uninstall.js

@@ -0,0 +1,45 @@
+// src/commands/uninstall.js
+// 从所有编辑器中卸载指定 skill
+
+import chalk from 'chalk';
+import { detectEditors, removeSkillFile, getSkillFilePath } from '../editors.js';
+
+/**
+ * 执行 uninstall 命令
+ * @param {string} name - 要卸载的 skill 名称
+ */
+export async function uninstallCommand(name) {
+  if (!name) {
+    console.log(chalk.red('请指定要卸载的 skill 名称。'));
+    console.log(`用法: heflc-skill uninstall <name>`);
+    process.exit(1);
+  }
+
+  const editors = detectEditors();
+  const activeEditors = editors.filter((e) => e.detected);
+
+  if (activeEditors.length === 0) {
+    console.log(chalk.yellow('未检测到任何编辑器。'));
+    process.exit(1);
+  }
+
+  console.log(`正在卸载 ${chalk.cyan(name)} ...\n`);
+
+  let removedCount = 0;
+  for (const editor of activeEditors) {
+    const filePath = getSkillFilePath(editor, name);
+    const removed = removeSkillFile(editor, name);
+    if (removed) {
+      console.log(`  ${chalk.green('✓')} 已删除 ${filePath}`);
+      removedCount++;
+    } else {
+      console.log(`  ${chalk.gray('-')} ${editor.name}: 未安装该 skill`);
+    }
+  }
+
+  if (removedCount > 0) {
+    console.log(chalk.green(`\n卸载完成，已从 ${removedCount} 个编辑器中移除。`));
+  } else {
+    console.log(chalk.yellow('\n该 skill 未安装在任何编辑器中。'));
+  }
+}

package/src/commands/update.js

@@ -0,0 +1,81 @@
+// src/commands/update.js
+// 更新已安装的 skill（重新从 GitHub 下载最新版覆盖）
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { detectEditors, listInstalledSkills } from '../editors.js';
+import { downloadSkill } from '../github.js';
+import { writeSkillFile, getSkillFilePath } from '../editors.js';
+
+/**
+ * 更新单个 skill 到所有检测到的编辑器
+ * @param {string} skillName - skill 名称
+ * @param {Array} activeEditors - 已检测到的编辑器列表
+ */
+async function updateOne(skillName, activeEditors) {
+  const spinner = ora(`正在更新 ${skillName} ...`).start();
+
+  try {
+    const content = await downloadSkill(skillName);
+    spinner.succeed(`已下载 ${chalk.cyan(skillName)}`);
+
+    for (const editor of activeEditors) {
+      try {
+        writeSkillFile(editor, skillName, content);
+        const filePath = getSkillFilePath(editor, skillName);
+        console.log(`  ${chalk.green('✓')} ${filePath}`);
+      } catch (err) {
+        console.log(`  ${chalk.red('✗')} ${editor.name}: ${err.message}`);
+      }
+    }
+  } catch (error) {
+    spinner.fail(chalk.red(`${skillName}: ${error.message}`));
+  }
+}
+
+/**
+ * 执行 update 命令
+ * @param {string|undefined} name - 指定更新的 skill 名称，不传则更新全部已安装的
+ */
+export async function updateCommand(name) {
+  const editors = detectEditors();
+  const activeEditors = editors.filter((e) => e.detected);
+
+  if (activeEditors.length === 0) {
+    console.log(chalk.yellow('未检测到任何编辑器。'));
+    process.exit(1);
+  }
+
+  if (name) {
+    // 更新指定 skill
+    console.log(`正在更新 ${chalk.cyan(name)} ...\n`);
+    await updateOne(name, activeEditors);
+    console.log(chalk.green('\n更新完成！'));
+    return;
+  }
+
+  // 扫描所有编辑器，收集已安装的 skill（去重）
+  const installedSet = new Set();
+  for (const editor of activeEditors) {
+    const skills = listInstalledSkills(editor);
+    for (const skill of skills) {
+      installedSet.add(skill);
+    }
+  }
+
+  if (installedSet.size === 0) {
+    console.log(chalk.yellow('未发现任何已安装的 Skill。'));
+    console.log(`使用 ${chalk.green('heflc-skill install <name>')} 安装。`);
+    return;
+  }
+
+  const installedNames = [...installedSet];
+  console.log(`发现 ${installedNames.length} 个已安装的 Skill：${chalk.cyan(installedNames.join(', '))}\n`);
+
+  // 逐个更新
+  for (const skillName of installedNames) {
+    await updateOne(skillName, activeEditors);
+  }
+
+  console.log(chalk.green('\n全部更新完成！'));
+}

package/src/config.js

@@ -0,0 +1,18 @@
+// src/config.js
+// 集中仓库配置，支持环境变量覆盖
+
+const config = {
+  // GitHub 仓库拥有者（组织名或用户名）
+  repoOwner: process.env.HEFLC_SKILL_OWNER || 'rendaoxian',
+
+  // GitHub 仓库名
+  repoName: process.env.HEFLC_SKILL_REPO || 'heflc-skills',
+
+  // GitHub API token（可选，提高速率限制到 5000 次/小时）
+  githubToken: process.env.GITHUB_TOKEN || null,
+
+  // GitHub API 基础地址
+  apiBase: 'https://api.github.com',
+};
+
+export default config;

package/src/editors.js

@@ -0,0 +1,123 @@
+// src/editors.js
+// 编辑器检测与路径映射
+
+import { existsSync, readdirSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
+/**
+ * 支持的编辑器列表
+ * 新增编辑器只需往数组里加一条记录
+ */
+const EDITORS = [
+  {
+    name: 'Claude Code',
+    detectPath: '.claude',
+    skillPath: '.claude/skills/{name}/SKILL.md',
+  },
+  {
+    name: 'Cursor',
+    detectPath: '.cursor',
+    skillPath: '.cursor/skills/{name}/SKILL.md',
+  },
+  {
+    name: 'Trae',
+    detectPath: '.trae',
+    skillPath: '.trae/skills/{name}/SKILL.md',
+  },
+  {
+    name: 'Gemini',
+    detectPath: '.gemini',
+    skillPath: '.gemini/antigravity/skills/{name}/SKILL.md',
+  },
+];
+
+/**
+ * 获取用户 home 目录（跨平台）
+ * @returns {string} home 目录绝对路径
+ */
+function getHomeDir() {
+  return homedir();
+}
+
+/**
+ * 检测本机安装了哪些编辑器
+ * @returns {Array<{name: string, detected: boolean, detectFullPath: string, skillPathTemplate: string}>}
+ */
+export function detectEditors() {
+  const home = getHomeDir();
+  return EDITORS.map((editor) => {
+    const detectFullPath = join(home, editor.detectPath);
+    return {
+      name: editor.name,
+      detected: existsSync(detectFullPath),
+      detectFullPath,
+      skillPathTemplate: editor.skillPath,
+    };
+  });
+}
+
+/**
+ * 获取指定 skill 在某个编辑器中的完整文件路径
+ * @param {object} editor - detectEditors() 返回的编辑器对象
+ * @param {string} skillName - skill 名称
+ * @returns {string} 完整文件路径
+ */
+export function getSkillFilePath(editor, skillName) {
+  const home = getHomeDir();
+  const relativePath = editor.skillPathTemplate.replace('{name}', skillName);
+  return join(home, relativePath);
+}
+
+/**
+ * 将 skill 内容写入指定编辑器的 skills 目录
+ * @param {object} editor - 编辑器对象
+ * @param {string} skillName - skill 名称
+ * @param {string} content - SKILL.md 文件内容
+ */
+export function writeSkillFile(editor, skillName, content) {
+  const filePath = getSkillFilePath(editor, skillName);
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * 从指定编辑器中删除 skill
+ * @param {object} editor - 编辑器对象
+ * @param {string} skillName - skill 名称
+ * @returns {boolean} 是否成功删除
+ */
+export function removeSkillFile(editor, skillName) {
+  const filePath = getSkillFilePath(editor, skillName);
+  const dir = dirname(filePath);
+  if (existsSync(dir)) {
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 扫描某个编辑器中已安装的 skill 列表
+ * @param {object} editor - 编辑器对象
+ * @returns {string[]} 已安装的 skill 名称数组
+ */
+export function listInstalledSkills(editor) {
+  const home = getHomeDir();
+  const parts = editor.skillPathTemplate.split('{name}');
+  const skillsDir = join(home, parts[0]);
+
+  if (!existsSync(skillsDir)) {
+    return [];
+  }
+
+  try {
+    const entries = readdirSync(skillsDir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}

package/src/github.js

@@ -0,0 +1,79 @@
+// src/github.js
+// GitHub REST API 封装
+
+import config from './config.js';
+
+/**
+ * 构造 GitHub API 请求头
+ * @returns {object} fetch headers
+ */
+function getHeaders() {
+  const headers = {
+    Accept: 'application/vnd.github.v3+json',
+    'User-Agent': 'heflc-skill-cli',
+  };
+  if (config.githubToken) {
+    headers.Authorization = `token ${config.githubToken}`;
+  }
+  return headers;
+}
+
+/**
+ * 统一错误处理
+ * @param {Response} response - fetch response
+ * @param {string} context - 错误上下文描述
+ */
+async function handleResponse(response, context) {
+  if (response.ok) {
+    return response.json();
+  }
+
+  if (response.status === 404) {
+    throw new Error(`未找到：${context}。请用 heflc-skill list 查看可用的 skill。`);
+  }
+  if (response.status === 403) {
+    throw new Error(
+      'GitHub API 请求频率超限。请稍后再试，或设置环境变量 GITHUB_TOKEN 提高限额。'
+    );
+  }
+  throw new Error(`GitHub API 请求失败 (${response.status})：${context}`);
+}
+
+/**
+ * 列出集中仓库中所有可用的 skill（顶层目录）
+ * @returns {Promise<string[]>} skill 名称数组
+ */
+export async function listRemoteSkills() {
+  const url = `${config.apiBase}/repos/${config.repoOwner}/${config.repoName}/contents/`;
+  let response;
+  try {
+    response = await fetch(url, { headers: getHeaders(), signal: AbortSignal.timeout(15000) });
+  } catch (err) {
+    throw new Error('无法连接 GitHub API，请检查网络连接或配置代理。');
+  }
+  const data = await handleResponse(response, '集中仓库');
+
+  return data
+    .filter((item) => item.type === 'dir')
+    .map((item) => item.name);
+}
+
+/**
+ * 下载指定 skill 的 SKILL.md 文件内容
+ * @param {string} skillName - skill 名称（即仓库中的目录名）
+ * @returns {Promise<string>} SKILL.md 的文本内容
+ */
+export async function downloadSkill(skillName) {
+  const url = `${config.apiBase}/repos/${config.repoOwner}/${config.repoName}/contents/${skillName}/SKILL.md`;
+  let response;
+  try {
+    response = await fetch(url, { headers: getHeaders(), signal: AbortSignal.timeout(15000) });
+  } catch (err) {
+    throw new Error('无法连接 GitHub API，请检查网络连接或配置代理。');
+  }
+  const data = await handleResponse(response, `skill "${skillName}"`);
+
+  // GitHub API 返回 Base64 编码的文件内容
+  const content = Buffer.from(data.content, 'base64').toString('utf-8');
+  return content;
+}