第二章：核心概念

2.1 任务 (Task)

任务是 OpenMatrix 的核心执行单元。每个任务代表一个独立的工作项。

任务定义

interface Task {
  id: string;                    // 任务ID，如 TASK-001
  title: string;                 // 任务标题
  description: string;           // 详细描述
  status: TaskStatus;            // 当前状态
  agentType: AgentType;          // 负责的 Agent
  dependencies: string[];        // 依赖的任务ID
  phases: Phase[];               // 执行阶段
  priority: number;              // 优先级 (1-10)
  estimatedComplexity: string;   // 预估复杂度
  artifacts: string[];           // 输出文件路径
}

任务状态机

stateDiagram-v2
    [*] --> pending: 创建任务
    pending --> scheduled: 依赖满足
    scheduled --> in_progress: 开始执行
    
    in_progress --> verify: 开发完成
    in_progress --> blocked: 遇到阻塞
    
    verify --> accept: 验证通过
    verify --> failed: 验证失败
    
    accept --> completed: 接受通过
    accept --> failed: 接受失败
    
    blocked --> waiting: 创建 Meeting
    waiting --> scheduled: Meeting 解决
    
    failed --> retry_queue: 重试队列
    retry_queue --> scheduled: 重新调度
    
    completed --> [*]

状态详解

任务依赖

graph TD
    T1[TASK-001: 数据模型] --> T2[TASK-002: API 接口]
    T1 --> T3[TASK-003: 数据库配置]
    T2 --> T4[TASK-004: 前端组件]
    T3 --> T5[TASK-005: 数据迁移]
    
    T4 --> T6[TASK-006: E2E 测试]
    T5 --> T6

依赖关系确保任务按正确顺序执行：

• 依赖未满足 → 状态保持 pending
• 所有依赖完成 → 状态转为 scheduled
• 循环依赖 → 创建时检测并报错

任务优先级

优先级影响调度顺序（数值越大优先级越高）：

2.2 阶段 (Phase)

每个任务经历四个执行阶段（strict 模式）。

四阶段模型

$$\text{Task}=\text{TDD}+\text{Develop}+\text{Verify}+\text{Accept}$$

graph LR
    A[TDD 阶段] --> |"RED"| B[Develop 阶段]
    B --> |"GREEN"| C[Verify 阶段]
    C --> |"质量门禁"| D[Accept 阶段]
    D --> |"最终确认"| E[完成]

TDD 阶段

graph TD
    A[TDD 开始] --> B[Tester Agent]
    B --> C[分析需求]
    C --> D[编写测试]
    D --> E{测试执行}
    E --> |"必须失败"| F[通过 TDD]
    E --> |"通过/无测试"| G[TDD 失败]
    
    F --> H[进入 Develop]
    G --> I[重新编写测试]

目的：确保测试真正覆盖新功能

Develop 阶段

graph TD
    A[Develop 开始] --> B[Coder Agent]
    B --> C[理解需求]
    C --> D[设计方案]
    D --> E[编写代码]
    E --> F{测试执行}
    F --> |"通过"| G[通过 Develop]
    F --> |"失败"| H[继续开发]
    
    G --> I[进入 Verify]
    H --> E

目的：实现功能，通过测试（GREEN）

Verify 阶段

graph TD
    A[Verify 开始] --> B[Executor Agent]
    B --> C[Build 检查]
    C --> D[测试运行]
    D --> E[覆盖率检查]
    E --> F[Lint 检查]
    F --> G[安全扫描]
    G --> H{E2E 可选}
    H --> I{全部通过}
    
    I --> |"通过"| J[进入 Accept]
    I --> |"失败"| K[Verify 失败]

目的：运行质量门禁验证

七个质量门禁：

Accept 阶段

graph TD
    A[Accept 开始] --> B[Reviewer Agent]
    B --> C[代码审查]
    C --> D[AI Review]
    D --> E{审查通过}
    
    E --> |"通过"| F[完成任务]
    E --> |"失败"| G[Accept 失败]

