itismyskillmarket 1.0.10

package/src/types.ts

@@ -0,0 +1,137 @@
+/**
+ * =============================================================================
+ * SkillMarket 类型定义文件
+ * =============================================================================
+ * 
+ * 本文件定义了 SkillMarket 中使用的所有 TypeScript 接口类型，包括：
+ * - Skill 元数据（用于 npm 包内的 skill 定义）
+ * - 已安装 Skill 信息（用于本地注册表）
+ * - 注册表数据结构
+ * 
+ * @module types
+ */
+
+// -----------------------------------------------------------------------------
+// Skill 元数据接口
+// -----------------------------------------------------------------------------
+
+/**
+ * Skill 元数据结构
+ * 
+ * 定义 npm 包中 skill 的元信息，通常存储在 package.json 的
+ * skillmarket 字段或独立的 metadata.json 文件中
+ * 
+ * @interface SkillMetadata
+ * 
+ * @example
+ * // package.json 中的 skillmarket 字段示例:
+ * {
+ *   "skillmarket": {
+ *     "id": "brainstorming",
+ *     "displayName": "Brainstorming",
+ *     "description": "多智能体头脑风暴能力",
+ *     "platforms": ["cursor", "opencode", "vscode"],
+ *     "defaultVersion": "v1"
+ *   }
+ * }
+ */
+export interface SkillMetadata {
+  /** Skill 唯一标识符，用于包名和命令行引用 */
+  id: string;
+  
+  /** Skill 的友好显示名称，用于 UI 展示 */
+  displayName: string;
+  
+  /** Skill 功能描述，说明其用途和功能 */
+  description: string;
+  
+  /** 支持的平台列表，只有列表中的平台才能使用此 skill */
+  platforms: string[];
+  
+  /** 默认版本标识，通常为 'v1', 'v2' 等 */
+  defaultVersion: string;
+}
+
+// -----------------------------------------------------------------------------
+// 已安装 Skill 接口
+// -----------------------------------------------------------------------------
+
+/**
+ * 已安装 Skill 的信息结构
+ * 
+ * 存储在本地注册表 (registry.json) 中，
+ * 记录用户已安装的 skill 及其相关信息
+ * 
+ * @interface InstalledSkill
+ * 
+ * @example
+ * // registry.json 中的示例:
+ * {
+ *   "skills": {
+ *     "brainstorming": {
+ *       "id": "brainstorming",
+ *       "version": "1.0.0",
+ *       "installedAt": "2026-04-01T10:00:00.000Z",
+ *       "platforms": ["opencode"]
+ *     }
+ *   }
+ * }
+ */
+export interface InstalledSkill {
+  /** Skill 唯一标识符，与 npm 包名对应 */
+  id: string;
+  
+  /** 已安装的版本号，遵循 semver 规范 */
+  version: string;
+  
+  /** 安装时间的 ISO 8601 格式时间戳 */
+  installedAt: string;
+  
+  /** 安装时检测到的目标平台列表 */
+  platforms: string[];
+}
+
+// -----------------------------------------------------------------------------
+// 注册表数据结构
+// -----------------------------------------------------------------------------
+
+/**
+ * SkillMarket 本地注册表数据结构
+ * 
+ * 存储在 ~/.skillmarket/registry.json 文件中，
+ * 记录所有已安装的 skills 和注册表元信息
+ * 
+ * @interface RegistryData
+ * 
+ * @example
+ * // 完整的 registry.json 结构:
+ * {
+ *   "skills": {
+ *     "skill1": { id, version, installedAt, platforms },
+ *     "skill2": { id, version, installedAt, platforms }
+ *   },
+ *   "lastUpdated": "2026-04-01T10:30:00.000Z"
+ * }
+ */
+export interface RegistryData {
+  /** 
+   * 已安装 skills 的字典
+   * 
+   * - Key: skill ID (唯一标识符)
+   * - Value: InstalledSkill 对象（包含版本、平台等信息）
+   * 
+   * @example
+   * // 访问已安装的 skill:
+   * const brainstorming = registry.skills['brainstorming'];
+   * console.log(brainstorming.version); // "1.0.0"
+   */
+  skills: Record<string, InstalledSkill>;
+  
+  /** 
+   * 注册表最后更新时间
+   * 
+   * ISO 8601 格式的时间戳，
+   * 每次修改注册表时自动更新
+   */
+  lastUpdated: string;
+}

package/src/utils/dirs.ts

