@kg-ai/kugou-skill 0.0.1

package/README.md

@@ -0,0 +1,130 @@
+# Kugou CLI
+
+酷狗音乐 API CLI 工具，用于搜索、推荐、收藏、统计、榜单等功能。
+
+## 安装
+
+### npm 安装（推荐）
+
+```bash
+npm install -g @kg-ai/kugou-skill
+```
+
+安装后使用 `kugou-cli` 命令。npm 安装时会自动安装 SKILL.md 到各平台的 skills 目录。
+
+## 前置条件
+
+使用前需要扫码登录：
+
+```bash
+kugou-cli auth login
+```
+
+登录后 token 会自动持久化存储。
+
+## 命令
+
+### 认证
+
+```bash
+# 扫码登录（默认保存二维码图片到临时目录）
+kugou-cli auth login
+
+# 输出 base64 编码的二维码图片
+kugou-cli auth login --output base64
+
+# 打开系统图片查看器扫码
+kugou-cli auth login --output terminal
+
+# 查看登录状态
+kugou-cli auth status
+
+# 登出
+kugou-cli auth logout
+```
+
+### 音乐
+
+```bash
+# 搜索歌曲
+kugou-cli music search "周杰伦"
+kugou-cli music search "周杰伦" --page 1 --size 20
+
+# 每日推荐
+kugou-cli music recommend daily
+kugou-cli music recommend daily --num 10
+
+# 相似推荐（需要指定歌曲）
+kugou-cli music recommend similar --song "晴天"
+kugou-cli music recommend similar -s "晴天" -n 5
+
+# 我的收藏
+kugou-cli music favorites
+kugou-cli music favorites --page 1 --size 20
+
+# 最近播放
+kugou-cli music recent
+kugou-cli music recent --page 1 --size 20
+
+# 听歌统计
+kugou-cli music stats
+
+# 酷狗榜单
+kugou-cli music charts 6666    # 飙升榜
+kugou-cli music charts 8888    # TOP500榜
+kugou-cli music charts 52144  # 抖音热歌酷狗榜
+kugou-cli music charts 90379  # 星耀星光榜
+kugou-cli music charts 85432  # 百万收藏榜
+kugou-cli music charts 74534  # 新歌榜
+```
+
+### 安装 SKILL.md
+
+```bash
+# 安装到所有平台
+kugou-cli install --all
+
+# 安装到指定平台
+kugou-cli install --claude
+kugou-cli install --hermes --openclaw --codex
+```
+
+### 全局
+
+```bash
+kugou-cli --version
+kugou-cli --help
+```
+
+## 输出格式
+
+所有命令输出 JSON 格式，方便其他程序调用：
+
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "song_name": "晴天",
+        "mix_song_id": "32100650",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/xxx.html"
+      }
+    ],
+    "total": 480,
+    "page": 1,
+    "size": 20
+  },
+  "status": 1
+}
+```
+
+## 错误处理
+
+错误信息输出到 stderr，程序 exit code 为 1：
+
+```bash
+kugou-cli music search "xxx" 2>&1
+echo $?  # 非 0 表示出错
+```

package/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: kugou-skill
+description: |
+  kugou-skill 是酷狗音乐 API CLI 工具，用于搜索、推荐、收藏、统计、榜单等功能。
+  触发场景：用户要求搜索歌曲、获取推荐、管理收藏、查看听歌统计、查看榜单等酷狗音乐相关操作。
+  安装方式：npm install -g @kg-ai/kugou-skill
+---
+
+# kugou-skill
+
+## 基础信息
+
+- **npm 包**: @kg-ai/kugou-skill
+- **二进制命令**: kugou-cli
+- **API 域名**: https://agentgateway.kugou.com（固定，无需配置）
+- **安装方式**: `npm install -g @kg-ai/kugou-skill`
+
+## 前置条件
+
+使用前需要扫码登录：
+```bash
+kugou-cli auth login
+```
+登录后 token 会自动持久化存储。
+
+## 命令列表
+
+### 认证命令 (auth)
+
+| 命令 | 说明 |
+|------|------|
+| `kugou-cli auth login` | 扫码登录（返回二维码信息） |
+| `kugou-cli auth status` | 查看登录状态 |
+| `kugou-cli auth logout` | 登出 |
+
+### 音乐命令 (music)
+
+| 命令 | 说明 |
+|------|------|
+| `kugou-cli music search <keyword>` | 搜索歌曲 |
+| `kugou-cli music recommend daily` | 每日推荐 |
+| `kugou-cli music recommend similar -s <song>` | 相似歌曲推荐 |
+| `kugou-cli music favorites` | 我的收藏 |
+| `kugou-cli music recent` | 最近播放 |
+| `kugou-cli music stats` | 听歌统计 |
+| `kugou-cli music charts <rank_id>` | 榜单 |
+
+### 安装命令 (install)
+
+| 命令 | 说明 |
+|------|------|
+| `kugou-cli install` | 显示帮助信息 |
+| `kugou-cli install --all` | 安装 SKILL.md 到所有平台 |
+| `kugou-cli install --claude` | 安装到 Claude skills 目录 |
+| `kugou-cli install --hermes` | 安装到 Hermes skills 目录 |
+| `kugou-cli install --openclaw` | 安装到 Openclaw skills 目录 |
+| `kugou-cli install --codex` | 安装到 Codex skills 目录 |
+
+---
+
+## 详细用法
+
+### 1. 扫码登录
+
+```bash
+kugou-cli auth login
+kugou-cli auth login --output image    # 默认，保存二维码图片到临时目录
+kugou-cli auth login --output base64  # 输出 base64 编码的图片数据（含 data:image/png;base64, 前缀）
+kugou-cli auth login --output terminal # 打开图片查看器扫码（Windows/macOS/Linux）
+```
+
+**参数**:
+- `-o, --output`: 输出模式
+  - `image` (默认): 保存二维码图片到临时目录，输出图片路径
+  - `base64`: 输出 base64 编码的图片数据（含 `data:image/png;base64,` 前缀）
+  - `terminal`: 打开系统图片查看器扫码（非 ASCII 渲染）
+
+**输出示例** (image 模式):
+```json
+{"qrcode": "xxx", "qrcode_img_path": "/tmp/kugou-qrcode.png", "status": "waiting"}
+```
+
+**输出示例** (base64 模式):
+```json
+{"qrcode": "xxx", "qrcode_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "status": "waiting"}
+```
+
+**输出示例** (terminal 模式):
+```json
+{"qrcode": "xxx", "qrcode_img_path": "C:\Users\xxx\AppData\Local\Temp\kugou-qrcode.png", "status": "waiting"}
+```
+
+**轮询状态**:
+- `status: scanned` - 已扫码，等待确认
+- `status: success` - 登录成功
+- `status: failed` - 登录失败（二维码过期）
+
+---
+
+### 2. 查看登录状态
+
+```bash
+kugou-cli auth status
+```
+
+**输出示例**:
+```json
+{"logged_in": true, "nickname": "沙墨", "login_time": "2024-01-01 12:00:00"}
+```
+
+---
+
+### 3. 搜索歌曲
+
+```bash
+kugou-cli music search "周杰伦"
+kugou-cli music search "周杰伦" --page 1 --size 20
+```
+
+**参数**:
+- `<keyword>`: 搜索关键词（必填）
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "list": [
+      {
+        "song_name": "晴天",
+        "mix_song_id": "32100650",
+        "artist_name": "周杰伦",
+        "play_link": "https://www.kugou.com/mixsong/agent_gateway/j410q78a01f.html"
+      }
+    ],
+    "total": 480,
+    "page": 1,
+    "size": 20
+  },
+  "status": 1
+}
+```
+
+---
+
+### 4. 每日推荐
+
+```bash
+kugou-cli music recommend daily
+kugou-cli music recommend daily --num 10
+```
+
+**参数**:
+- `--num`: 推荐数量，默认 10
+- `--text`: 描述文本（可选）
+
+---
+
+### 5. 相似推荐
+
+```bash
+kugou-cli music recommend similar -s "晴天"
+kugou-cli music recommend similar --song "晴天" -n 5
+```
+
+**参数**:
+- `-s, --song`: 歌曲名称（必填）
+- `-n, --num`: 推荐数量，默认 10
+- `-t, --text`: 描述文本（可选）
+
+---
+
+### 6. 我的收藏
+
+```bash
+kugou-cli music favorites
+kugou-cli music favorites --page 1 --size 20
+```
+
+**参数**:
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20
+
+---
+
+### 7. 最近播放
+
+```bash
+kugou-cli music recent
+kugou-cli music recent --page 1 --size 20
+```
+
+**参数**:
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20
+
+---
+
+### 8. 听歌统计
+
+```bash
+kugou-cli music stats
+```
+
+**输出示例**:
+```json
+{
+  "errcode": 0,
+  "data": {
+    "server_time": 1779977674,
+    "listen_duration": 80776,
+    "accumulate_listen_days": 1,
+    "continue_listen_days": 1,
+    "listen_total": 342,
+    "last_listen_total": 387,
+    "rank_song": [...],
+    "rank_singer": [...],
+    "rank_style": [...],
+    "rank_language": [...]
+  },
+  "status": 1
+}
+```
+
+**关键字段**:
+- `listen_duration`: 累计听歌时长（秒）
+- `listen_total`: 累计听歌数量
+- `rank_song`: 播放最多的歌曲排行
+- `rank_singer`: 播放最多的歌手排行
+
+---
+
+### 9. 榜单
+
+```bash
+kugou-cli music charts 6666
+kugou-cli music charts 52144 --page 1 --size 20
+```
+
+**可用榜单 ID**:
+
+| rank_id | 榜单名称 |
+|---------|----------|
+| 8888 | TOP500榜 |
+| 90379 | 星耀星光榜 |
+| 6666 | 飙升榜 |
+| 85432 | 百万收藏榜 |
+| 74534 | 新歌榜 |
+| 52144 | 抖音热歌酷狗榜 |
+
+**参数**:
+- `<rank_id>`: 榜单 ID（必填）
+- `--page`: 页码，默认 1
+- `--size`: 每页数量，默认 20
+
+---
+
+### 10. 安装 SKILL.md
+
+```bash
+kugou-cli install --all              # 安装到所有平台
+kugou-cli install --claude           # 仅安装到 Claude
+kugou-cli install --hermes --claude # 安装到 Hermes 和 Claude
+```
+
+**参数**:
+- `--claude`: 安装到 `~/.claude/skills/kugou-skill/`
+- `--hermes`: 安装到 `~/.hermes/skills/kugou-skill/`
+- `--openclaw`: 安装到 `~/.openclaw/skills/kugou-skill/`
+- `--codex`: 安装到 `~/.codex/skills/kugou-skill/`
+- `--all`: 安装到以上所有平台
+
+**说明**:
+- npm 安装时会自动调用 install.js 安装 SKILL.md
+- `kugou-cli install` 命令用于手动重新安装或更新 SKILL.md
+- 只在目标平台目录存在时才安装，不自动创建目录
+
+---
+
+## 全局参数
+
+所有命令支持以下隐藏参数：
+
+- `--proxy`: HTTP 代理地址，用于网络受限环境
+  ```bash
+  kugou-cli music search "周杰伦" --proxy "http://127.0.0.1:7890"
+  ```
+
+## 输出格式
+
+所有命令输出原始 JSON 响应，方便程序解析。
+
+**通用响应结构**:
+```json
+{
+  "errcode": 0,
+  "errmsg": "",
+  "data": { ... },
+  "status": 1
+}
+```
+
+**响应状态**:
+- `errcode: 0` 表示成功
+- `data` 包含实际业务数据
+- `status: 1` 表示接口调用成功
+
+---
+
+## 错误处理
+
+错误信息输出到 stderr，程序 exit code 为 1：
+
+```bash
+kugou-cli music search "xxx" 2>&1
+echo $?  # 非 0 表示出错
+```
+
+**常见错误**:
+- `not logged in`: 需要先登录
+- `HTTP error: 400/500`: 服务端错误
+- `network error`: 网络连接问题
+
+---
+
+## 使用示例
+
+### 完整使用流程
+
+```bash
+# 1. 登录
+kugou-cli auth login
+
+# 2. 查看登录状态
+kugou-cli auth status
+
+# 3. 搜索歌曲
+kugou-cli music search "周杰伦"
+
+# 4. 获取每日推荐
+kugou-cli music recommend daily --num 5
+
+# 5. 查看我的收藏
+kugou-cli music favorites --page 1
+
+# 6. 查看最近播放
+kugou-cli music recent --size 10
+
+# 7. 查看听歌统计
+kugou-cli music stats
+
+# 8. 查看抖音热歌榜
+kugou-cli music charts 52144
+```
+
+### 在脚本中使用
+
+```bash
+#!/bin/bash
+
+# 搜索并提取歌曲名
+result=$(kugou-cli music search "周杰伦" --size 1)
+echo "$result" | jq -r '.data.list[0].song_name'
+
+# 获取榜单第一首
+kugou-cli music charts 6666 --size 1 | jq -r '.data.list[0].song_name'
+```

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@kg-ai/kugou-skill",
+  "version": "0.0.1",
+  "description": "Kugou Skill CLI",
+  "main": "index.js",
+  "bin": {
+    "kugou-cli": "./scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/install.js"
+  },
+  "keywords": [
+    "cli",
+    "kugou"
+  ],
+  "files": [
+    "bin",
+    "scripts",
+    "SKILL.md"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/build-all.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * 构建所有平台二进制
+ * 使用方式: node scripts/build-all.js
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const platforms = [
+  { os: 'darwin', arch: 'arm64', name: 'darwin-arm64', exe: 'kugou-cli' },
+  { os: 'darwin', arch: 'amd64', name: 'darwin-x64', exe: 'kugou-cli' },
+  { os: 'linux', arch: 'arm64', name: 'linux-arm64', exe: 'kugou-cli' },
+  { os: 'linux', arch: 'amd64', name: 'linux-x64', exe: 'kugou-cli' },
+  { os: 'windows', arch: 'amd64', name: 'win32-x64', exe: 'kugou-cli.exe' },
+];
+
+const binDir = path.join(__dirname, '..', 'bin');
+
+console.log('=== Building all platforms ===\n');
+
+// 清理平台目录
+for (const p of platforms) {
+  const dir = path.join(binDir, p.name);
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true });
+  }
+}
+
+// 构建每个平台
+for (const p of platforms) {
+  const outDir = path.join(binDir, p.name);
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const outFile = path.join(outDir, p.exe);
+  console.log(`Building ${p.name}...`);
+
+  try {
+    execSync(`go build -ldflags="-s -w" -o "${outFile}" .`, {
+      env: { ...process.env, GOOS: p.os, GOARCH: p.arch, CGO_ENABLED: '0' },
+      stdio: 'inherit',
+    });
+    console.log(`✅ Built: ${p.name}\n`);
+  } catch (err) {
+    console.error(`❌ Failed: ${p.name}\n`);
+    process.exit(1);
+  }
+}
+
+console.log('=== All platforms built successfully! ===');
+console.log('\nRun: node scripts/pack.js');

