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

package/dist/core/src/env/skill/skill-component.js

@@ -0,0 +1,266 @@
+import { BaseComponent } from "../component.js";
+import { createLogger } from "../log-trace/logger.js";
+import { SkillScanner } from "./scanner.js";
+import { createSkillTool } from "./tool/index.js";
+import { DEFAULT_SKILL_CONFIG } from "./config.js";
+import { SKILL_CONFIG_REGISTRATION, SKILL_DEFAULTS } from "./skill-config-registration.js";
+import { envKeyToConfigKey } from "../../config/env-key.js";
+const logger = createLogger("skill");
+export class SkillComponent extends BaseComponent {
+    name = "skill";
+    version = "1.0.0";
+    config;
+    toolComponent;
+    scanner;
+    skillsMap = new Map();
+    configComponent;
+    configWatcher;
+    // ========================================================================
+    // Lifecycle
+    // ========================================================================
+    async init(config) {
+        await super.init(config);
+        // 从 options 获取 ConfigComponent
+        const options = config?.options;
+        if (!options?.configComponent) {
+            throw new Error("ConfigComponent is required for SkillComponent initialization");
+        }
+        this.configComponent = options.configComponent;
+        await this.registerConfig(options);
+        // 创建扫描器
+        this.scanner = new SkillScanner(this.config);
+        logger.info("[SkillComponent] Initialized");
+    }
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. Defaults - 默认值（最低）
+     * 2. FileSource - 从配置文件加载
+     * 3. EnvSource - 从环境变量加载
+     * 4. config 对象 - 直接传入的配置（最高）
+     */
+    async registerConfig(options) {
+        const configComponent = this.configComponent;
+        if (!configComponent)
+            return;
+        const { configPath, envPrefix, config } = options;
+        const prefix = envPrefix ?? "SKILL";
+        // 1. 使用 registerComponent 注册配置结构（keys 和 sources，不含 defaults）
+        configComponent.registerComponent(SKILL_CONFIG_REGISTRATION);
+        // 2. 注册 FileSource（如果提供了 configPath）
+        if (configPath) {
+            configComponent.registerSource({
+                type: "file",
+                relativePath: configPath,
+                optional: true,
+                watch: false
+            });
+        }
+        // 3. 注册 EnvSource
+        configComponent.registerSource({
+            type: "env",
+            envPrefix: prefix,
+            priority: 20,
+            watch: false
+        });
+        // 4. 从 sources 加载配置（FileSource 和 EnvSource）
+        await configComponent.load("skill");
+        // 5. 后备方案：直接读取环境变量（确保所有环境变量都被处理）
+        for (const envKey of Object.keys(process.env)) {
+            const configKey = envKeyToConfigKey(envKey, prefix, "skill");
+            if (!configKey)
+                continue;
+            const value = process.env[envKey];
+            if (value !== undefined) {
+                await configComponent.set(configKey, value);
+            }
+        }
+        // 6. 设置默认值（只有当配置不存在时）
+        for (const [key, value] of Object.entries(SKILL_DEFAULTS)) {
+            if (configComponent.get(key) === undefined) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 7. 直接配置对象（最高优先级）
+        if (config) {
+            const flatConfig = this.flattenConfig(config);
+            for (const [key, value] of Object.entries(flatConfig)) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 8. 注册配置热更新监听
+        this.registerConfigWatcher(configComponent);
+        // 9. 解析最终配置
+        this.buildConfig(configComponent);
+    }
+    /**
+     * 构建最终配置对象
+     */
+    buildConfig(configComponent) {
+        // 解析基本配置
+        const recursive = configComponent.get("skill.recursive") ?? true;
+        const cacheEnabled = configComponent.get("skill.cacheEnabled") ?? true;
+        // 从配置获取 skillPaths（需要解析 JSON 数组）
+        const skillPathsConfig = configComponent.get("skill.skillPaths");
+        let skillPaths = [];
+        if (Array.isArray(skillPathsConfig)) {
+            skillPaths = skillPathsConfig;
+        }
+        else if (typeof skillPathsConfig === "string") {
+            try {
+                skillPaths = JSON.parse(skillPathsConfig);
+            }
+            catch {
+                // 解析失败，使用默认值
+                skillPaths = DEFAULT_SKILL_CONFIG.skillPaths;
+            }
+        }
+        // 如果没有配置，使用默认值
+        if (skillPaths.length === 0) {
+            skillPaths = DEFAULT_SKILL_CONFIG.skillPaths;
+        }
+        this.config = {
+            skillPaths: skillPaths,
+            recursive,
+            cacheEnabled,
+        };
+    }
+    /**
+     * 将配置对象展平为点号路径
+     */
+    flattenConfig(obj, prefix = "skill") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const fullKey = `${prefix}.${key}`;
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                Object.assign(result, this.flattenConfig(value, fullKey));
+            }
+            else {
+                result[fullKey] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * 注册配置热更新监听
+     */
+    registerConfigWatcher(configComponent) {
+        if (typeof configComponent.watch !== "function") {
+            return;
+        }
+        this.configWatcher = configComponent.watch("skill.*", (event) => {
+            this.onConfigChange(event);
+        });
+    }
+    /**
+     * 处理配置变更
+     */
+    onConfigChange(event) {
+        logger.info(`[SkillComponent] Config changed: ${event.key}`, {
+            oldValue: event.oldValue,
+            newValue: event.newValue
+        });
+        // 重新构建配置
+        if (this.configComponent) {
+            this.buildConfig(this.configComponent);
+        }
+    }
+    async start() {
+        await super.start();
+        // 获取 ToolComponent
+        this.toolComponent = this.env?.getComponent("tool");
+        if (!this.toolComponent) {
+            logger.warn("[SkillComponent] ToolComponent not found, skipping tool registration");
+            return;
+        }
+        // 扫描 skills
+        await this.scanSkills();
+        // 注册 SkillTool
+        await this.registerTool();
+        this.setStatus("running");
+        logger.info(`[SkillComponent] Started with ${this.skillsMap.size} skills`);
+    }
+    async stop() {
+        // 清理配置 watcher
+        if (this.configWatcher) {
+            this.configWatcher();
+            this.configWatcher = undefined;
+        }
+        // 取消注册 Tool
+        if (this.toolComponent) {
+            this.toolComponent.unregister("skill");
+        }
+        await super.stop();
+        logger.info("[SkillComponent] Stopped");
+    }
+    // ========================================================================
+    // Skill Access
+    // ========================================================================
+    /**
+     * 获取指定 skill
+     */
+    getSkill(name) {
+        return this.skillsMap.get(name);
+    }
+    /**
+     * 获取所有 skill 列表（用于 tool description）
+     */
+    getSkillList() {
+        return Array.from(this.skillsMap.values()).map((entry) => ({
+            name: entry.name,
+            description: entry.description,
+            source: entry.source,
+        }));
+    }
+    /**
+     * 检查 skill 是否存在
+     */
+    hasSkill(name) {
+        return this.skillsMap.has(name);
+    }
+    /**
+     * 获取所有 skills
+     */
+    getAllSkills() {
+        return Array.from(this.skillsMap.values());
+    }
+    // ========================================================================
+    // Scanning & Reload
+    // ========================================================================
+    /**
+     * 扫描所有 skillPaths 并加载 skills
+     */
+    async scanSkills() {
+        this.scanner = new SkillScanner(this.config);
+        this.skillsMap = await this.scanner.scan();
+        logger.info(`[SkillComponent] Scanned ${this.skillsMap.size} skills`);
+    }
+    /**
+     * 重新扫描并更新 Tool
+     */
+    async reload() {
+        if (!this.toolComponent) {
+            throw new Error("ToolComponent not available");
+        }
+        logger.info("[SkillComponent] Reloading skills...");
+        // 1. 取消注册旧的 SkillTool
+        this.toolComponent.unregister("skill");
+        // 2. 重新扫描 skills
+        await this.scanSkills();
+        // 3. 注册新的 SkillTool
+        await this.registerTool();
+        logger.info(`[SkillComponent] Reloaded ${this.skillsMap.size} skills`);
+    }
+    // ========================================================================
+    // Tool Registration
+    // ========================================================================
+    async registerTool() {
+        if (!this.toolComponent)
+            return;
+        const tool = createSkillTool(() => this.getSkillList(), (name) => this.getSkill(name));
+        this.toolComponent.register(tool);
+        logger.info("[SkillComponent] Registered SkillTool");
+    }
+}
+//# sourceMappingURL=skill-component.js.map

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

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

package/dist/core/src/env/skill/skill-component.test.js

@@ -0,0 +1,187 @@
+import { describe, it, expect, beforeEach, vi } from "bun:test";
+import { SkillComponent } from "./skill-component.js";
+import { ConfigComponent } from "../../config/config-component.js";
+describe("SkillComponent", () => {
+    let component;
+    let configComponent;
+    let mockToolComponent;
+    beforeEach(() => {
+        configComponent = new ConfigComponent();
+        component = new SkillComponent();
+        // 创建 mock ToolComponent
+        mockToolComponent = {
+            register: vi.fn(),
+            unregister: vi.fn(),
+        };
+    });
+    describe("init", () => {
+        it("should initialize with default config", async () => {
+            await component.init({
+                options: {
+                    configComponent,
+                },
+            });
+            expect(component.getStatus()).toBe("running");
+        });
+        it("should use custom config when provided", async () => {
+            await component.init({
+                options: {
+                    configComponent,
+                    config: {
+                        recursive: false,
+                    },
+                },
+            });
+            expect(component.getStatus()).toBe("running");
+        });
+    });
+    describe("start", () => {
+        it("should register SkillTool to ToolComponent", async () => {
+            // 创建一个假的 env
+            const mockEnv = {
+                getComponent: vi.fn((name) => {
+                    if (name === "tool")
+                        return mockToolComponent;
+                    return null;
+                }),
+            };
+            await component.init({
+                options: {
+                    configComponent,
+                },
+            });
+            component.env = mockEnv;
+            // Mock scanner
+            const mockScanner = {
+                scan: vi.fn().mockResolvedValue(new Map()),
+            };
+            component.scanner = mockScanner;
+            await component.start();
+            expect(mockToolComponent.register).toHaveBeenCalled();
+        });
+        it("should handle missing ToolComponent gracefully", async () => {
+            const mockEnv = {
+                getComponent: vi.fn(() => null),
+            };
+            await component.init({
+                options: {
+                    configComponent,
+                },
+            });
+            component.env = mockEnv;
+            const mockScanner = {
+                scan: vi.fn().mockResolvedValue(new Map()),
+            };
+            component.scanner = mockScanner;
+            await component.start();
+            expect(mockToolComponent.register).not.toHaveBeenCalled();
+        });
+    });
+    describe("getSkill", () => {
+        it("should return undefined for unknown skill", () => {
+            component.skillsMap = new Map();
+            const result = component.getSkill("non-existent");
+            expect(result).toBeUndefined();
+        });
+    });
+    describe("getSkillList", () => {
+        it("should return empty array when no skills", () => {
+            component.skillsMap = new Map();
+            const result = component.getSkillList();
+            expect(result).toEqual([]);
+        });
+        it("should return skills as list items", () => {
+            component.skillsMap = new Map([
+                ["brainstorming", {
+                        name: "brainstorming",
+                        description: "Test",
+                        source: "user",
+                        filePath: "/test/path.md",
+                        content: "# Test",
+                        loadedAt: Date.now(),
+                    }],
+            ]);
+            const result = component.getSkillList();
+            expect(result).toHaveLength(1);
+            expect(result[0].name).toBe("brainstorming");
+            expect(result[0].description).toBe("Test");
+            expect(result[0].source).toBe("user");
+        });
+    });
+    describe("hasSkill", () => {
+        it("should return true for existing skill", () => {
+            component.skillsMap = new Map([["brainstorming", {}]]);
+            expect(component.hasSkill("brainstorming")).toBe(true);
+        });
+        it("should return false for non-existing skill", () => {
+            component.skillsMap = new Map();
+            expect(component.hasSkill("non-existent")).toBe(false);
+        });
+    });
+    describe("getAllSkills", () => {
+        it("should return empty array when no skills", () => {
+            component.skillsMap = new Map();
+            const result = component.getAllSkills();
+            expect(result).toEqual([]);
+        });
+        it("should return all skills as array", () => {
+            const skill1 = { name: "brainstorming", description: "Test", source: "user", filePath: "/1", content: "#1", loadedAt: 1 };
+            const skill2 = { name: "tdd", description: "Test2", source: "project", filePath: "/2", content: "#2", loadedAt: 2 };
+            component.skillsMap = new Map([["brainstorming", skill1], ["tdd", skill2]]);
+            const result = component.getAllSkills();
+            expect(result).toHaveLength(2);
+        });
+    });
+    describe("reload", () => {
+        it("should unregister and re-register SkillTool", async () => {
+            const mockEnv = {
+                getComponent: vi.fn(() => mockToolComponent),
+            };
+            await component.init({
+                options: {
+                    configComponent,
+                },
+            });
+            component.env = mockEnv;
+            component.toolComponent = mockToolComponent;
+            const mockScanner = {
+                scan: vi.fn().mockResolvedValue(new Map()),
+            };
+            component.scanner = mockScanner;
+            component.skillsMap = new Map();
+            await component.reload();
+            expect(mockToolComponent.unregister).toHaveBeenCalledWith("skill");
+            expect(mockToolComponent.register).toHaveBeenCalled();
+        });
+        it("should throw error when ToolComponent not available", async () => {
+            const mockEnv = {
+                getComponent: vi.fn(() => null),
+            };
+            await component.init({
+                options: {
+                    configComponent,
+                },
+            });
+            component.env = mockEnv;
+            component.toolComponent = undefined;
+            await expect(component.reload()).rejects.toThrow("ToolComponent not available");
+        });
+    });
+    describe("stop", () => {
+        it("should unregister tool on stop", async () => {
+            const mockEnv = {
+                getComponent: vi.fn(() => mockToolComponent),
+            };
+            await component.init({
+                options: {
+                    configComponent,
+                },
+            });
+            component.env = mockEnv;
+            component.toolComponent = mockToolComponent;
+            await component.stop();
+            expect(mockToolComponent.unregister).toHaveBeenCalledWith("skill");
+        });
+    });
+});
+//# sourceMappingURL=skill-component.test.js.map

package/dist/core/src/env/skill/skill-config-registration.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Skill Component 配置注册
+ *
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+import type { ComponentRegistration } from "../../config/config-component";
+/**
+ * Skill Component 默认配置值
+ *
+ * 注意：键使用完整格式（带 "skill." 前缀），在 registerConfig 中手动设置
+ */
+export declare const SKILL_DEFAULTS: Record<string, unknown>;
+/**
+ * Skill Component 配置注册常量
+ *
+ * 定义了所有 Skill 相关的配置项和来源
+ */
+export declare const SKILL_CONFIG_REGISTRATION: ComponentRegistration;
+//# sourceMappingURL=skill-config-registration.d.ts.map

package/dist/core/src/env/skill/skill-config-registration.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Skill Component 配置注册
+ *
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+import path from "path";
+import os from "os";
+/**
+ * Skill Component 默认配置值
+ *
+ * 注意：键使用完整格式（带 "skill." 前缀），在 registerConfig 中手动设置
+ */
+export const SKILL_DEFAULTS = {
+    "skill.skillPaths": [
+        { type: "user", path: path.join(os.homedir(), ".config", "roy-agent", "skills") },
+        { type: "project", path: ".roy/skills" },
+    ],
+    "skill.recursive": true,
+    "skill.cacheEnabled": true,
+};
+/**
+ * Skill Component 配置注册常量
+ *
+ * 定义了所有 Skill 相关的配置项和来源
+ */
+export const SKILL_CONFIG_REGISTRATION = {
+    name: "skill",
+    sources: [
+        { type: "env", envPrefix: "SKILL", priority: 20, watch: false },
+    ],
+    keys: [
+        { key: "skill.skillPaths", sources: ["env", "file"] },
+        { key: "skill.recursive", sources: ["env", "file"] },
+        { key: "skill.cacheEnabled", sources: ["env", "file"] },
+    ],
+    // 注意：不使用 defaults 字段，默认值在 registerConfig 中手动 set
+};
+//# sourceMappingURL=skill-config-registration.js.map

package/dist/core/src/env/skill/skill-config-registration.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Skill Component 配置注册测试
+ */
+export {};
+//# sourceMappingURL=skill-config-registration.test.d.ts.map

package/dist/core/src/env/skill/skill-config-registration.test.js

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Skill Component 配置注册测试
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { ConfigComponent } from "../../config/config-component.js";
+import { SKILL_CONFIG_REGISTRATION, SKILL_DEFAULTS } from "./skill-config-registration.js";
+describe("Skill Config Registration", () => {
+    let configComponent;
+    beforeEach(() => {
+        configComponent = new ConfigComponent();
+    });
+    describe("SKILL_CONFIG_REGISTRATION", () => {
+        it("应该包含正确的 name", () => {
+            expect(SKILL_CONFIG_REGISTRATION.name).toBe("skill");
+        });
+        it("应该包含 env source 配置", () => {
+            const envSource = SKILL_CONFIG_REGISTRATION.sources.find((s) => s.type === "env");
+            expect(envSource).toBeDefined();
+            expect(envSource?.envPrefix).toBe("SKILL");
+            expect(envSource?.priority).toBe(20);
+        });
+        it("应该包含所有配置 keys", () => {
+            const keys = SKILL_CONFIG_REGISTRATION.keys;
+            expect(keys).toContainEqual(expect.objectContaining({ key: "skill.skillPaths" }));
+            expect(keys).toContainEqual(expect.objectContaining({ key: "skill.recursive" }));
+            expect(keys).toContainEqual(expect.objectContaining({ key: "skill.cacheEnabled" }));
+        });
+    });
+    describe("SKILL_DEFAULTS", () => {
+        it("应该包含 recursive 默认值（完整格式）", () => {
+            expect(SKILL_DEFAULTS["skill.recursive"]).toBe(true);
+        });
+        it("应该包含 cacheEnabled 默认值（完整格式）", () => {
+            expect(SKILL_DEFAULTS["skill.cacheEnabled"]).toBe(true);
+        });
+    });
+    describe("配置注册到 ConfigComponent", () => {
+        it("应该能够注册 SKILL_CONFIG_REGISTRATION", () => {
+            configComponent.registerComponent(SKILL_CONFIG_REGISTRATION);
+            expect(() => configComponent.registerComponent(SKILL_CONFIG_REGISTRATION)).not.toThrow();
+        });
+    });
+});
+//# sourceMappingURL=skill-config-registration.test.js.map

package/dist/core/src/env/skill/tool/index.d.ts

@@ -0,0 +1,2 @@
+export { createSkillTool, buildSkillDescription } from "./skill-tool";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/src/env/skill/tool/index.js

@@ -0,0 +1,2 @@
+export { createSkillTool, buildSkillDescription } from "./skill-tool.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,16 @@
+import type { Tool } from "../../tool/types";
+import { type SkillListItem } from "../types";
+/**
+ * 构建 SkillTool 的 description
+ */
+export declare function buildSkillDescription(items: SkillListItem[]): string;
+/**
+ * 创建 SkillTool
+ *
+ * @param getSkillList - 获取 skill 列表的回调
+ * @param getSkill - 获取单个 skill 的回调
+ */
+export declare function createSkillTool(getSkillList: () => SkillListItem[], getSkill: (name: string) => {
+    content: string;
+} | undefined): Tool;
+//# sourceMappingURL=skill-tool.d.ts.map

package/dist/core/src/env/skill/tool/skill-tool.js

@@ -0,0 +1,64 @@
+import { SkillToolSchema } from "../types.js";
+/**
+ * 构建 SkillTool 的 description
+ */
+export function buildSkillDescription(items) {
+    const lines = [
+        "Load a skill by name. Available skills:",
+        "",
+        "## Available Skills",
+        "",
+    ];
+    if (items.length === 0) {
+        lines.push("No skills available.");
+    }
+    else {
+        for (const item of items) {
+            lines.push(`- **${item.name}**: "${item.description}"`);
+        }
+    }
+    lines.push("");
+    lines.push("Use the 'skill' parameter to specify which skill to load.");
+    return lines.join("\n");
+}
+/**
+ * 创建 SkillTool
+ *
+ * @param getSkillList - 获取 skill 列表的回调
+ * @param getSkill - 获取单个 skill 的回调
+ */
+export function createSkillTool(getSkillList, getSkill) {
+    return {
+        name: "skill",
+        description: buildSkillDescription(getSkillList()),
+        parameters: SkillToolSchema,
+        execute: async (args, ctx) => {
+            const params = SkillToolSchema.parse(args);
+            try {
+                const entry = getSkill(params.skill);
+                if (!entry) {
+                    return {
+                        success: false,
+                        output: "",
+                        error: `Skill not found: ${params.skill}`,
+                        metadata: { execution_time_ms: 0 },
+                    };
+                }
+                return {
+                    success: true,
+                    output: entry.content,
+                    metadata: { execution_time_ms: 0 },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    output: "",
+                    error: error instanceof Error ? error.message : String(error),
+                    metadata: { execution_time_ms: 0 },
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=skill-tool.js.map

package/dist/core/src/env/skill/tool/skill-tool.test.d.ts

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