@haoyiyin/workflow 0.2.10 → 0.3.0

package/src/router/namespace/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Namespace Router System - 分层命名空间路由
+ *
+ * 导出所有命名空间路由相关模块
+ */
+
+// Types
+export type {
+  UserRequest,
+  ConversationHistory,
+  RouterConfig,
+  RoutingContext,
+  AlternativeRoute,
+  RouteDecision,
+  RouteResult,
+  NamespaceRouter,
+  NamespaceHealth,
+  SubagentRouteRequest,
+  SubagentRouteResponse,
+  NamespaceRegistry,
+  NamespaceConfig,
+} from './types.js'
+
+export { DEFAULT_NAMESPACE_CONFIG } from './types.js'
+
+// Registry
+export {
+  NamespaceRouterRegistry,
+  getNamespaceRegistry,
+  resetNamespaceRegistry,
+} from './registry.js'
+
+// Core Layer Routers
+export {
+  lifecycleRouter,
+  LifecycleRouter,
+} from './core/lifecycle-router.js'
+
+export {
+  stateRouter,
+  StateRouter,
+} from './core/state-router.js'
+
+export {
+  intentRouter,
+  IntentRouter,
+} from './core/intent-router.js'
+
+// Domain Layer Routers
+export {
+  planRouter,
+  PlanRouter,
+} from './domain/plan-router.js'
+
+export {
+  codeRouter,
+  CodeRouter,
+} from './domain/code-router.js'
+
+export {
+  debugRouter,
+  DebugRouter,
+} from './domain/debug-router.js'
+
+export {
+  reviewRouter,
+  ReviewRouter,
+} from './domain/review-router.js'
+
+// Utility Layer Routers
+export {
+  quickTaskRouter,
+  QuickTaskRouter,
+} from './utility/quick-task-router.js'
+
+export {
+  researchRouter,
+  ResearchRouter,
+} from './utility/research-router.js'
+
+export {
+  fallbackRouter,
+  FallbackRouter,
+} from './utility/fallback-router.js'

package/src/router/namespace/registry.ts