package/scripts/install.js

@@ -0,0 +1,62 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const platform = process.platform;
+const arch = process.arch;
+const binDir = path.join(__dirname, '..', 'bin');
+const pkgRoot = path.join(__dirname, '..');
+
+// 平台映射
+const platformMap = {
+  'darwin': { dir: `darwin-${arch}`, exe: 'kugou-cli' },
+  'linux': { dir: `linux-${arch}`, exe: 'kugou-cli' },
+  'win32': { dir: `win32-x64`, exe: 'kugou-cli.exe' }
+};
+
+const config = platformMap[platform];
+if (!config) {
+  console.error(`Unsupported platform: ${platform}`);
+  process.exit(1);
+}
+
+// 安装二进制
+const srcBin = path.join(binDir, config.dir, config.exe);
+const destBin = path.join(binDir, config.exe);
+
+if (!fs.existsSync(srcBin)) {
+  console.error(`Binary not found for ${platform}-${arch}: ${srcBin}`);
+  console.error('Please report this issue: https://github.com/kg-ai/kugou-cli/issues');
+  process.exit(1);
+}
+
+fs.copyFileSync(srcBin, destBin);
+fs.chmodSync(destBin, 0o755);
+console.log(`Installed ${config.exe} for ${platform}-${arch}`);
+
+// 安装 SKILL.md 到各平台的 skills 目录
+const skillSrc = path.join(pkgRoot, 'SKILL.md');
+const skillDirs = [
+  path.join(os.homedir(), '.claude', 'skills', 'kugou-skill'),
+  path.join(os.homedir(), '.hermes', 'skills', 'kugou-skill'),
+  path.join(os.homedir(), '.openclaw', 'skills', 'kugou-skill'),
+  path.join(os.homedir(), '.codex', 'skills', 'kugou-skill'),
+];
+
+if (fs.existsSync(skillSrc)) {
+  for (const skillDir of skillDirs) {
+    // 只在 skills 目录存在时才复制，不创建目录
+    const parentDir = path.dirname(skillDir);
+    if (fs.existsSync(parentDir)) {
+      try {
+        if (!fs.existsSync(skillDir)) {
+          fs.mkdirSync(skillDir, { recursive: true });
+        }
+        fs.copyFileSync(skillSrc, path.join(skillDir, 'SKILL.md'));
+        console.log(`Installed SKILL.md to ${skillDir}`);
+      } catch (err) {
+        console.warn(`Warning: Failed to install SKILL.md to ${skillDir}: ${err.message}`);
+      }
+    }
+  }
+}