@@ -0,0 +1,166 @@
+/**
+ * =============================================================================
+ * SkillMarket 目录工具模块
+ * =============================================================================
+ * 
+ * 本模块提供获取和创建 SkillMarket 目录结构的工具函数。
+ * 所有路径都遵循 ~/.skillmarket/ 的主目录结构。
+ * 
+ * 目录结构:
+ *   ~/.skillmarket/
+ *   ├── registry.json     # 注册表文件
+ *   ├── cache/            # npm 包缓存
+ *   ├── skills/           # 已安装的 skills
+ *   └── platform-links/   # 平台适配软链接
+ * 
+ * @module utils/dirs
+ */
+
+// -----------------------------------------------------------------------------
+// 导入依赖
+// -----------------------------------------------------------------------------
+
+import os from 'os';           // Node.js OS 模块，用于获取用户主目录
+import path from 'path';       // Node.js 路径模块
+import fs from 'fs-extra';    // fs-extra，提供 Promise 化的文件系统操作
+import { 
+  MARKET_DIR,        // 主目录名称常量
+  SUBDIRS,           // 子目录名称常量
+  REGISTRY_FILE      // 注册表文件名常量
+} from '../constants.js';
+
+// -----------------------------------------------------------------------------
+// 路径获取函数
+// -----------------------------------------------------------------------------
+
+/**
+ * 获取 SkillMarket 主目录路径
+ * 
+ * 返回 ~/.skillmarket 路径，这是所有 skill 相关数据的存储根目录
+ * 
+ * @returns {string} 技能市场主目录的绝对路径
+ * 
+ * @example
+ * const home = getMarketHome();
+ * // 在 Linux/Mac: '/home/username/.skillmarket'
+ * // 在 Windows: 'C:\Users\username\.skillmarket'
+ */
+export function getMarketHome(): string {
+  return path.join(os.homedir(), MARKET_DIR);
+}
+
+/**
+ * 获取 npm 包缓存目录路径
+ * 
+ * 用于存储从 npm 下载的 skill 包（.tgz 文件）和解压后的内容
+ * 
+ * @returns {string} 缓存目录的绝对路径
+ * 
+ * @example
+ * const cacheDir = getCacheDir();
+ * // '~/.skillmarket/cache'
+ */
+export function getCacheDir(): string {
+  return path.join(getMarketHome(), SUBDIRS.CACHE);
+}
+
+/**
+ * 获取已安装 skills 的主存储目录路径
+ * 
+ * 所有安装的 skill 都会复制/链接到这个目录，
+ * 每个 skill 有独立的子目录，内部包含版本目录和 latest 软链接
+ * 
+ * @returns {string} skills 存储目录的绝对路径
+ * 
+ * @example
+ * const skillsDir = getSkillsDir();
+ * // '~/.skillmarket/skills'
+ * 
+ * // 典型目录结构:
+ * // skills/
+ * // ├── brainstorming/
+ * // │   ├── latest -> 1.0.0/
+ * // │   └── 1.0.0/
+ * // └── weather/
+ * //     ├── latest -> 2.0.0/
+ * //     └── 2.0.0/
+ */
+export function getSkillsDir(): string {
+  return path.join(getMarketHome(), SUBDIRS.SKILLS);
+}
+
+/**
+ * 获取平台适配层软链接目录路径
+ * 
+ * 这个目录为每个支持的平台创建独立的子目录，
+ * 里面包含指向对应平台 skill 文件的软链接
+ * 
+ * @returns {string} 平台链接目录的绝对路径
+ * 
+ * @example
+ * const platformLinksDir = getPlatformLinksDir();
+ * // '~/.skillmarket/platform-links'
+ * 
+ * // 典型目录结构:
+ * // platform-links/
+ * // ├── cursor/
+ * // │   └── skills/
+ * // │       └── brainstorming -> ../../skills/brainstorming/latest/cursor
+ * // ├── opencode/
+ * // │   └── skills/
+ * // │       └── brainstorming -> ../../skills/brainstorming/latest/opencode
+ * // └── ...
+ */
+export function getPlatformLinksDir(): string {
+  return path.join(getMarketHome(), SUBDIRS.PLATFORM_LINKS);
+}
+
+/**
+ * 获取本地注册表文件路径
+ * 
+ * 注册表文件存储所有已安装 skill 的元信息，
+ * 是一个 JSON 格式的文件
+ * 
+ * @returns {string} 注册表文件的绝对路径
+ * 
+ * @example
+ * const registryPath = getRegistryPath();
+ * // '~/.skillmarket/registry.json'
+ */
+export function getRegistryPath(): string {
+  return path.join(getMarketHome(), REGISTRY_FILE);
+}
+
+// -----------------------------------------------------------------------------
+// 目录创建函数
+// -----------------------------------------------------------------------------
+
+/**
+ * 确保 SkillMarket 所有必要目录都已创建
+ * 
+ * 在首次使用或安装 skill 之前调用此函数，
+ * 确保所有目录结构都存在
+ * 
+ * @returns {Promise<void>} 创建完成后 resolve
+ * 
+ * @example
+ * // 安装 skill 前确保目录存在
+ * await ensureMarketDirs();
+ * 
+ * // 这会依次创建:
+ * // ~/.skillmarket/cache/
+ * // ~/.skillmarket/skills/
+ * // ~/.skillmarket/platform-links/
+ */
+export async function ensureMarketDirs(): Promise<void> {
+  // 使用 fs-extra 的 ensureDir 确保目录存在
+  // 如果目录已存在则不进行任何操作
+  // 如果父目录不存在则递归创建
+  
+  await fs.ensureDir(getCacheDir());
+  await fs.ensureDir(getSkillsDir());
+  await fs.ensureDir(getPlatformLinksDir());
+  
+  // 注意: 注册表目录通过 getRegistryPath() 获取路径，
+  // 实际文件由 registry.ts 模块在写入时自动创建
+}

