tzskills 1.0.1

package/bin/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { findSkills } from "../src/commands/find.js";
+import { addSkill } from "../src/commands/add.js";
+
+const program = new Command();
+
+program
+    .name("TZSkills")
+    .description("Custom Skill CLI")
+    .version("1.0.0");
+
+program
+    .command("find")
+    .argument("<query>", "search keyword")
+    .action(findSkills);
+
+program
+    .command("add")
+    .argument("<name>", "skill name")
+    .argument("<skillId>", "skill id")
+    .action(addSkill);
+
+program.parse();

package/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "tzskills",
+    "version": "1.0.1",
+    "description": "Custom skill marketplace CLI",
+    "bin": {
+        "tzskills": "bin/index.js"
+    },
+    "files": [
+        "bin",
+        "src"
+    ],
+    "type": "module",
+    "dependencies": {
+        "adm-zip": "^0.5.10",
+        "axios": "^1.6.0",
+        "chalk": "^5.3.0",
+        "commander": "^11.1.0",
+        "gray-matter": "^4.0.3",
+        "ora": "^7.0.1",
+        "yaml": "^2.8.3"
+    }
+}

package/src/commands/add.js

@@ -0,0 +1,405 @@
+import { getDownloadUrl } from "../utils/api.js";
+import { download } from "../utils/download.js";
+import ora from "ora";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+import AdmZip from "adm-zip";
+import {
+  findAllSkillDirectories,
+  findSkillMdPath,
+  parseSkillMetadata
+} from "../utils/markdownParser.js";
+
+import { copyDirectoryRecursive, deleteDirectoryRecursive } from '../utils/fileOperations.js'
+
+const SKILL_MD_VARIANTS = ['SKILL.md', 'skill.md'];
+const MAX_NAME_LENGTH = 80;
+
+export async function addSkill(name, skillId) {
+    const spinner = ora("Fetching download URL...").start();
+
+    // 获取下载URL
+    spinner.text = "Fetching download URL...";
+    const url = await getDownloadUrl(skillId);
+
+    // 创建下载目录
+    spinner.text = "Creating download directory...";
+    const downloadDir = await createDownloadDir(name);
+
+    try {
+        // 下载技能包zip文件
+        spinner.text = "Downloading skill...";
+        const downloadedFilePath = await download(url, downloadDir);
+
+        // 验证文件是否为ZIP
+        spinner.text = "Validating ZIP file...";
+        await validateZipFile(downloadedFilePath)
+
+        // 提取ZIP文件到同一目录
+        const zipDir = path.dirname(downloadedFilePath)
+        await extractZip(downloadedFilePath, zipDir)
+        // 查找技能目录
+        const currentDir = process.cwd()
+        const skillDir = await findSkillDirectoryAfterExtraction(zipDir, name)
+        await installMarketplaceSkillFromDirectory(skillDir, currentDir, skillId)
+    } catch (err) {
+        spinner.fail("Installation failed.");
+        console.error(err.message);
+    } finally {
+        spinner.stop();
+        await safeRemoveDirectory(downloadDir, 'download directory')
+    }
+}
+
+async function createDownloadDir(name) {
+    const downloadDir = path.join(
+        os.tmpdir(),
+        "zhihuistudio",
+        "tzskills",
+        `${name}-${Date.now()}`
+    );
+
+    await fs.promises.mkdir(downloadDir, { recursive: true });
+    return downloadDir;
+}
+
+async function validateZipFile(zipFilePath){
+    try {
+        const stats = await fs.promises.stat(zipFilePath)
+        if (!stats.isFile()) {
+            throw { type: 'INVALID_ZIP_FORMAT', path: zipFilePath, reason: 'Not a file' }
+        }
+        if (!zipFilePath.toLowerCase().endsWith('.zip')) {
+            throw { type: 'INVALID_ZIP_FORMAT', path: zipFilePath, reason: 'Not a ZIP file' }
+        }
+    } catch (error) {
+        throw { type: 'FILE_NOT_FOUND', path: zipFilePath }
+    }
+}
+
+async function extractZip(zipFilePath, destDir) {
+    try {
+        // Check if ZIP file exists
+        if (!fs.existsSync(zipFilePath)) {
+            throw new Error(`ZIP file not found: ${zipFilePath}`);
+        }
+        
+        // Create destination directory if it doesn't exist
+        if (!fs.existsSync(destDir)) {
+            fs.mkdirSync(destDir, { recursive: true });
+        }
+        
+        const zip = new AdmZip(zipFilePath);
+        
+        // Simple validation: check if ZIP has entries
+        const zipEntries = zip.getEntries();
+        if (zipEntries.length === 0) {
+            throw new Error('ZIP file is empty');
+        }
+        
+        // Extract all entries to destination directory
+        zip.extractAllTo(destDir, true);
+        
+        console.log(`ZIP extracted successfully: ${zipFilePath} -> ${destDir}`);
+    } catch (error) {
+        console.error(`ZIP extraction failed: ${error.message}`);
+        throw error;
+    }
+}
+
+/**
+  * Sanitize folder name for skills (different rules than file names)
+  * NO dots allowed to avoid confusion with file extensions
+  */
+function sanitizeFolderName(folderName) {
+    // Remove path separators
+    let sanitized = folderName.replace(/[/\\]/g, '_')
+    // Remove null bytes using String method to avoid control-regex lint error
+    sanitized = sanitized.replace(new RegExp(String.fromCharCode(0), 'g'), '')
+    // Limit to safe characters (alphanumeric, dash, underscore)
+    // NOTE: No dots allowed to avoid confusion with file extensions
+    sanitized = sanitized.replace(/[^a-zA-Z0-9_-]/g, '_')
+
+    // Validate no extension was provided
+    if (folderName.includes('.')) {
+        console.warn('Skill folder name contained dots, sanitized', {
+            original: folderName,
+            sanitized
+        })
+    }
+
+    // Truncate to prevent Windows MAX_PATH issues
+    sanitized = truncateWithHash(sanitized, MAX_NAME_LENGTH)
+
+    return sanitized
+}
+
+/**
+ * Truncate a name to maxLength, appending a hash suffix for uniqueness.
+ * Names within the limit are returned unchanged.
+ */
+function truncateWithHash(name, maxLength) {
+    if (name.length <= maxLength) return name
+    if (maxLength <= 9) return name.slice(0, maxLength)
+    const hash = crypto.createHash('sha256').update(name).digest('hex').slice(0, 8)
+    const truncated = name.slice(0, maxLength - 9).replace(/[-_]+$/, '')
+    return `${truncated}-${hash}`
+}
+
+/**
+  * 在解压后的目录中查找技能目录
+  */
+async function findSkillDirectoryAfterExtraction(extractedDir, skillName) {
+    // 首先检查是否有skills/目录
+    const skillsDir = path.join(extractedDir, 'skills')
+    if (fs.existsSync(skillsDir)) {
+        // 在skills/目录下查找指定名称的目录
+        const skillCandidate = path.join(skillsDir, skillName)
+        if (fs.existsSync(skillCandidate)) {
+            const skillMdPath = await findSkillMdPath(skillCandidate)
+            if (skillMdPath) {
+                return skillCandidate
+            }
+        }
+
+        // 如果没有找到指定名称，查找所有包含SKILL.md的目录
+        const skillDirs = await findAllSkillDirectories(skillsDir, skillsDir)
+        if (skillDirs.length > 0) {
+            return skillDirs[0].folderPath
+        }
+    }
+
+
+    // 如果没有skills/目录，直接在根目录查找
+    const skillDirs = await findAllSkillDirectories(extractedDir, extractedDir)
+    if (skillDirs.length === 0) {
+        throw {
+            type: 'INVALID_METADATA',
+            reason: 'No skill directory found after extraction',
+            path: extractedDir
+        }
+    }
+
+    // 尝试匹配技能名称
+    const matchedDir = skillDirs.find((dir) => path.basename(dir.folderPath).toLowerCase() === skillName.toLowerCase())
+
+    if (matchedDir) {
+        return matchedDir.folderPath
+    }
+
+    // 返回第一个找到的技能目录
+    return skillDirs[0].folderPath
+}
+
+  /**
+   * Ensure .claude subdirectory exists for the given plugin type
+   */
+async function ensureClaudeDirectory(workdir) {
+    const typeDir = path.join(workdir, '.claude', 'skills')
+
+    try {
+        await fs.promises.mkdir(typeDir, { recursive: true })
+        console.debug('Ensured directory exists', { typeDir })
+    } catch (error) {
+        throw new Error('Failed to create directory', {
+            typeDir,
+            error: error instanceof Error ? error.message : String(error)
+        })
+    }
+}
+
+async function safeRemoveDirectory(targetPath, label) {
+    try {
+        await deleteDirectoryRecursive(targetPath)
+        console.info(`Rolled back ${label}`, { targetPath })
+    } catch (unlinkError) {
+        console.error(`Failed to rollback ${label}`, {
+            targetPath,
+            error: unlinkError instanceof Error ? unlinkError.message : String(unlinkError)
+        })
+    }
+}
+
+/**
+ * Check if a path exists (file or directory)
+ */
+async function pathExists(targetPath) {
+  try {
+    await fs.promises.access(targetPath, fs.constants.R_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function safeRename(from, to, label) {
+    try {
+        await fs.promises.rename(from, to)
+        console.debug(`Restored ${label}`, { from, to })
+    } catch (error) {
+        console.error(`Failed to restore ${label}`, {
+            from,
+            to,
+            error: error instanceof Error ? error.message : String(error)
+        })
+    }
+}
+
+async function installMarketplaceSkillFromDirectory(skillDir, currentDir, skillId) {
+    const folderName = path.basename(skillDir)
+    const sourcePath = path.join('skills', folderName)
+
+    const metadata = await parseSkillMetadata(skillDir, sourcePath, 'skills')
+    const sanitizedName = sanitizeFolderName(metadata.filename)
+
+    await ensureClaudeDirectory(currentDir)
+    const claudeBasePath = path.join(currentDir, '.claude')
+    const destPath = path.join(claudeBasePath, 'skills', sanitizedName)
+    await installWithBackup({
+        destPath,
+        copy: ()=> copyDirectoryRecursive(skillDir, destPath),
+        cleanup: (p, l) => safeRemoveDirectory(p, l)
+    })
+
+    const installedSkill = createInstalledSkillMetadata(
+        metadata,
+        sanitizedName,
+        'skill',
+        skillId
+    )
+    const pluginsFile = path.join(claudeBasePath, 'plugins.json')
+    
+    // 读取并更新 plugins.json
+    let pluginsData = { version: 1, lastUpdated: Date.now(), plugins: [] }
+    try {
+        if (fs.existsSync(pluginsFile)) {
+            const existingContent = await fs.promises.readFile(pluginsFile, 'utf-8')
+            pluginsData = JSON.parse(existingContent)
+            if (!pluginsData.plugins) {
+                pluginsData.plugins = []
+            }
+        }
+    } catch (error) {
+        console.warn('Failed to read existing plugins.json, creating new one:', error.message)
+    }
+    
+    // 检查是否有相同 skillId 的 plugin
+    const existingIndex = pluginsData.plugins.findIndex(
+        p => p.metadata && p.metadata.id === installedSkill.metadata.id
+    )
+    
+    if (existingIndex !== -1) {
+        // 覆盖已有的 plugin
+        pluginsData.plugins[existingIndex] = installedSkill
+    } else {
+        // 插入新的 plugin
+        pluginsData.plugins.push(installedSkill)
+    }
+    
+    pluginsData.lastUpdated = Date.now()
+    const content = JSON.stringify(pluginsData, null, 2)
+    await writeWithLock(pluginsFile, content, { atomic: true, encoding: 'utf-8' })
+}
+
+async function installWithBackup({ destPath, copy, cleanup }) {
+    const backupPath = `${destPath}.bak`
+    let hasBackup = false
+
+    try {
+      if (await pathExists(destPath)) {
+        await cleanup(backupPath, 'stale backup')
+        await fs.promises.rename(destPath, backupPath)
+        hasBackup = true
+        console.debug(`Backed up existing skill folder`, { backupPath })
+      }
+
+      await copy()
+      console.debug(`skill folder copied to destination`, { destPath })
+
+      if (hasBackup) {
+        await cleanup(backupPath, `backup skill folder`)
+      }
+    } catch (error) {
+      if (hasBackup) {
+        await cleanup(destPath, `partial skill folder`)
+        await safeRename(backupPath, destPath, `skill folder backup`)
+      }
+      throw error
+    }
+}
+
+function createInstalledSkillMetadata(metadata, filename, type, skillId) {
+    const installAt = Date.now()
+    const metadataWithInstall= {
+        ...metadata,
+        filename,
+        type,
+        installAt,
+        updatedAt: metadata.updatedAt ?? installAt,
+        id: skillId
+    }
+    const installedSkill = {
+        filename,
+        type,
+        metadata: metadataWithInstall
+    }
+    return installedSkill
+}
+
+async function writeWithLock(
+    filePath,
+    data,
+    options = {}
+) {
+    const {
+        atomic = false,
+        tempPath,
+        lockFilePath = `${filePath}.lock`,
+        retries = 50,
+        retryDelayMs = 50,
+        lockStaleMs = 30000,
+        ...writeOptions
+    } = options
+
+    const finalTempPath = tempPath ?? `${filePath}.tmp`
+
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+        try {
+            const handle = await fs.promises.open(lockFilePath, 'wx')
+            await handle.close()
+
+            try {
+                if (atomic) {
+                    await fs.promises.writeFile(finalTempPath, data, writeOptions)
+                    await fs.promises.rename(finalTempPath, filePath)
+                } else {
+                    await fs.promises.writeFile(filePath, data, writeOptions)
+                }
+            } finally {
+                await fs.promises.unlink(lockFilePath).catch(() => undefined)
+            }
+
+            return
+        } catch (error) {
+            if (error.code !== 'EEXIST' || attempt >= retries) {
+                throw error
+            }
+
+            if (lockStaleMs > 0) {
+                try {
+                    const stats = await fs.promises.stat(lockFilePath)
+                    if (Date.now() - stats.mtimeMs > lockStaleMs) {
+                        await fs.promises.unlink(lockFilePath)
+                        continue
+                    }
+                } catch {
+                    // Ignore stale checks if lock file disappears or stat fails
+                }
+            }
+
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs))
+        }
+    }
+}