@@ -0,0 +1,242 @@
+/**
+ * Namespace Router Registry
+ *
+ * 管理和协调所有命名空间路由
+ * 实现分层路由决策流程
+ */
+
+import type {
+  NamespaceRouter,
+  NamespaceRegistry,
+  RoutingContext,
+  RouteDecision,
+  NamespaceConfig,
+} from './types.js'
+import { DEFAULT_NAMESPACE_CONFIG } from './types.js'
+
+// 导入核心层路由
+import { lifecycleRouter } from './core/lifecycle-router.js'
+import { stateRouter } from './core/state-router.js'
+import { intentRouter } from './core/intent-router.js'
+
+// 导入领域层路由
+import { planRouter } from './domain/plan-router.js'
+import { codeRouter } from './domain/code-router.js'
+import { debugRouter } from './domain/debug-router.js'
+import { reviewRouter } from './domain/review-router.js'
+
+// 导入工具层路由
+import { quickTaskRouter } from './utility/quick-task-router.js'
+import { researchRouter } from './utility/research-router.js'
+import { fallbackRouter } from './utility/fallback-router.js'
+
+// ---------------------------------------------------------------------------
+// Default Routers
+// ---------------------------------------------------------------------------
+
+const DEFAULT_ROUTERS: NamespaceRouter[] = [
+  // Core Layer (高优先级)
+  stateRouter,      // priority 95 - 基于状态
+  lifecycleRouter,  // priority 90 - 基于生命周期
+  intentRouter,     // priority 80 - 基于意图
+
+  // Domain Layer (中优先级)
+  planRouter,       // priority 70 - 计划相关
+  debugRouter,      // priority 70 - 调试相关
+  codeRouter,       // priority 65 - 代码相关
+  reviewRouter,     // priority 65 - 审查相关
+
+  // Utility Layer (低优先级)
+  quickTaskRouter,  // priority 50 - 快速任务
+  researchRouter,   // priority 45 - 研究探索
+  fallbackRouter,   // priority 0  - 最终降级
+]
+
+// ---------------------------------------------------------------------------
+// Registry Implementation
+// ---------------------------------------------------------------------------
+
+export class NamespaceRouterRegistry implements NamespaceRegistry {
+  private routers: Map<string, NamespaceRouter> = new Map()
+  private config: NamespaceConfig
+
+  constructor(config: Partial<NamespaceConfig> = {}) {
+    this.config = this.mergeConfig(config)
+    this.registerDefaults()
+  }
+
+  /**
+   * 注册默认路由
+   */
+  private registerDefaults(): void {
+    for (const router of DEFAULT_ROUTERS) {
+      if (this.isLayerEnabled(router.layer)) {
+        this.register(router)
+      }
+    }
+  }
+
+  /**
+   * 合并配置
+   */
+  private mergeConfig(config: Partial<NamespaceConfig>): NamespaceConfig {
+    return {
+      core: { ...DEFAULT_NAMESPACE_CONFIG.core, ...config.core },
+      domain: { ...DEFAULT_NAMESPACE_CONFIG.domain, ...config.domain },
+      utility: { ...DEFAULT_NAMESPACE_CONFIG.utility, ...config.utility },
+    }
+  }
+
+  /**
+   * 检查某层是否启用
+   */
+  private isLayerEnabled(layer: 'core' | 'domain' | 'utility'): boolean {
+    return this.config[layer]?.enabled ?? true
+  }
+
+  // -----------------------------------------------------------------------
+  // Registry API
+  // -----------------------------------------------------------------------
+
+  register(router: NamespaceRouter): void {
+    if (this.routers.has(router.name)) {
+      console.warn(`[NamespaceRegistry] Router ${router.name} already exists, overwriting`)
+    }
+    this.routers.set(router.name, router)
+  }
+
+  unregister(name: string): void {
+    this.routers.delete(name)
+  }
+
+  get(name: string): NamespaceRouter | undefined {
+    return this.routers.get(name)
+  }
+
+  list(): NamespaceRouter[] {
+    return Array.from(this.routers.values())
+  }
+
+  listByLayer(layer: 'core' | 'domain' | 'utility'): NamespaceRouter[] {
+    return this.list().filter((r) => r.layer === layer)
+  }
+
+  /**
+   * 执行分层路由决策
+   *
+   * 流程：
+   * 1. 按优先级排序所有启用的路由
+   * 2. 从高优先级开始调用 canRoute
+   * 3. 第一个返回 true 的路由执行 route
+   * 4. 如果没有匹配，使用 fallback
+   */
+  async resolve(context: RoutingContext): Promise<RouteDecision> {
+    const candidates: RouteDecision[] = []
+
+    // 按优先级排序
+    const sorted = this.list().sort((a, b) => b.priority - a.priority)
+
+    for (const router of sorted) {
+      try {
+        const canHandle = await router.canRoute(context)
+        if (canHandle) {
+          const decision = await router.route(context)
+          candidates.push(decision)
+
+          // 如果置信度足够高，直接返回
+          if (decision.confidence >= 0.85) {
+            return {
+              ...decision,
+              metadata: {
+                layer: decision.metadata?.layer || router.layer,
+                processingTime: decision.metadata?.processingTime || 0,
+                hops: candidates.length,
+              },
+            }
+          }
+        }
+      } catch (error) {
+        console.error(`[NamespaceRegistry] Router ${router.name} failed:`, error)
+      }
+    }
+
+    // 如果没有候选，使用 fallback
+    if (candidates.length === 0) {
+      return await fallbackRouter.route(context)
+    }
+
+    // 返回最佳候选（按置信度排序）
+    candidates.sort((a, b) => b.confidence - a.confidence)
+    const best = candidates[0]
+
+    return {
+      ...best,
+      alternatives: candidates.slice(1, 4).map((c) => ({
+        skill: c.skill,
+        confidence: c.confidence,
+        reasoning: `From ${c.namespace}: ${c.reasoning}`,
+      })),
+      metadata: {
+        layer: best.metadata?.layer || 'utility',
+        processingTime: best.metadata?.processingTime || 0,
+        hops: candidates.length,
+      },
+    }
+  }
+
+  /**
+   * 获取所有路由的健康状态
+   */
+  getHealthReport(): Array<ReturnType<NamespaceRouter['getHealth']>> {
+    return this.list().map((r) => r.getHealth())
+  }
+
+  /**
+   * 获取路由统计
+   */
+  getStats(): {
+    total: number
+    byLayer: Record<'core' | 'domain' | 'utility', number>
+    avgSuccessRate: number
+  } {
+    const routers = this.list()
+    const health = routers.map((r) => r.getHealth())
+
+    return {
+      total: routers.length,
+      byLayer: {
+        core: this.listByLayer('core').length,
+        domain: this.listByLayer('domain').length,
+        utility: this.listByLayer('utility').length,
+      },
+      avgSuccessRate: health.length > 0
+        ? health.reduce((sum, h) => sum + h.successRate, 0) / health.length
+        : 1.0,
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+
+let globalRegistry: NamespaceRouterRegistry | null = null
+
+export function getNamespaceRegistry(config?: Partial<NamespaceConfig>): NamespaceRouterRegistry {
+  if (!globalRegistry) {
+    globalRegistry = new NamespaceRouterRegistry(config)
+  }
+  return globalRegistry
+}
+
+export function resetNamespaceRegistry(): void {
+  globalRegistry = null
+}
+
+// ---------------------------------------------------------------------------
+// Convenience exports
+// ---------------------------------------------------------------------------
+
+export { lifecycleRouter, stateRouter, intentRouter }
+export { planRouter, codeRouter, debugRouter, reviewRouter }
+export { quickTaskRouter, researchRouter, fallbackRouter }

package/src/router/namespace/types.ts

@@ -0,0 +1,182 @@
+/**
+ * Namespace Router Types - 分层命名空间路由系统
+ *
+ * 提供模块化的路由架构，将路由决策分散到多个命名空间中
+ */
+
+import type { WorkflowState, Plan } from '../../persistence/types.js'
+import type { SubagentConfig, SubagentContract } from '../../agents/types.js'
+
+// ---------------------------------------------------------------------------
+// Core Types
+// ---------------------------------------------------------------------------
+
+export interface UserRequest {
+  text: string
+  timestamp: number
+  metadata?: Record<string, unknown>
+}
+
+export interface ConversationHistory {
+  role: 'user' | 'assistant'
+  content: string
+  timestamp?: number
+}
+
+export interface RouterConfig {
+  defaultModel: string
+  confidenceThreshold: number
+  maxHops: number
+  enableLogging: boolean
+}
+
+export interface RoutingContext {
+  request: UserRequest
+  state: WorkflowState
+  plan: Plan | null
+  history: ConversationHistory[]
+  config: RouterConfig
+  metadata?: Record<string, unknown>
+}
+
+// ---------------------------------------------------------------------------
+// Route Decision
+// ---------------------------------------------------------------------------
+
+export interface AlternativeRoute {
+  skill: string
+  confidence: number
+  reasoning: string
+}
+
+export interface RouteDecision {
+  skill: string
+  confidence: number
+  reasoning: string
+  namespace: string
+  alternatives: AlternativeRoute[]
+  metadata?: {
+    layer: 'core' | 'domain' | 'utility'
+    processingTime: number
+    hops: number
+  }
+}
+
+export interface RouteResult {
+  decision: RouteDecision
+  executedNamespace: string
+  allCandidates: RouteDecision[]
+}
+
+// ---------------------------------------------------------------------------
+// Namespace Router Interface
+// ---------------------------------------------------------------------------
+
+export interface NamespaceRouter {
+  /** 命名空间名称 */
+  readonly name: string
+
+  /** 命名空间所属层 */
+  readonly layer: 'core' | 'domain' | 'utility'
+
+  /** 优先级，越高越先匹配 (0-100) */
+  readonly priority: number
+
+  /** 匹配模式（关键词正则） */
+  readonly patterns: RegExp[]
+
+  /**
+   * 检查此命名空间是否可以处理该请求
+   * 快速检查，不需要完整路由逻辑
+   */
+  canRoute(context: RoutingContext): boolean | Promise<boolean>
+
+  /**
+   * 执行路由决策
+   * 返回此命名空间的推荐路由
+   */
+  route(context: RoutingContext): RouteDecision | Promise<RouteDecision>
+
+  /**
+   * 获取此命名空间支持的所有技能
+   */
+  getSupportedSkills(): string[]
+
+  /**
+   * 获取健康状态
+   */
+  getHealth(): NamespaceHealth
+}
+
+export interface NamespaceHealth {
+  name: string
+  status: 'healthy' | 'degraded' | 'unhealthy'
+  totalRoutes: number
+  successRate: number
+  avgLatency: number
+}
+
+// ---------------------------------------------------------------------------
+// Subagent Dispatch
+// ---------------------------------------------------------------------------
+
+export interface SubagentRouteRequest {
+  role: SubagentConfig['role']
+  prompt: string
+  expectedOutput: string
+  timeout?: number
+}
+
+export interface SubagentRouteResponse {
+  skill: string
+  confidence: number
+  reasoning: string
+  alternatives?: AlternativeRoute[]
+}
+
+// ---------------------------------------------------------------------------
+// Namespace Registry
+// ---------------------------------------------------------------------------
+
+export interface NamespaceRegistry {
+  register(router: NamespaceRouter): void
+  unregister(name: string): void
+  get(name: string): NamespaceRouter | undefined
+  list(): NamespaceRouter[]
+  listByLayer(layer: 'core' | 'domain' | 'utility'): NamespaceRouter[]
+  resolve(context: RoutingContext): Promise<RouteDecision>
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface NamespaceConfig {
+  core: {
+    enabled: boolean
+    routers: string[]
+  }
+  domain: {
+    enabled: boolean
+    routers: string[]
+  }
+  utility: {
+    enabled: boolean
+    routers: string[]
+  }
+}
+
+export const DEFAULT_NAMESPACE_CONFIG: NamespaceConfig = {
+  core: {
+    enabled: true,
+    routers: ['lifecycle', 'state', 'intent'],
+  },
+  domain: {
+    enabled: true,
+    routers: ['plan', 'code', 'debug', 'review'],
+  },
+  utility: {
+    enabled: true,
+    routers: ['quick-task', 'research', 'fallback'],
+  },
+}

package/src/router/namespace/utility/fallback-router.ts

@@ -0,0 +1,107 @@
+/**
+ * Fallback Router - Utility Layer
+ *
+ * 当其他所有路由都无法确定时的最终降级方案
+ * 总是返回一个有效的路由决策
+ */
+
+import type {
+  NamespaceRouter,
+  RoutingContext,
+  RouteDecision,
+  NamespaceHealth,
+  AlternativeRoute,
+} from '../types.js'
+
+export class FallbackRouter implements NamespaceRouter {
+  readonly name = 'fallback'
+  readonly layer = 'utility' as const
+  readonly priority = 0 // 最低优先级
+  readonly patterns = [/.*/s] // 匹配所有
+
+  private routeCount = 0
+  private successCount = 0
+  private totalLatency = 0
+
+  async canRoute(context: RoutingContext): Promise<boolean> {
+    // 总是可以路由
+    return true
+  }
+
+  async route(context: RoutingContext): Promise<RouteDecision> {
+    const startTime = Date.now()
+    const { state, request } = context
+
+    this.routeCount++
+    this.totalLatency += Date.now() - startTime
+    this.successCount++
+
+    // 基于状态选择最合适的降级技能
+    const fallbackSkill = this.selectFallbackSkill(state, request.text)
+
+    return {
+      skill: fallbackSkill,
+      confidence: 0.4, // 低置信度
+      reasoning: `Fallback decision: ambiguous request, defaulting to ${fallbackSkill} based on phase ${state.phase}`,
+      namespace: this.name,
+      alternatives: [
+        { skill: 'quick-task', confidence: 0.3, reasoning: 'Quick approach' },
+        { skill: 'to-plan', confidence: 0.2, reasoning: 'Conservative approach' },
+      ],
+      metadata: {
+        layer: this.layer,
+        processingTime: Date.now() - startTime,
+        hops: 1,
+      },
+    }
+  }
+
+  /**
+   * 选择最合适的降级技能
+   */
+  private selectFallbackSkill(state: RoutingContext['state'], requestText: string): string {
+    // 基于生命周期阶段选择
+    switch (state.phase) {
+      case 'planning':
+        return 'to-plan'
+      case 'executing':
+        return 'execute-plan'
+      case 'verifying':
+        return 'review-diff'
+      case 'completed':
+        return 'quick-task'
+      case 'failed':
+        return 'systematic-debugging'
+      default:
+        // 基于请求内容启发式选择
+        if (requestText.length > 100) {
+          return 'to-plan' // 复杂请求需要规划
+        }
+        if (/fix|error|bug|fail/i.test(requestText)) {
+          return 'systematic-debugging' // 可能是错误
+        }
+        return 'quick-task' // 默认快速任务
+    }
+  }
+
+  getSupportedSkills(): string[] {
+    return ['quick-task', 'to-plan', 'execute-plan', 'systematic-debugging', 'review-diff']
+  }
+
+  getHealth(): NamespaceHealth {
+    return {
+      name: this.name,
+      status: 'healthy', // fallback 总是健康
+      totalRoutes: this.routeCount,
+      successRate: this.successRate(),
+      avgLatency: this.routeCount > 0 ? this.totalLatency / this.routeCount : 0,
+    }
+  }
+
+  private successRate(): number {
+    return this.routeCount > 0 ? this.successCount / this.routeCount : 1.0
+  }
+}
+
+export const fallbackRouter = new FallbackRouter()
+export default fallbackRouter