目的：最终确认和审查

阶段状态文件

每个阶段完成后生成状态文件：

.openmatrix/tasks/TASK-001/
├── develop.json    # 开发阶段结果
├── verify.json     # 验证阶段结果
├── accept.json     # 接受阶段结果
└── artifacts/      # 输出文件

2.3 Agent

Agent 是执行任务的智能体。

Agent 类型

type AgentType = 
  | 'planner'    // 规划 Agent - 拆解任务
  | 'coder'      // 编码 Agent - 实现功能
  | 'tester'     // 测试 Agent - 编写测试
  | 'reviewer'   // 审查 Agent - 代码审查
  | 'researcher' // 研究 Agent - 信息收集
  | 'executor';  // 执行 Agent - 运行验证

Agent 职责

graph TD
    subgraph "任务流程"
        P[Planner] --> T[Tester]
        T --> C[Coder]
        C --> E[Executor]
        E --> R[Reviewer]
    end
    
    subgraph "辅助流程"
        RS[Researcher] --> P
        RS --> C
    end

Agent 上下文 (Agent Memory)

每个 Agent 执行时接收前序 Agent 的上下文：

graph LR
    A[Tester 执行] --> B[生成 context.md]
    B --> C[Coder 执行]
    C --> D[读取 Tester context]
    D --> E[添加自身 context]
    E --> F[Executor 执行]
    F --> G[读取累积 context]

上下文文件 .openmatrix/context.md 包含：

• 关键决策
• 创建/修改的文件
• 重要发现
• 给后续 Agent 的建议

SubagentTask 配置

Agent 执行时生成 SubagentTask 配置：

interface SubagentTask {
  subagent_type: 'general-purpose' | 'Explore' | 'Plan';
  description: string;           // 简短描述
  prompt: string;                // 详细指令
  isolation?: 'worktree';        // 是否使用 worktree
  taskId: string;                // 关联任务ID
  agentType: AgentType;          // Agent类型
  timeout: number;               // 超时时间
  needsApproval: boolean;        // 是否需要审批
}

2.4 Meeting

Meeting 是处理阻塞任务的机制。

Meeting 的本质

Meeting 创建流程

graph TD
    A[任务执行] --> B{遇到阻塞}
    B --> C[标记 blocked]
    C --> D[创建 Meeting]
    D --> E[继续其他任务]
    E --> F{所有任务完成}
    F --> G[提示处理 Meeting]
    G --> H[用户决策]

Meeting 记录结构

.openmatrix/meetings/
└── MEETING-001/
    ├── meeting.json      # Meeting 定义
    ├── context.md        # 阻塞上下文
    └── resolution.md     # 解决方案（用户填写）

interface Meeting {
  id: string;                   // MEETING-001
  taskId: string;               // 关联任务
  type: MeetingType;            // 类型
  title: string;                // 标题
  description: string;          // 详细描述
  questions: Question[];        // 需要回答的问题
  status: 'pending' | 'resolved' | 'skipped';
  createdAt: string;
  resolvedAt?: string;
}

Meeting 类型

Meeting 处理选项

graph TD
    A[Meeting 待处理] --> B{用户决策}
    B --> |"提供信息"| C[解除阻塞]
    B --> |"跳过"| D[放弃任务]
    B --> |"重试"| E[重新执行]
    
    C --> F[任务继续]
    D --> G[任务标记 skipped]
    E --> H[任务进入 retry_queue]

2.5 质量等级

三种质量等级满足不同场景需求。

等级对比

strict 模式流程

graph TD
    A[任务] --> B[TDD 阶段]
    B --> C[Develop 阶段]
    C --> D[Verify 阶段]
    D --> E[Build ✓]
    E --> F[Test ✓]
    F --> G[Coverage >80% ✓]
    G --> H[Lint ✓]
    H --> I[Security ✓]
    I --> J[E2E Optional]
    J --> K[Accept 阶段]
    K --> L[AI Review ✓]
    L --> M[完成]

