@ai-setting/roy-agent-core 1.0.0

package/src/env/skill/skill-component.test.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect, beforeEach, vi } from "bun:test";
+import { SkillComponent } from "./skill-component";
+import { ConfigComponent } from "../../config/config-component";
+import type { ComponentConfig } from "../component";
+
+describe("SkillComponent", () => {
+  let component: SkillComponent;
+  let configComponent: ConfigComponent;
+  let mockToolComponent: any;
+
+  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,
+        },
+      } as ComponentConfig);
+      
+      expect(component.getStatus()).toBe("running");
+    });
+
+    it("should use custom config when provided", async () => {
+      await component.init({
+        options: {
+          configComponent,
+          config: {
+            recursive: false,
+          },
+        },
+      } as ComponentConfig);
+      
+      expect(component.getStatus()).toBe("running");
+    });
+  });
+
+  describe("start", () => {
+    it("should register SkillTool to ToolComponent", async () => {
+      // 创建一个假的 env
+      const mockEnv = {
+        getComponent: vi.fn((name: string) => {
+          if (name === "tool") return mockToolComponent;
+          return null;
+        }),
+      };
+      
+      await component.init({
+        options: {
+          configComponent,
+        },
+      } as ComponentConfig);
+      (component as any).env = mockEnv;
+      
+      // Mock scanner
+      const mockScanner = {
+        scan: vi.fn().mockResolvedValue(new Map()),
+      };
+      (component as any).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,
+        },
+      } as ComponentConfig);
+      (component as any).env = mockEnv;
+      
+      const mockScanner = {
+        scan: vi.fn().mockResolvedValue(new Map()),
+      };
+      (component as any).scanner = mockScanner;
+      
+      await component.start();
+      
+      expect(mockToolComponent.register).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("getSkill", () => {
+    it("should return undefined for unknown skill", () => {
+      (component as any).skillsMap = new Map();
+      
+      const result = component.getSkill("non-existent");
+      
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("getSkillList", () => {
+    it("should return empty array when no skills", () => {
+      (component as any).skillsMap = new Map();
+      
+      const result = component.getSkillList();
+      
+      expect(result).toEqual([]);
+    });
+
+    it("should return skills as list items", () => {
+      (component as any).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 as any).skillsMap = new Map([["brainstorming", {} as any]]);
+      
+      expect(component.hasSkill("brainstorming")).toBe(true);
+    });
+
+    it("should return false for non-existing skill", () => {
+      (component as any).skillsMap = new Map();
+      
+      expect(component.hasSkill("non-existent")).toBe(false);
+    });
+  });
+
+  describe("getAllSkills", () => {
+    it("should return empty array when no skills", () => {
+      (component as any).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 as any).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,
+        },
+      } as ComponentConfig);
+      (component as any).env = mockEnv;
+      (component as any).toolComponent = mockToolComponent;
+      
+      const mockScanner = {
+        scan: vi.fn().mockResolvedValue(new Map()),
+      };
+      (component as any).scanner = mockScanner;
+      (component as any).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,
+        },
+      } as ComponentConfig);
+      (component as any).env = mockEnv;
+      (component as any).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,
+        },
+      } as ComponentConfig);
+      (component as any).env = mockEnv;
+      (component as any).toolComponent = mockToolComponent;
+      
+      await component.stop();
+      
+      expect(mockToolComponent.unregister).toHaveBeenCalledWith("skill");
+    });
+  });
+});

package/src/env/skill/skill-component.ts