package/src/commands/find.js

@@ -0,0 +1,26 @@
+import { searchSkills } from "../utils/api.js";
+import chalk from "chalk";
+
+export async function findSkills(query) {
+    const skills = await searchSkills(query);
+
+    if (!skills.length) {
+        console.log("No skills found.");
+        return;
+    }
+    console.log(chalk.green(`Current working directory: ${process.cwd()}`));
+    console.log(chalk.green(`\nFound ${skills.length} skills:\n`));
+
+    skills.forEach((s) => {
+        console.log(chalk.cyan(`${s.name}`));
+        console.log(`  id: ${s.id}`);
+        console.log(`  version: ${s.version}`);
+        console.log(`  author: ${s.author || "TZGJ"}`);
+        console.log(`  description: ${s.description || "No description"}`);
+        console.log(`  source URL: ${s.sourceUrl || "No source URL"}`);
+        console.log("");
+    });
+
+    console.log(chalk.yellow("Install with:"));
+    console.log(`TZSkillS add <skill-name> <skill-id>\n`);
+}

package/src/utils/api.js

@@ -0,0 +1,54 @@
+import axios from "axios";
+import { getAccessToken } from "./token.js";
+
+const DEFAULT_BASE_URL = "http://10.16.48.194:30181/";
+
+async function getHeaders() {
+    const token = await getAccessToken();
+    return {
+        Authorization: `Bearer ${token}`
+    };
+}
+
+export async function searchSkills(query) {
+    const baseUrl = await getTZSkillBaseUrl();
+    const url = new URL(`${baseUrl}/api/studio/skills`);
+    const res = await axios.get(url, {
+        params: { q: query },
+        headers: await getHeaders()
+    });
+
+    return res.data.skills;
+}
+
+export async function getDownloadUrl(skillId) {
+    const baseUrl = await getTZSkillBaseUrl();
+    const resolveUrl = `${baseUrl}/api/studio/skill/${skillId}/download`
+    const res = await axios.get(
+        resolveUrl,
+        {
+            headers: await getHeaders()
+        }
+    );
+
+    return res.data; // zip url
+}
+
+export async function getTZSkillBaseUrl() {
+    try {
+        const res = await axios.get(
+            "http://127.0.0.1:28888/v1/bakertilly/tz-skills-url",
+            { timeout: 3000 }
+        );
+
+        if (!res.data.tzSkillsAPIUrl) {
+            console.error("Cannot get the TZ skills base URL! Will use default base URL instead.");
+            return DEFAULT_BASE_URL;
+        }
+
+        return res.data.tzSkillsAPIUrl;
+    } catch (err) {
+        console.error("Cannot connect to Zhihui Studio. Please make sure Zhihui Studio is running. Will use default base URL instead.");
+        return DEFAULT_BASE_URL;
+    }
+}

