@ai-setting/roy-agent-core 1.0.0

package/src/env/skill/config.ts

@@ -0,0 +1,39 @@
+import path from "path";
+import os from "os";
+import { type SkillConfig } from "./types";
+
+/**
+ * 默认配置
+ */
+export const DEFAULT_SKILL_CONFIG: SkillConfig = {
+  skillPaths: [
+    // 用户路径 (~/.config/roy-agent/skills/)
+    {
+      type: "user",
+      path: path.join(os.homedir(), ".config", "roy-agent", "skills"),
+    },
+    // 项目路径 (.roy/skills/)
+    {
+      type: "project",
+      path: ".roy/skills",
+    },
+  ],
+  recursive: true,
+  cacheEnabled: true,
+};
+
+/**
+ * 优先级映射（后面的优先级更高）
+ */
+export const SOURCE_PRIORITY: Record<string, number> = {
+  "built-in": 0,
+  "user": 1,
+  "project": 2,
+};
+
+/**
+ * 获取来源优先级
+ */
+export function getSourcePriority(source: string): number {
+  return SOURCE_PRIORITY[source] ?? 0;
+}

package/src/env/skill/index.ts

@@ -0,0 +1,6 @@
+export { SkillComponent } from "./skill-component";
+export * from "./types";
+export * from "./config";
+export * from "./parser";
+export * from "./scanner";
+export * from "./tool";

