@haoyiyin/workflow 0.2.11 → 0.3.1

package/src/router/namespace/README.md

@@ -0,0 +1,127 @@
+# Namespace 路由分层设计
+
+## 架构概述
+
+Namespace 路由分层设计将路由系统组织成层次化的命名空间，每个命名空间负责特定领域的路由决策。
+
+```
+Router (根命名空间)
+├── Core (核心命名空间)
+│   ├── LifecycleRouter    - 生命周期阶段路由
+│   ├── StateRouter        - 状态感知路由
+│   └── IntentRouter       - 意图分类路由
+├── Domain (领域命名空间)
+│   ├── PlanRouter         - 计划相关路由
+│   ├── CodeRouter         - 代码操作路由
+│   ├── DebugRouter        - 调试相关路由
+│   └── ReviewRouter       - 代码审查路由
+└── Utility (工具命名空间)
+    ├── QuickTaskRouter    - 快速任务路由
+    ├── ResearchRouter     - 研究探索路由
+    └── FallbackRouter     - 降级路由
+```
+
+## 分层原则
+
+### Layer 1: 核心层 (Core)
+负责基础路由决策：
+- **LifecycleRouter**: 根据项目生命周期阶段选择可用技能
+- **StateRouter**: 根据 STATE.md 和 PLAN.md 的状态进行路由
+- **IntentRouter**: 基于用户意图的分类和匹配
+
+### Layer 2: 领域层 (Domain)
+负责特定领域的复杂路由：
+- **PlanRouter**: 计划创建、执行、验证的完整流程
+- **CodeRouter**: 代码编写、重构、测试相关的路由
+- **DebugRouter**: 调试、错误诊断、修复建议
+- **ReviewRouter**: 代码审查、质量检查
+
+### Layer 3: 工具层 (Utility)
+处理简单的、独立的路由决策：
+- **QuickTaskRouter**: 小任务、快速修复
+- **ResearchRouter**: 研究、探索、信息收集
+- **FallbackRouter**: 当其他路由无法确定时使用
+
+## 路由流程
+
+```
+用户请求
+    ↓
+[Core Layer]
+  - 检查生命周期
+  - 读取 STATE/PLAN
+  - 提取意图
+    ↓
+[Domain Layer] (如果匹配)
+  - 领域特定路由逻辑
+  - 复杂决策流程
+    ↓
+[Utility Layer] (如果 Domain 不匹配)
+  - 简单匹配
+  - 快速决策
+    ↓
+选择目标 Skill
+```
+
+## Namespace 接口
+
+```typescript
+// 命名空间路由接口
+interface NamespaceRouter {
+  readonly name: string
+  readonly priority: number  // 优先级，越高越先匹配
+  readonly patterns: string[] // 匹配模式
+
+  // 检查是否可以处理此请求
+  canRoute(context: RoutingContext): boolean | Promise<boolean>
+
+  // 执行路由决策
+  route(context: RoutingContext): RouteDecision | Promise<RouteDecision>
+}
+
+// 路由上下文
+interface RoutingContext {
+  request: UserRequest
+  state: WorkflowState
+  plan: Plan | null
+  history: ConversationHistory[]
+  config: RouterConfig
+}
+
+// 路由决策
+interface RouteDecision {
+  skill: string
+  confidence: number
+  reasoning: string
+  namespace: string // 来源命名空间
+  alternatives: AlternativeRoute[]
+}
+```
+
+## 配置示例
+
+```typescript
+// router.config.ts
+export const namespaceConfig: NamespaceConfig = {
+  core: {
+    enabled: true,
+    routers: ['lifecycle', 'state', 'intent'],
+  },
+  domain: {
+    enabled: true,
+    routers: ['plan', 'code', 'debug', 'review'],
+  },
+  utility: {
+    enabled: true,
+    routers: ['quick-task', 'research', 'fallback'],
+  },
+}
+```
+
+## 扩展性
+
+新增命名空间只需：
+1. 创建命名空间目录
+2. 实现 NamespaceRouter 接口
+3. 在配置中注册
+4. 系统自动加载并按优先级排序

package/src/router/namespace/core/intent-router.ts