package/src/utils/download.js

@@ -0,0 +1,47 @@
+import axios from "axios";
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+export async function download(url, downloadDir) {
+  let filePath = null;
+
+  try {
+    const res = await axios({
+      url,
+      method: "GET",
+      responseType: "arraybuffer",
+      timeout: 60000
+    });
+
+    if (res.status !== 200) {
+      throw new Error(`file-download: HTTP ${res.status}: ${res.statusText || 'Download failed'}`);
+    }
+
+    // 从URL中提取文件名，如果没有则使用时间戳
+    const urlPath = new URL(url).pathname;
+    const originalFileName = path.basename(urlPath) || `download-${Date.now()}.zip`;
+    filePath = path.join(downloadDir, originalFileName);
+    fs.writeFileSync(filePath, res.data);
+
+    console.log(`Success: Downloaded to ${filePath}`);
+    return filePath;
+  } catch (error) {
+    // 清理已下载的部分文件
+    if (filePath && fs.existsSync(filePath)) {
+      try {
+        fs.unlinkSync(filePath);
+        console.log(`Cleaned up partial file: ${filePath}`);
+      } catch (cleanupError) {
+        console.error(`Failed to clean up partial file: ${cleanupError.message}`);
+      }
+    }
+
+    let msg = error.message;
+    if (error.code === "ECONNABORTED") {
+      msg = "Download timeout: exceeded 60 seconds";
+    }
+    console.error(`Failed: ${msg}`);
+    throw error;
+  }
+}