package/src/env/skill/parser.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "fs/promises";
+import path from "path";
+import { parseFrontmatter, parseSkillFile } from "./parser";
+import type { SkillSource } from "./types";
+
+describe("parser", () => {
+  const testDir = path.join(__dirname, "__test_temp__");
+
+  beforeEach(async () => {
+    await fs.mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    try {
+      await fs.rm(testDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  describe("parseFrontmatter", () => {
+    it("should parse simple frontmatter with quoted values", () => {
+      const text = `name: brainstorming
+description: "Use before any creative work..."`;
+      
+      const result = parseFrontmatter(text);
+      
+      expect(result.name).toBe("brainstorming");
+      expect(result.description).toBe("Use before any creative work...");
+    });
+
+    it("should parse frontmatter with unquoted values", () => {
+      const text = `name: tdd
+description: Use when implementing features`;
+      
+      const result = parseFrontmatter(text);
+      
+      expect(result.name).toBe("tdd");
+      expect(result.description).toBe("Use when implementing features");
+    });
+
+    it("should handle empty text", () => {
+      const result = parseFrontmatter("");
+      
+      expect(Object.keys(result).length).toBe(0);
+    });
+  });
+
+  describe("parseSkillFile", () => {
+    it("should parse valid SKILL.md file", async () => {
+      const filePath = path.join(testDir, "test-skill.md");
+      const content = `---
+name: test-skill
+description: A test skill for unit testing
+---
+# Test Skill
+
+This is the skill content.`;
+      
+      await fs.writeFile(filePath, content);
+      const result = await parseSkillFile(filePath, "user");
+      
+      expect(result).not.toBeNull();
+      expect(result!.name).toBe("test-skill");
+      expect(result!.description).toBe("A test skill for unit testing");
+      expect(result!.source).toBe("user");
+      expect(result!.content).toContain("# Test Skill");
+      expect(result!.content).not.toContain("---");
+    });
+
+    it("should return null for missing frontmatter", async () => {
+      const filePath = path.join(testDir, "no-frontmatter.md");
+      const content = `# No Frontmatter
+
+This file has no frontmatter.`;
+      
+      await fs.writeFile(filePath, content);
+      const result = await parseSkillFile(filePath, "user");
+      
+      expect(result).toBeNull();
+    });
+
+    it("should return null for missing name", async () => {
+      const filePath = path.join(testDir, "no-name.md");
+      const content = `---
+description: Has description but no name
+---
+Content`;
+      
+      await fs.writeFile(filePath, content);
+      const result = await parseSkillFile(filePath, "user");
+      
+      expect(result).toBeNull();
+    });
+
+    it("should return null for missing description", async () => {
+      const filePath = path.join(testDir, "no-description.md");
+      const content = `---
+name: skill-without-description
+---
+Content`;
+      
+      await fs.writeFile(filePath, content);
+      const result = await parseSkillFile(filePath, "user");
+      
+      expect(result).toBeNull();
+    });
+
+    it("should handle non-existent file", async () => {
+      const result = await parseSkillFile("/non/existent/path.md", "user");
+      
+      expect(result).toBeNull();
+    });
+  });
+});

package/src/env/skill/parser.ts

@@ -0,0 +1,77 @@
+import fs from "fs/promises";
+import { createLogger } from "../log-trace/logger";
+import type { SkillEntry, SkillSource } from "./types";
+
+const logger = createLogger("skill-parser");
+
+/**
+ * 解析 frontmatter 文本
+ */
+export function parseFrontmatter(text: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  const lines = text.split("\n");
+
+  for (const line of lines) {
+    // 匹配 key: value 格式
+    const match = line.match(/^(\w+):\s*"?(.+?)"?\s*$/);
+    if (match) {
+      const key = match[1];
+      let value = match[2];
+      // 移除首尾引号
+      if (value.startsWith('"') && value.endsWith('"')) {
+        value = value.slice(1, -1);
+      }
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 解析 SKILL.md 文件
+ */
+export async function parseSkillFile(
+  filePath: string,
+  source: SkillSource
+): Promise<SkillEntry | null> {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+
+    // 匹配 frontmatter: --- ... ---
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n?/);
+    if (!frontmatterMatch) {
+      logger.warn(`[SkillParser] Missing frontmatter in: ${filePath}`);
+      return null;
+    }
+
+    const frontmatter = parseFrontmatter(frontmatterMatch[1]);
+    const name = frontmatter.name;
+    const description = frontmatter.description;
+
+    if (!name) {
+      logger.warn(`[SkillParser] Missing name in frontmatter: ${filePath}`);
+      return null;
+    }
+
+    if (!description) {
+      logger.warn(`[SkillParser] Missing description in frontmatter: ${filePath}`);
+      return null;
+    }
+
+    // 移除 frontmatter 获取实际内容
+    const actualContent = content.replace(/^---\n[\s\S]*?\n---\n?/, "");
+
+    return {
+      name,
+      description,
+      filePath,
+      content: actualContent,
+      source,
+      loadedAt: Date.now(),
+    };
+  } catch (error) {
+    logger.error(`[SkillParser] Failed to parse file: ${filePath}`, error);
+    return null;
+  }
+}

package/src/env/skill/scanner.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs/promises";
+import path from "path";
+import { SkillScanner } from "./scanner";
+import type { SkillConfig } from "./types";
+
+/**
+ * Helper: Build glob pattern using the same logic as scanner
+ * This mimics the Windows behavior to test cross-platform compatibility
+ */
+function buildGlobPattern(expandedPath: string, recursive: boolean): string {
+  const sep = "/";
+  const basePattern = expandedPath.replace(/\\/g, "/");
+  return recursive
+    ? `${basePattern}${sep}**${sep}SKILL.md`
+    : `${basePattern}${sep}SKILL.md`;
+}
+
+describe("SkillScanner", () => {
+  const testBaseDir = path.join(__dirname, "__test_scanner__");
+  const userSkillsDir = path.join(testBaseDir, "user", "skills");
+  const projectSkillsDir = path.join(testBaseDir, "project", "skills");
+
+  const config: SkillConfig = {
+    skillPaths: [
+      { type: "user", path: userSkillsDir },
+      { type: "project", path: projectSkillsDir },
+    ],
+    recursive: true,
+    cacheEnabled: true,
+  };
+
+  beforeEach(async () => {
+    // 创建测试目录结构
+    await fs.mkdir(path.join(userSkillsDir, "brainstorming"), { recursive: true });
+    await fs.mkdir(path.join(projectSkillsDir, "tdd"), { recursive: true });
+    
+    // 写入测试 SKILL.md 文件
+    await fs.writeFile(
+      path.join(userSkillsDir, "brainstorming", "SKILL.md"),
+      `---
+name: brainstorming
+description: Use before any creative work
+---
+# Brainstorming Skill
+
+This is the brainstorming skill content.`
+    );
+
+    await fs.writeFile(
+      path.join(projectSkillsDir, "tdd", "SKILL.md"),
+      `---
+name: tdd
+description: Use when implementing any feature
+---
+# TDD Skill
+
+This is the TDD skill content.`
+    );
+  });
+
+  afterEach(async () => {
+    try {
+      await fs.rm(testBaseDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  describe("expandPath", () => {
+    it("should expand ~ to home directory", async () => {
+      const scanner = new SkillScanner({
+        ...config,
+        skillPaths: [{ type: "user", path: "~/test-skills" }],
+      });
+      
+      const skills = await scanner.scan();
+      expect(skills.size).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe("glob pattern generation", () => {
+    it("should use forward slashes for glob patterns (Windows compatibility)", () => {
+      // Simulate Windows path with backslashes
+      const windowsPath = "C:\\Users\\test\\skills";
+      
+      const patternRecursive = buildGlobPattern(windowsPath, true);
+      const patternNonRecursive = buildGlobPattern(windowsPath, false);
+      
+      // Pattern must use forward slashes for glob compatibility
+      expect(patternRecursive).toBe("C:/Users/test/skills/**/SKILL.md");
+      expect(patternNonRecursive).toBe("C:/Users/test/skills/SKILL.md");
+      
+      // Must NOT contain backslashes (glob doesn't support them)
+      expect(patternRecursive).not.toContain("\\");
+      expect(patternNonRecursive).not.toContain("\\");
+    });
+
+    it("should preserve forward slashes in Unix paths", () => {
+      const unixPath = "/home/user/skills";
+      
+      const patternRecursive = buildGlobPattern(unixPath, true);
+      const patternNonRecursive = buildGlobPattern(unixPath, false);
+      
+      expect(patternRecursive).toBe("/home/user/skills/**/SKILL.md");
+      expect(patternNonRecursive).toBe("/home/user/skills/SKILL.md");
+    });
+
+    it("should normalize mixed slashes to forward slashes", () => {
+      const mixedPath = "/home\\user/skills\\nested";
+      
+      const patternRecursive = buildGlobPattern(mixedPath, true);
+      
+      // All backslashes should be converted to forward slashes
+      expect(patternRecursive).not.toContain("\\");
+      expect(patternRecursive).toContain("/");
+    });
+
+    it("should generate patterns without backslashes for Unix paths", async () => {
+      // Test with real Unix path
+      const scanner = new SkillScanner({
+        ...config,
+        skillPaths: [{ type: "user", path: userSkillsDir }],
+        recursive: true,
+        cacheEnabled: false,
+      });
+      
+      // The scanner should find skills without issues
+      const skills = await scanner.scan();
+      expect(skills.size).toBeGreaterThan(0);
+      
+      // Verify no backslashes in resulting paths
+      for (const skill of skills.values()) {
+        expect(skill.filePath).not.toContain("\\");
+        expect(skill.filePath).toContain("/");
+      }
+    });
+  });
+
+  describe("scan", () => {
+    it("should scan directory and find SKILL.md files", async () => {
+      const scanner = new SkillScanner(config);
+      const skills = await scanner.scan();
+      
+      expect(skills.size).toBe(2);
+    });
+
+    it("should load skill with correct properties", async () => {
+      const scanner = new SkillScanner(config);
+      const skills = await scanner.scan();
+      
+      const brainstorming = skills.get("brainstorming");
+      expect(brainstorming).toBeDefined();
+      expect(brainstorming!.name).toBe("brainstorming");
+      expect(brainstorming!.description).toBe("Use before any creative work");
+      expect(brainstorming!.source).toBe("user");
+      expect(brainstorming!.content).toContain("Brainstorming Skill");
+    });
+
+    it("should skip non-existing paths gracefully", async () => {
+      const scanner = new SkillScanner({
+        ...config,
+        skillPaths: [
+          { type: "user", path: "/non/existent/path" },
+        ],
+      });
+      
+      const skills = await scanner.scan();
+      expect(skills.size).toBe(0);
+    });
+
+    it("should handle multiple SKILL.md in subdirectories", async () => {
+      // 添加子目录中的 skill
+      await fs.mkdir(path.join(userSkillsDir, "parent", "child"), { recursive: true });
+      await fs.writeFile(
+        path.join(userSkillsDir, "parent", "child", "SKILL.md"),
+        `---
+name: nested-skill
+description: A skill in a nested directory
+---
+# Nested Skill Content`
+      );
+
+      const scanner = new SkillScanner(config);
+      const skills = await scanner.scan();
+      
+      expect(skills.get("nested-skill")).toBeDefined();
+    });
+
+    it("should deduplicate by name with higher priority source", async () => {
+      // 在 project 目录添加同名 skill（应该覆盖 user 目录的）
+      await fs.mkdir(path.join(projectSkillsDir, "brainstorming"), { recursive: true });
+      await fs.writeFile(
+        path.join(projectSkillsDir, "brainstorming", "SKILL.md"),
+        `---
+name: brainstorming
+description: Project version of brainstorming
+---
+# Project Brainstorming`
+      );
+
+      const scanner = new SkillScanner(config);
+      const skills = await scanner.scan();
+      
+      // project 优先级高于 user
+      const brainstorming = skills.get("brainstorming");
+      expect(brainstorming!.source).toBe("project");
+      expect(brainstorming!.description).toBe("Project version of brainstorming");
+    });
+  });
+});

package/src/env/skill/scanner.ts

@@ -0,0 +1,119 @@
+import fs from "fs/promises";
+import path from "path";
+import { glob } from "glob";
+import { createLogger } from "../log-trace/logger";
+import { parseSkillFile } from "./parser";
+import { getSourcePriority } from "./config";
+import type { SkillConfig, SkillEntry, SkillPath, SkillSource } from "./types";
+
+const logger = createLogger("skill-scanner");
+
+/**
+ * 展开路径（支持 ~ 展开）
+ */
+function expandPath(inputPath: string): string {
+  if (inputPath.startsWith("~/")) {
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    return path.join(home, inputPath.slice(2));
+  }
+  return path.resolve(inputPath);
+}
+
+/**
+ * 检查路径是否存在
+ */
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Skill 扫描器
+ */
+export class SkillScanner {
+  private config: SkillConfig;
+  private skillsMap: Map<string, SkillEntry>;
+
+  constructor(config: SkillConfig) {
+    this.config = config;
+    this.skillsMap = new Map();
+  }
+
+  /**
+   * 扫描所有 skillPaths 并加载 skills
+   */
+  async scan(): Promise<Map<string, SkillEntry>> {
+    this.skillsMap.clear();
+
+    for (const skillPath of this.config.skillPaths) {
+      await this.scanPath(skillPath);
+    }
+
+    return this.skillsMap;
+  }
+
+  /**
+   * 扫描单个路径
+   */
+  private async scanPath(skillPath: SkillPath): Promise<void> {
+    const expandedPath = expandPath(skillPath.path);
+
+    if (!(await pathExists(expandedPath))) {
+      logger.info(`[SkillScanner] Path not found, skipping: ${expandedPath}`);
+      return;
+    }
+
+    logger.info(`[SkillScanner] Scanning: ${expandedPath}`);
+
+    // 使用正斜杠构建 glob pattern，确保 Windows 兼容性
+    // glob 库需要正斜杠路径，不能使用 path.join（Windows 会用反斜杠）
+    const sep = "/";
+    const basePattern = expandedPath.replace(/\\/g, "/");
+    const pattern = this.config.recursive
+      ? `${basePattern}${sep}**${sep}SKILL.md`
+      : `${basePattern}${sep}SKILL.md`;
+
+    const files = await glob(pattern, {
+      absolute: true,
+      ignore: ["**/node_modules/**"],
+    });
+
+    logger.info(`[SkillScanner] Found ${files.length} SKILL.md files`);
+
+    for (const filePath of files) {
+      await this.processFile(filePath, skillPath.type);
+    }
+  }
+
+  /**
+   * 处理单个 SKILL.md 文件
+   */
+  private async processFile(
+    filePath: string,
+    source: SkillSource
+  ): Promise<void> {
+    const entry = await parseSkillFile(filePath, source);
+
+    if (!entry) {
+      return;
+    }
+
+    // 按优先级合并去重
+    const existing = this.skillsMap.get(entry.name);
+    if (!existing || getSourcePriority(source) > getSourcePriority(existing.source)) {
+      this.skillsMap.set(entry.name, entry);
+      logger.debug(`[SkillScanner] Loaded skill: ${entry.name} (${source})`);
+    }
+  }
+
+  /**
+   * 获取扫描结果
+   */
+  getSkills(): Map<string, SkillEntry> {
+    return this.skillsMap;
+  }
+}