balanced 模式流程

graph TD
    A[任务] --> B[Develop 阶段]
    B --> C[Verify 阶段]
    C --> D[Build ✓]
    D --> E[Test ✓]
    E --> F[Coverage >60% ✓]
    F --> G[Lint ✓]
    G --> H[Security ✓]
    H --> I[E2E Optional]
    I --> J[Accept 阶段]
    J --> K[AI Review ✓]
    K --> L[完成]

fast 模式流程

graph TD
    A[任务] --> B[Develop 阶段]
    B --> C[完成]

适用场景

2.6 执行模式

三种执行模式控制交互程度。

模式对比

interactive 模式

sequenceDiagram
    participant U as 用户
    participant OM as OpenMatrix
    participant A as Agent
    
    OM->>U: 展示任务计划
    U->>OM: 确认计划
    OM->>A: 执行任务
    A->>OM: 返回结果
    OM->>U: 展示结果，请求确认
    U->>OM: 确认继续
    OM->>A: 执行下一任务

每个步骤都需要用户确认。

semi-auto 模式

sequenceDiagram
    participant U as 用户
    participant OM as OpenMatrix
    participant A as Agent
    
    OM->>U: 展示任务计划
    U->>OM: 确认计划
    OM->>A: 执行任务 (自动)
    A->>OM: 返回结果
    OM->>A: 执行下一任务 (自动)
    A->>OM: 遇到关键决策
    OM->>U: 请求决策
    U->>OM: 提供决策
    OM->>A: 继续执行

关键决策点需要用户介入。

full-auto 模式

sequenceDiagram
    participant U as 用户
    participant OM as OpenMatrix
    participant A as Agent
    
    U->>OM: 启动执行
    OM->>A: 自动执行所有任务
    A->>OM: 遇到阻塞
    OM->>OM: 创建 Meeting
    OM->>A: 继续其他任务
    A->>OM: 所有任务完成
    OM->>U: 展示 Meeting 列表

完全自动执行，阻塞记录为 Meeting。

2.7 状态持久化

状态持久化确保执行过程可恢复。

持久化目录结构

.openmatrix/
├── state.json              # 全局状态
├── plan.md                 # AI 生成的计划
├── context.md              # Agent Memory
├── tasks-input.json        # 任务输入定义
├── tasks/
│   └── TASK-001/
│       ├── task.json       # 任务定义
│       ├── context.md      # 任务上下文
│       ├── develop.json    # 开发结果
│       ├── verify.json     # 验证结果
│       ├── accept.json     # 接受结果
│       └── artifacts/      # 输出文件
├── approvals/
│   └── APPROVAL-001/
│       └── approval.json   # 审批记录
└── meetings/
│   └── MEETING-001/
│       ├── meeting.json    # Meeting 定义
│       └── resolution.md   # 解决方案

state.json 结构

{
  "runId": "run-2024-01-15-001",
  "status": "running",
  "config": {
    "quality": "strict",
    "mode": "semi-auto",
    "e2eTests": true
  },
  "statistics": {
    "totalTasks": 10,
    "completedTasks": 3,
    "failedTasks": 1,
    "blockedTasks": 2
  },
  "currentTask": "TASK-004",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T12:30:00Z"
}

step/complete 循环

graph TD
    A[step 命令] --> B[读取 state.json]
    B --> C[计算下一个任务]
    C --> D[返回任务配置]
    D --> E[Agent 执行]
    E --> F[complete 命令]
    F --> G[保存结果到磁盘]
    G --> H[更新 state.json]
    H --> I[回到 step]

这种循环设计确保：

• Context 压缩后状态不丢失
• 可以跨会话恢复执行
• 支持分布式执行场景

下一章将深入探讨 OpenMatrix 的系统架构。