@ai-setting/roy-agent-cli 1.0.0

package/src/commands/workflow/validators/workflow-validator.ts

@@ -0,0 +1,320 @@
+/**
+ * @fileoverview Workflow-level validator
+ */
+
+import { ValidationErrorType, type ValidationResult, type RawWorkflowDefinition, type RawNodeDefinition, type ValidationError } from './types';
+import { getNodeValidator, getSupportedNodeTypes } from './node-validator-factory';
+
+/**
+ * Workflow validator - validates both structure and nodes
+ */
+export class WorkflowValidator {
+  /**
+   * Validate a raw workflow definition
+   */
+  validate(workflow: RawWorkflowDefinition): ValidationResult {
+    const errors: ValidationError[] = [];
+    
+    // 1. Structure validation
+    const structureErrors = this.validateStructure(workflow);
+    errors.push(...structureErrors);
+    
+    // If structure is invalid, skip node validation
+    if (structureErrors.length > 0) {
+      return {
+        valid: false,
+        errors,
+        workflowName: typeof workflow.name === 'string' ? workflow.name : undefined,
+      };
+    }
+    
+    // 2. Node validation
+    const nodes = workflow.nodes || [];
+    const nodeIds = new Set<string>();
+    const nodeErrors = this.validateNodes(nodes, nodeIds);
+    errors.push(...nodeErrors);
+    
+    // 3. Dependency validation
+    const depErrors = this.validateDependencies(nodes, nodeIds);
+    errors.push(...depErrors);
+    
+    // 4. Template reference validation
+    const templateErrors = this.validateTemplateReferences(nodes, nodeIds);
+    errors.push(...templateErrors);
+    
+    return {
+      valid: errors.length === 0,
+      errors,
+      workflowName: workflow.name as string,
+      nodeCount: nodes.length,
+    };
+  }
+  
+  /**
+   * Validate workflow structure
+   */
+  private validateStructure(workflow: RawWorkflowDefinition): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    // Check name
+    if (!workflow.name || typeof workflow.name !== 'string' || !workflow.name.trim()) {
+      errors.push({
+        type: ValidationErrorType.MISSING_REQUIRED_FIELD,
+        description: 'Workflow name is missing or empty',
+        expected: 'name must be a non-empty string',
+        actual: String(workflow.name),
+        fix: 'Add a "name" field to the workflow, e.g., name: "my-workflow"',
+      });
+    }
+    
+    // Check nodes
+    if (!workflow.nodes || !Array.isArray(workflow.nodes)) {
+      errors.push({
+        type: ValidationErrorType.EMPTY_NODES,
+        description: 'Workflow nodes is missing or not an array',
+        expected: 'nodes must be an array of node definitions',
+        actual: String(workflow.nodes),
+        fix: 'Add a "nodes" array to the workflow',
+      });
+      return errors;
+    }
+    
+    if (workflow.nodes.length === 0) {
+      errors.push({
+        type: ValidationErrorType.EMPTY_NODES,
+        description: 'Workflow nodes array is empty',
+        expected: 'nodes must contain at least one node',
+        actual: '[]',
+        fix: 'Add at least one node to the workflow',
+      });
+    }
+    
+    return errors;
+  }
+  
+  /**
+   * Validate all nodes
+   */
+  private validateNodes(nodes: RawNodeDefinition[], nodeIds: Set<string>): ValidationError[] {
+    const errors: ValidationError[] = [];
+    const seenIds = new Set<string>();
+    
+    for (const node of nodes) {
+      // Check for duplicate IDs
+      if (node.id) {
+        if (seenIds.has(node.id)) {
+          errors.push({
+            type: ValidationErrorType.DUPLICATE_NODE_ID,
+            description: `Duplicate node ID found: "${node.id}"`,
+            expected: 'Each node must have a unique ID',
+            actual: `ID "${node.id}" appears multiple times`,
+            fix: `Rename one of the nodes with ID "${node.id}" to a unique value`,
+            nodeId: node.id,
+          });
+        }
+        seenIds.add(node.id);
+        nodeIds.add(node.id);
+      }
+      
+      // Validate node type
+      if (!node.type) {
+        errors.push({
+          type: ValidationErrorType.MISSING_REQUIRED_FIELD,
+          description: 'Node type is missing',
+          expected: `type must be one of: ${getSupportedNodeTypes().join(', ')}`,
+          actual: 'undefined',
+          fix: `Add a "type" field to the node, e.g., type: "tool"`,
+          nodeId: node.id,
+        });
+        continue;
+      }
+      
+      // Get validator for node type
+      const validator = getNodeValidator(node.type);
+      if (!validator) {
+        errors.push({
+          type: ValidationErrorType.INVALID_NODE_TYPE,
+          description: `Unknown node type: "${node.type}"`,
+          expected: `type must be one of: ${getSupportedNodeTypes().join(', ')}`,
+          actual: String(node.type),
+          fix: `Change type to one of: ${getSupportedNodeTypes().join(', ')}`,
+          nodeId: node.id,
+        });
+        continue;
+      }
+      
+      // Validate with type-specific validator
+      const nodeErrors = validator.validate(node);
+      errors.push(...nodeErrors);
+    }
+    
+    return errors;
+  }
+  
+  /**
+   * Validate node dependencies
+   */
+  private validateDependencies(nodes: RawNodeDefinition[], nodeIds: Set<string>): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    for (const node of nodes) {
+      if (!node.depends_on || !Array.isArray(node.depends_on)) continue;
+      
+      for (const depId of node.depends_on) {
+        if (!nodeIds.has(depId)) {
+          errors.push({
+            type: ValidationErrorType.INVALID_REFERENCE,
+            description: `depends_on references non-existent node`,
+            expected: 'All node IDs in depends_on must exist in workflow',
+            actual: `depends_on: ["${depId}"], but "${depId}" not found`,
+            fix: `Remove "${depId}" from depends_on or create a node with that ID`,
+            nodeId: node.id,
+          });
+        }
+      }
+    }
+    
+    // Check for circular dependencies
+    const circularErrors = this.detectCircularDependencies(nodes);
+    errors.push(...circularErrors);
+    
+    return errors;
+  }
+  
+  /**
+   * Validate template references in node configs
+   * 
+   * Extracts all template references like {{nodes.xxx.output}}, {{xxx.output}}, ${xxx.output}
+   * and validates that the referenced node IDs exist in the workflow.
+   */
+  private validateTemplateReferences(nodes: RawNodeDefinition[], nodeIds: Set<string>): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    // Template reference patterns:
+    // 1. {{nodes.nodeId}} or {{nodes.nodeId.path}} or {{nodes.nodeId.path.more}}
+    // 2. {{nodeId}} or {{nodeId.path}} (bare node reference)
+    // 3. ${nodes.nodeId} or ${nodes.nodeId.path} (dollar-style)
+    // 4. ${nodeId} or ${nodeId.path} (dollar-style bare)
+    // 5. {{input.key}} - workflow input, not a node reference
+    
+    const templatePatterns = [
+      /\{\{nodes\.([a-zA-Z_][a-zA-Z0-9_-]*)(?:\.[^}]+)?\}\}/g,  // {{nodes.xxx}} or {{nodes.xxx.yyy}}
+      /\{\{([a-zA-Z_][a-zA-Z0-9_-]*)(?:\.[^}]+)?\}\}/g,          // {{xxx}} or {{xxx.yyy}} (not input or nodes)
+      /\$\{nodes\.([a-zA-Z_][a-zA-Z0-9_-]*)(?:\.[^}]+)?\}/g,     // ${nodes.xxx} or ${nodes.xxx.yyy}
+      /\$\{([a-zA-Z_][a-zA-Z0-9_-]*)(?:\.[^}]+)?\}/g,            // ${xxx} or ${xxx.yyy}
+    ];
+    
+    for (const node of nodes) {
+      if (!node.id || !node.config) continue;
+      
+      // Get all config values as strings to search for templates
+      const configStr = JSON.stringify(node.config);
+      
+      // Find all template references
+      const foundRefs = new Set<string>();
+      
+      for (const pattern of templatePatterns) {
+        pattern.lastIndex = 0;  // Reset regex state
+        let match;
+        while ((match = pattern.exec(configStr)) !== null) {
+          // Skip 'input' and 'nodes' keywords
+          const refId = match[1];
+          if (refId !== 'input' && refId !== 'nodes') {
+            foundRefs.add(refId);
+          }
+        }
+      }
+      
+      // Check each reference against node IDs
+      for (const refId of foundRefs) {
+        if (!nodeIds.has(refId)) {
+          // Check if there's a similar node ID (hyphen/underscore mismatch)
+          const normalizedRef = refId.includes('-') 
+            ? refId.replace(/-/g, '_') 
+            : refId.replace(/_/g, '-');
+          
+          let fix: string;
+          if (nodeIds.has(normalizedRef)) {
+            fix = `Change "${refId}" to "${normalizedRef}" to match the existing node ID`;
+          } else {
+            // Find all existing node IDs that are similar (for suggestions)
+            const similarIds = Array.from(nodeIds).filter(id => {
+              const n1 = id.replace(/-/g, '_').replace(/_/g, '-');
+              const n2 = refId.replace(/-/g, '_').replace(/_/g, '-');
+              return n1 === n2;
+            });
+            
+            if (similarIds.length > 0) {
+              fix = `Change "${refId}" to one of: ${similarIds.join(', ')}`;
+            } else {
+              fix = `Remove "${refId}" or create a node with that ID`;
+            }
+          }
+          
+          errors.push({
+            type: ValidationErrorType.INVALID_TEMPLATE_REFERENCE,
+            description: `Template references non-existent node: "${refId}"`,
+            expected: `Referenced node ID must exist in the workflow`,
+            actual: `Template references "${refId}" but this node does not exist`,
+            fix,
+            nodeId: node.id,
+            template: `{{${refId}}}`,
+            referencedNodeId: refId,
+          });
+        }
+      }
+    }
+    
+    return errors;
+  }
+  
+  /**
+   * Detect circular dependencies using DFS
+   */
+  private detectCircularDependencies(nodes: RawNodeDefinition[]): ValidationError[] {
+    const errors: ValidationError[] = [];
+    const nodeMap = new Map<string, RawNodeDefinition>();
+    
+    for (const node of nodes) {
+      if (node.id) nodeMap.set(node.id, node);
+    }
+    
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+    
+    const dfs = (nodeId: string, path: string[]): boolean => {
+      visited.add(nodeId);
+      recursionStack.add(nodeId);
+      
+      const node = nodeMap.get(nodeId);
+      if (!node) return false;
+      
+      for (const depId of node.depends_on || []) {
+        if (!visited.has(depId)) {
+          if (dfs(depId, [...path, depId])) return true;
+        } else if (recursionStack.has(depId)) {
+          errors.push({
+            type: ValidationErrorType.CIRCULAR_DEPENDENCY,
+            description: 'Circular dependency detected',
+            expected: 'Workflow should be a DAG (no cycles)',
+            actual: `Cycle: ${[...path, depId].join(' → ')} → ${depId}`,
+            fix: 'Remove the circular dependency by changing depends_on references',
+            nodeId,
+          });
+          return true;
+        }
+      }
+      
+      recursionStack.delete(nodeId);
+      return false;
+    };
+    
+    for (const node of nodes) {
+      if (node.id && !visited.has(node.id)) {
+        dfs(node.id, [node.id]);
+      }
+    }
+    
+    return errors;
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @roy-agent/cli - CLI for roy-agent
+ */
+
+// Re-export for convenience
+export { runCli } from "./cli";
+export { OutputService } from "./services/output.service";
+export { EnvironmentService } from "./services/environment.service";
+
+// Re-export all commands
+export { ActCommand } from "./commands/act";
+export { InteractiveCommand } from "./commands/interactive";
+export { SessionsCommand } from "./commands/sessions";
+export { TasksCommand } from "./commands/tasks";
+export { CommandsCommand } from "./commands/commands";
+export { MemoryCommand } from "./commands/memory";
+export { SkillsCommand } from "./commands/skills";
+export { ToolsCommand } from "./commands/tools";
+export { McpCommand } from "./commands/mcp";

package/src/plugin/apply.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Apply Plugins to Yargs
+ *
+ * 将插件命令应用到 yargs 实例
+ */
+
+import { globalPluginRegistry } from "./registry";
+
+/**
+ * 将插件命令应用到 yargs 实例
+ *
+ * @param yargsInstance - yargs 实例
+ * @returns 应用了插件命令的 yargs 实例
+ *
+ * @example
+ * ```typescript
+ * import { applyPluginCommands } from "./plugin";
+ *
+ * let y = yargs();
+ * y = y.command(ActCommand);
+ * y = applyPluginCommands(y);
+ * y.parse();
+ * ```
+ */
+export function applyPluginCommands<T = any>(
+  yargsInstance: any
+): any {
+  const commands = globalPluginRegistry.getAllCommands();
+
+  for (const { command } of commands) {
+    yargsInstance = yargsInstance.command(command as any);
+  }
+
+  return yargsInstance;
+}
+
+/**
+ * 创建插件命令包装命令
+ *
+ * 用于在 yargs 中添加一个空的命令包装器，
+ * 使得插件命令可以在 strict 模式下正常工作
+ *
+ * @returns CommandModule
+ *
+ * @deprecated 此方法已废弃，仅用于兼容旧版本
+ */
+export function createPluginCommandsCommand(): any {
+  return {
+    command: "$0",
+    describe: false,
+    handler: () => {
+      // 不做任何事，由其他命令处理
+    },
+  };
+}
+
+/**
+ * 获取所有插件命令信息摘要
+ *
+ * @returns 命令摘要数组
+ */
+export function getPluginCommandsSummary(): Array<{
+  plugin: string;
+  command: string;
+  description?: string;
+}> {
+  const summary: Array<{
+    plugin: string;
+    command: string;
+    description?: string;
+  }> = [];
+
+  for (const plugin of globalPluginRegistry.getAll()) {
+    const commands = plugin.getCommands?.() ?? [];
+    for (const { command } of commands) {
+      summary.push({
+        plugin: plugin.info.name,
+        command: command.command as string,
+        description: command.describe as string | undefined,
+      });
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * 检查是否存在指定名称的命令
+ *
+ * @param commandName - 命令名称
+ * @returns 是否存在
+ */
+export function hasPluginCommand(commandName: string): boolean {
+  for (const plugin of globalPluginRegistry.getAll()) {
+    const commands = plugin.getCommands?.() ?? [];
+    for (const { command } of commands) {
+      if ((command.command as string).startsWith(commandName)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}

package/src/plugin/discover.ts

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview Plugin Discovery
+ *
+ * 扫描并发现已安装的插件
+ */
+
+import type { RoyCliPlugin } from "./types";
+import { globalPluginRegistry } from "./registry";
+import { readFileSync, existsSync } from "fs";
+import { join, resolve } from "path";
+
+/**
+ * 插件包识别模式
+ *
+ * 扫描 node_modules 中匹配这些模式的包
+ */
+const PLUGIN_PATTERNS = [
+  "@ai-setting/agent-*",
+  "@roy-agent/plugin-*",
+];
+
+/**
+ * 插件入口文件名
+ *
+ * 插件包根目录下必须包含此文件
+ */
+const PLUGIN_ENTRY_FILE = "roy-plugin.js";
+
+/**
+ * 扫描路径
+ *
+ * 从这些路径扫描插件，默认包含项目 node_modules 和全局 node_modules
+ */
+const DEFAULT_SCAN_PATHS: string[] = [];
+
+/**
+ * 缓存已发现的插件路径，避免重复加载
+ */
+const loadedPaths = new Set<string>();
+
+/**
+ * 初始化扫描路径
+ */
+function initScanPaths(): string[] {
+  if (DEFAULT_SCAN_PATHS.length > 0) {
+    return DEFAULT_SCAN_PATHS;
+  }
+
+  // 项目 node_modules
+  const projectNodeModules = resolve(process.cwd(), "node_modules");
+  if (existsSync(projectNodeModules)) {
+    DEFAULT_SCAN_PATHS.push(projectNodeModules);
+  }
+
+  // 全局 bun/node_modules
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  if (homeDir) {
+    const globalNodeModules = join(homeDir, ".bun", "install", "global", "node_modules");
+    if (existsSync(globalNodeModules)) {
+      DEFAULT_SCAN_PATHS.push(globalNodeModules);
+    }
+  }
+
+  // NODE_PATH 环境变量
+  if (process.env.NODE_PATH) {
+    const extraPaths = process.env.NODE_PATH.split(":").filter((p) => {
+      const fullPath = resolve(p);
+      if (!DEFAULT_SCAN_PATHS.includes(fullPath) && existsSync(fullPath)) {
+        return true;
+      }
+      return false;
+    });
+    DEFAULT_SCAN_PATHS.push(...extraPaths);
+  }
+
+  return DEFAULT_SCAN_PATHS;
+}
+
+/**
+ * 类型守卫：检查对象是否为有效的 RoyCliPlugin
+ */
+function isRoyCliPlugin(obj: unknown): obj is RoyCliPlugin {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "info" in obj &&
+    typeof (obj as any).info.name === "string" &&
+    typeof (obj as any).info.version === "string"
+  );
+}
+
+/**
+ * 加载单个插件
+ *
+ * @param pkgPath - 插件包路径
+ * @returns 是否成功加载
+ */
+async function loadPlugin(pkgPath: string): Promise<boolean> {
+  const pluginFile = join(pkgPath, PLUGIN_ENTRY_FILE);
+
+  if (!existsSync(pluginFile)) {
+    return false;
+  }
+
+  if (loadedPaths.has(pluginFile)) {
+    return true; // 已加载过
+  }
+
+  try {
+    // 使用动态导入加载插件
+    const plugin = await import(pluginFile);
+    
+    // 尝试多种方式获取插件实例
+    const pluginInstance = 
+      plugin.default || 
+      plugin.bountyPlugin || 
+      plugin;
+
+    if (isRoyCliPlugin(pluginInstance)) {
+      // 跳过已注册的插件
+      if (globalPluginRegistry.has(pluginInstance.info.name)) {
+        console.log(`[roy] Plugin "${pluginInstance.info.name}" is already registered, skipping`);
+        return true;
+      }
+
+      globalPluginRegistry.register(pluginInstance);
+      console.log(`[roy] Loaded plugin: ${pluginInstance.info.name}@${pluginInstance.info.version}`);
+      loadedPaths.add(pluginFile);
+      return true;
+    } else {
+      console.warn(`[roy] Invalid plugin at ${pkgPath}: missing required "info" property`);
+      // 调试信息
+      console.warn(`[roy] Available exports:`, Object.keys(plugin));
+    }
+  } catch (err) {
+    console.warn(`[roy] Failed to load plugin from ${pkgPath}:`, (err as Error).message);
+  }
+
+  return false;
+}
+
+/**
+ * 扫描单个路径下的插件
+ *
+ * @param basePath - 基础路径
+ */
+async function scanPath(basePath: string): Promise<void> {
+  if (!existsSync(basePath)) {
+    return;
+  }
+
+  const { glob } = await import("glob");
+
+  for (const pattern of PLUGIN_PATTERNS) {
+    try {
+      const matches = await glob(pattern, {
+        cwd: basePath,
+        onlyDirectories: true,
+        absolute: true,
+      } as any);
+
+      for (const match of matches) {
+        await loadPlugin(match);
+      }
+    } catch {
+      // 忽略 glob 扫描错误
+    }
+  }
+}
+
+/**
+ * 扫描指定路径并加载所有发现的插件
+ *
+ * @param scanPaths - 要扫描的路径数组，默认扫描标准 node_modules 位置
+ * @returns 已加载的插件数量
+ */
+export async function discoverPlugins(
+  scanPaths: string[] = initScanPaths()
+): Promise<number> {
+  const initialCount = globalPluginRegistry.size;
+
+  for (const path of scanPaths) {
+    await scanPath(path);
+  }
+
+  const loadedCount = globalPluginRegistry.size - initialCount;
+  if (loadedCount > 0) {
+    console.log(`[roy] Discovered and loaded ${loadedCount} plugin(s)`);
+  }
+
+  return loadedCount;
+}
+
+/**
+ * 获取已加载的插件数量
+ */
+export function getLoadedPluginCount(): number {
+  return globalPluginRegistry.size;
+}
+
+/**
+ * 清除插件加载缓存
+ *
+ * 主要用于测试
+ */
+export function clearPluginCache(): void {
+  loadedPaths.clear();
+}
+
+/**
+ * 重新扫描并加载插件
+ *
+ * 会先清空已注册的插件，然后重新发现
+ */
+export async function reloadPlugins(): Promise<number> {
+  globalPluginRegistry.clear();
+  loadedPaths.clear();
+  return discoverPlugins();
+}

package/src/plugin/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Plugin System
+ *
+ * Roy CLI 插件系统入口
+ *
+ * @example
+ * ```typescript
+ * import { globalPluginRegistry } from "@ai-setting/roy-agent-cli/plugin";
+ * import type { RoyCliPlugin } from "@ai-setting/roy-agent-cli/plugin";
+ * ```
+ */
+
+// 类型导出
+export type {
+  PluginInfo,
+  PluginComponentDefinition,
+  PluginCommandDefinition,
+  PluginEnvironmentContext,
+  RoyCliPlugin,
+  ComponentPluginDefinition,
+  ComponentPluginInstance,
+} from "./types";
+
+// 注册表导出
+export {
+  PluginRegistry,
+  globalPluginRegistry,
+  loadBuiltinComponentPlugin,
+} from "./registry";
+
+// 发现机制导出
+export {
+  discoverPlugins,
+  getLoadedPluginCount,
+  clearPluginCache,
+  reloadPlugins,
+} from "./discover";
+
+// 应用插件导出
+export {
+  applyPluginCommands,
+  createPluginCommandsCommand,
+  getPluginCommandsSummary,
+  hasPluginCommand,
+} from "./apply";