@haoyiyin/workflow 0.2.10 → 0.3.0

package/src/persistence/index.ts

@@ -1,8 +1,14 @@
 /**
- * Persistence layer exports
+ * Persistence layer entry point
+ *
+ * Provides STATE.md and PLAN.md management for workflow state persistence.
  */
+
+// Managers
 export { StateMdManager } from './state-md.js'
 export { PlanMdManager } from './plan-md.js'
+
+// Types
 export type {
   Task,
   Wave,
@@ -11,7 +17,7 @@ export type {
   VerificationResult,
   DimensionResult,
   WorkflowState,
-  StateMdManager as IStateMdManager,
-  PlanMdManager as IPlanMdManager,
-  PersistenceManager
+  StateMdManager as StateMdManagerInterface,
+  PlanMdManager as PlanMdManagerInterface,
+  PersistenceManager,
 } from './types.js'

package/src/persistence/plan-md.ts

@@ -3,7 +3,7 @@
  */
 import { promises as fs } from 'fs'
 import { dirname } from 'path'
-import type { Plan, Task, PlanMdManager as IPlanMdManager } from './types.js'
+import type { Plan, Task, Wave, PlanMdManager as IPlanMdManager } from './types.js'
 
 export class PlanMdManager implements IPlanMdManager {
   private planPath: string
@@ -20,9 +20,16 @@ export class PlanMdManager implements IPlanMdManager {
     await fs.writeFile(this.planPath, content, 'utf-8')
   }
 
-  async readPlan(): Promise<Plan> {
-    const content = await fs.readFile(this.planPath, 'utf-8')
-    return this.parsePlan(content)
+  async readPlan(): Promise<Plan | null> {
+    try {
+      const content = await fs.readFile(this.planPath, 'utf-8')
+      return this.parsePlan(content)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return null
+      }
+      throw error
+    }
   }
 
   async updateTaskStatus(taskId: string, status: 'pending' | 'in_progress' | 'complete'): Promise<void> {
@@ -35,14 +42,37 @@ export class PlanMdManager implements IPlanMdManager {
     await fs.writeFile(this.planPath, updated, 'utf-8')
   }
 
+  async getNextPendingWave(): Promise<Wave | null> {
+    const plan = await this.readPlan()
+    if (!plan) {
+      return null
+    }
+
+    // Find first wave with pending tasks
+    for (const wave of plan.waves) {
+      const hasPendingTask = wave.tasks.some(task => task.status === 'pending')
+      if (hasPendingTask) {
+        return wave
+      }
+    }
+
+    return null
+  }
+
   private generatePlanMarkdown(plan: Plan): string {
+    const getStatusChar = (status: Task['status']) => {
+      if (status === 'completed') return 'x'
+      if (status === 'in_progress') return '~'
+      return ' '
+    }
+
     return `# Execution Plan
 
 ## Goal
 ${plan.goal}
 
 ## Tasks
-${plan.tasks.map(t => `- [ ] ${t.id}: ${t.description} (${t.estimatedComplexity})`).join('\n')}
+${plan.tasks.map(t => `- [${getStatusChar(t.status)}] ${t.id}: ${t.description} (${t.estimatedComplexity})`).join('\n')}
 
 ## Dependencies
 ${Object.entries(plan.dependencies).length > 0
@@ -51,7 +81,7 @@ ${Object.entries(plan.dependencies).length > 0
     }
 
 ## Waves
-${plan.waves.map(w => `- ${w.id}: ${w.tasks.join(', ')}`).join('\n')}
+${plan.waves.map(w => `- ${w.id}: ${w.tasks.map(t => t.id).join(', ')}`).join('\n')}
 
 ## Verification Criteria
 ${plan.verificationCriteria.map(c => `- ${c}`).join('\n')}
@@ -60,9 +90,6 @@ ${plan.verificationCriteria.map(c => `- ${c}`).join('\n')}
 - Total Tasks: ${plan.tasks.length}
 - Parallel Waves: ${plan.waves.length}
 - Estimated Duration: ${plan.estimatedDuration}ms
-
-## Rationale
-${plan.rationale}
 `
   }
 
@@ -73,19 +100,22 @@ ${plan.rationale}
     const wavesMatch = content.match(/## Waves\n([\s\S]*?)(?=\n## |$)/)
     const criteriaMatch = content.match(/## Verification Criteria\n([\s\S]*?)(?=\n## |$)/)
     const durationMatch = content.match(/- Estimated Duration: (\d+)/)
-    const rationaleMatch = content.match(/## Rationale\n([\s\S]*?)(?=\n## |$)/)
 
     // Parse tasks
     const tasks: Task[] = []
     if (tasksMatch) {
       const taskLines = tasksMatch[1].split('\n').filter(l => l.trim().startsWith('- ['))
       for (const line of taskLines) {
-        const match = line.match(/- \[[x\s~]]\s+(\w+):\s+(.+)\s+\((\w+)\)/)
+        const match = line.match(/- \[(.)\]\s+(\w+):\s+(.+)\s+\((\w+)\)/)
         if (match) {
+          const statusChar = match[1]
+          const status = statusChar === 'x' ? 'completed' : statusChar === '~' ? 'in_progress' : 'pending'
           tasks.push({
-            id: match[1],
-            description: match[2],
-            estimatedComplexity: match[3] as 'low' | 'medium' | 'high'
+            id: match[2],
+            description: match[3],
+            status,
+            dependencies: [],
+            estimatedComplexity: match[4] as 'low' | 'medium' | 'high'
           })
         }
       }
@@ -103,16 +133,21 @@ ${plan.rationale}
       }
     }
 
+    // Build task map for wave parsing
+    const taskMap = new Map<string, Task>(tasks.map(t => [t.id, t]))
+
     // Parse waves
-    const waves = []
+    const waves: Wave[] = []
     if (wavesMatch) {
       const waveLines = wavesMatch[1].split('\n').filter(l => l.trim().startsWith('- '))
       for (const line of waveLines) {
         const match = line.match(/- (\w+):\s*(.+)/)
         if (match) {
+          const taskIds = match[2].split(',').map(s => s.trim()).filter(s => s)
+          const waveTasks = taskIds.map(id => taskMap.get(id)).filter((t): t is Task => t !== undefined)
           waves.push({
             id: match[1],
-            tasks: match[2].split(',').map(s => s.trim()).filter(s => s)
+            tasks: waveTasks
           })
         }
       }
@@ -134,8 +169,7 @@ ${plan.rationale}
       dependencies,
       waves,
       verificationCriteria,
-      estimatedDuration: durationMatch ? parseInt(durationMatch[1], 10) : 0,
-      rationale: rationaleMatch?.[1]?.trim() || ''
+      estimatedDuration: durationMatch ? parseInt(durationMatch[1], 10) : 0
     }
   }
 }

package/src/persistence/state-md.ts

@@ -36,10 +36,7 @@ ${goal}
 <!-- Populated by verify phase -->
 
 ## Token Usage
-- Plan Phase: 0
-- Execute Phase: 0
-- Verify Phase: 0
-- Total: 0 / 1000000
+0
 `
     await fs.writeFile(this.statePath, content, 'utf-8')
   }
@@ -65,7 +62,14 @@ ${goal}
 
   async recordTaskComplete(taskId: string, result: TaskResult): Promise<void> {
     const content = await fs.readFile(this.statePath, 'utf-8')
-    const entry = `- [x] ${taskId}: ${result.success ? '✓' : '✗'} (${result.duration}ms) - ${result.notes || ''}\n`
+    const entry = `- [x] ${taskId}: ✓ (${result.duration}ms) - ${result.notes || ''}\n`
+    const updated = this.appendToSection(content, 'Completed Tasks', entry)
+    await fs.writeFile(this.statePath, updated, 'utf-8')
+  }
+
+  async recordTaskFailed(taskId: string, error?: string): Promise<void> {
+    const content = await fs.readFile(this.statePath, 'utf-8')
+    const entry = `- [x] ${taskId}: ✗ FAILED${error ? ` - ${error}` : ''}\n`
     const updated = this.appendToSection(content, 'Completed Tasks', entry)
     await fs.writeFile(this.statePath, updated, 'utf-8')
   }
@@ -77,6 +81,15 @@ ${goal}
     await fs.writeFile(this.statePath, updated, 'utf-8')
   }
 
+  async updateTokenUsage(tokens: number): Promise<void> {
+    const content = await fs.readFile(this.statePath, 'utf-8')
+    const updated = content.replace(
+      /## Token Usage\n\d+/,
+      `## Token Usage\n${tokens}`
+    )
+    await fs.writeFile(this.statePath, updated, 'utf-8')
+  }
+
   async readCurrentState(): Promise<WorkflowState> {
     const content = await fs.readFile(this.statePath, 'utf-8')
     return this.parseState(content)
@@ -91,7 +104,7 @@ ${plan.goal}
 ${plan.tasks.map(t => `- ${t.id}: ${t.description} (${t.estimatedComplexity})`).join('\n')}
 
 ### Waves (${plan.waves.length})
-${plan.waves.map(w => `- ${w.id}: ${w.tasks.join(', ')}`).join('\n')}
+${plan.waves.map(w => `- ${w.id}: ${w.tasks.map(t => t.id).join(', ')}`).join('\n')}
 
 ### Verification Criteria
 ${plan.verificationCriteria.map(c => `- ${c}`).join('\n')}
@@ -99,8 +112,8 @@ ${plan.verificationCriteria.map(c => `- ${c}`).join('\n')}
 ### Estimated Duration
 ${plan.estimatedDuration}ms
 
-### Rationale
-${plan.rationale}
+### Dependencies
+${Object.entries(plan.dependencies).map(([taskId, deps]) => `- ${taskId}: ${deps.join(', ') || 'none'}`).join('\n')}
 `
   }
 
@@ -141,27 +154,36 @@ ${results.join('\n')}
     const phaseMatch = content.match(/- Phase: (\w+)/)
     const goalMatch = content.match(/## Goal\n(.+)/)
     const startedMatch = content.match(/- Started: (.+)/)
-    const totalMatch = content.match(/### Tasks \((\d+)\)/)
+    const lastUpdatedMatch = content.match(/- Last Updated: (.+)/)
+    const tokenMatch = content.match(/## Token Usage\n(\d+)/)
     const completedMatch = content.match(/## Completed Tasks\n([\s\S]*?)(?=\n## |$)/)
 
-    const completedTasks = completedMatch
-      ? completedMatch[1].split('\n').filter(l => l.trim().startsWith('- [x]')).length
-      : 0
-
-    const totalTasks = totalMatch ? parseInt(totalMatch[1], 10) : 0
+    const completedTasks: string[] = []
+    const failedTasks: string[] = []
+
+    if (completedMatch) {
+      const lines = completedMatch[1].split('\n').filter(l => l.trim().startsWith('- [x]'))
+      for (const line of lines) {
+        const taskIdMatch = line.match(/- \[x\] ([^:]+):/)
+        if (taskIdMatch) {
+          if (line.includes('✗ FAILED')) {
+            failedTasks.push(taskIdMatch[1])
+          } else {
+            completedTasks.push(taskIdMatch[1])
+          }
+        }
+      }
+    }
 
     return {
       goal: goalMatch?.[1] || '',
       phase: (phaseMatch?.[1] as WorkflowState['phase']) || 'planning',
-      started: startedMatch?.[1] || new Date().toISOString(),
-      lastUpdated: new Date().toISOString(),
-      totalTasks,
-      completedTasks: [],
-      tokenUsage: {
-        used: 0,
-        limit: 1000000,
-        percentage: 0
-      }
+      startedAt: startedMatch?.[1] || new Date().toISOString(),
+      lastUpdated: lastUpdatedMatch?.[1] || new Date().toISOString(),
+      completedTasks,
+      failedTasks,
+      totalTasks: 0,
+      tokenUsage: { used: tokenMatch ? parseInt(tokenMatch[1], 10) : 0, limit: 1000000, percentage: 0 }
     }
   }
 }

package/src/persistence/types.ts

@@ -5,67 +5,45 @@
 export interface Task {
   id: string
   description: string
+  status: 'pending' | 'in_progress' | 'completed' | 'failed'
+  dependencies: string[]
   estimatedComplexity: 'low' | 'medium' | 'high'
   relatedFiles?: string[]
-  verificationCriteria?: string[]
 }
 
 export interface Wave {
   id: string
-  tasks: string[]
+  tasks: Task[]
 }
 
 export interface Plan {
   goal: string
   tasks: Task[]
-  dependencies: Record<string, string[]>
   waves: Wave[]
+  dependencies: Record<string, string[]>
   verificationCriteria: string[]
   estimatedDuration: number
-  rationale: string
+}
+
+export interface WorkflowState {
+  goal: string
+  phase: 'discovery' | 'planning' | 'executing' | 'verifying' | 'completed' | 'failed' | 'idle'
+  startedAt: string
+  lastUpdated: string
+  completedTasks: string[]
+  failedTasks: string[]
+  totalTasks: number
+  tokenUsage: { used: number; limit: number; percentage: number }
 }
 
 export interface TaskResult {
   taskId: string
   success: boolean
-  filesModified: string[]
-  testsAdded: string[]
   duration: number
   notes: string
+  filesModified?: string[]
+  testsAdded?: string[]
   error?: string
-  phases?: { phase: string; status: string; command?: string; evidence?: string }[]
-  worktreePath?: string
-  branchName?: string
-}
-
-export interface VerificationResult {
-  success: boolean
-  dimensions: {
-    goals?: DimensionResult
-    quality?: DimensionResult
-    tests?: DimensionResult
-  }
-}
-
-export interface DimensionResult {
-  success: boolean
-  details?: unknown
-  evidence?: string[]
-  gaps?: string[]
-}
-
-export interface WorkflowState {
-  goal: string
-  phase: 'planning' | 'executing' | 'verifying' | 'complete'
-  started: string
-  lastUpdated: string
-  totalTasks: number
-  completedTasks: TaskResult[]
-  tokenUsage: {
-    used: number
-    limit: number
-    percentage: number
-  }
 }
 
 export interface StateMdManager {
@@ -73,17 +51,36 @@ export interface StateMdManager {
   updatePhase(phase: WorkflowState['phase']): Promise<void>
   recordPlan(plan: Plan): Promise<void>
   recordTaskComplete(taskId: string, result: TaskResult): Promise<void>
+  recordTaskFailed(taskId: string, error?: string): Promise<void>
   recordVerification(verification: VerificationResult): Promise<void>
+  updateTokenUsage(tokens: number): Promise<void>
   readCurrentState(): Promise<WorkflowState>
 }
 
 export interface PlanMdManager {
   writePlan(plan: Plan): Promise<void>
-  readPlan(): Promise<Plan>
+  readPlan(): Promise<Plan | null>
   updateTaskStatus(taskId: string, status: 'pending' | 'in_progress' | 'complete'): Promise<void>
+  getNextPendingWave(): Promise<Wave | null>
 }
 
 export interface PersistenceManager {
   state: StateMdManager
   plan: PlanMdManager
 }
+
+export interface VerificationResult {
+  success: boolean
+  dimensions: {
+    goals?: DimensionResult
+    quality?: DimensionResult
+    tests?: DimensionResult
+  }
+}
+
+export interface DimensionResult {
+  success: boolean
+  details?: unknown
+  evidence?: string[]
+  gaps?: string[]
+}

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. 系统自动加载并按优先级排序