@ai-setting/roy-agent-cli 1.3.15 → 1.3.17

package/dist/core/src/env/skill/parser.d.ts

@@ -0,0 +1,10 @@
+import type { SkillEntry, SkillSource } from "./types";
+/**
+ * 解析 frontmatter 文本
+ */
+export declare function parseFrontmatter(text: string): Record<string, string>;
+/**
+ * 解析 SKILL.md 文件
+ */
+export declare function parseSkillFile(filePath: string, source: SkillSource): Promise<SkillEntry | null>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/core/src/env/skill/parser.js

@@ -0,0 +1,64 @@
+import fs from "fs/promises";
+import { createLogger } from "../log-trace/logger.js";
+const logger = createLogger("skill-parser");
+/**
+ * 解析 frontmatter 文本
+ */
+export function parseFrontmatter(text) {
+    const result = {};
+    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, source) {
+    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;
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/core/src/env/skill/parser.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parser.test.d.ts.map

package/dist/core/src/env/skill/parser.test.js

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs/promises";
+import path from "path";
+import { parseFrontmatter, parseSkillFile } from "./parser.js";
+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();
+        });
+    });
+});
+//# sourceMappingURL=parser.test.js.map

package/dist/core/src/env/skill/scanner.d.ts

@@ -0,0 +1,26 @@
+import type { SkillConfig, SkillEntry } from "./types";
+/**
+ * Skill 扫描器
+ */
+export declare class SkillScanner {
+    private config;
+    private skillsMap;
+    constructor(config: SkillConfig);
+    /**
+     * 扫描所有 skillPaths 并加载 skills
+     */
+    scan(): Promise<Map<string, SkillEntry>>;
+    /**
+     * 扫描单个路径
+     */
+    private scanPath;
+    /**
+     * 处理单个 SKILL.md 文件
+     */
+    private processFile;
+    /**
+     * 获取扫描结果
+     */
+    getSkills(): Map<string, SkillEntry>;
+}
+//# sourceMappingURL=scanner.d.ts.map

package/dist/core/src/env/skill/scanner.js

@@ -0,0 +1,98 @@
+import fs from "fs/promises";
+import path from "path";
+import { glob } from "glob";
+import { createLogger } from "../log-trace/logger.js";
+import { parseSkillFile } from "./parser.js";
+import { getSourcePriority } from "./config.js";
+const logger = createLogger("skill-scanner");
+/**
+ * 展开路径（支持 ~ 展开）
+ */
+function expandPath(inputPath) {
+    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) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Skill 扫描器
+ */
+export class SkillScanner {
+    config;
+    skillsMap;
+    constructor(config) {
+        this.config = config;
+        this.skillsMap = new Map();
+    }
+    /**
+     * 扫描所有 skillPaths 并加载 skills
+     */
+    async scan() {
+        this.skillsMap.clear();
+        for (const skillPath of this.config.skillPaths) {
+            await this.scanPath(skillPath);
+        }
+        return this.skillsMap;
+    }
+    /**
+     * 扫描单个路径
+     */
+    async scanPath(skillPath) {
+        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 文件
+     */
+    async processFile(filePath, source) {
+        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() {
+        return this.skillsMap;
+    }
+}
+//# sourceMappingURL=scanner.js.map

package/dist/core/src/env/skill/scanner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scanner.test.d.ts.map

package/dist/core/src/env/skill/scanner.test.js

@@ -0,0 +1,166 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs/promises";
+import path from "path";
+import { SkillScanner } from "./scanner.js";
+/**
+ * Helper: Build glob pattern using the same logic as scanner
+ * This mimics the Windows behavior to test cross-platform compatibility
+ */
+function buildGlobPattern(expandedPath, recursive) {
+    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 = {
+        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");
+        });
+    });
+});
+//# sourceMappingURL=scanner.test.js.map

package/dist/core/src/env/skill/skill-component.d.ts

@@ -0,0 +1,90 @@
+import { BaseComponent, type ComponentConfig } from "../component";
+import type { SkillConfig, SkillEntry, SkillListItem } from "./types";
+import type { ConfigComponent } from "../../config/config-component";
+/**
+ * SkillComponent 配置选项（通过 options 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface SkillComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "SKILL"） */
+    envPrefix?: string;
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<SkillConfig>;
+}
+export declare class SkillComponent extends BaseComponent {
+    name: string;
+    version: string;
+    private config;
+    private toolComponent?;
+    private scanner;
+    private skillsMap;
+    private configComponent?;
+    private configWatcher?;
+    init(config?: ComponentConfig): Promise<void>;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. Defaults - 默认值（最低）
+     * 2. FileSource - 从配置文件加载
+     * 3. EnvSource - 从环境变量加载
+     * 4. config 对象 - 直接传入的配置（最高）
+     */
+    private registerConfig;
+    /**
+     * 构建最终配置对象
+     */
+    private buildConfig;
+    /**
+     * 将配置对象展平为点号路径
+     */
+    private flattenConfig;
+    /**
+     * 注册配置热更新监听
+     */
+    private registerConfigWatcher;
+    /**
+     * 处理配置变更
+     */
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * 获取指定 skill
+     */
+    getSkill(name: string): SkillEntry | undefined;
+    /**
+     * 获取所有 skill 列表（用于 tool description）
+     */
+    getSkillList(): SkillListItem[];
+    /**
+     * 检查 skill 是否存在
+     */
+    hasSkill(name: string): boolean;
+    /**
+     * 获取所有 skills
+     */
+    getAllSkills(): SkillEntry[];
+    /**
+     * 扫描所有 skillPaths 并加载 skills
+     */
+    scanSkills(): Promise<void>;
+    /**
+     * 重新扫描并更新 Tool
+     */
+    reload(): Promise<void>;
+    private registerTool;
+}
+//# sourceMappingURL=skill-component.d.ts.map