第三章：系统架构

3.1 架构总览

OpenMatrix 采用分层架构设计，清晰分离各层职责。

分层架构图

graph TD
    subgraph "接口层 Interface Layer"
        CLI[CLI Commands]
        SK[Skills]
    end
    
    subgraph "编排层 Orchestration Layer"
        OR[Orchestrator]
        EX[Executor]
        SC[Scheduler]
        SM[State Machine]
        PE[Phase Executor]
        MM[Meeting Manager]
        AM[Approval Manager]
    end
    
    subgraph "执行层 Execution Layer"
        AR[Agent Runner]
        AG[Agents]
    end
    
    subgraph "存储层 Storage Layer"
        FS[File Store]
        STM[State Manager]
    end
    
    CLI --> OR
    SK --> OR
    
    OR --> EX
    EX --> SC
    EX --> SM
    EX --> PE
    EX --> MM
    EX --> AM
    
    EX --> AR
    AR --> AG
    
    EX --> STM
    STM --> FS

层级职责

层级	组件	职责
接口层	CLI, Skills	用户交互入口
编排层	Orchestrator	任务调度、状态管理、流程控制
执行层	Agent Runner, Agents	任务执行、代码生成
存储层	File Store, State Manager	状态持久化、文件管理

3.2 接口层

CLI 模块

CLI 使用 Commander.js 实现，提供命令行交互。

// cli/index.ts
import { Command } from 'commander';

const program = new Command();
program
  .command('start')
  .description('Start new task execution')
  .action(() => startCommand());

program
  .command('auto')
  .description('Fully automatic execution')
  .action(() => autoCommand());

核心命令：