package/src/utils/fileOperations.js

@@ -0,0 +1,188 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+const MAX_RECURSION_DEPTH = 1000
+
+/**
+ * Recursively copy a directory and all its contents
+ * @param source - Source directory path (must be absolute)
+ * @param destination - Destination directory path (must be absolute)
+ * @param options - Copy options
+ * @param depth - Current recursion depth (internal use)
+ * @throws If copy operation fails or paths are invalid
+ */
+export async function copyDirectoryRecursive(
+  source,
+  destination,
+  depth = 0
+) {
+  // Input validation
+  if (!source || !destination) {
+    throw new TypeError('Source and destination paths are required')
+  }
+
+  if (!path.isAbsolute(source) || !path.isAbsolute(destination)) {
+    throw new Error('Source and destination paths must be absolute')
+  }
+
+  // Depth limit to prevent stack overflow
+  if (depth > MAX_RECURSION_DEPTH) {
+    throw new Error(`Maximum recursion depth exceeded: ${MAX_RECURSION_DEPTH}`)
+  }
+
+  try {
+    // Verify source exists and is a directory
+    const sourceStats = await fs.promises.lstat(source)
+    if (!sourceStats.isDirectory()) {
+      throw new Error(`Source is not a directory: ${source}`)
+    }
+
+    // Create destination directory
+    await fs.promises.mkdir(destination, { recursive: true })
+    console.debug('Created destination directory', { destination })
+
+    // Read source directory
+    const entries = await fs.promises.readdir(source, { withFileTypes: true })
+
+    // Copy each entry
+    for (const entry of entries) {
+      const sourcePath = path.join(source, entry.name)
+      const destPath = path.join(destination, entry.name)
+
+      // Use lstat to detect symlinks and prevent following them
+      const entryStats = await fs.promises.lstat(sourcePath)
+
+      if (entryStats.isSymbolicLink()) {
+        console.warn('Skipping symlink for security', { path: sourcePath })
+        continue
+      }
+
+      if (entryStats.isDirectory()) {
+        // Recursively copy subdirectory
+        await copyDirectoryRecursive(sourcePath, destPath, depth + 1)
+      } else if (entryStats.isFile()) {
+        // Copy file with error handling for race conditions
+        try {
+          await fs.promises.copyFile(sourcePath, destPath)
+          // Preserve file permissions
+          await fs.promises.chmod(destPath, entryStats.mode)
+          console.debug('Copied file', { from: sourcePath, to: destPath })
+        } catch (error) {
+          // Handle race condition where file was deleted during copy
+          if (error.code === 'ENOENT') {
+            console.warn('File disappeared during copy', { sourcePath })
+            continue
+          }
+          throw error
+        }
+      } else {
+        // Skip special files (pipes, sockets, devices, etc.)
+        console.debug('Skipping special file', { path: sourcePath })
+      }
+    }
+
+    console.info('Directory copied successfully', { from: source, to: destination, depth })
+  } catch (error) {
+    console.error('Failed to copy directory', { source, destination, depth, error })
+    throw error
+  }
+}
+
+/**
+ * Recursively delete a directory and all its contents
+ * @param dirPath - Directory path to delete (must be absolute)
+ * @param options - Delete options
+ * @throws If deletion fails or path is invalid
+ */
+export async function deleteDirectoryRecursive(dirPath) {
+  // Input validation
+  if (!dirPath) {
+    throw new TypeError('Directory path is required')
+  }
+
+  if (!path.isAbsolute(dirPath)) {
+    throw new Error('Directory path must be absolute')
+  }
+
+  try {
+    // Verify path exists before attempting deletion
+    try {
+      const stats = await fs.promises.lstat(dirPath)
+      if (!stats.isDirectory()) {
+        throw new Error(`Path is not a directory: ${dirPath}`)
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        console.warn('Directory already deleted', { dirPath })
+        return
+      }
+      throw error
+    }
+
+    // Node.js 14.14+ has fs.rm with recursive option
+    await fs.promises.rm(dirPath, { recursive: true, force: true })
+    console.info('Directory deleted successfully', { dirPath })
+  } catch (error) {
+    console.error('Failed to delete directory', { dirPath, error })
+    throw error
+  }
+}
+
+/**
+ * Get total size of a directory (in bytes)
+ * @param dirPath - Directory path (must be absolute)
+ * @param options - Size calculation options
+ * @param depth - Current recursion depth (internal use)
+ * @returns Total size in bytes
+ * @throws If size calculation fails or path is invalid
+ */
+export async function getDirectorySize(dirPath, depth = 0) {
+  // Input validation
+  if (!dirPath) {
+    throw new TypeError('Directory path is required')
+  }
+
+  if (!path.isAbsolute(dirPath)) {
+    throw new Error('Directory path must be absolute')
+  }
+
+  // Depth limit to prevent stack overflow
+  if (depth > MAX_RECURSION_DEPTH) {
+    throw new Error(`Maximum recursion depth exceeded: ${MAX_RECURSION_DEPTH}`)
+  }
+
+  let totalSize = 0
+
+  try {
+    const entries = await fs.promises.readdir(dirPath, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const entryPath = path.join(dirPath, entry.name)
+
+      // Use lstat to detect symlinks and prevent following them
+      const entryStats = await fs.promises.lstat(entryPath)
+
+      if (entryStats.isSymbolicLink()) {
+        console.debug('Skipping symlink in size calculation', { path: entryPath })
+        continue
+      }
+
+      if (entryStats.isDirectory()) {
+        // Recursively get size of subdirectory
+        totalSize += await getDirectorySize(entryPath, depth + 1)
+      } else if (entryStats.isFile()) {
+        // Get file size from lstat (already have it)
+        totalSize += entryStats.size
+      } else {
+        // Skip special files
+        console.debug('Skipping special file in size calculation', { path: entryPath })
+      }
+    }
+
+    console.debug('Calculated directory size', { dirPath, size: totalSize, depth })
+    return totalSize
+  } catch (error) {
+    console.error('Failed to calculate directory size', { dirPath, depth, error })
+    throw error
+  }
+}