@@ -0,0 +1,221 @@
+/**
+ * Intent Router - Core Layer
+ *
+ * 基于用户意图的分类进行路由决策
+ * 使用关键词和模式匹配提取意图
+ */
+
+import type {
+  NamespaceRouter,
+  RoutingContext,
+  RouteDecision,
+  NamespaceHealth,
+  AlternativeRoute,
+} from '../types.js'
+
+// 意图定义
+interface IntentPattern {
+  name: string
+  patterns: RegExp[]
+  targetSkill: string
+  confidence: number
+  complexity: 'low' | 'medium' | 'high'
+}
+
+const INTENTS: IntentPattern[] = [
+  {
+    name: 'plan',
+    patterns: [
+      /plan|设计|架构|方案/i,
+      /how to implement|如何实现/i,
+      /architecture|结构/i,
+      /strategy|策略/i,
+    ],
+    targetSkill: 'to-plan',
+    confidence: 0.85,
+    complexity: 'high',
+  },
+  {
+    name: 'execute',
+    patterns: [
+      /implement|实现|完成/i,
+      /build|创建|建立/i,
+      /develop|开发/i,
+      /execute|执行/i,
+    ],
+    targetSkill: 'execute-plan',
+    confidence: 0.8,
+    complexity: 'high',
+  },
+  {
+    name: 'fix',
+    patterns: [
+      /fix|修复|解决/i,
+      /correct|修正/i,
+      /update|更新.*(typo|typo|错误)/i,
+    ],
+    targetSkill: 'quick-task',
+    confidence: 0.75,
+    complexity: 'low',
+  },
+  {
+    name: 'debug',
+    patterns: [
+      /debug|调试/i,
+      /bug|错误|故障/i,
+      /error|异常/i,
+      /not working|不工作|失效/i,
+      /investigate|调查/i,
+    ],
+    targetSkill: 'systematic-debugging',
+    confidence: 0.85,
+    complexity: 'medium',
+  },
+  {
+    name: 'review',
+    patterns: [
+      /review|审查|检查/i,
+      /audit|审核/i,
+      /check.*quality|检查.*质量/i,
+      /code review|代码审查/i,
+    ],
+    targetSkill: 'review-diff',
+    confidence: 0.8,
+    complexity: 'medium',
+  },
+  {
+    name: 'test',
+    patterns: [
+      /test|测试/i,
+      /tdd|test.*driven/i,
+      /unit test|单元测试/i,
+      /coverage|覆盖率/i,
+    ],
+    targetSkill: 'tdd',
+    confidence: 0.85,
+    complexity: 'medium',
+  },
+  {
+    name: 'research',
+    patterns: [
+      /research|研究/i,
+      /explore|探索/i,
+      /find out|查找/i,
+      /learn about|了解/i,
+      /what is|什么是/i,
+      /how does|如何.*工作/i,
+    ],
+    targetSkill: 'research',
+    confidence: 0.7,
+    complexity: 'low',
+  },
+  {
+    name: 'docs',
+    patterns: [
+      /document|文档/i,
+      /claude\.md|agents\.md/i,
+      /readme|说明/i,
+      /update.*doc|更新.*文档/i,
+    ],
+    targetSkill: 'agents-md',
+    confidence: 0.75,
+    complexity: 'low',
+  },
+]
+
+export class IntentRouter implements NamespaceRouter {
+  readonly name = 'intent'
+  readonly layer = 'core' as const
+  readonly priority = 80
+  readonly patterns = INTENTS.flatMap((i) => i.patterns)
+
+  private routeCount = 0
+  private successCount = 0
+  private totalLatency = 0
+
+  async canRoute(context: RoutingContext): Promise<boolean> {
+    // 检查是否能匹配到任何意图
+    const request = context.request.text.toLowerCase()
+    return INTENTS.some((intent) => intent.patterns.some((p) => p.test(request)))
+  }
+
+  async route(context: RoutingContext): Promise<RouteDecision> {
+    const startTime = Date.now()
+    const requestText = context.request.text.toLowerCase()
+
+    // 计算每个意图的匹配分数
+    const scored = INTENTS.map((intent) => {
+      let score = 0
+      for (const pattern of intent.patterns) {
+        if (pattern.test(requestText)) {
+          score += intent.confidence / intent.patterns.length
+        }
+      }
+      return { intent, score }
+    }).filter((s) => s.score > 0)
+
+    // 按分数排序
+    scored.sort((a, b) => b.score - a.score)
+
+    const best = scored[0]
+    const alternatives: AlternativeRoute[] = scored.slice(1, 4).map((s) => ({
+      skill: s.intent.targetSkill,
+      confidence: s.score,
+      reasoning: `Intent: ${s.intent.name}`,
+    }))
+
+    this.routeCount++
+    this.totalLatency += Date.now() - startTime
+
+    if (best) {
+      this.successCount++
+      return {
+        skill: best.intent.targetSkill,
+        confidence: Math.min(best.score, 1.0),
+        reasoning: `Intent matched: ${best.intent.name} (${best.intent.complexity} complexity)`,
+        namespace: this.name,
+        alternatives,
+        metadata: {
+          layer: this.layer,
+          processingTime: Date.now() - startTime,
+          hops: 1,
+        },
+      }
+    }
+
+    // 无匹配
+    return {
+      skill: 'quick-task',
+      confidence: 0.3,
+      reasoning: 'No clear intent matched',
+      namespace: this.name,
+      alternatives: [],
+      metadata: {
+        layer: this.layer,
+        processingTime: Date.now() - startTime,
+        hops: 1,
+      },
+    }
+  }
+
+  getSupportedSkills(): string[] {
+    return INTENTS.map((i) => i.targetSkill)
+  }
+
+  getHealth(): NamespaceHealth {
+    return {
+      name: this.name,
+      status: this.successRate() > 0.7 ? 'healthy' : 'degraded',
+      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 intentRouter = new IntentRouter()
+export default intentRouter

package/src/router/namespace/core/lifecycle-router.ts

@@ -0,0 +1,156 @@
+/**
+ * Lifecycle Router - Core Layer
+ *
+ * 基于项目生命周期阶段进行路由决策
+ * 生命周期: idle → planning → executing → verifying → completed
+ */
+
+import type {
+  NamespaceRouter,
+  RoutingContext,
+  RouteDecision,
+  NamespaceHealth,
+  AlternativeRoute,
+} from '../types.js'
+
+// 各阶段可用的技能
+const SKILLS_BY_PHASE: Record<string, string[]> = {
+  idle: ['to-plan', 'research', 'quick-task', 'agents-md'],
+  planning: ['to-plan', 'research', 'review-diff', 'agents-md'],
+  executing: ['execute-plan', 'quick-task', 'tdd', 'systematic-debugging'],
+  verifying: ['review-diff', 'systematic-debugging', 'execute-plan'],
+  completed: ['review-diff', 'agents-md', 'research'],
+  failed: ['systematic-debugging', 'to-plan', 'review-diff'],
+}
+
+export class LifecycleRouter implements NamespaceRouter {
+  readonly name = 'lifecycle'
+  readonly layer = 'core' as const
+  readonly priority = 90
+  readonly patterns = [
+    /plan|规划|设计/i,
+    /execute|执行|实现/i,
+    /debug|调试|fix/i,
+    /review|审查|review/i,
+    /complete|完成|结束/i,
+  ]
+
+  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 phase = context.state.phase
+    const availableSkills = SKILLS_BY_PHASE[phase] || SKILLS_BY_PHASE.idle
+
+    // 基于请求内容匹配最佳技能
+    const requestText = context.request.text.toLowerCase()
+    let bestSkill: string | null = null
+    let bestScore = 0
+    const alternatives: AlternativeRoute[] = []
+
+    for (const skill of availableSkills) {
+      const score = this.calculateSkillScore(skill, requestText, phase)
+      if (score > bestScore) {
+        // 当前最佳变为备选
+        if (bestSkill) {
+          alternatives.push({
+            skill: bestSkill,
+            confidence: bestScore,
+            reasoning: `Matched lifecycle phase ${phase}`,
+          })
+        }
+        bestSkill = skill
+        bestScore = score
+      } else if (score > 0.3) {
+        alternatives.push({
+          skill,
+          confidence: score,
+          reasoning: `Alternative for ${phase} phase`,
+        })
+      }
+    }
+
+    this.routeCount++
+    this.totalLatency += Date.now() - startTime
+    if (bestSkill) this.successCount++
+
+    return {
+      skill: bestSkill || 'quick-task',
+      confidence: bestScore || 0.5,
+      reasoning: `Lifecycle phase: ${phase}. Available: ${availableSkills.join(', ')}`,
+      namespace: this.name,
+      alternatives: alternatives.slice(0, 3),
+      metadata: {
+        layer: this.layer,
+        processingTime: Date.now() - startTime,
+        hops: 1,
+      },
+    }
+  }
+
+  /**
+   * 计算技能匹配分数
+   */
+  private calculateSkillScore(skill: string, request: string, phase: string): number {
+    const keywordMap: Record<string, string[]> = {
+      'to-plan': ['plan', 'design', 'architecture', '规划', '设计'],
+      'execute-plan': ['implement', 'build', 'execute', '实现', '执行'],
+      'quick-task': ['fix', 'typo', 'rename', 'small', '快速', '修复'],
+      'review-diff': ['review', 'audit', 'check', '审查', '检查'],
+      'systematic-debugging': ['debug', 'bug', 'error', '调试', '错误'],
+      'tdd': ['test', 'tdd', '测试'],
+      'research': ['research', 'explore', 'learn', '研究', '探索'],
+      'agents-md': ['agent', 'claude.md', 'agents.md', '文档'],
+    }
+
+    const keywords = keywordMap[skill] || []
+    let score = 0
+
+    for (const keyword of keywords) {
+      if (request.includes(keyword.toLowerCase())) {
+        score += 0.2
+      }
+    }
+
+    // 根据生命周期阶段调整分数
+    const phaseBoost: Record<string, Record<string, number>> = {
+      planning: { 'to-plan': 0.3, 'research': 0.2 },
+      executing: { 'execute-plan': 0.3, 'tdd': 0.2, 'quick-task': 0.1 },
+      verifying: { 'review-diff': 0.3, 'systematic-debugging': 0.2 },
+    }
+
+    if (phaseBoost[phase]?.[skill]) {
+      score += phaseBoost[phase][skill]
+    }
+
+    return Math.min(score, 1.0)
+  }
+
+  getSupportedSkills(): string[] {
+    return Object.values(SKILLS_BY_PHASE).flat()
+  }
+
+  getHealth(): NamespaceHealth {
+    return {
+      name: this.name,
+      status: this.successRate() > 0.8 ? 'healthy' : 'degraded',
+      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 lifecycleRouter = new LifecycleRouter()
+export default lifecycleRouter

package/src/router/namespace/core/state-router.ts

@@ -0,0 +1,192 @@
+/**
+ * State Router - Core Layer
+ *
+ * 基于 STATE.md 和 PLAN.md 的状态进行路由决策
+ * 优先使用状态信号而非关键词匹配
+ */
+
+import type {
+  NamespaceRouter,
+  RoutingContext,
+  RouteDecision,
+  NamespaceHealth,
+  AlternativeRoute,
+} from '../types.js'
+
+export class StateRouter implements NamespaceRouter {
+  readonly name = 'state'
+  readonly layer = 'core' as const
+  readonly priority = 95 // 高于 lifecycle
+  readonly patterns = [
+    /state|状态/i,
+    /plan|计划/i,
+    /continue|继续/i,
+    /resume|恢复/i,
+  ]
+
+  private routeCount = 0
+  private successCount = 0
+  private totalLatency = 0
+
+  async canRoute(context: RoutingContext): Promise<boolean> {
+    // 如果有 plan 或 state 信息，可以路由
+    return context.plan !== null || context.state.phase !== 'idle'
+  }
+
+  async route(context: RoutingContext): Promise<RouteDecision> {
+    const startTime = Date.now()
+    const { state, plan, request } = context
+
+    // 基于状态的路由决策
+    const decision = this.makeStateBasedDecision(state, plan, request.text)
+
+    this.routeCount++
+    this.totalLatency += Date.now() - startTime
+    this.successCount++
+
+    return {
+      ...decision,
+      namespace: this.name,
+      metadata: {
+        layer: this.layer,
+        processingTime: Date.now() - startTime,
+        hops: 1,
+      },
+    }
+  }
+
+  /**
+   * 基于状态的路由决策
+   */
+  private makeStateBasedDecision(
+    state: RoutingContext['state'],
+    plan: RoutingContext['plan'],
+    requestText: string
+  ): Omit<RouteDecision, 'namespace' | 'metadata'> {
+    const alternatives: AlternativeRoute[] = []
+
+    // 规则1: 如果有 plan 且未完成，默认路由到 execute-plan
+    if (plan && state.phase === 'executing') {
+      const completedCount = state.completedTasks?.length || 0
+      const totalCount = plan.tasks?.length || 0
+      const progress = totalCount > 0 ? completedCount / totalCount : 0
+
+      // 检查是否继续执行
+      if (progress < 1.0) {
+        return {
+          skill: 'execute-plan',
+          confidence: 0.9,
+          reasoning: `Plan exists with ${completedCount}/${totalCount} tasks complete. Phase: ${state.phase}`,
+          alternatives: [
+            { skill: 'quick-task', confidence: 0.3, reasoning: 'Small task bypass' },
+          ],
+        }
+      }
+    }
+
+    // 规则2: 如果正在 verifying，路由到 review-diff
+    if (state.phase === 'verifying') {
+      return {
+        skill: 'review-diff',
+        confidence: 0.85,
+        reasoning: `Phase is ${state.phase}, need verification`,
+        alternatives: [
+          { skill: 'systematic-debugging', confidence: 0.4, reasoning: 'If verification fails' },
+        ],
+      }
+    }
+
+    // 规则3: 如果有 plan 但还没开始执行
+    if (plan && state.phase === 'planning') {
+      return {
+        skill: 'execute-plan',
+        confidence: 0.8,
+        reasoning: `Plan ready (${plan.tasks?.length || 0} tasks), waiting to execute`,
+        alternatives: [
+          { skill: 'to-plan', confidence: 0.3, reasoning: 'Revise plan' },
+        ],
+      }
+    }
+
+    // 规则4: 如果用户说 "continue" 或 "继续"
+    if (/^\s*(continue|resume|proceed|继续|恢复)/i.test(requestText)) {
+      if (plan) {
+        return {
+          skill: 'execute-plan',
+          confidence: 0.95,
+          reasoning: 'User requested to continue with existing plan',
+          alternatives: [],
+        }
+      }
+    }
+
+    // 规则5: 默认情况 - 检查是否需要创建 plan
+    if (!plan && state.phase === 'idle') {
+      // 请求复杂度检测
+      const isComplex = this.isComplexRequest(requestText)
+      if (isComplex) {
+        return {
+          skill: 'to-plan',
+          confidence: 0.75,
+          reasoning: 'No plan exists and request appears complex',
+          alternatives: [
+            { skill: 'quick-task', confidence: 0.4, reasoning: 'Simple approach' },
+            { skill: 'research', confidence: 0.3, reasoning: 'Need more info' },
+          ],
+        }
+      }
+    }
+
+    // 默认返回 low confidence
+    return {
+      skill: 'quick-task',
+      confidence: 0.3,
+      reasoning: `State-based routing default: ${state.phase}, no plan`,
+      alternatives: [],
+    }
+  }
+
+  /**
+   * 判断请求是否复杂（需要创建 plan）
+   */
+  private isComplexRequest(request: string): boolean {
+    const complexityIndicators = [
+      /implement|实现/i,
+      /feature|功能/i,
+      /refactor|重构/i,
+      /architecture|架构/i,
+      /design|设计/i,
+      /multiple|多个/i,
+      /steps?|步骤/i,
+      /phase|阶段/i,
+    ]
+
+    const indicatorCount = complexityIndicators.filter((pattern) =>
+      pattern.test(request)
+    ).length
+
+    // 如果匹配多个复杂度指标，认为是复杂请求
+    return indicatorCount >= 2 || request.length > 100
+  }
+
+  getSupportedSkills(): string[] {
+    return ['to-plan', 'execute-plan', 'quick-task', 'review-diff', 'systematic-debugging', 'research']
+  }
+
+  getHealth(): NamespaceHealth {
+    return {
+      name: this.name,
+      status: this.successRate() > 0.8 ? 'healthy' : 'degraded',
+      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 stateRouter = new StateRouter()
+export default stateRouter