命令	功能	参数
`start`	交互式启动任务	`--quality`, `--mode`
`auto`	自动执行	`--bypass-approvals`
`status`	查看状态	`--json`
`approve`	处理审批	`--all`
`meeting`	处理阻塞	`--skip`, `--resolve`
`resume`	恢复执行	无
`retry`	重试失败	`--task TASK-XXX`
`report`	生成报告	`--format json
`step`	获取下一任务	`--json`
`complete`	完成任务	`--success`, `--summary`

Skills 模块

Skills 是 Claude Code 的扩展机制，位于 ~/.claude/commands/om/。

graph LR
    A[用户输入 /om:start] --> B[Claude Code]
    B --> C[加载 ~/.claude/commands/om/start.md]
    C --> D[解析 YAML frontmatter]
    D --> E[执行 Skill 内容]
    E --> F[调用 OpenMatrix CLI]

Skill 文件结构：

---
name: start
description: Interactive task start with quality/mode selection
---

# /om:start

Start a new task execution cycle with interactive quality selection...

```bash
openmatrix start --quality "$quality" --mode "$mode"
```

3.3 编排层

编排层是 OpenMatrix 的核心，负责任务调度和流程控制。

Orchestrator 组件图

graph TD
    subgraph "核心组件"
        EX[Executor<br/>主执行循环]
        SC[Scheduler<br/>任务调度]
        SM[StateMachine<br/>状态转换]
    end
    
    subgraph "阶段组件"
        PE[PhaseExecutor<br/>四阶段执行]
        TP[TaskPlanner<br/>任务拆解]
    end
    
    subgraph "管理组件"
        MM[MeetingManager<br/>阻塞管理]
        AM[ApprovalManager<br/>审批管理]
        RM[RetryManager<br/>重试管理]
        GC[GitCommitManager<br/>自动提交]
    end
    
    EX --> SC
    EX --> SM
    EX --> PE
    EX --> MM
    EX --> AM
    
    PE --> TP
    PE --> MM
    PE --> RM
    
    EX --> GC

Executor（主执行器）

Executor 是编排层的主控制器：

interface Executor {
  // 主执行循环
  execute(input: TaskInput): Promise<ExecutionResult>;
  
  // 返回 Agent 执行任务列表
  getSubagentTasks(): SubagentTask[];
  
  // 处理任务完成
  handleTaskComplete(taskId: string, result: TaskResult): void;
}

执行流程：

graph TD
    A[execute] --> B[初始化存储]
    B --> C[TaskPlanner 拆解]
    C --> D[Scheduler 调度]
    D --> E{获取下一个任务}
    E --> F[PhaseExecutor 执行]
    F --> G{任务结果}
    G --> |"成功"| H[更新状态]
    G --> |"阻塞"| I[MeetingManager]
    G --> |"失败"| J[RetryManager]
    H --> K{还有任务?}
    I --> K
    J --> K
    K --> |"有"| E
    K --> |"无"| L[生成报告]

Scheduler（调度器）

Scheduler 负责：

任务优先级排序
依赖关系解析
循环依赖检测

interface Scheduler {
  // 获取下一个可执行任务
  getNextTask(): Task | null;
  
  // 检查依赖是否满足
  checkDependencies(taskId: string): boolean;
  
  // 检测循环依赖
  detectCircularDependency(): string[];
}

调度算法：

graph TD
    A[getNextTask] --> B[获取 scheduled 状态任务]
    B --> C[按优先级排序]
    C --> D[遍历任务]
    D --> E{依赖满足?}
    E --> |"是"| F[返回该任务]
    E --> |"否"| G[检查下一个]
    G --> D
    D --> |"无可用任务"| H[返回 null]

StateMachine（状态机）

StateMachine 管理任务状态转换：

interface StateMachine {
  // 状态转换
  transition(taskId: string, newStatus: TaskStatus): void;
  
  // 获取有效转换
  getValidTransitions(currentStatus: TaskStatus): TaskStatus[];
  
  // 检查转换是否有效
  isValidTransition(from: TaskStatus, to: TaskStatus): boolean;
}

状态转换表：

当前状态	有效转换
pending	scheduled
scheduled	in_progress
in_progress	verify, blocked
blocked	waiting
waiting	scheduled
verify	accept, failed
accept	completed, failed
failed	retry_queue
retry_queue	scheduled

PhaseExecutor（阶段执行器）

PhaseExecutor 执行任务的四阶段：

interface PhaseExecutor {
  // 执行指定阶段
  executePhase(taskId: string, phase: PhaseType): Promise<PhaseResult>;
  
  // 获取当前阶段
  getCurrentPhase(taskId: string): PhaseType;
  
  // 检查阶段是否可进入
  canEnterPhase(taskId: string, phase: PhaseType): boolean;
}

阶段执行流程（strict 模式）：

graph TD
    A[executePhase] --> B{阶段类型}
    B --> |"TDD"| C[Tester Agent]
    B --> |"Develop"| D[Coder Agent]
    B --> |"Verify"| E[Executor Agent]
    B --> |"Accept"| F[Reviewer Agent]
    
    C --> G{测试失败?}
    G --> |"是"| H[通过]
    G --> |"否"| I[失败]
    
    D --> J{测试通过?}
    J --> |"是"| K[通过]
    J --> |"否"| L[失败]
    
    E --> M{质量门禁?}
    M --> |"全部通过"| N[通过]
    M --> |"有失败"| O[失败]
    
    F --> P{审查通过?}
    P --> |"是"| Q[通过]
    P --> |"否"| R[失败]

TaskPlanner（任务规划器）

TaskPlanner 将用户指令拆解为任务列表：

interface TaskPlanner {
  // 拆解任务
  plan(input: TaskInput): Promise<Task[]>;
  
  // 分析依赖关系
  analyzeDependencies(tasks: Task[]): DependencyGraph;
  
  // 分配 Agent
  assignAgents(tasks: Task[]): void;
}

拆解流程：

graph TD
    A[用户指令] --> B[AI 分析]
    B --> C[识别子任务]
    C --> D[分析依赖关系]
    D --> E[分配 Agent]
    E --> F[生成任务列表]
    
    F --> G[TASK-001]
    F --> H[TASK-002]
    F --> I[TASK-003]

MeetingManager（阻塞管理器）

MeetingManager 处理阻塞任务：

interface MeetingManager {
  // 创建 Meeting
  createMeeting(taskId: string, blockInfo: BlockInfo): Meeting;
  
  // 获取待处理 Meeting
  getPendingMeetings(): Meeting[];
  
  // 解决 Meeting
  resolveMeeting(meetingId: string, resolution: Resolution): void;
}

ApprovalManager（审批管理器）

ApprovalManager 管理审批流程：

interface ApprovalManager {
  // 创建审批
  createApproval(type: ApprovalType, content: any): Approval;
  
  // 获取待处理审批
  getPendingApprovals(): Approval[];
  
  // 处理审批
  processApproval(approvalId: string, decision: 'approve' | 'reject'): void;
}

审批类型：

类型	触发时机
plan	任务计划生成后
merge	准备合并代码
deploy	准备部署
meeting	Meeting 需要决策

3.4 执行层

执行层负责实际任务执行。

Agent Runner

Agent Runner 准备 Agent 执行配置：

interface AgentRunner {
  // 准备 SubagentTask
  prepareSubagentTask(task: Task, phase: PhaseType): SubagentTask;
  
  // 运行 Agent
  runAgent(subagentTask: SubagentTask): Promise<AgentResult>;
}

SubagentTask 配置：

interface SubagentTask {
  subagent_type: 'general-purpose' | 'Explore' | 'Plan';
  description: string;      // "Execute TASK-001 Develop phase"
  prompt: string;           // 详细指令
  isolation?: 'worktree';   // 是否隔离执行
  taskId: string;           // TASK-001
  agentType: AgentType;     // coder
  timeout: number;          // 300000ms
  needsApproval: boolean;   // false
}

Agent 实现

每个 Agent 有特定职责：

graph TD
    subgraph "Agent 实现"
        BA[BaseAgent<br/>基类]
        
        PA[PlannerAgent]
        CA[CoderAgent]
        TA[TesterAgent]
        RA[ReviewerAgent]
        REA[ResearcherAgent]
        EXA[ExecutorAgent]
    end
    
    BA --> PA
    BA --> CA
    BA --> TA
    BA --> RA
    BA --> REA
    BA --> EXA

BaseAgent 基类：

abstract class BaseAgent {
  abstract execute(context: AgentContext): Promise<AgentResult>;
  
  // 读取上下文
  readContext(): string;
  
  // 写入上下文
  writeContext(content: string): void;
  
  // 记录决策
  logDecision(decision: Decision): void;
}

3.5 存储层

存储层提供状态持久化能力。

FileStore

FileStore 提供文件操作：

interface FileStore {
  // 读取 JSON 文件
  readJson<T>(path: string): T;
  
  // 写入 JSON 文件
  writeJson<T>(path: string, data: T): void;
  
  // 读取 Markdown 文件
  readMd(path: string): string;
  
  // 写入 Markdown 文件
  writeMd(path: string, content: string): void;
  
  // 原子追加
  atomicAppend(path: string, content: string): void;
  
  // 文件存在检查
  exists(path: string): boolean;
  
  // 删除文件
  delete(path: string): void;
}

StateManager

StateManager 管理全局状态：

interface StateManager {
  // 获取全局状态
  getState(): GlobalState;
  
  // 更新全局状态
  updateState(updates: Partial<GlobalState>): void;
  
  // 获取任务状态
  getTaskState(taskId: string): Task;
  
  // 更新任务状态
  updateTaskState(taskId: string, updates: Partial<Task>): void;
  
  // 文件锁（跨进程安全）
  acquireLock(): Promise<void>;
  releaseLock(): void;
}

文件锁机制：

graph TD
    A[acquireLock] --> B[检查 .lock 文件]
    B --> C{锁存在?}
    C --> |"是"| D[等待]
    D --> B
    C --> |"否"| E[创建锁文件]
    E --> F[执行操作]
    F --> G[releaseLock]
    G --> H[删除锁文件]

3.6 数据流

初始化流程

sequenceDiagram
    participant U as 用户
    participant CLI as CLI/Skill
    participant OR as Orchestrator
    participant TP as TaskPlanner
    participant SM as StateManager
    
    U->>CLI: /om:start
    CLI->>OR: execute(input)
    OR->>SM: 初始化 .openmatrix/
    SM->>SM: 创建 state.json
    OR->>TP: plan(input)
    TP->>TP: AI 分析拆解
    TP->>SM: 写入任务列表
    OR->>U: 展示任务计划

任务执行流程

sequenceDiagram
    participant OR as Orchestrator
    participant SC as Scheduler
    participant PE as PhaseExecutor
    participant AR as AgentRunner
    participant AG as Agent
    participant SM as StateManager
    
    OR->>SC: getNextTask()
    SC->>SC: 检查依赖
    SC->>OR: 返回 TASK-001
    OR->>PE: executePhase(TASK-001, TDD)
    PE->>AR: prepareSubagentTask
    AR->>AG: Tester Agent 执行
    AG->>AG: 编写测试
    AG->>PE: 返回结果
    PE->>SM: 保存 develop.json
    OR->>OR: 继续下一阶段

Meeting 处理流程

sequenceDiagram
    participant OR as Orchestrator
    participant PE as PhaseExecutor
    participant MM as MeetingManager
    participant SM as StateManager
    participant U as 用户
    
    PE->>PE: 任务阻塞
    PE->>MM: createMeeting
    MM->>SM: 写入 meeting.json
    PE->>SM: 任务状态 → waiting
    OR->>OR: 继续其他任务
    OR->>U: 展示 Meeting 列表
    U->>MM: resolveMeeting
    MM->>SM: 任务状态 → scheduled
    OR->>OR: 重新调度任务