package/scripts/pack.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * 本地打包脚本
+ * 使用方式: node scripts/pack.js
+ *
+ * 发布流程:
+ * 1. 构建所有平台二进制到 bin/{platform}/
+ * 2. 运行 node scripts/pack.js
+ * 3. 运行 npm publish
+ */
+
+const fs = require('fs');
+const path = require('path');
+const pkgRoot = path.join(__dirname, '..');
+
+// 检查必要文件
+const requiredFiles = [
+  'package.json',
+  'SKILL.md',
+  'scripts/install.js',
+  'scripts/run.js'
+];
+
+// 检查平台二进制
+const platforms = [
+  'darwin-arm64',
+  'darwin-x64',
+  'linux-arm64',
+  'linux-x64',
+  'win32-x64'
+];
+
+console.log('=== 检查必要文件 ===');
+let hasError = false;
+
+for (const file of requiredFiles) {
+  const filePath = path.join(pkgRoot, file);
+  if (fs.existsSync(filePath)) {
+    console.log(`✅ ${file}`);
+  } else {
+    console.log(`❌ ${file} - 缺失`);
+    hasError = true;
+  }
+}
+
+console.log('\n=== 检查平台二进制 ===');
+for (const platform of platforms) {
+  const exeName = platform.startsWith('win32') ? 'kugou-cli.exe' : 'kugou-cli';
+  const binPath = path.join(pkgRoot, 'bin', platform, exeName);
+  if (fs.existsSync(binPath)) {
+    const size = fs.statSync(binPath).size;
+    console.log(`✅ ${platform}: ${exeName} (${(size / 1024 / 1024).toFixed(2)} MB)`);
+  } else {
+    console.log(`❌ ${platform}: ${exeName} - 缺失`);
+    hasError = true;
+  }
+}
+
+if (hasError) {
+  console.log('\n❌ 打包检查失败，请确保所有文件都已构建');
+  process.exit(1);
+}
+
+console.log('\n=== 构建完成 ===');
+console.log('运行以下命令发布:');
+console.log('  npm pack');
+console.log('  npm publish --access public --scope=@kugouai');

package/scripts/run.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const path = require('path');
+
+// 获取当前平台对应的二进制路径
+const platform = process.platform; // darwin, linux, win32
+
+const binName = platform === 'win32' ? 'kugou-cli.exe' : 'kugou-cli';
+// scripts/ 的父目录就是项目根目录，bin/ 在根目录下
+// 使用简单名称，install.js 会复制对应平台的二进制到这里
+const rootDir = path.join(__dirname, '..');
+const binPath = path.join(rootDir, 'bin', binName);
+
+const child = spawn(binPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  shell: platform === 'win32'
+});
+
+child.on('exit', (code) => {
+  process.exit(code);
+});