Skills 与 Plugins

// Skill 文件结构 (.claude/skills/my-skill.md)
// ---
// name: my-custom-skill
// description: 自定义代码审查 Skill
// hooks:
//   PreToolUse:
//     - tool: Write
//       match: "**/*.ts"
//   PostToolUse:
//     - tool: Bash
// ---
// 你是一个代码审查专家。在写入 TypeScript 文件前...

interface SkillDefinition {
  name: string;
  description: string;
  content: string;       // Markdown 正文 = 提示词
  hooks?: {
    PreToolUse?: HookConfig[];
    PostToolUse?: HookConfig[];
  };
  source: "bundled" | "user" | "mcp" | "plugin";
}

interface HookConfig {
  tool: string;         // 匹配的工具名
  match?: string;       // 文件模式（glob）
}

// loadSkillsDir.ts: 从磁盘加载用户 Skills
async function loadSkillsDir(
  skillsPath: string
): Promise<SkillDefinition[]> {
  const files = await glob(skillsPath + "/**/*.md");
  const skills: SkillDefinition[] = [];

  for (const file of files) {
    const raw = await readFile(file, "utf-8");
    const { frontmatter, body } = parseFrontmatter(raw);

    skills.push({
      name: frontmatter.name || basename(file, ".md"),
      description: frontmatter.description || "",
      content: body,
      hooks: frontmatter.hooks,
      source: "user"
    });
  }

  return skills;
}

// bundledSkills.ts: 内置 Skills 注册表
const bundledSkills: SkillDefinition[] = [
  {
    name: "simplify",
    description: "审查变更代码的质量和效率",
    content: "检查代码复用性、质量和效率...",
    source: "bundled"
  },
  {
    name: "loop",
    description: "以固定间隔循环执行命令",
    content: "按照指定的时间间隔重复运行...",
    source: "bundled"
  }
  // ... 15+ 更多内置 Skills
];

// SkillTool: 执行 Skill 的核心工具
class SkillTool {
  private registry: Map<string, SkillDefinition>;

  async execute(input: {
    skill: string;
    args?: string;
  }): Promise<SkillResult> {
    // 按名称或完全限定名查找 Skill
    const skill = this.findSkill(input.skill);
    if (!skill) {
      throw new Error(
        "Skill not found: " + input.skill
      );
    }

    // 将 Skill 内容注入子对话
    const subConversation = createSubConversation({
      systemPrompt: skill.content,
      userMessage: input.args || "",
      tools: getAvailableTools()
    });

    // 执行子对话
    return await runSubConversation(subConversation);
  }

  private findSkill(name: string): SkillDefinition | undefined {
    // 完全限定名: "plugin:skill-name"
    if (name.includes(":")) {
      return this.registry.get(name);
    }
    // 短名称匹配
    return this.registry.get(name)
      || [...this.registry.values()].find(
        s => s.name === name
      );
  }
}

// pluginLoader.ts: 插件加载与缓存
class PluginLoader {
  private cache = new Map<string, Plugin>();

  async loadPlugin(
    pluginId: string
  ): Promise<Plugin> {
    // 检查缓存
    if (this.cache.has(pluginId)) {
      return this.cache.get(pluginId)!;
    }

    // 从 marketplace 或本地加载
    const manifest = await this.fetchManifest(pluginId);

    // 黑名单检查
    if (isBlocklisted(pluginId, manifest.version)) {
      throw new Error(
        "Plugin " + pluginId + " is blocklisted"
      );
    }

    const plugin = await this.instantiate(manifest);
    this.cache.set(pluginId, plugin);
    return plugin;
  }
}

// installedPluginsManager.ts: 版本化管理
class InstalledPluginsManager {
  private plugins: Map<string, InstalledPlugin>;

  async install(
    pluginId: string,
    version: string
  ): Promise<void> {
    const plugin = await PluginLoader.loadPlugin(
      pluginId
    );
    this.plugins.set(pluginId, {
      ...plugin,
      installedVersion: version,
      installedAt: new Date()
    });
  }

  async checkUpdates(): Promise<UpdateInfo[]> {
    const updates: UpdateInfo[] = [];
    for (const [id, plugin] of this.plugins) {
      const latest = await fetchLatestVersion(id);
      if (latest !== plugin.installedVersion) {
        updates.push({
          pluginId: id,
          current: plugin.installedVersion,
          latest
        });
      }
    }
    return updates;
  }
}

// commands/ 目录: Slash 命令定义
interface SlashCommand {
  name: string;           // 命令名（不含 /）
  description: string;
  aliases?: string[];     // 别名
  category: CommandCategory;
  execute: (
    args: string,
    context: CommandContext
  ) => Promise<void>;
}

type CommandCategory =
  | "git"
  | "session"
  | "debug"
  | "config"
  | "project";

// 示例: /commit 命令
const commitCommand: SlashCommand = {
  name: "commit",
  description: "分析变更并创建 Git 提交",
  category: "git",
  execute: async (args, ctx) => {
    // 触发 commit Skill
    await ctx.skillTool.execute({
      skill: "commit",
      args: args
    });
  }
};

// 命令路由器
class CommandRouter {
  private commands = new Map<string, SlashCommand>();

  register(cmd: SlashCommand): void {
    this.commands.set(cmd.name, cmd);
    // 注册别名
    if (cmd.aliases) {
      for (const alias of cmd.aliases) {
        this.commands.set(alias, cmd);
      }
    }
  }

  async route(
    input: string,
    ctx: CommandContext
  ): Promise<boolean> {
    if (!input.startsWith("/")) return false;

    const parts = input.slice(1).split(" ");
    const cmdName = parts[0];
    const args = parts.slice(1).join(" ");

    const cmd = this.commands.get(cmdName);
    if (!cmd) {
      // 尝试模糊匹配
      const fuzzy = this.fuzzyMatch(cmdName);
      if (fuzzy) {
        await fuzzy.execute(args, ctx);
        return true;
      }
      return false;
    }

    await cmd.execute(args, ctx);
    return true;
  }

  private fuzzyMatch(
    name: string
  ): SlashCommand | undefined {
    const candidates = [...this.commands.entries()]
      .filter(([k]) => k.startsWith(name));
    return candidates.length === 1
      ? candidates[0][1]
      : undefined;
  }

  listByCategory(
    cat: CommandCategory
  ): SlashCommand[] {
    return [...this.commands.values()]
      .filter(c => c.category === cat);
  }
}