@@ -0,0 +1,352 @@
+import { BaseComponent, type ComponentConfig } from "../component";
+import { createLogger } from "../log-trace/logger";
+import { SkillScanner } from "./scanner";
+import { createSkillTool } from "./tool";
+import { DEFAULT_SKILL_CONFIG } from "./config";
+import type {
+  SkillConfig,
+  SkillEntry,
+  SkillListItem,
+} from "./types";
+import type { ToolComponent } from "../tool";
+import type { Tool } from "../tool/types";
+import { SKILL_CONFIG_REGISTRATION, SKILL_DEFAULTS } from "./skill-config-registration";
+import type { ConfigComponent } from "../../config/config-component";
+import { envKeyToConfigKey } from "../../config/env-key";
+
+const logger = createLogger("skill");
+
+/**
+ * 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 class SkillComponent extends BaseComponent {
+  name = "skill";
+  version = "1.0.0";
+
+  private config!: SkillConfig;
+  private toolComponent?: ToolComponent;
+  private scanner!: SkillScanner;
+  private skillsMap: Map<string, SkillEntry> = new Map();
+  private configComponent?: ConfigComponent;
+  private configWatcher?: () => void;
+
+  // ========================================================================
+  // Lifecycle
+  // ========================================================================
+
+  async init(config?: ComponentConfig): Promise<void> {
+    await super.init(config);
+
+    // 从 options 获取 ConfigComponent
+    const options = config?.options as unknown as SkillComponentOptions | undefined;
+    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 对象 - 直接传入的配置（最高）
+   */
+  private async registerConfig(options: SkillComponentOptions): Promise<void> {
+    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);
+  }
+
+  /**
+   * 构建最终配置对象
+   */
+  private buildConfig(configComponent: ConfigComponent): void {
+    // 解析基本配置
+    const recursive = (configComponent.get("skill.recursive") as boolean) ?? true;
+    const cacheEnabled = (configComponent.get("skill.cacheEnabled") as boolean) ?? true;
+
+    // 从配置获取 skillPaths（需要解析 JSON 数组）
+    const skillPathsConfig = configComponent.get("skill.skillPaths");
+    let skillPaths: { type: string; path: string }[] = [];
+
+    if (Array.isArray(skillPathsConfig)) {
+      skillPaths = skillPathsConfig as { type: string; path: string }[];
+    } 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 as any,
+      recursive,
+      cacheEnabled,
+    };
+  }
+
+  /**
+   * 将配置对象展平为点号路径
+   */
+  private flattenConfig(
+    obj: Record<string, unknown>,
+    prefix = "skill"
+  ): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    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 as Record<string, unknown>, fullKey)
+        );
+      } else {
+        result[fullKey] = value;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 注册配置热更新监听
+   */
+  private registerConfigWatcher(configComponent: ConfigComponent): void {
+    if (typeof configComponent.watch !== "function") {
+      return;
+    }
+    
+    this.configWatcher = configComponent.watch("skill.*", (event) => {
+      this.onConfigChange(event);
+    });
+  }
+
+  /**
+   * 处理配置变更
+   */
+  protected onConfigChange(event: { key: string; oldValue?: unknown; newValue?: unknown }): void {
+    logger.info(`[SkillComponent] Config changed: ${event.key}`, {
+      oldValue: event.oldValue,
+      newValue: event.newValue
+    });
+    // 重新构建配置
+    if (this.configComponent) {
+      this.buildConfig(this.configComponent);
+    }
+  }
+
+  async start(): Promise<void> {
+    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(): Promise<void> {
+    // 清理配置 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: string): SkillEntry | undefined {
+    return this.skillsMap.get(name);
+  }
+
+  /**
+   * 获取所有 skill 列表（用于 tool description）
+   */
+  getSkillList(): SkillListItem[] {
+    return Array.from(this.skillsMap.values()).map((entry) => ({
+      name: entry.name,
+      description: entry.description,
+      source: entry.source,
+    }));
+  }
+
+  /**
+   * 检查 skill 是否存在
+   */
+  hasSkill(name: string): boolean {
+    return this.skillsMap.has(name);
+  }
+
+  /**
+   * 获取所有 skills
+   */
+  getAllSkills(): SkillEntry[] {
+    return Array.from(this.skillsMap.values());
+  }
+
+  // ========================================================================
+  // Scanning & Reload
+  // ========================================================================
+
+  /**
+   * 扫描所有 skillPaths 并加载 skills
+   */
+  async scanSkills(): Promise<void> {
+    this.scanner = new SkillScanner(this.config);
+    this.skillsMap = await this.scanner.scan();
+    logger.info(`[SkillComponent] Scanned ${this.skillsMap.size} skills`);
+  }
+
+  /**
+   * 重新扫描并更新 Tool
+   */
+  async reload(): Promise<void> {
+    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
+  // ========================================================================
+
+  private async registerTool(): Promise<void> {
+    if (!this.toolComponent) return;
+
+    const tool = createSkillTool(
+      () => this.getSkillList(),
+      (name) => this.getSkill(name)
+    );
+
+    this.toolComponent.register(tool);
+    logger.info("[SkillComponent] Registered SkillTool");
+  }
+}

package/src/env/skill/skill-config-registration.test.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Skill Component 配置注册测试
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { ConfigComponent } from "../../config/config-component";
+import { SKILL_CONFIG_REGISTRATION, SKILL_DEFAULTS } from "./skill-config-registration";
+
+describe("Skill Config Registration", () => {
+  let configComponent: 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();
+    });
+  });
+});

package/src/env/skill/skill-config-registration.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Skill Component 配置注册
+ * 
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+
+import path from "path";
+import os from "os";
+import type { ComponentRegistration } from "../../config/config-component";
+
+/**
+ * Skill Component 默认配置值
+ * 
+ * 注意：键使用完整格式（带 "skill." 前缀），在 registerConfig 中手动设置
+ */
+export const SKILL_DEFAULTS: Record<string, unknown> = {
+  "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: ComponentRegistration = {
+  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
+};

package/src/env/skill/tool/index.ts

@@ -0,0 +1 @@
+export { createSkillTool, buildSkillDescription } from "./skill-tool";