package/src/utils/markdownParser.js

@@ -0,0 +1,326 @@
+import * as crypto from 'crypto'
+import * as fs from 'fs'
+import matter from 'gray-matter'
+import * as path from 'path'
+import { parse } from 'yaml'
+
+import { getDirectorySize } from './fileOperations.js'
+
+const YAML_PARSE_OPTIONS = { schema: 'failsafe' }
+
+// Skill markdown filename variants (case-insensitive support)
+const SKILL_MD_VARIANTS = ['SKILL.md', 'skill.md']
+
+/**
+ * Find the skill markdown file in a directory (supports SKILL.md or skill.md)
+ * @returns The full path to the skill file if found, null otherwise
+ */
+export async function findSkillMdPath(dirPath) {
+  for (const variant of SKILL_MD_VARIANTS) {
+    const skillMdPath = path.join(dirPath, variant)
+    try {
+      await fs.promises.stat(skillMdPath)
+      return skillMdPath
+    } catch {
+      // Try next variant
+    }
+  }
+  return null
+}
+
+/**
+ * Check if a directory entry is a directory or a symlink pointing to a directory
+ * Follows symlinks to determine if they point to valid directories
+ */
+async function isDirectoryOrSymlinkToDirectory(entry, parentDir) {
+  if (entry.isDirectory()) {
+    return true
+  }
+  if (entry.isSymbolicLink()) {
+    try {
+      const fullPath = path.join(parentDir, entry.name)
+      const stats = await fs.promises.stat(fullPath) // stat follows symlinks
+      return stats.isDirectory()
+    } catch {
+      // Broken symlink or permission error
+      return false
+    }
+  }
+  return false
+}
+
+const isString = (value) => typeof value === 'string'
+
+function toStringArray(value) {
+  if (Array.isArray(value)) {
+    return value.filter(isString)
+  }
+  if (isString(value)) {
+    return value
+      .split(',')
+      .map((t) => t.trim())
+      .filter(Boolean)
+  }
+  return undefined
+}
+
+function toString(value) {
+  return isString(value) ? value : undefined
+}
+
+function parseLooseValue(raw) {
+  if (!raw) return ''
+  try {
+    const parsed = parse(raw, YAML_PARSE_OPTIONS)
+    return parsed === undefined ? raw : parsed
+  } catch {
+    return raw
+  }
+}
+
+function parseFrontmatterLoose(content) {
+  const lines = content.split(/\r?\n/)
+  if (lines.length === 0 || lines[0].trim() !== '---') {
+    return {}
+  }
+
+  let endIndex = -1
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      endIndex = i
+      break
+    }
+  }
+  if (endIndex === -1) {
+    return {}
+  }
+
+  const frontmatterLines = lines.slice(1, endIndex)
+  const data = {}
+  let currentKey = null
+  let buffer = []
+
+  const flush = () => {
+    if (!currentKey) return
+    const rawValue = buffer.join('\n').trim()
+    data[currentKey] = parseLooseValue(rawValue)
+    buffer = []
+    currentKey = null
+  }
+
+  for (const line of frontmatterLines) {
+    const keyMatch = line.match(/^([A-Za-z0-9_-]+)\s*:(.*)$/)
+    if (keyMatch) {
+      flush()
+      currentKey = keyMatch[1]
+      const rest = keyMatch[2].trimStart()
+      if (rest.length > 0) {
+        data[currentKey] = parseLooseValue(rest)
+        currentKey = null
+      }
+      continue
+    }
+    if (currentKey) {
+      buffer.push(line)
+    }
+  }
+
+  flush()
+  return data
+}
+
+function recoverFrontmatter(content, context) {
+  const data = parseFrontmatterLoose(content)
+  console.warn('Recovered frontmatter using loose parser', {
+    ...context,
+    keys: Object.keys(data)
+  })
+  return data
+}
+
+/**
+ * Recursively find all directories containing SKILL.md or skill.md
+ * Supports symlinks and deduplicates by skill name
+ *
+ * @param dirPath - Directory to search in
+ * @param basePath - Base path for calculating relative source paths
+ * @param maxDepth - Maximum depth to search (default: 10 to prevent infinite loops)
+ * @param currentDepth - Current search depth (used internally)
+ * @param seen - Set of already seen skill names (for deduplication)
+ * @returns Array of objects with absolute folder path and relative source path
+ */
+export async function findAllSkillDirectories(
+  dirPath,
+  basePath,
+  maxDepth = 10,
+  currentDepth = 0,
+  seen = new Set()
+) {
+  const results = []
+
+  // Prevent excessive recursion
+  if (currentDepth > maxDepth) {
+    return results
+  }
+
+  // Check if current directory contains SKILL.md or skill.md
+  const skillMdPath = await findSkillMdPath(dirPath)
+
+  if (skillMdPath) {
+    // Found skill markdown in this directory
+    const skillName = path.basename(dirPath)
+
+    // Deduplicate: only add if we haven't seen this skill name yet
+    if (!seen.has(skillName)) {
+      seen.add(skillName)
+      const relativePath = path.relative(basePath, dirPath)
+      results.push({
+        folderPath: dirPath,
+        sourcePath: relativePath
+      })
+    }
+    return results
+  }
+
+  // Only search subdirectories if current directory doesn't have SKILL.md
+  try {
+    const entries = await fs.promises.readdir(dirPath, { withFileTypes: true })
+
+    for (const entry of entries) {
+      // Support both directories and symlinks pointing to directories
+      if (await isDirectoryOrSymlinkToDirectory(entry, dirPath)) {
+        const subDirPath = path.join(dirPath, entry.name)
+        const subResults = await findAllSkillDirectories(subDirPath, basePath, maxDepth, currentDepth + 1, seen)
+        results.push(...subResults)
+      }
+    }
+  } catch (error) {
+    // Ignore errors when reading subdirectories (e.g., permission denied)
+    console.debug('Failed to read subdirectory during skill search', {
+      dirPath,
+      error: error.message
+    })
+  }
+
+  return results
+}
+
+/**
+ * Parse metadata from SKILL.md within a skill folder
+ *
+ * @param skillFolderPath - Absolute path to skill folder (must be absolute and contain SKILL.md)
+ * @param sourcePath - Relative path from plugins base (e.g., "skills/my-skill")
+ * @param category - Category name (typically "skills" for flat structure)
+ * @returns PluginMetadata with folder name as filename (no extension)
+ * @throws PluginError if SKILL.md not found or parsing fails
+ */
+export async function parseSkillMetadata(skillFolderPath, sourcePath, category) {
+  // Input validation
+  if (!skillFolderPath || !path.isAbsolute(skillFolderPath)) {
+    throw {
+      type: 'INVALID_METADATA',
+      reason: 'Skill folder path must be absolute',
+      path: skillFolderPath
+    }
+  }
+
+  // Look for SKILL.md or skill.md directly in this folder (no recursion)
+  const skillMdPath = await findSkillMdPath(skillFolderPath)
+
+  // Check if skill markdown exists
+  if (!skillMdPath) {
+    console.error('SKILL.md or skill.md not found in skill folder', { skillFolderPath })
+    throw {
+      type: 'FILE_NOT_FOUND',
+      path: path.join(skillFolderPath, 'SKILL.md'),
+      message: 'SKILL.md or skill.md not found in skill folder'
+    }
+  }
+
+  // Read SKILL.md content
+  let content
+  try {
+    content = await fs.promises.readFile(skillMdPath, 'utf8')
+  } catch (error) {
+    console.error('Failed to read SKILL.md', { skillMdPath, error })
+    throw {
+      type: 'READ_FAILED',
+      path: skillMdPath,
+      reason: error.message || 'Unknown error'
+    }
+  }
+
+  // Parse frontmatter safely with FAILSAFE_SCHEMA to prevent deserialization attacks
+  let data = {}
+  try {
+    const parsed = matter(content, {
+      engines: {
+        yaml: (s) => parse(s, YAML_PARSE_OPTIONS)
+      }
+    })
+    data = parsed.data ?? {}
+  } catch (error) {
+    console.warn('Failed to parse SKILL.md frontmatter, attempting recovery', {
+      skillMdPath,
+      error: error?.message || String(error)
+    })
+    data = recoverFrontmatter(content, { skillMdPath })
+  }
+
+  // Calculate hash of SKILL.md only (not entire folder)
+  // Note: This means changes to other files in the skill won't trigger cache invalidation
+  // This is intentional - only SKILL.md metadata changes should trigger updates
+  const contentHash = crypto.createHash('sha256').update(content).digest('hex')
+
+  // Get folder name as identifier (NO EXTENSION)
+  const folderName = path.basename(skillFolderPath)
+
+  // Get total folder size
+  let folderSize
+  try {
+    folderSize = await getDirectorySize(skillFolderPath)
+  } catch (error) {
+    console.error('Failed to calculate skill folder size', { skillFolderPath, error })
+    // Use 0 as fallback instead of failing completely
+    folderSize = 0
+  }
+
+  // Parse tools (skills use 'tools', not 'allowed_tools')
+  const tools = toStringArray(data.tools)
+
+  // Parse tags
+  const tags = toStringArray(data.tags)
+
+  // Validate and sanitize name
+  const rawName = toString(data.name)
+  const name = rawName && rawName.trim() ? rawName.trim() : folderName
+
+  // Validate and sanitize description
+  const rawDescription = toString(data.description)
+  const description = rawDescription && rawDescription.trim() ? rawDescription.trim() : undefined
+
+  // Validate version and author
+  const version = toString(data.version)
+  const author = toString(data.author)
+
+  console.debug('Successfully parsed skill metadata', {
+    skillFolderPath,
+    folderName,
+    size: folderSize
+  })
+
+  return {
+    sourcePath, // e.g., "skills/my-skill"
+    filename: folderName, // e.g., "my-skill" (folder name, NO .md extension)
+    name,
+    description,
+    tools,
+    category, // "skills" for flat structure
+    type: 'skill',
+    tags,
+    version,
+    author,
+    size: folderSize,
+    contentHash // Hash of SKILL.md content only
+  }
+}

package/src/utils/token.js

@@ -0,0 +1,22 @@
+import axios from "axios";
+
+export async function getAccessToken() {
+    try {
+        const res = await axios.get(
+            "http://127.0.0.1:28888/v1/bakertilly/token",
+            { timeout: 3000 }
+        );
+
+        if (!res.data.hasToken) {
+            console.error("Cannot get the user token!");
+            console.error("Please login in Cherry Studio first.");
+            process.exit(1);
+        }
+
+        return res.data.accessToken;
+    } catch (err) {
+        console.error("Cannot connect to Zhihui Studio.");
+        console.error("Make sure Zhihui Studio is running.");
+        process.exit(1);
+    }
+}