package/src/utils/platform.ts

@@ -0,0 +1,139 @@
+/**
+ * =============================================================================
+ * SkillMarket 平台检测模块
+ * =============================================================================
+ * 
+ * 本模块负责检测当前运行的环境是哪个 AI 编程工具平台。
+ * 通过检查环境变量来判断平台类型。
+ * 
+ * 支持的平台:
+ * - Cursor IDE
+ * - Visual Studio Code
+ * - OpenAI Codex
+ * - OpenCode
+ * - Claude Code
+ * - Antigravity
+ * 
+ * @module utils/platform
+ */
+
+// -----------------------------------------------------------------------------
+// 导入依赖
+// -----------------------------------------------------------------------------
+
+import { PLATFORMS } from '../constants.js';
+
+// -----------------------------------------------------------------------------
+// 类型定义
+// -----------------------------------------------------------------------------
+
+/**
+ * 平台类型
+ * 
+ * 从 PLATFORMS 常量推断出的联合类型，
+ * 表示所有支持的平台
+ * 
+ * @typedef {typeof PLATFORMS[number]} Platform
+ */
+export type Platform = typeof PLATFORMS[number];
+
+// -----------------------------------------------------------------------------
+// 平台检测函数
+// -----------------------------------------------------------------------------
+
+/**
+ * 检测当前运行环境所属的平台
+ * 
+ * 通过检查环境变量来判断当前运行在哪个 AI 编程工具中：
+ * 
+ * | 环境变量 | 平台 |
+ * |---------|------|
+ * | OPENCODE | opencode |
+ * | CURSOR | cursor |
+ * | VSCODE | vscode |
+ * | CLAUDE_CODE | claude |
+ * | ANTIGRAVITY | antigravity |
+ * | (默认) | codex |
+ * 
+ * @returns {Platform} 检测到的平台标识符
+ * 
+ * @example
+ * // 在 Cursor 中运行
+ * const platform = detectPlatform();
+ * console.log(platform); // 'cursor'
+ * 
+ * // 在 OpenCode 中运行
+ * const platform = detectPlatform();
+ * console.log(platform); // 'opencode'
+ */
+export function detectPlatform(): Platform {
+  // 按优先级检查环境变量
+  // 一旦找到匹配就立即返回
+  
+  // OpenCode 环境检测
+  if (process.env.OPENCODE) return 'opencode';
+  
+  // Cursor 环境检测
+  if (process.env.CURSOR) return 'cursor';
+  
+  // VSCode 环境检测
+  if (process.env.VSCODE) return 'vscode';
+  
+  // Claude Code 环境检测
+  if (process.env.CLAUDE_CODE) return 'claude';
+  
+  // Antigravity 环境检测
+  if (process.env.ANTIGRAVITY) return 'antigravity';
+  
+  // 默认返回 codex（作为通用 fallback）
+  return 'codex';
+}
+
+/**
+ * 验证平台名称是否有效
+ * 
+ * 使用类型守卫（Type Guard）模式，
+ * 可以在运行时验证字符串是否是有效的平台标识符
+ * 
+ * @param {string} name - 待验证的平台名称
+ * @returns {boolean} 如果是有效平台返回 true，否则返回 false
+ * 
+ * @example
+ * if (isValidPlatform('opencode')) {
+ *   // 这里 TypeScript 知道 name 的类型收窄为 Platform
+ *   console.log(`Valid platform: ${name}`);
+ * }
+ */
+export function isValidPlatform(name: string): name is Platform {
+  // Array.includes 需要类型断言，因为我们使用 as const 定义的数组
+  return PLATFORMS.includes(name as Platform);
+}
+
+/**
+ * 从用户输入获取平台类型
+ * 
+ * 将用户输入转换为有效的 Platform 类型，
+ * 如果输入无效则返回 null
+ * 
+ * @param {string} name - 用户输入的平台名称
+ * @returns {Platform | null} 有效的平台或 null
+ * 
+ * @example
+ * const platform = getPlatformFromInput('OpenCode');
+ * // 返回 'opencode'（小写化）
+ * 
+ * const invalid = getPlatformFromInput('unknown');
+ * // 返回 null
+ */
+export function getPlatformFromInput(name: string): Platform | null {
+  // 先转为小写，再验证是否有效
+  const lowerName = name.toLowerCase();
+  
+  // 如果是有效平台，返回小写版本
+  if (isValidPlatform(lowerName)) {
+    return lowerName as Platform;
+  }
+  
+  // 无效输入返回 null
+  return null;
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  }
+}

package/tsup.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  banner: {
+    /**
+     * 添加 shebang 到编译后的输出
+     * 
+     * 注意: tsup 的 banner 选项会在模块内容前添加字符串，
+     * 这里用 JSON 格式传递以确保正确处理
+     */
+    js: '#!/usr/bin/env node'
+  },
+  /**
+   * 禁用 shims 以避免潜在的兼容性问题
+   * shims 会自动为某些 Node.js 模块提供垫片，
+   * 但可能与我们的场景不兼容
+   */
+  shims: false
+});