前言

关于这本书

OpenMatrix 是一个 AI Agent 任务编排系统，它为 Claude Code Skills 提供自动化任务执行框架，集成质量保障机制（TDD、覆盖率、Lint、安全扫描），支持多种执行模式，并通过 Meeting 机制处理阻塞任务而不中断执行流程。

本书是 OpenMatrix 的官方技术文档，旨在为开发者提供全面的技术参考，帮助理解系统架构、掌握使用方法、进行扩展开发。

AI 编码的三层演进

AI 编码工具正在经历三层演进：

graph TD
    L1["Layer 1: AI Code Completion<br/>（Copilot）"] --> L2["Layer 2: Conversational Coding<br/>（Claude Code）"]
    L2 --> L3["Layer 3: Process Orchestration + QA<br/>（OpenMatrix）"]
    
    L1 --> S1["解决「写代码」"]
    L2 --> S2["解决「复杂任务」"]
    L3 --> S3["解决「可信交付」"]

OpenMatrix 定位在第三层——它不直接执行代码生成，而是编排 Claude Code 的能力，同时注入质量保障流程。

为什么需要 OpenMatrix

当使用 Claude Code 等对话式编码工具时，开发者面临以下挑战：

质量保障缺失

graph LR
    A[用户指令] --> B[Claude Code]
    B --> C[生成代码]
    C --> D[???]
    
    D -.->|"质量如何验证？"| E[人工审查]

• AI 生成的代码缺少自动化测试
• 没有覆盖率检查机制
• 缺乏安全扫描流程
• 无法保证代码规范一致性

执行中断问题

当任务遇到阻塞时（如需要用户确认、依赖外部信息）：

graph TD
    A[任务执行] --> B{遇到阻塞}
    B -->|传统方式| C[暂停等待]
    C --> D[用户响应]
    D --> E[继续执行]
    
    B -->|OpenMatrix| F[记录 Meeting]
    F --> G[继续其他任务]
    G --> H[最终处理 Meeting]

传统方式会完全暂停，而 OpenMatrix 通过 Meeting 机制最大化前向进度。

状态持久化

Claude Code 存在 Context 压缩问题，长任务执行时状态可能丢失：

graph TD
    A[开始任务] --> B[执行过程]
    B --> C{Context 压缩}
    C -->|无持久化| D[状态丢失]
    D --> E[需要重新开始]
    
    C -->|OpenMatrix| F[状态保存到磁盘]
    F --> G[恢复执行]

OpenMatrix 的 step/complete 循环通过磁盘持久化解决这个问题。

OpenMatrix 的解决方案

委托模型

OpenMatrix 不直接执行，它编排 Claude Code：

graph TD
    OM[OpenMatrix] --> |"编排"| CC[Claude Code Agent]
    OM --> |"注入"| QA[质量保障流程]
    OM --> |"管理"| ST[状态持久化]
    
    CC --> EX[执行任务]
    QA --> VV[验证质量]
    ST --> PS[持久化状态]

四阶段执行

每个任务经历四个阶段：

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

三种质量等级

这本书解决什么问题

当你面对以下需求时，这本书会给你答案：

• 如何使用 OpenMatrix？ — CLI 命令和 Skills 使用指南
• 理解系统架构？ — Orchestrator、Agent、Storage 设计详解
• 如何扩展系统？ — 自定义 Agent、质量门禁、技能开发
• 如何集成到项目？ — 最佳实践和配置建议
• 如何调试问题？ — 工作流程详解和常见问题解答

你将学到什么

概览篇：建立全局认知

• OpenMatrix 的定位与价值
• 核心概念：任务、Agent、质量门禁、Meeting

架构篇：理解系统设计

• 系统架构分层
• Orchestrator 编排器实现
• Agent 系统设计
• Storage 存储层实现

功能篇：掌握具体功能

• CLI 命令完整用法
• Skills 技能系统
• 质量保障体系详解

实战篇：落地应用

• 工作流程详解
• 最佳实践指南
• 扩展开发方法

核心方法论

本书贯穿一个核心方法论：

$$\text{可信交付}=\text{流程编排}+\text{质量门禁}+\text{状态持久化}$$

graph LR
    A[用户指令] --> B[任务拆解]
    B --> C[编排执行]
    C --> D[质量验证]
    D --> E[状态持久化]
    E --> F[可信交付]

阅读建议

适用读者

• Claude Code 用户：想系统化使用 Skills 进行任务编排
• AI 工程师：想理解 AI 编码工具的编排层设计
• DevOps 工程师：想建设 AI 编码的质量保障基础设施
• 技术管理者：想理解 AI 辅助开发的质量保障方法论

"AI 编码的质量不是靠信任，是靠流程保障。"

第一章：项目概述

1.1 项目定位

OpenMatrix 是一个 AI Agent 任务编排系统，作为 Claude Code Skills 的执行引擎，提供自动化任务执行框架。

核心价值主张

自动化不牺牲质量 | 高质量不依赖人工操作

在 AI 编码工具栈中的位置

graph TD
    subgraph "Layer 1: Code Completion"
        C1[GitHub Copilot]
        C2[Cursor]
    end
    
    subgraph "Layer 2: Conversational Coding"
        CC[Claude Code]
        CD[Codex CLI]
    end
    
    subgraph "Layer 3: Process Orchestration"
        OM[OpenMatrix]
    end
    
    C1 --> CC
    C2 --> CC
    CC --> OM
    
    L1["解决「写代码」"] -.-> C1
    L2["解决「复杂任务」"] -.-> CC  
    L3["解决「可信交付」"] -.-> OM

委托模型

OpenMatrix 采用委托模型——它不直接执行代码生成，而是编排 Claude Code Agent：

graph LR
    OM[OpenMatrix<br/>编排层] --> |"委托"| CC[Claude Code<br/>执行层]
    OM --> |"注入"| QA[质量保障<br/>验证层]
    
    CC --> CODE[代码生成]
    QA --> VERIFY[质量验证]

1.2 项目基本信息

技术栈

{
  "production": {
    "commander": "^14.0.3",    // CLI 框架
    "chokidar": "^5.0.0",      // 文件监听
    "chalk": "^5.6.2",         // 终端输出
    "winston": "^3.19.0"       // 日志系统
  },
  "development": {
    "typescript": "^5.3.3",
    "vitest": "^1.6.0"
  }
}

1.3 核心功能

1. 自动化任务执行

graph TD
    A[用户指令] --> B[任务拆解]
    B --> C[依赖分析]
    C --> D[调度执行]
    D --> E[质量验证]
    E --> F[完成交付]

将用户的一个指令拆解为多个子任务，自动调度执行。

2. 质量保障体系

graph LR
    A[代码生成] --> B[Build]
    B --> C[Test]
    C --> D[Coverage]
    D --> E[Lint]
    E --> F[Security]
    F --> G[E2E]
    G --> H[Accept]

七个质量门禁确保代码质量：

• Build 检查
• 测试运行
• 覆盖率检查
• Lint 检查
• 安全扫描
• E2E 测试（可选）
• 接受标准验证

3. Meeting 机制

graph TD
    A[任务执行] --> B{遇到阻塞}
    B --> C[创建 Meeting]
    C --> D[继续其他任务]
    D --> E[所有任务完成]
    E --> F[处理 Meeting]
    F --> G{用户决策}
    G --> |"提供信息"| H[解除阻塞]
    G --> |"跳过"| I[放弃任务]
    G --> |"重试"| J[重新执行]

阻塞不中断执行，而是记录 Meeting 继续推进其他任务。

4. 状态持久化

graph TD
    A[step 命令] --> B[从磁盘读取状态]
    B --> C[返回下一个任务]
    C --> D[Agent 执行]
    D --> E[complete 命令]
    E --> F[保存状态到磁盘]
    F --> G[回到 step]

step/complete 循环确保状态在 Context 压缩后可恢复。

5. 多种执行模式

1.4 项目结构

openmatrix/
├── src/
│   ├── index.ts                 # 主导出
│   ├── types/
│   │   └── index.ts             # TypeScript 类型定义
│   ├── orchestrator/            # 编排器模块
│   │   ├── executor.ts          # 主执行循环
│   │   ├── scheduler.ts         # 任务调度
│   │   ├── state-machine.ts     # 状态机
│   │   ├── phase-executor.ts    # 阶段执行
│   │   ├── task-planner.ts      # 任务规划
│   │   ├── meeting-manager.ts   # Meeting 管理
│   │   ├── approval-manager.ts  # 审批管理
│   │   └── retry-manager.ts     # 重试管理
│   │   └── ...                  # 其他编排器组件
│   ├── agents/                  # Agent 模块
│   │   ├── base-agent.ts        # 基类
│   │   ├── agent-runner.ts      # Agent 运行器
│   │   └── impl/                # 具体实现
│   │       ├── planner-agent.ts
│   │       ├── coder-agent.ts
│   │       ├── tester-agent.ts
│   │       ├── reviewer-agent.ts
│   │       ├── researcher-agent.ts
│   │       └── executor-agent.ts
│   ├── storage/                 # 存储模块
│   │   ├── state-manager.ts     # 状态管理
│   │   └── file-store.ts        # 文件存储
│   ├── utils/                   # 工具模块
│   │   ├── logger.ts
│   │   ├── progress-reporter.ts
│   │   └── gitignore.ts
│   └── cli/                     # CLI 模块
│       ├── index.ts             # CLI 入口
│       └── commands/            # 命令实现
│           ├── start.ts
│           ├── auto.ts
│           ├── status.ts
│           ├── approve.ts
│           ├── meeting.ts
│           ├── resume.ts
│           ├── retry.ts
│           ├── report.ts
│           └── ...
├── skills/                      # Claude Code Skills
│   ├── om.md                    # 默认入口
│   ├── start.md
│   ├── auto.md
│   ├── brainstorm.md
│   ├── research.md
│   ├── status.md
│   ├── approve.md
│   ├── meeting.md
│   ├── resume.md
│   ├── retry.md
│   ├── report.md
│   └── check.md
├── tests/                       # 测试目录
│   ├── storage/
│   ├── orchestrator/
│   ├── agents/
│   └── utils/
├── docs/                        # 文档目录
│   ├── FLOW.md
│   ├── CORE_VALUE.md
│   └── require.md
├── scripts/
│   └── install-skills.js        # Skills 安装脚本
├── dist/                        # 编译输出
├── package.json
├── tsconfig.json
└── vitest.config.ts

1.5 安装与使用

安装

npm install openmatrix

安装 Skills

openmatrix install-skills

Skills 会安装到 ~/.claude/commands/om/ 目录。

快速开始

# 在 Claude Code 中使用 Skills
/om:start

# 或使用 CLI
openmatrix start

验证安装

openmatrix status

1.6 开发命令

# 编译
npm run build

# 开发模式 CLI
npm run dev -- <command>

# 运行测试
npm test

# 单文件测试
npx vitest run tests/orchestrator/executor.test.ts

# 手动安装 Skills
openmatrix install-skills

1.7 版本演进

OpenMatrix 正在持续演进，当前版本 (0.1.98) 已实现：

• ✓ 完整的任务编排系统
• ✓ 三种质量等级
• ✓ Meeting 机制
• ✓ 状态持久化
• ✓ 多种 CLI 命令
• ✓ Claude Code Skills 集成
• ✓ Git 自动提交

未来规划：

• 更多质量门禁类型
• 更丰富的 Agent 类型
• Web UI 界面
• 更多 LLM 平台支持

下一章将深入探讨 OpenMatrix 的核心概念，包括任务生命周期、Agent 类型、质量门禁等。

第二章：核心概念

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 的系统架构。

第三章：系统架构

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

层级职责

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());

核心命令：

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;
}

状态转换表：

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;
}

审批类型：

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: 重新调度任务

3.7 设计原则

委托原则

OpenMatrix 不直接执行，而是委托：

最大前向进度原则

阻塞不停止执行：

状态持久化原则

所有状态写入磁盘：

单一职责原则

每个组件职责明确：

下一章将深入探讨 Orchestrator 编排器 的实现细节。

第四章：Orchestrator 编排器

Orchestrator 是 OpenMatrix 的核心组件，负责任务调度、状态管理和流程控制。

4.1 Executor 主执行器

Executor 是编排层的中心控制器，协调所有其他组件。

核心接口

// orchestrator/executor.ts

interface Executor {
  /**
   * 主执行入口
   * @param input 用户输入的任务定义
   * @returns 执行结果
   */
  execute(input: TaskInput): Promise<ExecutionResult>;
  
  /**
   * 获取待执行的 SubagentTask 列表
   * 用于 Skills 调用 Agent tool
   */
  getSubagentTasks(): SubagentTask[];
  
  /**
   * 处理 Agent 执行完成
   * @param taskId 任务ID
   * @param result Agent 执行结果
   */
  handleTaskComplete(taskId: string, result: AgentResult): void;
  
  /**
   * 获取当前执行状态
   */
  getStatus(): ExecutionStatus;
}

执行流程图

flowchart TD
    subgraph "初始化阶段"
        A[execute 入口] --> B[创建 runId]
        B --> C[初始化 .openmatrix/]
        C --> D[生成 state.json]
    end
    
    subgraph "规划阶段"
        D --> E[调用 TaskPlanner]
        E --> F[AI 分析任务]
        F --> G[生成任务列表]
        G --> H[写入 tasks/*.json]
    end
    
    subgraph "调度阶段"
        H --> I[调用 Scheduler]
        I --> J[解析依赖关系]
        J --> K[按优先级排序]
        K --> L[标记 scheduled]
    end
    
    subgraph "执行阶段"
        L --> M{获取下一任务}
        M --> N[调用 PhaseExecutor]
        N --> O[生成 SubagentTask]
        O --> P[返回给 Skills]
        P --> Q[Agent 执行]
        Q --> R{执行结果}
        
        R --> |"成功"| S[handleTaskComplete]
        R --> |"阻塞"| T[创建 Meeting]
        R --> |"失败"| U[进入 retry_queue]
        
        S --> V{还有任务?}
        T --> V
        U --> V
        
        V --> |"有"| M
        V --> |"无"| W[生成报告]
    end
    
    subgraph "完成阶段"
        W --> X[Git 自动提交]
        X --> Y[返回 ExecutionResult]
    end

关键实现

class ExecutorImpl implements Executor {
  private scheduler: Scheduler;
  private phaseExecutor: PhaseExecutor;
  private meetingManager: MeetingManager;
  private stateManager: StateManager;
  
  async execute(input: TaskInput): Promise<ExecutionResult> {
    // 1. 初始化
    const runId = this.generateRunId();
    await this.stateManager.initialize(runId, input);
    
    // 2. 任务规划
    const tasks = await this.taskPlanner.plan(input);
    await this.stateManager.saveTasks(tasks);
    
    // 3. 调度
    await this.scheduler.scheduleAll(tasks);
    
    // 4. 执行循环
    while (this.scheduler.hasPendingTasks()) {
      const task = this.scheduler.getNextTask();
      if (!task) break;
      
      const subagentTask = await this.phaseExecutor.prepare(task);
      this.pendingTasks.push(subagentTask);
    }
    
    return {
      status: 'running',
      subagentTasks: this.pendingTasks
    };
  }
  
  handleTaskComplete(taskId: string, result: AgentResult): void {
    const task = this.stateManager.getTask(taskId);
    
    if (result.status === 'blocked') {
      this.meetingManager.createMeeting(taskId, result.blockInfo);
      this.stateManager.updateTaskStatus(taskId, 'waiting');
    } else if (result.status === 'success') {
      this.stateManager.updateTaskStatus(taskId, 'verify');
      // 进入验证阶段
    } else {
      this.stateManager.updateTaskStatus(taskId, 'failed');
    }
    
    // 继续调度
    this.continueExecution();
  }
}

ExecutionResult 结构

interface ExecutionResult {
  runId: string;
  status: 'running' | 'completed' | 'failed' | 'blocked';
  subagentTasks: SubagentTask[];
  statistics: {
    total: number;
    completed: number;
    failed: number;
    blocked: number;
  };
  report?: QualityReport;
}

4.2 Scheduler 调度器

Scheduler 管理任务的调度顺序和依赖关系。

核心接口

// orchestrator/scheduler.ts

interface Scheduler {
  /**
   * 获取下一个可执行任务
   * @returns 任务或 null（无可用任务）
   */
  getNextTask(): Task | null;
  
  /**
   * 调度所有任务
   * 设置初始状态和依赖关系
   */
  scheduleAll(tasks: Task[]): void;
  
  /**
   * 检查任务依赖是否满足
   */
  checkDependencies(taskId: string): boolean;
  
  /**
   * 检测是否存在循环依赖
   * @returns 循环依赖的任务ID列表
   */
  detectCircularDependency(): string[];
  
  /**
   * 检查是否有待执行任务
   */
  hasPendingTasks(): boolean;
}

调度算法

flowchart TD
    A[getNextTask] --> B[获取所有 scheduled 任务]
    B --> C[过滤依赖未满足的]
    C --> D[按优先级排序]
    D --> E[取最高优先级任务]
    
    E --> F{任务存在?}
    F --> |"是"| G[返回任务]
    F --> |"否"| H[返回 null]

依赖检查实现

class SchedulerImpl implements Scheduler {
  checkDependencies(taskId: string): boolean {
    const task = this.stateManager.getTask(taskId);
    
    for (const depId of task.dependencies) {
      const depTask = this.stateManager.getTask(depId);
      
      // 依赖任务必须已完成
      if (depTask.status !== 'completed') {
        return false;
      }
    }
    
    return true;
  }
  
  detectCircularDependency(): string[] {
    const visited = new Set<string>();
    const recursionStack = new Set<string>();
    const cycles: string[] = [];
    
    for (const task of this.getAllTasks()) {
      if (this.detectCycle(task.id, visited, recursionStack, cycles)) {
        return cycles;
      }
    }
    
    return [];
  }
  
  private detectCycle(
    taskId: string,
    visited: Set<string>,
    stack: Set<string>,
    cycles: string[]
  ): boolean {
    if (stack.has(taskId)) {
      cycles.push(taskId);
      return true;
    }
    
    if (visited.has(taskId)) {
      return false;
    }
    
    visited.add(taskId);
    stack.add(taskId);
    
    const task = this.stateManager.getTask(taskId);
    for (const depId of task.dependencies) {
      if (this.detectCycle(depId, visited, stack, cycles)) {
        cycles.push(taskId);
        return true;
      }
    }
    
    stack.delete(taskId);
    return false;
  }
}

优先级排序

class SchedulerImpl implements Scheduler {
  getNextTask(): Task | null {
    const scheduledTasks = this.stateManager
      .getTasksByStatus('scheduled')
      .filter(t => this.checkDependencies(t.id));
    
    if (scheduledTasks.length === 0) {
      return null;
    }
    
    // 按优先级降序排序
    scheduledTasks.sort((a, b) => b.priority - a.priority);
    
    return scheduledTasks[0];
  }
}

依赖图示例

graph TD
    T1["TASK-001<br/>priority: 10<br/>status: scheduled"] --> T2["TASK-002<br/>priority: 7"]
    T1 --> T3["TASK-003<br/>priority: 8"]
    T2 --> T4["TASK-004<br/>priority: 5"]
    T3 --> T5["TASK-005<br/>priority: 6"]
    T4 --> T6["TASK-006<br/>priority: 3"]
    T5 --> T6
    
    style T1 fill:#90EE90
    style T2 fill:#FFFACD
    style T3 fill:#FFFACD
    style T4 fill:#D3D3D3
    style T5 fill:#D3D3D3
    style T6 fill:#D3D3D3

执行顺序：

1. TASK-001（优先级最高，无依赖）
2. TASK-003（优先级 8）
3. TASK-002（优先级 7）
4. TASK-005（优先级 6）
5. TASK-004（优先级 5）
6. TASK-006（优先级最低，依赖多个）

4.3 StateMachine 状态机

StateMachine 定义任务状态的合法转换。

状态定义

// orchestrator/state-machine.ts

type TaskStatus =
  | 'pending'      // 初始状态
  | 'scheduled'    // 已调度，等待执行
  | 'in_progress'  // 正在执行
  | 'blocked'      // 阻塞中
  | 'waiting'      // 等待 Meeting
  | 'verify'       // 验证阶段
  | 'accept'       // 接收阶段
  | 'completed'    // 已完成
  | 'failed'       // 已失败
  | 'retry_queue'; // 待重试

状态转换图

stateDiagram-v2
    [*] --> pending: 创建
    
    pending --> scheduled: 依赖满足
    scheduled --> in_progress: 开始执行
    
    in_progress --> blocked: 需要外部信息
    blocked --> waiting: 创建 Meeting
    waiting --> scheduled: Meeting 解决
    
    in_progress --> verify: 开发完成
    verify --> accept: 质量门禁通过
    verify --> failed: 质量门禁失败
    
    accept --> completed: 审查通过
    accept --> failed: 审查失败
    
    failed --> retry_queue: 进入重试队列
    retry_queue --> scheduled: 重新调度
    
    completed --> [*]

转换规则表

interface StateMachine {
  // 状态转换规则
  transitions: Map<TaskStatus, TaskStatus[]>;
}

const TRANSITIONS: Map<TaskStatus, TaskStatus[]> = new Map([
  ['pending', ['scheduled']],
  ['scheduled', ['in_progress']],
  ['in_progress', ['blocked', 'verify']],
  ['blocked', ['waiting']],
  ['waiting', ['scheduled']],
  ['verify', ['accept', 'failed']],
  ['accept', ['completed', 'failed']],
  ['failed', ['retry_queue']],
  ['retry_queue', ['scheduled']],
  ['completed', []]  // 最终状态
]);

核心实现

class StateMachineImpl implements StateMachine {
  transition(taskId: string, newStatus: TaskStatus): void {
    const task = this.stateManager.getTask(taskId);
    const currentStatus = task.status;
    
    if (!this.isValidTransition(currentStatus, newStatus)) {
      throw new Error(
        `Invalid transition: ${currentStatus} → ${newStatus}`
      );
    }
    
    this.stateManager.updateTaskStatus(taskId, newStatus);
    
    // 记录状态历史
    this.logStateTransition(taskId, currentStatus, newStatus);
  }
  
  isValidTransition(from: TaskStatus, to: TaskStatus): boolean {
    const validTargets = TRANSITIONS.get(from) || [];
    return validTargets.includes(to);
  }
  
  getValidTransitions(currentStatus: TaskStatus): TaskStatus[] {
    return TRANSITIONS.get(currentStatus) || [];
  }
}

状态转换触发条件

4.4 PhaseExecutor 阶段执行器

PhaseExecutor 执行任务的四阶段流程。

四阶段流程

flowchart TD
    subgraph "strict 模式"
        A[TDD] --> B[Develop]
        B --> C[Verify]
        C --> D[Accept]
    end
    
    subgraph "balanced 模式"
        E[Develop] --> F[Verify]
        F --> G[Accept]
    end
    
    subgraph "fast 模式"
        H[Develop] --> I[完成]
    end

核心接口

// orchestrator/phase-executor.ts

type PhaseType = 'tdd' | 'develop' | 'verify' | 'accept';

interface PhaseExecutor {
  /**
   * 执行指定阶段
   */
  executePhase(taskId: string, phase: PhaseType): Promise<PhaseResult>;
  
  /**
   * 准备阶段执行配置
   */
  preparePhase(taskId: string, phase: PhaseType): SubagentTask;
  
  /**
   * 获取当前阶段
   */
  getCurrentPhase(taskId: string): PhaseType;
  
  /**
   * 确定下一阶段
   */
  getNextPhase(currentPhase: PhaseType, quality: QualityLevel): PhaseType | null;
}

PhaseResult 结构

interface PhaseResult {
  phase: PhaseType;
  status: 'success' | 'blocked' | 'failed';
  taskId: string;
  
  // 成功时
  artifacts?: string[];         // 生成的文件
  contextUpdate?: string;       // Agent Memory 更新
  
  // 阻塞时
  blockInfo?: BlockInfo;
  
  // 失败时
  error?: ErrorInfo;
  
  // Verify 阶段特有的质量报告
  qualityReport?: QualityReport;
}

阶段执行实现

class PhaseExecutorImpl implements PhaseExecutor {
  
  preparePhase(taskId: string, phase: PhaseType): SubagentTask {
    const task = this.stateManager.getTask(taskId);
    const context = this.readAgentContext(taskId);
    
    switch (phase) {
      case 'tdd':
        return {
          subagent_type: 'general-purpose',
          description: `Execute ${taskId} TDD phase`,
          prompt: this.buildTDDPrompt(task, context),
          taskId,
          agentType: 'tester',
          timeout: 300000,
          needsApproval: false
        };
        
      case 'develop':
        return {
          subagent_type: 'general-purpose',
          description: `Execute ${taskId} Develop phase`,
          prompt: this.buildDevelopPrompt(task, context),
          taskId,
          agentType: 'coder',
          timeout: 600000,
          needsApproval: false
        };
        
      case 'verify':
        return {
          subagent_type: 'general-purpose',
          description: `Execute ${taskId} Verify phase`,
          prompt: this.buildVerifyPrompt(task, context),
          taskId,
          agentType: 'executor',
          timeout: 300000,
          needsApproval: false
        };
        
      case 'accept':
        return {
          subagent_type: 'general-purpose',
          description: `Execute ${taskId} Accept phase`,
          prompt: this.buildAcceptPrompt(task, context),
          taskId,
          agentType: 'reviewer',
          timeout: 180000,
          needsApproval: false
        };
    }
  }
  
  getNextPhase(
    currentPhase: PhaseType,
    quality: QualityLevel
  ): PhaseType | null {
    if (quality === 'fast') {
      return null;  // fast 模式无后续阶段
    }
    
    if (quality === 'balanced') {
      const sequence: PhaseType[] = ['develop', 'verify', 'accept'];
      const idx = sequence.indexOf(currentPhase);
      return idx < sequence.length - 1 ? sequence[idx + 1] : null;
    }
    
    // strict 模式
    const sequence: PhaseType[] = ['tdd', 'develop', 'verify', 'accept'];
    const idx = sequence.indexOf(currentPhase);
    return idx < sequence.length - 1 ? sequence[idx + 1] : null;
  }
}

阶段 Prompt 构建

class PhaseExecutorImpl {
  
  buildTDDPrompt(task: Task, context: string): string {
    return `
# Task: ${task.title}
# Phase: TDD (Test-Driven Development)

## Task Description
${task.description}

## Context from Previous Agents
${context}

## Your Goal
Write comprehensive tests that:
1. Cover the expected functionality described above
2. Tests MUST FAIL currently (RED phase of TDD)
3. Include edge cases and error scenarios

## Requirements
- Test file should be placed in appropriate test directory
- Use the project's existing test framework
- Tests should be clear and well-structured

## Output
Create test files and report:
- Files created
- Test cases written
- Current test execution status (should be failing)
`;
  }
  
  buildDevelopPrompt(task: Task, context: string): string {
    return `
# Task: ${task.title}
# Phase: Develop (Implementation)

## Task Description
${task.description}

## Context from Previous Agents
${context}

## Existing Tests (from TDD phase)
Read the test files and understand what needs to be implemented.

## Your Goal
Implement the functionality that:
1. Passes all the tests written in TDD phase (GREEN)
2. Follows project coding standards
3. Is clean and maintainable

## Requirements
- All tests must pass after implementation
- Code should be well-structured
- Add necessary comments for complex logic

## Output
Create/modify implementation files and report:
- Files created/modified
- Key decisions made
- Suggestions for next phases
`;
  }
}

4.5 TaskPlanner 任务规划器

TaskPlanner 将用户指令拆解为可执行任务。

核心接口

// orchestrator/task-planner.ts

interface TaskPlanner {
  /**
   * 根据用户输入规划任务
   */
  plan(input: TaskInput): Promise<Task[]>;
  
  /**
   * 分析任务依赖关系
   */
  analyzeDependencies(tasks: Task[]): DependencyGraph;
  
  /**
   * 为任务分配 Agent
   */
  assignAgents(tasks: Task[]): void;
}

TaskInput 结构

interface TaskInput {
  // 用户原始指令
  instruction: string;
  
  // 目标描述
  goals: string[];
  
  // 约束条件
  constraints?: string[];
  
  // 交付物定义
  deliverables?: string[];
  
  // 上下文信息
  context?: {
    projectType?: string;
    techStack?: string[];
    existingCodebase?: boolean;
  };
}

规划流程

flowchart TD
    A[用户指令] --> B[AI 分析]
    B --> C[识别子任务]
    C --> D[估算复杂度]
    D --> E[分析依赖关系]
    E --> F[分配优先级]
    F --> G[分配 Agent]
    G --> H[生成 Task 对象]
    
    H --> I[TASK-001]
    H --> J[TASK-002]
    H --> K[TASK-003]
    H --> L[...]

依赖图构建

interface DependencyGraph {
  nodes: Map<string, Task>;
  edges: Map<string, string[]>;  // taskId -> dependent taskIds
}

class TaskPlannerImpl implements TaskPlanner {
  analyzeDependencies(tasks: Task[]): DependencyGraph {
    const graph: DependencyGraph = {
      nodes: new Map(),
      edges: new Map()
    };
    
    // 构建节点
    for (const task of tasks) {
      graph.nodes.set(task.id, task);
      graph.edges.set(task.id, []);
    }
    
    // 分析依赖关系
    for (const task of tasks) {
      for (const depId of task.dependencies) {
        const dependents = graph.edges.get(depId) || [];
        dependents.push(task.id);
        graph.edges.set(depId, dependents);
      }
    }
    
    return graph;
  }
}

AI 规划 Prompt

class TaskPlannerImpl {
  buildPlanPrompt(input: TaskInput): string {
    return `
# Task Planning Request

## User Instruction
${input.instruction}

## Goals
${input.goals.map(g => `- ${g}`).join('\n')}

## Constraints
${input.constraints?.map(c => `- ${c}`).join('\n') || 'None specified'}

## Deliverables
${input.deliverables?.map(d => `- ${d}`).join('\n') || 'To be determined'}

## Context
- Project Type: ${input.context?.projectType || 'Unknown'}
- Tech Stack: ${input.context?.techStack?.join(', ') || 'Unknown'}
- Existing Codebase: ${input.context?.existingCodebase ? 'Yes' : 'No'}

## Your Task
Break down this request into specific, actionable sub-tasks.

For each task, provide:
1. **id**: TASK-XXX format
2. **title**: Short, clear title
3. **description**: Detailed description of what to do
4. **dependencies**: List of task IDs this depends on
5. **priority**: 1-10 (higher = more important)
6. **estimatedComplexity**: low/medium/high
7. **agentType**: planner/coder/tester/reviewer/researcher/executor

## Output Format
Return a JSON array of tasks.
`;
  }
}

4.6 MeetingManager 阻塞管理器

MeetingManager 处理阻塞任务的记录和解决。

核心接口

// orchestrator/meeting-manager.ts

type MeetingType = 'information' | 'decision' | 'approval' | 'dependency';

interface Meeting {
  id: string;
  taskId: string;
  type: MeetingType;
  title: string;
  description: string;
  questions: Question[];
  status: 'pending' | 'resolved' | 'skipped';
  createdAt: string;
  resolvedAt?: string;
}

interface MeetingManager {
  createMeeting(taskId: string, blockInfo: BlockInfo): Meeting;
  getPendingMeetings(): Meeting[];
  resolveMeeting(meetingId: string, resolution: Resolution): void;
  skipMeeting(meetingId: string): void;
}

Meeting 创建流程

flowchart TD
    A[Agent 阻塞] --> B[返回 BlockInfo]
    B --> C[MeetingManager.createMeeting]
    C --> D[生成 Meeting ID]
    D --> E[分析阻塞类型]
    E --> F[生成问题列表]
    F --> G[写入 meetings/MEETING-XXX/]
    G --> H[任务状态 → waiting]

BlockInfo 结构

interface BlockInfo {
  reason: string;              // 阻塞原因
  type: MeetingType;           // 阻塞类型
  missingInfo?: string[];      // 缺少的信息
  options?: Option[];          // 可选方案（decision 类型）
  externalDependency?: string; // 外部依赖描述
}

interface Question {
  id: string;
  text: string;
  type: 'text' | 'choice' | 'boolean';
  options?: string[];          // 选择类型时提供
  required: boolean;
}

Meeting 解决处理

interface Resolution {
  meetingId: string;
  answers: Map<string, string>;  // 问题ID -> 答案
  decision?: 'skip' | 'retry';
}

class MeetingManagerImpl implements MeetingManager {
  resolveMeeting(meetingId: string, resolution: Resolution): void {
    const meeting = this.stateManager.getMeeting(meetingId);
    const task = this.stateManager.getTask(meeting.taskId);
    
    // 更新 Meeting 状态
    meeting.status = 'resolved';
    meeting.resolvedAt = new Date().toISOString();
    
    // 写入解决方案
    this.fileStore.writeJson(
      `.openmatrix/meetings/${meetingId}/resolution.json`,
      resolution
    );
    
    // 更新任务状态
    this.stateManager.updateTaskStatus(task.id, 'scheduled');
    
    // 触发重新调度
    this.scheduler.reschedule(task.id);
  }
}

4.7 ApprovalManager 审批管理器

ApprovalManager 管理需要用户确认的审批流程。

审批类型

type ApprovalType = 'plan' | 'merge' | 'deploy' | 'meeting';

interface Approval {
  id: string;
  type: ApprovalType;
  content: any;
  status: 'pending' | 'approved' | 'rejected';
  createdAt: string;
  processedAt?: string;
}

核心接口

// orchestrator/approval-manager.ts

interface ApprovalManager {
  createApproval(type: ApprovalType, content: any): Approval;
  getPendingApprovals(): Approval[];
  processApproval(
    approvalId: string,
    decision: 'approve' | 'reject'
  ): void;
}

审批触发时机

审批流程

flowchart TD
    A[触发审批点] --> B[ApprovalManager.createApproval]
    B --> C[写入 approvals/]
    C --> D{执行模式}
    
    D --> |"interactive"| E[暂停等待用户]
    D --> |"semi-auto"| F{关键审批?}
    F --> |"是"| E
    F --> |"否"| G[自动批准]
    D --> |"full-auto"| G
    
    E --> H{用户决策}
    H --> |"批准"| I[processApproval approve]
    H --> |"拒绝"| J[processApproval reject]
    
    G --> I
    
    I --> K[继续执行]
    J --> L[调整流程]

4.8 RetryManager 重试管理器

RetryManager 管理失败任务的重试策略。

核心接口

// orchestrator/retry-manager.ts

interface RetryManager {
  /**
   * 将失败任务加入重试队列
   */
  addToRetryQueue(taskId: string, error: ErrorInfo): void;
  
  /**
   * 获取待重试任务
   */
  getRetryQueueTasks(): Task[];
  
  /**
   * 执行重试
   */
  executeRetry(taskId: string): Promise<void>;
  
  /**
   * 检查是否应该放弃重试
   */
  shouldAbandon(taskId: string): boolean;
}

重试策略

interface RetryPolicy {
  maxRetries: number;          // 最大重试次数（默认 3）
  backoffStrategy: 'linear' | 'exponential';
  baseDelay: number;           // 基础延迟（ms）
  maxDelay: number;            // 最大延迟（ms）
}

const DEFAULT_POLICY: RetryPolicy = {
  maxRetries: 3,
  backoffStrategy: 'exponential',
  baseDelay: 1000,
  maxDelay: 30000
};

重试流程

flowchart TD
    A[任务失败] --> B[RetryManager.addToRetryQueue]
    B --> C[记录失败原因]
    C --> D[计算延迟]
    D --> E[等待延迟时间]
    E --> F[状态 → scheduled]
    F --> G[重新执行]
    
    G --> H{执行结果}
    H --> |"成功"| I[完成]
    H --> |"失败"| J{重试次数}
    J --> |"< maxRetries"| B
    J --> |">= maxRetries"| K[放弃任务]

延迟计算

class RetryManagerImpl implements RetryManager {
  calculateDelay(retryCount: number): number {
    const policy = this.getRetryPolicy();
    
    if (policy.backoffStrategy === 'linear') {
      return Math.min(
        policy.baseDelay * retryCount,
        policy.maxDelay
      );
    }
    
    // exponential
    return Math.min(
      policy.baseDelay * Math.pow(2, retryCount - 1),
      policy.maxDelay
    );
  }
  
  shouldAbandon(taskId: string): boolean {
    const task = this.stateManager.getTask(taskId);
    const retryCount = task.retryCount || 0;
    return retryCount >= this.policy.maxRetries;
  }
}

4.9 GitCommitManager 自动提交

GitCommitManager 在任务完成后自动提交代码。

核心接口

// orchestrator/git-commit-manager.ts

interface GitCommitManager {
  /**
   * 提交完成的任务
   */
  commitTask(taskId: string): Promise<void>;
  
  /**
   * 生成 commit 信息
   */
  generateCommitMessage(task: Task): string;
  
  /**
   * 检查是否有未提交变更
   */
  hasUncommittedChanges(): boolean;
}

Commit 格式

<type>(TASK-XXX): Short description

Change 1
Change 2

Impact scope: Module name
Files changed: file1, file2

Co-Authored-By: OpenMatrix https://github.com/bigfish1913/openmatrix

Commit Types:

• feat: 新功能
• fix: Bug 修复
• test: 测试相关
• refactor: 重构
• docs: 文档

提交流程

flowchart TD
    A[任务完成] --> B[检查文件变更]
    B --> C{有变更?}
    C --> |"有"| D[生成 commit 信息]
    C --> |"无"| E[跳过提交]
    
    D --> F[git add]
    F --> G[git commit]
    G --> H[记录 commit hash]
    H --> I[更新任务状态]

下一章将深入探讨 Agent 系统 的设计与实现。

第五章：Agent 系统

Agent 系统是 OpenMatrix 的执行层，负责实际任务执行。

5.1 Agent 架构总览

Agent 类型定义

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

Agent 层级结构

graph TD
    subgraph "Agent 基础架构"
        BA[BaseAgent<br/>抽象基类]
        AR[AgentRunner<br/>配置生成]
    end
    
    subgraph "具体 Agent 实现"
        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
    
    AR --> BA

Agent 职责矩阵

5.2 BaseAgent 基类

BaseAgent 定义所有 Agent 的通用行为。

核心接口

// agents/base-agent.ts

abstract class BaseAgent {
  protected taskId: string;
  protected agentType: AgentType;
  protected stateManager: StateManager;
  protected fileStore: FileStore;
  
  /**
   * Agent 执行入口
   * 子类必须实现
   */
  abstract execute(context: AgentContext): Promise<AgentResult>;
  
  /**
   * 读取累积的 Agent 上下文
   */
  protected readContext(): string {
    return this.fileStore.readMd('.openmatrix/context.md');
  }
  
  /**
   * 写入新的上下文内容
   */
  protected writeContext(content: string): void {
    this.fileStore.atomicAppend('.openmatrix/context.md', content);
  }
  
  /**
   * 记录决策到上下文
   */
  protected logDecision(decision: Decision): void {
    const entry = `
## Decision [${this.agentType}]
- **Task**: ${this.taskId}
- **Decision**: ${decision.description}
- **Reason**: ${decision.reason}
- **Impact**: ${decision.impact}
`;
    this.writeContext(entry);
  }
  
  /**
   * 记录文件变更
   */
  protected logFileChange(change: FileChange): void {
    const entry = `
## File Change [${this.agentType}]
- **Task**: ${this.taskId}
- **Action**: ${change.action}  // create/modify/delete
- **File**: ${change.file}
- **Purpose**: ${change.purpose}
`;
    this.writeContext(entry);
  }
}

AgentContext 结构

interface AgentContext {
  taskId: string;
  task: Task;
  phase: PhaseType;
  accumulatedContext: string;    // 前序 Agent 的上下文
  projectContext: {
    techStack: string[];
    structure: string;
    conventions: string;
  };
}

AgentResult 结构

interface AgentResult {
  taskId: string;
  agentType: AgentType;
  status: 'success' | 'blocked' | 'failed';
  
  // 成功时
  output?: {
    artifacts: string[];         // 生成的文件
    contextUpdate: string;       // 新增的上下文内容
    suggestions?: string[];      // 给后续 Agent 的建议
  };
  
  // 阻塞时
  blockInfo?: BlockInfo;
  
  // 失败时
  error?: {
    message: string;
    stack?: string;
    retryable: boolean;
  };
}

5.3 AgentRunner 配置器

AgentRunner 负责生成 Agent 执行配置。

核心接口

// agents/agent-runner.ts

interface AgentRunner {
  /**
   * 准备 SubagentTask 配置
   * 用于 Skills 调用 Agent tool
   */
  prepareSubagentTask(
    task: Task,
    phase: PhaseType
  ): SubagentTask;
  
  /**
   * 构建 Agent 执行 Prompt
   */
  buildPrompt(
    task: Task,
    phase: PhaseType,
    context: string
  ): string;
  
  /**
   * 确定超时时间
   */
  determineTimeout(phase: PhaseType, complexity: string): number;
  
  /**
   * 确定是否需要隔离执行
   */
  determineIsolation(task: Task): 'worktree' | undefined;
}

SubagentTask 配置生成

class AgentRunnerImpl implements AgentRunner {
  prepareSubagentTask(task: Task, phase: PhaseType): SubagentTask {
    const context = this.readContext(task.id);
    const prompt = this.buildPrompt(task, phase, context);
    
    return {
      subagent_type: this.mapSubagentType(task.agentType),
      description: this.buildDescription(task, phase),
      prompt,
      isolation: this.determineIsolation(task),
      taskId: task.id,
      agentType: task.agentType,
      timeout: this.determineTimeout(phase, task.estimatedComplexity),
      needsApproval: this.determineNeedsApproval(phase)
    };
  }
  
  private mapSubagentType(agentType: AgentType): string {
    const mapping: Record<AgentType, string> = {
      'planner': 'Plan',
      'coder': 'general-purpose',
      'tester': 'general-purpose',
      'reviewer': 'general-purpose',
      'researcher': 'Explore',
      'executor': 'general-purpose'
    };
    return mapping[agentType];
  }
}

超时时间配置

隔离执行策略

class AgentRunnerImpl {
  determineIsolation(task: Task): 'worktree' | undefined {
    // 高风险任务使用 worktree 隔离
    if (task.estimatedComplexity === 'high') {
      return 'worktree';
    }
    
    // 涉及重要文件的任务使用隔离
    const criticalFiles = ['package.json', 'tsconfig.json', 'config.*'];
    if (task.artifacts.some(a => criticalFiles.includes(a))) {
      return 'worktree';
    }
    
    return undefined;
  }
}

5.4 PlannerAgent 规划 Agent

PlannerAgent 负责将用户指令拆解为任务列表。

执行流程

flowchart TD
    A[execute 入口] --> B[读取用户指令]
    B --> C[分析项目结构]
    C --> D[识别子任务]
    D --> E[分析依赖关系]
    E --> F[分配优先级]
    F --> G[分配 Agent]
    G --> H[生成 Task 对象]
    H --> I[返回任务列表]

Prompt 构建

class PlannerAgent extends BaseAgent {
  protected buildPrompt(context: AgentContext): string {
    return `
# Task Planning Request

## User Instruction
${context.task.description}

## Project Context
- Tech Stack: ${context.projectContext.techStack.join(', ')}
- Structure: ${context.projectContext.structure}
- Conventions: ${context.projectContext.conventions}

## Your Task
Analyze the user instruction and break it down into actionable sub-tasks.

## Requirements for Each Task
1. **id**: Use TASK-XXX format (start from TASK-001)
2. **title**: Clear, concise title (max 50 chars)
3. **description**: Detailed description of what needs to be done
4. **dependencies**: List IDs of tasks this depends on (empty array if none)
5. **priority**: 
   - 10: Critical/blocking other tasks
   - 7-9: High priority/core features
   - 4-6: Medium priority/regular features
   - 1-3: Low priority/optional features
6. **estimatedComplexity**: low/medium/high
7. **agentType**: One of planner/coder/tester/reviewer/researcher/executor
8. **artifacts**: Expected output files (if known)

## Dependency Analysis
- Identify which tasks depend on others
- Ensure no circular dependencies
- Consider logical execution order

## Output Format
Return a JSON array of tasks. Each task must have all required fields.

Example:
[
  {
    "id": "TASK-001",
    "title": "Create data model",
    "description": "Define TypeScript interfaces...",
    "dependencies": [],
    "priority": 10,
    "estimatedComplexity": "low",
    "agentType": "coder",
    "artifacts": ["src/models/user.ts"]
  },
  ...
]

Now analyze and plan the tasks.
`;
  }
}

输出处理

class PlannerAgent extends BaseAgent {
  async execute(context: AgentContext): Promise<AgentResult> {
    const prompt = this.buildPrompt(context);
    
    // Agent 执行（通过 Skills 委托）
    const response = await this.runAgent(prompt);
    
    // 解析 JSON 输出
    const tasks = this.parseTaskList(response);
    
    // 验证任务列表
    this.validateTasks(tasks);
    
    // 保存任务
    for (const task of tasks) {
      this.stateManager.saveTask(task);
    }
    
    // 记录决策
    this.logDecision({
      description: 'Created task breakdown',
      reason: 'Based on user instruction analysis',
      impact: `${tasks.length} tasks identified`
    });
    
    return {
      taskId: context.taskId,
      agentType: 'planner',
      status: 'success',
      output: {
        artifacts: [],
        contextUpdate: `## Planning Complete\n- Total tasks: ${tasks.length}`,
        suggestions: ['Review task dependencies before execution']
      }
    };
  }
}

5.5 TesterAgent 测试 Agent

TesterAgent 负责在 TDD 阶段编写测试。

执行流程

flowchart TD
    A[execute 入口] --> B[读取任务描述]
    B --> C[分析预期行为]
    C --> D[设计测试用例]
    D --> E[编写测试文件]
    E --> F[运行测试]
    F --> G{测试结果}
    
    G --> |"失败 (RED)"| H[通过 TDD]
    G --> |"通过"| I[重新设计测试]
    G --> |"无测试"| I
    
    H --> J[返回成功]
    I --> E

Prompt 构建

class TesterAgent extends BaseAgent {
  protected buildPrompt(context: AgentContext): string {
    return `
# Task: ${context.task.title}
# Phase: TDD (Test-Driven Development)

## Task Description
${context.task.description}

## Expected Behavior
Based on the description, tests should verify:
1. What is the expected functionality?
2. What are the edge cases?
3. What error scenarios should be handled?

## Context from Previous Agents
${context.accumulatedContext}

## Your Goal: RED Phase
Write comprehensive tests that **MUST FAIL** currently.

The tests should:
1. Define the expected behavior clearly
2. Cover normal cases, edge cases, and error scenarios
3. Be well-structured and readable
4. Use the project's test framework

## Test Framework
${this.detectTestFramework(context.projectContext)}

## Requirements
- Test files should be in appropriate test directory
- Test names should clearly describe what is being tested
- Each test should be independent
- Use descriptive assertions

## Output
1. Create test files
2. Report current test execution status
3. Explain what each test verifies

## Important
Tests MUST be failing (RED phase). If tests pass, the tests are not properly testing new functionality.
`;
  }
  
  private detectTestFramework(projectContext: any): string {
    // 检测项目使用的测试框架
    if (projectContext.techStack.includes('vitest')) {
      return 'Vitest - use describe/it/expect';
    }
    if (projectContext.techStack.includes('jest')) {
      return 'Jest - use describe/test/expect';
    }
    return 'Use existing test framework conventions';
  }
}

测试验证

class TesterAgent extends BaseAgent {
  async execute(context: AgentContext): Promise<AgentResult> {
    // ... 执行 Agent ...
    
    // 验证测试是否失败
    const testResult = await this.runTests();
    
    if (testResult.status === 'passed') {
      // TDD 要求测试失败（RED）
      return {
        taskId: context.taskId,
        agentType: 'tester',
        status: 'failed',
        error: {
          message: 'Tests passed - TDD requires failing tests (RED phase)',
          retryable: true
        }
      };
    }
    
    if (testResult.status === 'failed') {
      // 测试失败 = TDD 成功
      this.logFileChange({
        action: 'create',
        file: testResult.testFile,
        purpose: 'TDD test file'
      });
      
      return {
        taskId: context.taskId,
        agentType: 'tester',
        status: 'success',
        output: {
          artifacts: [testResult.testFile],
          contextUpdate: `## TDD Complete\n- Test file: ${testResult.testFile}\n- Tests failing: ${testResult.failedCount}`,
          suggestions: ['Implement functionality to pass these tests']
        }
      };
    }
  }
}

5.6 CoderAgent 编码 Agent

CoderAgent 负责在 Develop 阶段实现功能。

执行流程

flowchart TD
    A[execute 入口] --> B[读取任务描述]
    B --> C[读取测试文件]
    C --> D[理解测试需求]
    D --> E[设计实现方案]
    E --> F[编写实现代码]
    F --> G[运行测试]
    G --> H{测试结果}
    
    H --> |"通过 (GREEN)"| I[通过 Develop]
    H --> |"失败"| J[继续开发]
    
    I --> K[返回成功]
    J --> E

Prompt 构建

class CoderAgent extends BaseAgent {
  protected buildPrompt(context: AgentContext): string {
    const testFiles = this.findTestFiles(context.task);
    
    return `
# Task: ${context.task.title}
# Phase: Develop (Implementation)

## Task Description
${context.task.description}

## Context from Previous Agents
${context.accumulatedContext}

## Test Files (from TDD phase)
${testFiles.map(f => `### ${f}\n${this.fileStore.read(f)}`).join('\n\n')}

## Your Goal: GREEN Phase
Implement functionality that passes **ALL** tests written in TDD phase.

## Implementation Guidelines
1. Read and understand each test case
2. Implement the required functionality
3. Follow project coding conventions
4. Keep code clean and maintainable
5. Add necessary comments for complex logic

## Coding Conventions
${context.projectContext.conventions}

## Requirements
- All tests must pass after implementation
- Code should be well-structured
- No unnecessary complexity
- Handle edge cases and errors as tests specify

## Output
1. Create/modify implementation files
2. Run tests and verify they pass
3. Report:
   - Files created/modified
   - Key implementation decisions
   - Any suggestions for verify/accept phases

## Important
Tests MUST pass (GREEN phase). If tests fail, continue implementation.
`;
  }
}

实现验证

class CoderAgent extends BaseAgent {
  async execute(context: AgentContext): Promise<AgentResult> {
    // ... 执行 Agent ...
    
    // 验证测试是否通过
    const testResult = await this.runTests();
    
    if (testResult.status === 'failed') {
      // 测试未通过，需要继续开发
      return {
        taskId: context.taskId,
        agentType: 'coder',
        status: 'blocked',
        blockInfo: {
          reason: 'Tests still failing after implementation',
          type: 'information',
          missingInfo: ['Implementation approach guidance']
        }
      };
    }
    
    // 测试通过 = Develop 成功
    const changedFiles = this.getChangedFiles();
    
    for (const file of changedFiles) {
      this.logFileChange({
        action: file.action,
        file: file.path,
        purpose: 'Feature implementation'
      });
    }
    
    this.logDecision({
      description: 'Implementation approach',
      reason: 'To pass all test cases',
      impact: changedFiles.map(f => f.path).join(', ')
    });
    
    return {
      taskId: context.taskId,
      agentType: 'coder',
      status: 'success',
      output: {
        artifacts: changedFiles.map(f => f.path),
        contextUpdate: `## Develop Complete\n- Implementation files: ${changedFiles.length}`,
        suggestions: ['Run quality gates in verify phase']
      }
    };
  }
}

5.7 ExecutorAgent 执行 Agent

ExecutorAgent 负责在 Verify 阶段运行质量门禁。

七个质量门禁

flowchart TD
    A[Verify 开始] --> B[Build 检查]
    B --> C[Test 运行]
    C --> D[Coverage 检查]
    D --> E[Lint 检查]
    E --> F[Security 扫描]
    F --> G[E2E 测试<br/>可选]
    G --> H[Acceptance 标准]
    
    H --> I{全部通过?}
    I --> |"是"| J[Verify 成功]
    I --> |"否"| K[Verify 失败]

Prompt 构建

class ExecutorAgent extends BaseAgent {
  protected buildPrompt(context: AgentContext): string {
    const qualityConfig = this.getQualityConfig();

    return `
# Task: ${context.task.title}
# Phase: Verify (Quality Gates)

## Task Description
${context.task.description}

## Context from Previous Agents
${context.accumulatedContext}

## Quality Configuration
- Level: ${qualityConfig.level}
- TDD: ${qualityConfig.tdd ? 'Yes' : 'No'}
- Min Coverage: ${qualityConfig.minCoverage}%
- Strict Lint: ${qualityConfig.strictLint ? 'Yes' : 'No'}
- Security Scan: ${qualityConfig.securityScan ? 'Yes' : 'No'}
- E2E Tests: ${qualityConfig.e2eTests ? 'Yes' : 'No'}

## Your Task: Run Quality Gates

Execute the following checks in order:

### 1. Build Check
```bash
npm run build
```
Must complete without errors.

### 2. Test Run
```bash
npm test
```
All tests must pass.

### 3. Coverage Check
Run coverage tool and verify minimum threshold.
- Required: ${qualityConfig.minCoverage}% coverage
- Report: Line, function, and branch coverage

### 4. Lint Check
${qualityConfig.strictLint ? 'Run strict lint mode' : 'Run standard lint'}
```bash
npm run lint
```
No errors allowed.

### 5. Security Scan
${qualityConfig.securityScan ? `Run security audit
```bash
npm audit
```
No high/critical vulnerabilities allowed.` : 'Skipped'}

### 6. E2E Tests
${qualityConfig.e2eTests ? `Run end-to-end tests if available
```bash
npm run e2e
``` ` : 'Skipped'}

### 7. Acceptance Criteria
Verify task-specific acceptance criteria from description.

## Output Format
Return a JSON report:
{
  "build": { "status": "pass/fail", "details": "..." },
  "test": { "status": "pass/fail", "passed": N, "failed": M },
  "coverage": { "status": "pass/fail", "percentage": X },
  "lint": { "status": "pass/fail", "errors": N },
  "security": { "status": "pass/fail", "vulnerabilities": [...] },
  "e2e": { "status": "pass/fail/skipped", "..." },
  "acceptance": { "status": "pass/fail", "criteria": [...] }
}

## Important
Run ALL gates. Report failures honestly. Do not skip gates.
`;
  }
}

验证结果处理

interface QualityReport {
  build: GateResult;
  test: GateResult;
  coverage: CoverageResult;
  lint: GateResult;
  security: SecurityResult;
  e2e: GateResult;
  acceptance: AcceptanceResult;
  overallStatus: 'pass' | 'fail';
}

interface GateResult {
  status: 'pass' | 'fail';
  details?: string;
}

interface CoverageResult extends GateResult {
  line: number;
  function: number;
  branch: number;
  threshold: number;
}

class ExecutorAgent extends BaseAgent {
  async execute(context: AgentContext): Promise<AgentResult> {
    const report = await this.runQualityGates(context);
    
    // 保存验证报告
    this.stateManager.savePhaseResult(
      context.taskId,
      'verify',
      report
    );
    
    if (report.overallStatus === 'pass') {
      return {
        taskId: context.taskId,
        agentType: 'executor',
        status: 'success',
        output: {
          artifacts: [],
          contextUpdate: `## Verify Complete\n- All quality gates passed`,
          suggestions: ['Proceed to accept phase for final review']
        }
      };
    }
    
    // 有失败的质量门禁
    const failedGates = this.getFailedGates(report);
    
    return {
      taskId: context.taskId,
      agentType: 'executor',
      status: 'failed',
      error: {
        message: `Quality gates failed: ${failedGates.join(', ')}`,
        retryable: this.isRetryable(report)
      }
    };
  }
}

5.8 ReviewerAgent 审查 Agent

ReviewerAgent 负责在 Accept 阶段进行最终审查。

审查维度

graph TD
    A[Accept 开始] --> B[代码质量审查]
    A --> C[最佳实践检查]
    A --> D[安全考虑审查]
    A --> E[文档完整性检查]
    
    B --> F{审查结果}
    C --> F
    D --> F
    E --> F
    
    F --> |"全部通过"| G[Accept 成功]
    F --> |"有问题"| H[Accept 失败]

Prompt 构建

class ReviewerAgent extends BaseAgent {
  protected buildPrompt(context: AgentContext): string {
    const changedFiles = this.getChangedFiles(context.taskId);
    const verifyReport = this.getVerifyReport(context.taskId);
    
    return `
# Task: ${context.task.title}
# Phase: Accept (Final Review)

## Task Description
${context.task.description}

## Context from Previous Agents
${context.accumulatedContext}

## Verify Phase Report
${JSON.stringify(verifyReport, null, 2)}

## Changed Files
${changedFiles.map(f => `### ${f}\n${this.fileStore.read(f)}`).join('\n\n')}

## Your Task: Final Review

Review the implementation for:

### 1. Code Quality
- Structure: Is the code well-organized?
- Naming: Are names clear and consistent?
- Complexity: Is complexity appropriate?
- Duplication: Is there unnecessary duplication?

### 2. Best Practices
- Patterns: Are appropriate patterns used?
- Conventions: Does code follow project conventions?
- Error Handling: Are errors handled properly?
- Testing: Is testing adequate?

### 3. Security Considerations
- Input Validation: Is input validated?
- Authentication: Is auth handled properly?
- Authorization: Are permissions checked?
- Data Protection: Is sensitive data protected?

### 4. Documentation Completeness
- Comments: Are complex parts commented?
- Types: Are types well-defined?
- README: Is README updated if needed?

## Output Format
Return a JSON review:
{
  "codeQuality": { 
    "score": 1-10,
    "issues": [...],
    "suggestions": [...]
  },
  "bestPractices": { 
    "score": 1-10,
    "issues": [...]
  },
  "security": { 
    "score": 1-10,
    "issues": [...]
  },
  "documentation": { 
    "score": 1-10,
    "issues": [...]
  },
  "overallScore": 1-10,
  "approved": true/false,
  "blockers": [...],
  "recommendations": [...]
}

## Important
Be thorough but practical. Focus on significant issues, not minor nitpicks.
Approve if code is good enough for production, suggest improvements separately.
`;
  }
}

审查结果处理

interface AcceptanceResult {
  codeQuality: ReviewDimension;
  bestPractices: ReviewDimension;
  security: ReviewDimension;
  documentation: ReviewDimension;
  overallScore: number;
  approved: boolean;
  blockers: string[];
  recommendations: string[];
}

interface ReviewDimension {
  score: number;       // 1-10
  issues: string[];
  suggestions?: string[];
}

class ReviewerAgent extends BaseAgent {
  async execute(context: AgentContext): Promise<AgentResult> {
    const review = await this.runReview(context);
    
    // 保存接受报告
    this.stateManager.savePhaseResult(
      context.taskId,
      'accept',
      review
    );
    
    if (review.approved) {
      this.logDecision({
        description: 'Accepted implementation',
        reason: `Overall score: ${review.overallScore}/10`,
        impact: 'Task marked complete'
      });
      
      return {
        taskId: context.taskId,
        agentType: 'reviewer',
        status: 'success',
        output: {
          artifacts: [],
          contextUpdate: `## Accept Complete\n- Score: ${review.overallScore}/10\n- Approved: Yes`,
          suggestions: review.recommendations
        }
      };
    }
    
    // 未通过审查
    return {
      taskId: context.taskId,
      agentType: 'reviewer',
      status: 'failed',
      error: {
        message: `Review not approved: ${review.blockers.join('; ')}`,
        retryable: true
      }
    };
  }
}

5.9 ResearcherAgent 研究 Agent

ResearcherAgent 是辅助 Agent，负责信息收集和调研。

使用场景

• 任务开始前的技术调研
• 阻塞问题的问题诊断
• 最佳实践和方案选择

Prompt 构建

class ResearcherAgent extends BaseAgent {
  protected buildPrompt(context: AgentContext): string {
    return `
# Research Request

## Task Context
${context.task.description}

## Research Question
${context.task.researchQuestion}

## Research Goals
1. Understand existing approaches and best practices
2. Identify relevant tools and libraries
3. Gather information to unblock the task
4. Provide actionable recommendations

## Research Areas
- Technical feasibility
- Implementation patterns
- Alternative approaches
- Potential challenges

## Output Format
Return a structured research report:
{
  "summary": "Brief overview of findings",
  "approaches": [
    {
      "name": "Approach name",
      "description": "How it works",
      "pros": [...],
      "cons": [...],
      "recommendation": "Why choose/not choose"
    }
  ],
  "tools": [
    {
      "name": "Tool name",
      "purpose": "What it does",
      "usage": "How to use"
    }
  ],
  "challenges": [...],
  "recommendations": [...],
  "resources": [
    {
      "type": "documentation/article/example",
      "url": "...",
      "description": "..."
    }
  ]
}

## Important
Focus on actionable information. Provide specific recommendations.
`;
  }
}

5.10 Agent Memory (上下文传递)

Agent Memory 是 Agent 之间传递信息的机制。

上下文文件结构

.openmatrix/
├── context.md              # 全局上下文
└── tasks/
    └── TASK-001/
        └── context.md      # 任务特定上下文

全局上下文内容

## Decision [planner]
- **Task**: TASK-001
- **Decision**: Use Vitest as test framework
- **Reason**: Project already uses Vitest
- **Impact**: Tester Agent should use Vitest syntax

## File Change [tester]
- **Task**: TASK-001
- **Action**: create
- **File**: tests/user.test.ts
- **Purpose**: TDD test file for user model

## Decision [coder]
- **Task**: TASK-001
- **Decision**: Use interface for User type
- **Reason**: Better type safety and extensibility
- **Impact**: src/models/user.ts defines IUser interface

## File Change [coder]
- **Task**: TASK-001
- **Action**: create
- **File**: src/models/user.ts
- **Purpose**: User model implementation

## Suggestion [tester]
- **Task**: TASK-001
- **Suggestion**: Add edge case test for empty name
- **For**: Verify phase

## Decision [executor]
- **Task**: TASK-001
- **Decision**: All quality gates passed
- **Reason**: Coverage 85%, lint clean, security clean
- **Impact**: Proceed to accept phase

## Accept Complete [reviewer]
- **Task**: TASK-001
- **Score**: 8/10
- **Approved**: Yes
- **Recommendations**: Add JSDoc comments for public methods

上下文传递流程

sequenceDiagram
    participant P as Planner
    participant T as Tester
    participant C as Coder
    participant E as Executor
    participant R as Reviewer
    
    P->>P: 执行规划
    P->>CTX: 写入决策
    
    T->>CTX: 读取前序上下文
    T->>T: 执行 TDD
    T->>CTX: 写入文件变更
    
    C->>CTX: 读取累积上下文
    C->>C: 执行 Develop
    C->>CTX: 写入实现决策
    
    E->>CTX: 读取累积上下文
    E->>E: 执行 Verify
    E->>CTX: 写入验证结果
    
    R->>CTX: 读取完整上下文
    R->>R: 执行 Accept
    R->>CTX: 写入接受报告

上下文 API

interface ContextManager {
  /**
   * 读取全局上下文
   */
  readGlobalContext(): string;
  
  /**
   * 读取任务上下文
   */
  readTaskContext(taskId: string): string;
  
  /**
   * 追加全局上下文
   */
  appendGlobalContext(content: string): void;
  
  /**
   * 追加任务上下文
   */
  appendTaskContext(taskId: string, content: string): void;
  
  /**
   * 获取累积上下文（全局 + 任务）
   */
  getAccumulatedContext(taskId: string): string;
}

下一章将深入探讨 Storage 存储层 的设计与实现。

第六章：Storage 存储层

Storage 存储层提供状态持久化能力，确保执行过程可恢复。

6.1 存储架构总览

目录结构

.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/      # 输出文件
│   ├── TASK-002/
│   │   └── ...
│   └── ...
├── approvals/
│   ├── APPROVAL-001/
│   │   └── approval.json   # 审批记录
│   └── ...
├── meetings/
│   ├── MEETING-001/
│   │   ├── meeting.json    # Meeting 定义
│   │   ├── context.md      # 阻塞上下文
│   │   └── resolution.md   # 解决方案
│   └── ...
└── .lock                   # 文件锁（运行时）

存储层级结构

graph TD
    subgraph "存储层组件"
        FS[FileStore<br/>文件操作]
        SM[StateManager<br/>状态管理]
    end
    
    subgraph "文件结构"
        ST[state.json]
        PL[plan.md]
        CTX[context.md]
        TI[tasks-input.json]
        TK[tasks/*.json]
        AP[approvals/*.json]
        MT[meetings/*.json]
        LK[.lock]
    end
    
    FS --> ST
    FS --> PL
    FS --> CTX
    FS --> TI
    FS --> TK
    FS --> AP
    FS --> MT
    
    SM --> FS
    SM --> LK

6.2 FileStore 文件存储

FileStore 提供底层文件操作能力。

核心接口

// storage/file-store.ts

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;
  
  /**
   * 列出目录内容
   */
  listDir(path: string): string[];
  
  /**
   * 创建目录
   */
  createDir(path: string): void;
  
  /**
   * 删除目录
   */
  removeDir(path: string): void;
}

JSON 文件操作

class FileStoreImpl implements FileStore {
  readJson<T>(path: string): T {
    if (!this.exists(path)) {
      throw new Error(`File not found: ${path}`);
    }
    
    const content = fs.readFileSync(path, 'utf-8');
    return JSON.parse(content) as T;
  }
  
  writeJson<T>(path: string, data: T): void {
    const content = JSON.stringify(data, null, 2);
    
    // 确保目录存在
    const dir = path.dirname(path);
    if (!this.exists(dir)) {
      this.createDir(dir);
    }
    
    fs.writeFileSync(path, content, 'utf-8');
  }
}

Markdown 文件操作

class FileStoreImpl implements FileStore {
  readMd(path: string): string {
    if (!this.exists(path)) {
      return '';  // 空文件返回空字符串
    }
    
    return fs.readFileSync(path, 'utf-8');
  }
  
  writeMd(path: string, content: string): void {
    const dir = path.dirname(path);
    if (!this.exists(dir)) {
      this.createDir(dir);
    }
    
    fs.writeFileSync(path, content, 'utf-8');
  }
  
  atomicAppend(path: string, content: string): void {
    // 使用追加模式确保原子性
    const dir = path.dirname(path);
    if (!this.exists(dir)) {
      this.createDir(dir);
    }
    
    // 添加时间戳分隔
    const timestamp = new Date().toISOString();
    const fullContent = `\n\n---\n**${timestamp}**\n${content}`;
    
    fs.appendFileSync(path, fullContent, 'utf-8');
  }
}

文件锁机制

class FileStoreImpl implements FileStore {
  private lockPath = '.openmatrix/.lock';
  private lockTimeout = 30000;  // 30秒
  
  acquireLock(): Promise<void> {
    const startTime = Date.now();
    
    while (Date.now() - startTime < this.lockTimeout) {
      try {
        // 尝试创建锁文件
        const lockContent = JSON.stringify({
          pid: process.pid,
          timestamp: Date.now()
        });
        
        fs.writeFileSync(this.lockPath, lockContent, { flag: 'wx' });
        return;  // 成功获取锁
      } catch (err) {
        if (err.code === 'EEXIST') {
          // 锁文件已存在，检查是否过期
          const lockData = this.readJson(this.lockPath);
          const lockAge = Date.now() - lockData.timestamp;
          
          if (lockAge > this.lockTimeout) {
            // 锁已过期，强制删除
            this.delete(this.lockPath);
            continue;
          }
          
          // 等待一小段时间后重试
          await new Promise(r => setTimeout(r, 100));
        } else {
          throw err;
        }
      }
    }
    
    throw new Error('Failed to acquire lock within timeout');
  }
  
  releaseLock(): void {
    if (this.exists(this.lockPath)) {
      const lockData = this.readJson(this.lockPath);
      
      // 只释放自己持有的锁
      if (lockData.pid === process.pid) {
        this.delete(this.lockPath);
      }
    }
  }
}

6.3 StateManager 状态管理

StateManager 管理全局和任务状态。

核心接口

// storage/state-manager.ts

interface StateManager {
  /**
   * 初始化存储
   */
  initialize(runId: string, input: TaskInput): void;
  
  /**
   * 获取全局状态
   */
  getState(): GlobalState;
  
  /**
   * 更新全局状态
   */
  updateState(updates: Partial<GlobalState>): void;
  
  /**
   * 获取任务
   */
  getTask(taskId: string): Task;
  
  /**
   * 获取所有任务
   */
  getAllTasks(): Task[];
  
  /**
   * 按状态获取任务
   */
  getTasksByStatus(status: TaskStatus): Task[];
  
  /**
   * 保存任务
   */
  saveTask(task: Task): void;
  
  /**
   * 更新任务状态
   */
  updateTaskStatus(taskId: string, status: TaskStatus): void;
  
  /**
   * 保存阶段结果
   */
  savePhaseResult(taskId: string, phase: PhaseType, result: any): void;
  
  /**
   * 获取 Meeting
   */
  getMeeting(meetingId: string): Meeting;
  
  /**
   * 获取待处理 Meeting
   */
  getPendingMeetings(): Meeting[];
  
  /**
   * 保存 Meeting
   */
  saveMeeting(meeting: Meeting): void;
  
  /**
   * 获取审批
   */
  getApproval(approvalId: string): Approval;
  
  /**
   * 获取待处理审批
   */
  getPendingApprovals(): Approval[];
  
  /**
   * 保存审批
   */
  saveApproval(approval: Approval): void;
  
  /**
   * 获取执行统计
   */
  getStatistics(): ExecutionStatistics;
  
  /**
   * 清理存储
   */
  cleanup(): void;
}

GlobalState 结构

interface GlobalState {
  // 运行标识
  runId: string;
  status: ExecutionStatus;
  
  // 配置
  config: {
    quality: QualityLevel;
    mode: ExecutionMode;
    e2eTests: boolean;
    bypassApprovals: boolean;
  };
  
  // 统计
  statistics: {
    totalTasks: number;
    completedTasks: number;
    failedTasks: number;
    blockedTasks: number;
    pendingMeetings: number;
    pendingApprovals: number;
  };
  
  // 当前任务
  currentTask: string | null;
  
  // 时间信息
  createdAt: string;
  updatedAt: string;
  completedAt?: string;
}

状态初始化

class StateManagerImpl implements StateManager {
  initialize(runId: string, input: TaskInput): void {
    const basePath = '.openmatrix';
    
    // 创建目录结构
    if (!this.fileStore.exists(basePath)) {
      this.fileStore.createDir(basePath);
      this.fileStore.createDir(`${basePath}/tasks`);
      this.fileStore.createDir(`${basePath}/approvals`);
      this.fileStore.createDir(`${basePath}/meetings`);
    }
    
    // 初始化全局状态
    const state: GlobalState = {
      runId,
      status: 'running',
      config: {
        quality: 'balanced',
        mode: 'semi-auto',
        e2eTests: false,
        bypassApprovals: false
      },
      statistics: {
        totalTasks: 0,
        completedTasks: 0,
        failedTasks: 0,
        blockedTasks: 0,
        pendingMeetings: 0,
        pendingApprovals: 0
      },
      currentTask: null,
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString()
    };
    
    this.fileStore.writeJson(`${basePath}/state.json`, state);
    
    // 保存任务输入
    this.fileStore.writeJson(`${basePath}/tasks-input.json`, input);
    
    // 初始化上下文文件
    this.fileStore.writeMd(`${basePath}/context.md`, '# Agent Memory\n\n');
    this.fileStore.writeMd(`${basePath}/plan.md`, '# Execution Plan\n\n');
  }
}

任务状态管理

class StateManagerImpl implements StateManager {
  saveTask(task: Task): void {
    const basePath = `.openmatrix/tasks/${task.id}`;
    
    // 创建任务目录
    if (!this.fileStore.exists(basePath)) {
      this.fileStore.createDir(basePath);
      this.fileStore.createDir(`${basePath}/artifacts`);
    }
    
    // 保存任务定义
    this.fileStore.writeJson(`${basePath}/task.json`, task);
    
    // 更新统计
    this.updateStatistics();
  }
  
  updateTaskStatus(taskId: string, status: TaskStatus): void {
    const task = this.getTask(taskId);
    task.status = status;
    task.updatedAt = new Date().toISOString();
    
    // 记录状态历史
    task.statusHistory.push({
      from: task.status,
      to: status,
      timestamp: new Date().toISOString()
    });
    
    this.saveTask(task);
    
    // 更新全局状态
    this.updateState({
      currentTask: status === 'in_progress' ? taskId : null,
      updatedAt: new Date().toISOString()
    });
    
    // 更新统计
    this.updateStatistics();
  }
  
  updateStatistics(): void {
    const tasks = this.getAllTasks();
    const meetings = this.getPendingMeetings();
    const approvals = this.getPendingApprovals();
    
    this.updateState({
      statistics: {
        totalTasks: tasks.length,
        completedTasks: tasks.filter(t => t.status === 'completed').length,
        failedTasks: tasks.filter(t => t.status === 'failed').length,
        blockedTasks: tasks.filter(t => t.status === 'waiting').length,
        pendingMeetings: meetings.length,
        pendingApprovals: approvals.length
      }
    });
  }
}

阶段结果保存

class StateManagerImpl implements StateManager {
  savePhaseResult(taskId: string, phase: PhaseType, result: any): void {
    const basePath = `.openmatrix/tasks/${taskId}`;
    
    // 保存阶段结果文件
    this.fileStore.writeJson(`${basePath}/${phase}.json`, result);
    
    // 更新任务的状态
    const task = this.getTask(taskId);
    task.phases.push({
      type: phase,
      status: result.status,
      completedAt: new Date().toISOString()
    });
    
    this.saveTask(task);
  }
}

Meeting 管理

class StateManagerImpl implements StateManager {
  getPendingMeetings(): Meeting[] {
    const basePath = '.openmatrix/meetings';
    
    if (!this.fileStore.exists(basePath)) {
      return [];
    }
    
    const meetingDirs = this.fileStore.listDir(basePath);
    const meetings: Meeting[] = [];
    
    for (const dir of meetingDirs) {
      const meetingPath = `${basePath}/${dir}/meeting.json`;
      if (this.fileStore.exists(meetingPath)) {
        const meeting = this.fileStore.readJson<Meeting>(meetingPath);
        if (meeting.status === 'pending') {
          meetings.push(meeting);
        }
      }
    }
    
    return meetings;
  }
  
  saveMeeting(meeting: Meeting): void {
    const basePath = `.openmatrix/meetings/${meeting.id}`;
    
    if (!this.fileStore.exists(basePath)) {
      this.fileStore.createDir(basePath);
    }
    
    this.fileStore.writeJson(`${basePath}/meeting.json`, meeting);
    
    // 如果有上下文，保存上下文
    if (meeting.context) {
      this.fileStore.writeMd(`${basePath}/context.md`, meeting.context);
    }
    
    this.updateStatistics();
  }
}

审批管理

class StateManagerImpl implements StateManager {
  getPendingApprovals(): Approval[] {
    const basePath = '.openmatrix/approvals';
    
    if (!this.fileStore.exists(basePath)) {
      return [];
    }
    
    const approvalDirs = this.fileStore.listDir(basePath);
    const approvals: Approval[] = [];
    
    for (const dir of approvalDirs) {
      const approvalPath = `${basePath}/${dir}/approval.json`;
      if (this.fileStore.exists(approvalPath)) {
        const approval = this.fileStore.readJson<Approval>(approvalPath);
        if (approval.status === 'pending') {
          approvals.push(approval);
        }
      }
    }
    
    return approvals;
  }
  
  saveApproval(approval: Approval): void {
    const basePath = `.openmatrix/approvals/${approval.id}`;
    
    if (!this.fileStore.exists(basePath)) {
      this.fileStore.createDir(basePath);
    }
    
    this.fileStore.writeJson(`${basePath}/approval.json`, approval);
    
    this.updateStatistics();
  }
}

清理存储

class StateManagerImpl implements StateManager {
  cleanup(): void {
    const basePath = '.openmatrix';
    
    // 删除锁文件
    if (this.fileStore.exists(`${basePath}/.lock`)) {
      this.fileStore.delete(`${basePath}/.lock`);
    }
    
    // 可选：清理临时文件
    // 注意：不删除实际数据，只清理运行时临时文件
  }
}

6.4 数据类型定义

Task 类型

interface Task {
  id: string;                    // TASK-001
  title: string;                 // 任务标题
  description: string;           // 详细描述
  status: TaskStatus;            // 当前状态
  
  // Agent 相关
  agentType: AgentType;          // 负责的 Agent
  phases: PhaseRecord[];         // 阶段执行记录
  
  // 依赖关系
  dependencies: string[];        // 依赖的任务 ID
  dependents: string[];          // 被依赖的任务 ID
  
  // 优先级和复杂度
  priority: number;              // 优先级 (1-10)
  estimatedComplexity: string;   // 预估复杂度
  
  // 输出
  artifacts: string[];           // 输出文件路径
  
  // 时间信息
  createdAt: string;
  updatedAt: string;
  completedAt?: string;
  
  // 状态历史
  statusHistory: StatusTransition[];
  
  // 重试信息
  retryCount?: number;
  lastError?: ErrorInfo;
}

interface PhaseRecord {
  type: PhaseType;
  status: 'pending' | 'running' | 'success' | 'failed';
  startedAt?: string;
  completedAt?: string;
  error?: ErrorInfo;
}

interface StatusTransition {
  from: TaskStatus;
  to: TaskStatus;
  timestamp: string;
  reason?: string;
}

Meeting 类型

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

type MeetingType = 
  | 'information'    // 缺少信息
  | 'decision'       // 需要决策
  | 'approval'       // 需要审批
  | 'dependency';    // 依赖问题

interface Question {
  id: string;
  text: string;
  type: 'text' | 'choice' | 'boolean';
  options?: string[];
  required: boolean;
  default?: string;
}

interface Resolution {
  answers: Map<string, string>;
  decision?: 'skip' | 'retry';
  notes?: string;
}

Approval 类型

interface Approval {
  id: string;                    // APPROVAL-001
  type: ApprovalType;            // 审批类型
  
  content: ApprovalContent;      // 审批内容
  context?: string;              // 相关上下文
  
  status: 'pending' | 'approved' | 'rejected';
  
  createdAt: string;
  processedAt?: string;
  
  decision?: 'approve' | 'reject';
  feedback?: string;
}

type ApprovalType = 
  | 'plan'         // 计划审批
  | 'merge'        // 合并审批
  | 'deploy'       // 部署审批
  | 'meeting';     // Meeting 决策

interface ApprovalContent {
  // plan 类型
  tasks?: Task[];
  planSummary?: string;
  
  // merge 类型
  files?: string[];
  commitMessage?: string;
  
  // deploy 类型
  environment?: string;
  config?: any;
  
  // meeting 类型
  meeting?: Meeting;
}

统计类型

interface ExecutionStatistics {
  totalTasks: number;
  completedTasks: number;
  failedTasks: number;
  blockedTasks: number;
  
  // 阶段统计
  phases: {
    tdd: { completed: number; failed: number };
    develop: { completed: number; failed: number };
    verify: { completed: number; failed: number };
    accept: { completed: number; failed: number };
  };
  
  // 时间统计
  timing: {
    startedAt: string;
    estimatedCompletion?: string;
    actualCompletion?: string;
    totalDurationMs?: number;
  };
  
  // 质量统计
  quality: {
    averageCoverage?: number;
    averageReviewScore?: number;
    totalLintErrors?: number;
    securityIssues?: number;
  };
}

6.5 数据一致性保障

写前读验证

class StateManagerImpl {
  updateTask(taskId: string, updates: Partial<Task>): void {
    // 获取锁
    this.fileStore.acquireLock();
    
    try {
      // 读取当前状态
      const currentTask = this.getTask(taskId);
      
      // 验证状态一致性
      if (currentTask.updatedAt !== updates.updatedAt) {
        throw new Error('Task state conflict - concurrent modification');
      }
      
      // 应用更新
      const updatedTask = { ...currentTask, ...updates };
      updatedTask.updatedAt = new Date().toISOString();
      
      // 保存
      this.saveTask(updatedTask);
    } finally {
      // 释放锁
      this.fileStore.releaseLock();
    }
  }
}

状态版本控制

interface VersionedState {
  version: number;
  state: GlobalState;
  checksum: string;
}

class StateManagerImpl {
  updateState(updates: Partial<GlobalState>): void {
    this.fileStore.acquireLock();
    
    try {
      const current = this.getStateWithVersion();
      
      // 验证版本
      const newVersion = current.version + 1;
      
      // 创建新状态
      const newState = {
        version: newVersion,
        state: { ...current.state, ...updates },
        checksum: this.calculateChecksum({ ...current.state, ...updates })
      };
      
      // 保存
      this.fileStore.writeJson('.openmatrix/state.json', newState);
    } finally {
      this.fileStore.releaseLock();
    }
  }
  
  calculateChecksum(data: any): string {
    const content = JSON.stringify(data);
    return crypto.createHash('md5').update(content).digest('hex');
  }
}

并发写入处理

flowchart TD
    A[并发写入请求] --> B[获取文件锁]
    B --> C{锁获取成功?}
    
    C --> |"成功"| D[读取当前状态]
    C --> |"失败"| E[等待重试]
    
    D --> F[验证版本一致性]
    F --> G{版本一致?}
    
    G --> |"一致"| H[应用更新]
    G --> |"不一致"| I[合并变更<br/>或报错]
    
    H --> J[写入新状态]
    J --> K[释放锁]
    
    E --> B
    I --> J
    
    K --> L[完成]

6.6 数据恢复机制

状态恢复

class StateManagerImpl {
  recoverState(): GlobalState | null {
    const statePath = '.openmatrix/state.json';
    
    if (!this.fileStore.exists(statePath)) {
      return null;  // 无历史状态
    }
    
    try {
      const versioned = this.fileStore.readJson<VersionedState>(statePath);
      
      // 验证 checksum
      const expectedChecksum = this.calculateChecksum(versioned.state);
      if (versioned.checksum !== expectedChecksum) {
        // 状态文件损坏，尝试恢复
        return this.recoverFromBackup();
      }
      
      return versioned.state;
    } catch (err) {
      // JSON 解析失败，文件损坏
      return this.recoverFromBackup();
    }
  }
  
  recoverFromBackup(): GlobalState | null {
    const backupPath = '.openmatrix/state.json.backup';
    
    if (this.fileStore.exists(backupPath)) {
      try {
        return this.fileStore.readJson<GlobalState>(backupPath);
      } catch {
        return null;
      }
    }
    
    return null;
  }
}

任务恢复

class StateManagerImpl {
  recoverTasks(): Task[] {
    const basePath = '.openmatrix/tasks';
    
    if (!this.fileStore.exists(basePath)) {
      return [];
    }
    
    const tasks: Task[] = [];
    const taskDirs = this.fileStore.listDir(basePath);
    
    for (const dir of taskDirs) {
      const taskPath = `${basePath}/${dir}/task.json`;
      
      if (this.fileStore.exists(taskPath)) {
        try {
          const task = this.fileStore.readJson<Task>(taskPath);
          tasks.push(task);
        } catch {
          // 单个任务文件损坏，跳过
          console.warn(`Corrupted task file: ${taskPath}`);
        }
      }
    }
    
    return tasks;
  }
}

6.7 存储监控

存储健康检查

interface StorageHealth {
  status: 'healthy' | 'warning' | 'critical';
  checks: {
    stateFile: 'ok' | 'missing' | 'corrupted';
    tasksDir: 'ok' | 'missing';
    meetingsDir: 'ok' | 'missing';
    approvalsDir: 'ok' | 'missing';
  };
  issues: string[];
  lastChecked: string;
}

class StateManagerImpl {
  checkHealth(): StorageHealth {
    const health: StorageHealth = {
      status: 'healthy',
      checks: {
        stateFile: 'ok',
        tasksDir: 'ok',
        meetingsDir: 'ok',
        approvalsDir: 'ok'
      },
      issues: [],
      lastChecked: new Date().toISOString()
    };
    
    // 检查 state.json
    const statePath = '.openmatrix/state.json';
    if (!this.fileStore.exists(statePath)) {
      health.checks.stateFile = 'missing';
      health.issues.push('state.json is missing');
      health.status = 'critical';
    } else {
      try {
        this.fileStore.readJson(statePath);
      } catch {
        health.checks.stateFile = 'corrupted';
        health.issues.push('state.json is corrupted');
        health.status = 'critical';
      }
    }
    
    // 检查目录
    const dirs = ['tasks', 'meetings', 'approvals'];
    for (const dir of dirs) {
      const dirPath = `.openmatrix/${dir}`;
      if (!this.fileStore.exists(dirPath)) {
        health.checks[`dir`] = 'missing';
        health.issues.push(`${dir} directory is missing`);
        health.status = 'warning';
      }
    }
    
    return health;
  }
}

存储大小监控

class StateManagerImpl {
  getStorageSize(): StorageSizeInfo {
    const basePath = '.openmatrix';
    
    const sizeInfo = {
      totalSizeBytes: 0,
      files: {
        state: 0,
        tasks: 0,
        meetings: 0,
        approvals: 0,
        context: 0,
        plan: 0
      }
    };
    
    // 计算各部分大小
    const statePath = `${basePath}/state.json`;
    if (this.fileStore.exists(statePath)) {
      sizeInfo.files.state = fs.statSync(statePath).size;
    }
    
    const tasksDir = `${basePath}/tasks`;
    if (this.fileStore.exists(tasksDir)) {
      sizeInfo.files.tasks = this.calculateDirSize(tasksDir);
    }
    
    // ... 其他部分
    
    sizeInfo.totalSizeBytes = Object.values(sizeInfo.files)
      .reduce((a, b) => a + b, 0);
    
    return sizeInfo;
  }
}

下一章将详细讲解 CLI 命令系统。

第七章：CLI 命令详解

OpenMatrix 提供完整的 CLI 命令系统，支持多种执行模式和状态管理。

7.1 CLI 架构总览

命令结构

graph TD
    CLI[openmatrix CLI] --> CMDS[Commands]
    
    CMDS --> START[start]
    CMDS --> AUTO[auto]
    CMDS --> STATUS[status]
    CMDS --> APPROVE[approve]
    CMDS --> MEETING[meeting]
    CMDS --> RESUME[resume]
    CMDS --> RETRY[retry]
    CMDS --> REPORT[report]
    CMDS --> STEP[step]
    CMDS --> COMPLETE[complete]
    CMDS --> BRAIN[brainstorm]
    CMDS --> RESEARCH[research]
    CMDS --> CHECK[check]
    CMDS --> INSTALL[install-skills]

基本使用

# 查看帮助
openmatrix --help

# 查看命令帮助
openmatrix start --help

# 执行命令
openmatrix start --quality strict --mode semi-auto

7.2 start 命令

启动新的任务执行周期。

命令签名

openmatrix start [options]

选项

执行流程

sequenceDiagram
    participant U as 用户
    participant CLI as CLI
    participant SM as StateManager
    participant TP as TaskPlanner
    participant OR as Orchestrator
    
    U->>CLI: openmatrix start
    CLI->>CLI: 检查现有状态
    
    alt "有未完成状态"
        CLI->>U: 提示恢复或新建
        U->>CLI: 选择
    end
    
    CLI->>U: 交互式配置
    U->>CLI: 质量等级、执行模式
    
    CLI->>SM: initialize()
    SM->>SM: 创建 .openmatrix/
    
    CLI->>U: 输入任务指令
    U->>CLI: "实现用户认证系统"
    
    CLI->>TP: plan(input)
    TP->>TP: AI 分析拆解
    TP->>SM: 保存任务列表
    
    CLI->>U: 展示任务计划
    U->>CLI: 确认/修改
    
    CLI->>OR: execute()
    OR->>CLI: 返回 SubagentTask[]
    
    CLI->>U: 输出执行配置

输出格式

普通输出：

OpenMatrix Execution Started
─────────────────────────────
Run ID: run-2024-01-15-001
Quality: strict
Mode: semi-auto

Task Plan:
  TASK-001: Create user model [priority: 10]
  TASK-002: Implement auth API [priority: 8]
  TASK-003: Add validation [priority: 5]

Total Tasks: 3
Ready for execution with /om:step

JSON 输出：

{
  "runId": "run-2024-01-15-001",
  "status": "running",
  "config": {
    "quality": "strict",
    "mode": "semi-auto",
    "e2eTests": false
  },
  "subagentTasks": [
    {
      "taskId": "TASK-001",
      "agentType": "coder",
      "description": "Create user model",
      "prompt": "...",
      "timeout": 300000
    }
  ]
}

实现代码

// cli/commands/start.ts

import { Command } from 'commander';
import inquirer from 'inquirer';

export function registerStartCommand(program: Command) {
  program
    .command('start')
    .description('Start new task execution')
    .option('--quality <level>', 'Quality level (strict/balanced/fast)')
    .option('--mode <mode>', 'Execution mode (interactive/semi-auto/full-auto)')
    .option('--e2e', 'Enable E2E tests')
    .option('--json', 'JSON output format')
    .action(async (options) => {
      // 检查现有状态
      const existingState = stateManager.recoverState();
      if (existingState && existingState.status === 'running') {
        const { action } = await inquirer.prompt([
          {
            type: 'list',
            name: 'action',
            message: 'Found existing running state. What to do?',
            choices: [
              { name: 'Resume existing execution', value: 'resume' },
              { name: 'Start new execution (will clear existing)', value: 'new' }
            ]
          }
        ]);
        
        if (action === 'resume') {
          console.log('Use openmatrix resume to continue');
          return;
        }
        
        // 清理旧状态
        stateManager.cleanup();
      }
      
      // 交互式配置
      if (!options.quality) {
        const { quality } = await inquirer.prompt([
          {
            type: 'list',
            name: 'quality',
            message: 'Select quality level',
            choices: [
              { name: 'strict - Full TDD, >80% coverage, strict lint', value: 'strict' },
              { name: 'balanced - No TDD, >60% coverage, standard lint', value: 'balanced' },
              { name: 'fast - No quality gates', value: 'fast' }
            ]
          }
        ]);
        options.quality = quality;
      }
      
      if (!options.mode) {
        const { mode } = await inquirer.prompt([
          {
            type: 'list',
            name: 'mode',
            message: 'Select execution mode',
            choices: [
              { name: 'interactive - Confirm every step', value: 'interactive' },
              { name: 'semi-auto - Confirm critical points', value: 'semi-auto' },
              { name: 'full-auto - No interruptions', value: 'full-auto' }
            ]
          }
        ]);
        options.mode = mode;
      }
      
      // 获取用户指令
      const { instruction } = await inquirer.prompt([
        {
          type: 'input',
          name: 'instruction',
          message: 'Enter your task instruction:'
        }
      ]);
      
      // 初始化
      const runId = generateRunId();
      stateManager.initialize(runId, { instruction });
      
      // 规划任务
      const taskPlanner = new TaskPlanner();
      const tasks = await taskPlanner.plan({ instruction });
      
      // 保存任务
      for (const task of tasks) {
        stateManager.saveTask(task);
      }
      
      // 展示计划
      if (!options.json) {
        displayPlan(tasks, options);
      }
      
      // 请求审批（interactive/semi-auto 模式）
      if (options.mode !== 'full-auto') {
        const { approved } = await inquirer.prompt([
          {
            type: 'confirm',
            name: 'approved',
            message: 'Approve task plan?',
            default: true
          }
        ]);
        
        if (!approved) {
          console.log('Execution cancelled');
          stateManager.cleanup();
          return;
        }
      }
      
      // 开始执行
      const executor = new Executor();
      const result = await executor.execute({ instruction });
      
      // 输出结果
      if (options.json) {
        console.log(JSON.stringify(result, null, 2));
      } else {
        displayResult(result);
      }
    });
}

7.3 auto 命令

完全自动执行，无阻塞。

命令签名

openmatrix auto [options]

选项

执行流程

sequenceDiagram
    participant U as 用户
    participant CLI as CLI
    participant OR as Orchestrator
    participant AG as Agents
    
    U->>CLI: openmatrix auto --quality strict
    CLI->>OR: execute({ bypassApprovals: true })
    
    OR->>AG: 执行 TASK-001
    
    loop "直到完成"
        AG->>OR: 任务结果
        
        alt "成功"
            OR->>OR: 下一个任务
        alt "阻塞"
            OR->>OR: 创建 Meeting
            OR->>OR: 继续其他任务
        alt "失败"
            OR->>OR: 加入 retry_queue
        end
    end
    
    OR->>CLI: 完成
    CLI->>U: 报告 + Meeting 列表

与 start 的区别

7.4 status 命令

查看当前执行状态。

命令签名

openmatrix status [options]

选项

输出格式

普通输出：

OpenMatrix Status
─────────────────────────────
Run ID: run-2024-01-15-001
Status: running
Quality: strict
Mode: semi-auto

Progress:
  Total:     10 tasks
  Completed:  3 tasks (30%)
  Failed:     1 task
  Blocked:    2 tasks

Current Task: TASK-004 (Develop phase)

Pending Meetings: 2
Pending Approvals: 0

Started:  2024-01-15 10:00:00
Updated:  2024-01-15 12:30:00
Duration: 2h 30m

详细输出：

Tasks Detail:
─────────────────────────────
TASK-001: Create user model
  Status: completed
  Agent: coder
  Phases: TDD ✓, Develop ✓, Verify ✓, Accept ✓
  Duration: 45m

TASK-002: Implement auth API
  Status: failed
  Agent: coder
  Error: Tests failed after 3 retries
  Retry Queue: pending

TASK-003: Add validation
  Status: waiting
  Agent: coder
  Meeting: MEETING-001 (need API spec)

TASK-004: Create UI components
  Status: in_progress
  Agent: coder
  Phase: Develop
  Started: 2024-01-15 11:45:00
...

JSON 输出：

{
  "runId": "run-2024-01-15-001",
  "status": "running",
  "config": {
    "quality": "strict",
    "mode": "semi-auto"
  },
  "statistics": {
    "totalTasks": 10,
    "completedTasks": 3,
    "failedTasks": 1,
    "blockedTasks": 2
  },
  "currentTask": "TASK-004",
  "tasks": [
    {
      "id": "TASK-001",
      "status": "completed",
      "phases": ["TDD", "Develop", "Verify", "Accept"]
    }
  ],
  "meetings": ["MEETING-001", "MEETING-002"],
  "approvals": []
}

7.5 approve 命令

处理待审批项。

命令签名

openmatrix approve [options]
openmatrix approve <approval-id> [options]

选项

审批类型处理

// cli/commands/approve.ts

async function handleApproval(approval: Approval, options: any) {
  switch (approval.type) {
    case 'plan':
      // 展示任务计划
      displayPlan(approval.content.tasks);
      
      const { decision } = await inquirer.prompt([
        {
          type: 'confirm',
          name: 'decision',
          message: 'Approve this task plan?'
        }
      ]);
      
      approvalManager.processApproval(
        approval.id,
        decision ? 'approve' : 'reject'
      );
      break;
      
    case 'merge':
      // 展示变更
      displayChanges(approval.content.files);
      
      const { mergeDecision } = await inquirer.prompt([
        {
          type: 'confirm',
          name: 'mergeDecision',
          message: 'Approve merge?'
        }
      ]);
      
      approvalManager.processApproval(
        approval.id,
        mergeDecision ? 'approve' : 'reject'
      );
      break;
      
    case 'deploy':
      // 展示部署配置
      displayDeployConfig(approval.content);
      
      const { deployDecision } = await inquirer.prompt([
        {
          type: 'confirm',
          name: 'deployDecision',
          message: 'Approve deployment?'
        }
      ]);
      
      approvalManager.processApproval(
        approval.id,
        deployDecision ? 'approve' : 'reject'
      );
      break;
      
    case 'meeting':
      // 处理 Meeting 决策
      await handleMeetingDecision(approval.content.meeting);
      break;
  }
}

7.6 meeting 命令

处理阻塞的 Meeting。

命令签名

openmatrix meeting [options]
openmatrix meeting <meeting-id> [options]

选项

Meeting 处理流程

sequenceDiagram
    participant U as 用户
    participant CLI as CLI
    participant MM as MeetingManager
    participant SM as StateManager
    
    U->>CLI: openmatrix meeting
    CLI->>MM: getPendingMeetings()
    MM->>CLI: Meeting 列表
    
    CLI->>U: 展示 Meeting 详情
    
    alt "提供信息"
        U->>CLI: --answer '{"q1": "answer"}'
        CLI->>MM: resolveMeeting(id, answers)
        MM->>SM: 任务状态 → scheduled
    end
    
    alt "跳过"
        U->>CLI: --skip
        CLI->>MM: skipMeeting(id)
        MM->>SM: 任务状态 → skipped
    end
    
    alt "重试"
        U->>CLI: 选择 retry
        CLI->>MM: resolveMeeting(id, {decision: 'retry'})
        MM->>SM: 任务状态 → retry_queue
    end

交互式处理

async function handleMeeting(meeting: Meeting) {
  console.log(`\nMeeting: ${meeting.title}`);
  console.log(`Type: ${meeting.type}`);
  console.log(`\nDescription:\n${meeting.description}`);
  
  // 展示问题
  for (const question of meeting.questions) {
    console.log(`\nQuestion: ${question.text}`);
    
    if (question.type === 'text') {
      const { answer } = await inquirer.prompt([
        {
          type: 'input',
          name: 'answer',
          message: question.text
        }
      ]);
      answers[question.id] = answer;
    } else if (question.type === 'choice') {
      const { answer } = await inquirer.prompt([
        {
          type: 'list',
          name: 'answer',
          message: question.text,
          choices: question.options
        }
      ]);
      answers[question.id] = answer;
    } else if (question.type === 'boolean') {
      const { answer } = await inquirer.prompt([
        {
          type: 'confirm',
          name: 'answer',
          message: question.text
        }
      ]);
      answers[question.id] = answer ? 'yes' : 'no';
    }
  }
  
  // 处理
  meetingManager.resolveMeeting(meeting.id, { answers });
}

7.7 resume 命令

恢复中断的任务执行。

命令签名

openmatrix resume [options]

选项

恢复流程

sequenceDiagram
    participant U as 用户
    participant CLI as CLI
    participant SM as StateManager
    participant OR as Orchestrator
    
    U->>CLI: openmatrix resume
    CLI->>SM: recoverState()
    SM->>CLI: GlobalState
    
    CLI->>CLI: 验证状态完整性
    
    CLI->>SM: recoverTasks()
    SM->>CLI: Task[]
    
    CLI->>U: 展示恢复信息
    
    U->>CLI: 确认恢复
    
    CLI->>OR: resume(state, tasks)
    OR->>OR: 从中断点继续
    OR->>CLI: SubagentTask[]

7.8 retry 命令

重试失败的任务。

命令签名

openmatrix retry [options]
openmatrix retry <task-id> [options]

选项

重试流程

flowchart TD
    A[openmatrix retry] --> B[获取失败任务]
    B --> C{指定任务?}
    
    C --> |"是"| D[获取指定任务]
    C --> |"否"| E[获取所有失败任务]
    
    D --> F[重置任务状态]
    E --> F
    
    F --> G[状态 → scheduled]
    G --> H[清空错误信息]
    H --> I[重置阶段]
    I --> J[触发重新调度]

7.9 report 命令

生成执行报告。

命令签名

openmatrix report [options]

选项

报告内容

# OpenMatrix Execution Report

## Summary
- **Run ID**: run-2024-01-15-001
- **Status**: completed
- **Duration**: 4h 30m
- **Started**: 2024-01-15 10:00:00
- **Completed**: 2024-01-15 14:30:00

## Configuration
- **Quality**: strict
- **Mode**: semi-auto
- **E2E Tests**: Yes

## Task Statistics
| Metric | Count |
|--------|-------|
| Total Tasks | 10 |
| Completed | 8 |
| Failed | 1 |
| Skipped | 1 |

## Phase Statistics
| Phase | Completed | Failed |
|-------|-----------|--------|
| TDD | 8 | 1 |
| Develop | 8 | 1 |
| Verify | 8 | 0 |
| Accept | 8 | 0 |

## Quality Metrics
- **Average Coverage**: 85%
- **Average Review Score**: 8.5/10
- **Lint Errors**: 0
- **Security Issues**: 0

## Task Details

### TASK-001: Create user model
- **Status**: completed
- **Agent**: coder
- **Duration**: 45m
- **Coverage**: 92%
- **Review Score**: 9/10
- **Files**: src/models/user.ts, tests/user.test.ts

### TASK-002: Implement auth API
- **Status**: failed
- **Agent**: coder
- **Error**: Tests failed after 3 retries
- **Retry Attempts**: 3

...

## Meetings
| ID | Type | Status | Resolution |
|----|------|--------|------------|
| MEETING-001 | information | resolved | API spec provided |
| MEETING-002 | decision | skipped | Alternative approach |

## Recommendations
1. Review failed task TASK-002 for root cause
2. Consider adding integration tests for auth module
3. Update documentation for new user model

7.10 step/complete 命令

持久化执行循环的核心命令。

step 命令

从磁盘获取下一个任务。

openmatrix step [options]

输出：

{
  "taskId": "TASK-004",
  "phase": "develop",
  "agentType": "coder",
  "prompt": "...",
  "timeout": 600000,
  "context": "..."
}

complete 命令

标记任务完成并保存结果。

openmatrix complete <task-id> [options]

step/complete 循环

sequenceDiagram
    participant CLI as CLI
    participant SM as StateManager
    participant SC as Scheduler
    participant SK as Skills/Agent
    
    CLI->>SM: step
    SM->>SC: getNextTask()
    SC->>SM: TASK-004
    SM->>CLI: SubagentTask
    
    CLI->>SK: Agent 执行
    SK->>CLI: 执行结果
    
    CLI->>SM: complete TASK-004 --success
    SM->>SM: 保存结果
    SM->>SM: 更新状态
    
    CLI->>SM: step
    SM->>SC: getNextTask()
    ...

用途

step/complete 循环用于：

1. Context 压缩恢复 - 状态持久化到磁盘
2. 分布式执行 - 多进程协作
3. 手动调试 - 单步执行调试

7.11 brainstorm 命令

交互式头脑风暴，深入探索需求。

命令签名

openmatrix brainstorm [options]

执行流程

sequenceDiagram
    participant U as 用户
    participant CLI as CLI
    participant AG as Researcher Agent
    
    U->>CLI: openmatrix brainstorm "用户系统"
    
    CLI->>AG: 分析需求
    
    AG->>U: 问题1: 需要什么认证方式?
    U->>CLI: JWT + OAuth
    
    AG->>U: 问题2: 需要什么权限模型?
    U->>CLI: RBAC
    
    AG->>U: 问题3: 需要什么用户属性?
    U->>CLI: 基本 + 扩展
    
    AG->>CLI: 生成调研报告
    CLI->>U: 展示方案建议

7.12 research 命令

领域调研，收集背景知识。

命令签名

openmatrix research <topic> [options]

输出

# Research Report: OAuth 2.0 Implementation

## Overview
OAuth 2.0 is an authorization framework...

## Approaches
### Approach 1: Authorization Code Flow
- **Description**: Standard web app flow
- **Pros**: Secure, well-supported
- **Cons**: Requires backend

### Approach 2: Implicit Flow
- **Description**: Pure frontend flow
- **Pros**: No backend needed
- **Cons**: Less secure

## Recommended Libraries
1. **passport-oauth2** - Node.js OAuth middleware
2. **node-oauth2-server** - Complete OAuth server

## Implementation Guide
...

## Resources
- OAuth 2.0 Spec: https://oauth.net/2/
- Passport.js: http://www.passportjs.org/

7.13 check 命令

项目改进检测和建议。

命令签名

openmatrix check [options]

检查项目

输出示例

OpenMatrix Check Report
─────────────────────────────

Code Quality:
  ✓ Test coverage: 85%
  ✓ No lint errors
  
Security:
  ⚠ 2 moderate vulnerabilities in dependencies
  ✗ Found .env file with secrets
  
Configuration:
  ✓ tsconfig.json valid
  ⚠ package.json missing description
  
Documentation:
  ✓ README.md exists
  ✗ API documentation missing
  
Dependencies:
  ⚠ 5 outdated packages
  ✓ No redundant dependencies

Recommendations:
1. Run npm audit fix to resolve vulnerabilities
2. Remove secrets from .env, use .env.example
3. Add API documentation (TypeDoc suggested)
4. Update outdated packages

7.14 install-skills 命令

安装 Skills 到 Claude Code。

命令签名

openmatrix install-skills [options]

选项

安装流程

// scripts/install-skills.js

async function installSkills() {
  const sourceDir = './skills';
  const targetDir = process.env.CLAUDE_COMMANDS_DIR 
    || path.join(os.homedir(), '.claude', 'commands', 'om');
  
  // 确保目标目录存在
  if (!fs.existsSync(targetDir)) {
    fs.mkdirSync(targetDir, { recursive: true });
  }
  
  // 复制所有 Skill 文件
  const skills = fs.readdirSync(sourceDir);
  
  for (const skill of skills) {
    const sourcePath = path.join(sourceDir, skill);
    const targetPath = path.join(targetDir, skill);
    
    if (fs.existsSync(targetPath) && !options.force) {
      console.log(`Skipping ${skill} (already exists)`);
      continue;
    }
    
    fs.copyFileSync(sourcePath, targetPath);
    console.log(`Installed: ${skill}`);
  }
  
  console.log(`\nSkills installed to: ${targetDir}`);
  console.log('Use with: /om:<skill-name>');
}

下一章将详细讲解 Skills 技能系统。

第八章：Skills 技能系统

Skills 是 OpenMatrix 与 Claude Code 的集成接口，提供声明式的任务执行入口。

8.1 Skills 架构总览

Skills 定位

graph TD
    subgraph "Claude Code 环境"
        CC[Claude Code CLI]
        SK[Skills 目录<br/>~/.claude/commands/om/]
    end

    subgraph "OpenMatrix 核心"
        OM[OpenMatrix Package]
        CLI[CLI Commands]
        OR[Orchestrator]
    end

    CC --> |"/om:start"| SK
    SK --> |"调用"| CLI
    CLI --> OR

Skills vs CLI 对比

Skills 工作原理

sequenceDiagram
    participant U as 用户
    participant CC as Claude Code
    participant SK as Skill 文件
    participant OM as OpenMatrix CLI
    participant AT as Agent Tool
    participant AG as Agent

    U->>CC: /om:start
    CC->>SK: 加载 start.md
    SK->>SK: 解析 frontmatter
    SK->>OM: openmatrix start --json
    OM->>SK: SubagentTask[]
    
    loop 每个 SubagentTask
        SK->>AT: invoke Agent tool
        AT->>AG: 执行 Agent
        AG->>AT: AgentResult
        AT->>SK: 返回结果
        SK->>OM: openmatrix complete
    end
    
    SK->>CC: 生成报告
    CC->>U: 展示结果

8.2 Skill 文件结构详解

文件格式

Skill 文件使用 Markdown 格式，包含 YAML frontmatter：

---
name: start
description: Interactive task start with quality/mode selection
version: 1.0.0
author: OpenMatrix Team
aliases: [begin, init]
---

# /om:start

Start a new OpenMatrix execution cycle.

## Usage

```bash
/om:start [options]
```

## Implementation

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

Frontmatter 字段详解

Skill 目录结构

~/.claude/commands/om/
├── om.md              # 默认入口
├── start.md           # 启动任务
├── auto.md            # 自动执行
├── status.md          # 查看状态
├── approve.md         # 处理审批
├── meeting.md         # 处理阻塞
├── resume.md          # 恢复执行
├── retry.md           # 重试失败
├── report.md          # 生成报告
├── brainstorm.md      # 头脑风暴
├── research.md        # 领域调研
└── check.md           # 项目检测

8.3 Prompt 设计模式

Prompt 模板结构

OpenMatrix 的 Agent Prompt 遵循统一模板：

# Task: {{task.title}}
# Phase: {{phase}}

## Task Description
{{task.description}}

## Context from Previous Agents
{{accumulatedContext}}

## Your Goal
{{phaseSpecificGoal}}

## Requirements
{{requirements}}

## Output Format
{{outputFormat}}

## Important
{{criticalNotes}}

各阶段 Prompt 设计

TDD 阶段 Prompt

# Task: {{task.title}}
# Phase: TDD (Test-Driven Development)

## Task Description
{{task.description}}

## Context from Previous Agents
{{accumulatedContext}}

## Your Goal: RED Phase
Write comprehensive tests that **MUST FAIL** currently.

The tests should:
1. Define the expected behavior clearly
2. Cover normal cases, edge cases, and error scenarios
3. Be well-structured and readable
4. Use the project's test framework

## Test Framework
{{detectTestFramework()}}

## Requirements
- Test files should be in appropriate test directory
- Test names should clearly describe what is being tested
- Each test should be independent
- Use descriptive assertions

## Output Format
After creating tests, report:
1. Files created
2. Test cases written (with descriptions)
3. Current test execution status (should be failing)

## Important
Tests MUST be failing (RED phase). If tests pass, the tests 
are not properly testing new functionality. This is critical 
for TDD methodology.

### TDD Cycle
RED (write failing tests) → GREEN (make tests pass) → REFACTOR

You are in the RED phase. Tests should fail.

Develop 阶段 Prompt

# Task: {{task.title}}
# Phase: Develop (Implementation)

## Task Description
{{task.description}}

## Context from Previous Agents
{{accumulatedContext}}

## Existing Tests (from TDD phase)
Read the test files and understand what needs to be implemented.

Test files:
{{testFiles}}

## Your Goal: GREEN Phase
Implement functionality that passes **ALL** tests written in TDD phase.

## Implementation Guidelines
1. Read and understand each test case
2. Implement the required functionality
3. Follow project coding conventions:
   {{projectConventions}}
4. Keep code clean and maintainable
5. Handle edge cases and errors as tests specify

## Requirements
- All tests must pass after implementation
- Code should be well-structured
- No unnecessary complexity
- Add necessary comments for complex logic

## Output Format
Report:
1. Files created/modified
2. Key implementation decisions
3. Test execution results (must be GREEN)
4. Suggestions for verify/accept phases

## Important
Tests MUST pass (GREEN phase). If tests fail, continue implementation.
Do not modify tests to make them pass - fix the implementation.

### Definition of Done
- All tests passing
- No TypeScript errors
- Code follows conventions
- Complex logic documented

Verify 阶段 Prompt

# Task: {{task.title}}
# Phase: Verify (Quality Gates)

## Quality Configuration
- Level: {{qualityLevel}}
- TDD: {{config.tdd}}
- Min Coverage: {{config.minCoverage}}%
- Strict Lint: {{config.strictLint}}
- Security Scan: {{config.securityScan}}
- E2E Tests: {{config.e2eTests}}

## Your Task: Run Quality Gates

Execute the following checks in order:

### 1. Build Check
```bash
npm run build
```
Must complete without errors.

### 2. Test Run
```bash
npm test
```
All tests must pass.

### 3. Coverage Check
Run coverage and verify minimum threshold.
- Required: {{config.minCoverage}}% coverage
- Report: Line, function, and branch coverage

### 4. Lint Check
```bash
npm run lint
```
{{config.strictLint ? 'No warnings or errors allowed' : 'No errors allowed'}}

### 5. Security Scan
{{config.securityScan ? `
```bash
npm audit
```
No high/critical vulnerabilities allowed.
` : 'Skipped'}}

### 6. E2E Tests
{{config.e2eTests ? `
```bash
npm run e2e
```
` : 'Skipped'}}

### 7. Acceptance Criteria
Verify task-specific acceptance criteria from description.

## Output Format
Return a JSON report for each gate:
```json
{
  "build": { "status": "pass/fail", "details": "..." },
  "test": { "status": "pass/fail", "passed": N, "failed": M },
  "coverage": { "status": "pass/fail", "percentage": X },
  "lint": { "status": "pass/fail", "errors": N, "warnings": M },
  "security": { "status": "pass/fail", "vulnerabilities": [...] },
  "e2e": { "status": "pass/fail/skipped" },
  "acceptance": { "status": "pass/fail", "criteria": [...] }
}
```

## Important
Run ALL gates. Report failures honestly. Do not skip gates.
If a gate fails, include detailed failure information.

Accept 阶段 Prompt

# Task: {{task.title}}
# Phase: Accept (Final Review)

## Changed Files
{{changedFiles}}

## Verify Phase Report
{{verifyReport}}

## Your Task: Final Review

Review the implementation for:

### 1. Code Quality (score 1-10)
- Structure: Is the code well-organized?
- Naming: Are names clear and consistent?
- Complexity: Is complexity appropriate?
- Duplication: Is there unnecessary duplication?

### 2. Best Practices (score 1-10)
- Patterns: Are appropriate patterns used?
- Conventions: Does code follow project conventions?
- Error Handling: Are errors handled properly?
- Testing: Is testing adequate?

### 3. Security (score 1-10)
- Input Validation: Is input validated?
- Authentication: Is auth handled properly?
- Authorization: Are permissions checked?
- Data Protection: Is sensitive data protected?

### 4. Documentation (score 1-10)
- Comments: Are complex parts commented?
- Types: Are types well-defined?
- README: Is README updated if needed?

## Output Format
```json
{
  "codeQuality": { 
    "score": 1-10,
    "issues": [...],
    "suggestions": [...]
  },
  "bestPractices": { "score": 1-10, "issues": [...] },
  "security": { "score": 1-10, "issues": [...] },
  "documentation": { "score": 1-10, "issues": [...] },
  "overallScore": 1-10,
  "approved": true/false,
  "blockers": [...],
  "recommendations": [...]
}
```

## Decision Criteria
- Score >= 7: Approve
- Score 5-6: Conditional approve with improvements
- Score < 5: Reject, require changes

## Important
Be thorough but practical. Focus on significant issues, not minor nitpicks.
Approve if code is good enough for production, suggest improvements separately.

Prompt 变量系统

interface PromptVariables {
  // 任务信息
  task: {
    id: string;
    title: string;
    description: string;
    estimatedComplexity: string;
  };

  // 阶段信息
  phase: 'tdd' | 'develop' | 'verify' | 'accept';

  // 累积上下文
  accumulatedContext: string;

  // 项目上下文
  projectContext: {
    techStack: string[];
    testFramework: string;
    lintTool: string;
    conventions: string;
  };

  // 配置
  config: QualityConfig;

  // 条件渲染
  conditions: {
    isStrict: boolean;
    hasE2E: boolean;
    needsSecurityScan: boolean;
  };
}

8.4 核心 Skills 详解

/om 默认入口

自动路由到合适的命令：

---
name: om
description: OpenMatrix default entry - auto-routes to appropriate command
aliases: [openmatrix, matrix]
---

# /om

OpenMatrix 的智能入口，根据输入自动选择命令。

## 自动路由规则

| 输入模式 | 路由目标 | 示例 |
|----------|----------|------|
| `implement...`, `add...`, `build...` | `/om:start` | `/om implement user auth` |
| `fix...`, `repair...` | `/om:start` | `/om fix login bug` |
| `optimize...`, `improve...` | `/om:start` | `/om improve performance` |
| `status`, `progress` | `/om:status` | `/om status` |
| 空输入 | 显示帮助 | `/om` |

## 实现

```bash
# 分析输入
input="{{user_input}}"

if [[ "$input" =~ ^(implement|add|build|create|fix|optimize|improve) ]]; then
    # 提取任务描述
    task="${input#* }"
    openmatrix start --instruction "$task"
elif [[ "$input" =~ ^(status|progress) ]]; then
    openmatrix status
else
    openmatrix --help
fi
```

/om:start 启动任务

完整的交互式启动流程：

flowchart TD
    A[/om:start] --> B[检查现有状态]
    B --> C{有未完成状态?}
    
    C --> |"是"| D[选择: 恢复/新建]
    C --> |"否"| E[开始配置]
    
    D --> |"恢复"| F[调用 /om:resume]
    D --> |"新建"| E
    
    E --> G[选择质量等级]
    G --> H[选择执行模式]
    H --> I[选择 E2E 测试]
    I --> J[输入任务指令]
    
    J --> K[AI 分析规划]
    K --> L[生成任务列表]
    L --> M[展示计划]
    
    M --> N{确认计划?}
    N --> |"是"| O[开始执行]
    N --> |"修改"| P[调整计划]
    N --> |"取消"| Q[退出]
    
    O --> R[返回 SubagentTask]
    R --> S[调用 Agent Tool]

/om:auto 自动执行

---
name: auto
description: Fully automatic execution without approvals or pauses
---

# /om:auto

完全自动执行，适用于 CI/CD 环境。

## 特点

1. **自动批准所有审批**
2. **阻塞创建 Meeting 后继续**
3. **无用户交互**
4. **生成完整报告**

## 执行流程

```mermaid
graph TD
    A[开始] --> B[任务规划]
    B --> C[调度执行]
    
    C --> D{执行结果}
    
    D --> |"成功"| E[下一个任务]
    D --> |"阻塞"| F[创建 Meeting]
    D --> |"失败"| G[加入重试队列]
    
    F --> E
    G --> H{重试次数}
    H --> |"< max"| E
    H --> |">= max"| I[标记失败]
    
    E --> J{还有任务?}
    J --> |"是"| C
    J --> |"否"| K[生成报告]
```

## 实现

```bash
openmatrix auto \
    --quality "${QUALITY:-balanced}" \
    --bypass-approvals \
    --json > execution.json

# 解析结果
status=$(jq -r '.status' execution.json)

if [ "$status" = "completed" ]; then
    echo "✓ Execution completed successfully"
    exit 0
else
    echo "✗ Execution failed or blocked"
    jq '.meetings' execution.json
    exit 1
fi
```

## CI/CD 集成示例

```yaml
# GitHub Actions
- name: Run OpenMatrix
  run: |
    npm install -g openmatrix
    openmatrix auto --quality strict --bypass-approvals
    
- name: Upload Report
  if: always()
  uses: actions/upload-artifact@v3
  with:
    name: openmatrix-report
    path: .openmatrix/report.md
```

/om:meeting 处理阻塞

---
name: meeting
description: Handle blocked tasks (Meetings) with information/decisions
---

# /om:meeting

处理阻塞任务的 Meeting。

## Meeting 类型与处理

| 类型 | 触发条件 | 处理方式 | 示例 |
|------|----------|----------|------|
| information | 缺少必要信息 | 用户提供信息 | API 端点地址 |
| decision | 多种可行方案 | 用户选择方案 | 认证方式选择 |
| approval | 需要用户确认 | 用户批准/拒绝 | 数据库迁移确认 |
| dependency | 外部依赖问题 | 用户解决依赖 | 第三方服务配置 |

## 交互式处理

```
Meeting: MEETING-001
Type: decision
Task: TASK-003 - Implement Authentication

Description:
需要选择认证方式，请从以下选项中选择：

Options:
1. JWT (推荐) - 无状态，适合微服务
2. Session - 有状态，适合传统应用
3. OAuth - 第三方认证集成

Your choice [1-3]: _
```

## 实现

```bash
# 获取 Meeting 列表
meetings=$(openmatrix meeting --json)

# 逐个处理
for meeting in $(echo "$meetings" | jq -c '.[]'); do
    id=$(echo "$meeting" | jq -r '.id')
    type=$(echo "$meeting" | jq -r '.type')
    
    echo "Processing Meeting: $id"
    
    case $type in
        information)
            # 收集信息
            read -p "Enter required info: " info
            openmatrix meeting $id --answer "{\"info\": \"$info\"}"
            ;;
        decision)
            # 选择方案
            echo "$meeting" | jq -r '.options[]'
            read -p "Select option: " choice
            openmatrix meeting $id --answer "{\"choice\": $choice}"
            ;;
        approval)
            # 审批确认
            read -p "Approve? (y/n): " confirm
            openmatrix meeting $id --$([ "$confirm" = "y" ] && echo "resolve" || echo "skip")
            ;;
    esac
done
```

8.5 Skills 与 Agent Tool 集成

Agent Tool 调用模式

// Skill 中调用 Agent Tool 的模式

async function executeSubagentTasks(tasks: SubagentTask[]) {
    for (const task of tasks) {
        // 1. 准备 Agent Tool 配置
        const agentConfig = {
            subagent_type: task.subagent_type,
            description: task.description,
            prompt: task.prompt,
            isolation: task.isolation,
            timeout: task.timeout
        };

        // 2. 调用 Agent Tool
        const result = await invokeAgentTool(agentConfig);

        // 3. 处理结果
        if (result.status === 'success') {
            // 调用 complete 保存状态
            await exec(`openmatrix complete ${task.taskId} --success --summary "${result.summary}"`);
        } else if (result.status === 'blocked') {
            // 创建 Meeting
            await exec(`openmatrix complete ${task.taskId} --blocked`);
        } else {
            // 标记失败
            await exec(`openmatrix complete ${task.taskId} --failed --error "${result.error}"`);
        }

        // 4. 检查是否继续
        const status = await getStatus();
        if (status.currentTask) {
            // 继续下一个任务
            continue;
        }
    }
}

状态同步机制

sequenceDiagram
    participant SK as Skill
    participant CLI as OpenMatrix CLI
    participant DISK as 磁盘状态
    participant AT as Agent Tool

    SK->>CLI: step --json
    CLI->>DISK: 读取 state.json
    DISK->>CLI: 返回状态
    CLI->>SK: SubagentTask

    Note over SK,AT: Context 可能被压缩

    SK->>AT: invoke Agent tool
    AT->>AT: 执行 Agent
    AT->>SK: AgentResult

    SK->>CLI: complete --success
    CLI->>DISK: 写入结果
    CLI->>DISK: 更新 state.json
    CLI->>SK: 确认

    SK->>CLI: step --json
    Note over SK,DISK: 状态从磁盘恢复

8.6 自定义 Skill 开发

Skill 模板

---
name: {{skill-name}}
description: {{one-line description}}
version: 1.0.0
---

# /om:{{skill-name}}

{{detailed description}}

## Usage

\`\`\`bash
/om:{{skill-name}} [options]
\`\`\`

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--option1` | string | - | Option description |

## Examples

\`\`\`bash
# Example 1: Basic usage
/om:{{skill-name}}

# Example 2: With options
/om:{{skill-name}} --option1 value
\`\`\`

## Flow

\`\`\`mermaid
graph TD
    A[/om:{{skill-name}}] --> B[Step 1]
    B --> C[Step 2]
    C --> D[Complete]
\`\`\`

## Implementation

\`\`\`bash
# 1. 调用 OpenMatrix CLI
openmatrix {{cli-command}} --options

# 2. 处理结果
status=$?
if [ $status -eq 0 ]; then
    echo "✓ Success"
else
    echo "✗ Failed"
fi
\`\`\`

## Error Handling

\`\`\`bash
# 错误处理示例
if ! openmatrix {{cli-command}}; then
    echo "Command failed, checking state..."
    openmatrix status --detailed
fi
\`\`\`

## See Also

- /om:start
- /om:status

开发最佳实践

1. 清晰的描述 - frontmatter 中准确描述功能
2. 完整的使用示例 - 包含多种使用场景
3. 流程图 - 用 Mermaid 展示执行流程
4. 错误处理 - 处理可能的异常情况
5. 与 CLI 集成 - 调用 OpenMatrix CLI 命令

8.7 Skills 安装与管理

安装命令

# 安装 Skills
openmatrix install-skills

# 强制覆盖安装
openmatrix install-skills --force

# 指定安装目录
openmatrix install-skills --target /custom/path

# 验证安装
ls ~/.claude/commands/om/

更新 Skills

# 更新 OpenMatrix 包
npm update -g openmatrix

# 重新安装 Skills
openmatrix install-skills --force

自定义 Skills 安装

# 复制自定义 Skill
cp my-custom-skill.md ~/.claude/commands/om/

# 验证
/om:my-custom-skill --help

下一章将详细讲解 质量保障体系。

第九章：质量保障体系

OpenMatrix 的质量保障体系通过七个质量门禁确保代码质量，是可信交付的核心保障。

9.1 质量门禁总览

七个质量门禁

graph TD
    A[代码提交] --> B1[Build 检查]
    B1 --> B2[Test 运行]
    B2 --> B3[Coverage 检查]
    B3 --> B4[Lint 检查]
    B4 --> B5[Security 扫描]
    B5 --> B6[E2E 测试]
    B6 --> B7[Acceptance 标准]

    B7 --> C{全部通过?}
    C --> |"是"| D[进入 Accept 阶段]
    C --> |"否"| E[返回失败报告]

门禁与质量等级

质量评分公式

OpenMatrix 使用加权评分模型计算综合质量得分：

$$Q_{total}=\sum _{i=1}^7{w}_i\cdot s_i$$

其中：

• $w_i$ 为第 $i$ 个门禁的权重
• $s_i$ 为第 $i$ 个门禁的得分（0-100）

权重配置：

得分阈值：

• $Q_{total}\ge 80$：通过
• $60\le Q_{total}<80$：警告（可接受）
• $Q_{total}<60$：失败

9.2 Build 检查

目的

确保代码可以成功编译/构建。

执行命令

npm run build

检查内容

实际输出案例

成功输出：

✓ Build Check Passed
─────────────────────────────
Compiler: TypeScript 5.3.3
Duration: 12.5s
Output: dist/
  ├── index.js        (45.2 KB)
  ├── index.d.ts      (12.8 KB)
  └── utils/
      └── helpers.js  (8.3 KB)

Files compiled: 23
Warnings: 0
Errors: 0

失败输出：

✗ Build Check Failed
─────────────────────────────
Errors: 2

[1] src/models/user.ts:42:10
    TS2339: Property 'validate' does not exist on type 'User'.

[2] src/api/auth.ts:15:5
    TS2307: Cannot find module '../config' or its corresponding declarations.

Duration: 2.3s
Files with errors: 2

Fix suggestions:
1. Add 'validate' method to User class
2. Check import path: '../config' → './config'

调优建议

1. 增量编译：使用 tsc --incremental 加速
2. 并行编译：配置 typescript 的 maxNodeModuleJsDepth
3. 缓存利用：启用 tsconfig.json 中的 composite: true

{
  "compilerOptions": {
    "incremental": true,
    "composite": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

9.3 Test 运行

目的

确保所有测试通过。

执行命令

npm test

支持的测试框架

实际输出案例

成功输出：

✓ Test Check Passed
─────────────────────────────
Framework: Vitest 1.6.0
Duration: 3.5s

 Test Files  12 passed (12)
      Tests  156 passed (156)
   Start at  14:32:15
   Duration  3.52s (transform 0.8s, setup 0.3s, collect 0.5s, tests 1.9s)

Coverage:
  Statements:  85.2%
  Branches:    78.6%
  Functions:   90.1%
  Lines:       84.8%

失败输出：

✗ Test Check Failed
─────────────────────────────
Framework: Vitest 1.6.0
Duration: 5.2s

 Test Files  10 passed, 2 failed (12)
      Tests  145 passed, 11 failed (156)

Failed Tests:

[1] tests/auth.test.ts:45 - "should validate JWT token"
    AssertionError: expected false to be true
    at tests/auth.test.ts:48:12

[2] tests/user.test.ts:102 - "should hash password"
    Error: Cannot read property 'hash' of undefined
    at src/utils/crypto.ts:15:8

Failures Summary:
  - Auth: 3 failures
  - User: 8 failures

Rerun with: npm test -- --reporter=verbose

调优建议

1. 并行执行：配置测试框架并行运行
2. 测试隔离：确保测试之间无状态依赖
3. 快照更新：定期更新快照避免假失败

// vitest.config.ts
export default defineConfig({
  test: {
    pool: 'threads',
    poolOptions: {
      threads: {
        singleThread: false,
        minThreads: 2,
        maxThreads: 4
      }
    }
  }
});

9.4 Coverage 检查

目的

确保代码覆盖率达到阈值。

执行命令

npm test -- --coverage

覆盖率类型详解

实际输出案例

成功输出：

✓ Coverage Check Passed
─────────────────────────────
Threshold: 80%

Coverage Report:
┌─────────────────┬────────┬────────┬────────┬────────┐
│ File            │ Lines  │ Branch │ Func   │ Stmt   │
├─────────────────┼────────┼────────┼────────┼────────┤
│ src/index.ts    │ 95.2%  │ 88.0%  │ 100%   │ 95.0%  │
│ src/models/     │ 88.5%  │ 75.0%  │ 90.0%  │ 87.2%  │
│ src/api/        │ 82.1%  │ 70.5%  │ 85.0%  │ 81.8%  │
│ src/utils/      │ 91.3%  │ 82.0%  │ 95.0%  │ 90.5%  │
├─────────────────┼────────┼────────┼────────┼────────┤
│ TOTAL           │ 85.2%  │ 78.6%  │ 90.1%  │ 84.8%  │
└─────────────────┴────────┴────────┴────────┴────────┘

Uncovered Lines:
  - src/api/auth.ts: 45-52 (error handling)
  - src/models/user.ts: 120-125 (edge case)

失败输出：

✗ Coverage Check Failed
─────────────────────────────
Threshold: 80%
Actual: 72.5%
Gap: 7.5%

Uncovered Areas:

High Priority (0% coverage):
  - src/api/websocket.ts: Entire file
  - src/utils/logger.ts: 15-45

Medium Priority (<50% coverage):
  - src/models/config.ts: 45-80
  - src/api/upload.ts: 30-60

Improvement Suggestions:
1. Add tests for websocket.ts (estimated +5%)
2. Add tests for logger.ts error paths (estimated +2%)
3. Add integration tests for config.ts (estimated +1.5%)

调优建议

1. 排除配置：排除不需要覆盖的文件

{
  "coverage": {
    "exclude": [
      "**/*.d.ts",
      "**/dist/**",
      "**/node_modules/**",
      "**/*.config.ts",
      "**/*.test.ts"
    ]
  }
}

2. 增量覆盖：只检查变更文件的覆盖率

3. 覆盖率报告：生成 HTML 报告便于分析

npm test -- --coverage --reporter=html

9.5 Lint 检查

目的

确保代码符合规范。

执行命令

npm run lint

支持的 Lint 工具

Strict vs Standard 配置

// Strict 配置示例
module.exports = {
  rules: {
    'no-unused-vars': 'error',
    'no-console': 'error',
    '@typescript-eslint/explicit-function-return-type': 'error',
    'complexity': ['error', 10]
  }
};

// Standard 配置示例
module.exports = {
  rules: {
    'no-unused-vars': 'warn',
    'no-console': 'off',
    '@typescript-eslint/explicit-function-return-type': 'off',
    'complexity': 'off'
  }
};

实际输出案例

成功输出：

✓ Lint Check Passed
─────────────────────────────
Linter: ESLint 8.57.0
Config: .eslintrc.strict.js
Duration: 2.1s

Files checked: 45
Errors: 0
Warnings: 3

Warnings (low priority):
  - src/utils/helpers.ts:25 - Consider adding JSDoc
  - src/api/routes.ts:120 - Function complexity 8/10
  - src/models/user.ts:80 - Missing return type annotation

失败输出：

✗ Lint Check Failed
─────────────────────────────
Linter: ESLint 8.57.0
Duration: 1.8s

Files checked: 45
Errors: 5
Warnings: 12

Errors:

[1] src/api/auth.ts:45:10
    no-unused-vars: 'temp' is defined but never used
    Fix: Remove unused variable or prefix with underscore

[2] src/models/user.ts:80:5
    @typescript-eslint/explicit-function-return-type: Missing return type
    Fix: Add ': User | null' return type annotation

[3] src/utils/helpers.ts:120:1
    complexity: Function has complexity of 15 (max: 10)
    Fix: Break down into smaller functions

[4] src/api/routes.ts:200:1
    no-console: Unexpected console statement
    Fix: Use logger instead

[5] src/config/index.ts:15:1
    no-process-env: Do not use process.env directly
    Fix: Use config.get('VAR_NAME')

Auto-fix available for 3 errors. Run: npm run lint -- --fix

调优建议

1. 自动修复：配置 pre-commit hook 自动修复

{
  "lint-staged": {
    "*.ts": ["eslint --fix", "prettier --write"]
  }
}

2. 增量检查：只检查变更文件

3. 性能优化：启用缓存

module.exports = {
  cache: true,
  cacheLocation: '.eslintcache'
};

9.6 Security 扫描

目的

检查依赖中的安全漏洞。

执行命令

npm audit

漏洞级别与处理

实际输出案例

成功输出：

✓ Security Check Passed
─────────────────────────────
Scanner: npm audit
Duration: 1.2s

Dependencies: 245 direct, 1,234 transitive
Vulnerabilities found: 0

Known advisories checked: 2,456

失败输出：

✗ Security Check Failed
─────────────────────────────
Scanner: npm audit
Duration: 1.5s

Vulnerabilities Summary:
┌───────────┬───────────┬───────────┬───────────┐
│ Critical  │ High      │ Moderate  │ Low       │
├───────────┼───────────┼───────────┼───────────┤
│    1      │    2      │    5      │    8      │
└───────────┴───────────┴───────────┴───────────┘

Critical Vulnerabilities:

[1] lodash < 4.17.21
    CVE-2021-23337: Prototype Pollution
    CVSS: 9.8 (Critical)
    Package: lodash@4.17.15
    Fixed in: lodash@4.17.21
    Path: app > express > lodash
    Fix: npm install lodash@latest

High Vulnerabilities:

[1] axios < 0.21.2
    CVE-2021-3749: SSRF
    CVSS: 7.5 (High)
    Package: axios@0.21.1
    Fixed in: axios@0.21.2
    Fix: npm install axios@latest

Fix Commands:
  npm audit fix              # Auto-fix safe updates
  npm audit fix --force      # Include breaking changes

调优建议

1. 审计配置：配置忽略已知且可接受的漏洞

{
  "audit": {
    "ignore": [
      {
        "id": "CVE-XXXX-XXXX",
        "reason": "Not used in production",
        "until": "2024-12-31"
      }
    ]
  }
}

2. 定期扫描：配置 CI 每日安全扫描

3. 依赖锁定：使用 lockfile 固定版本

9.7 E2E 测试

目的

进行端到端集成测试。

执行命令

npm run e2e

支持的 E2E 工具

实际输出案例

成功输出：

✓ E2E Check Passed
─────────────────────────────
Runner: Playwright 1.42.0
Browsers: chromium, firefox, webkit
Duration: 45.2s

Test Suites: 5
Tests: 32 passed, 32 total

Results by Browser:
┌─────────────┬────────┬────────┬────────┐
│ Browser     │ Passed │ Failed │ Time   │
├─────────────┼────────┼────────┼────────┤
│ chromium    │ 32     │ 0      │ 12.5s  │
│ firefox     │ 32     │ 0      │ 15.3s  │
│ webkit      │ 32     │ 0      │ 17.4s  │
└─────────────┴────────┴────────┴────────┘

Key Scenarios:
  ✓ User registration flow
  ✓ Login with OAuth
  ✓ Shopping cart operations
  ✓ Payment processing
  ✓ Order tracking

失败输出：

✗ E2E Check Failed
─────────────────────────────
Runner: Playwright 1.42.0
Duration: 52.1s

Test Suites: 5
Tests: 28 passed, 4 failed, 32 total

Failed Tests:

[1] tests/e2e/checkout.spec.ts:45
    "should complete payment"
    Browser: chromium
    Error: Timeout waiting for element '#payment-success'
    Screenshot: screenshots/checkout-fail-1.png

[2] tests/e2e/auth.spec.ts:120
    "should handle OAuth callback"
    Browser: firefox
    Error: Navigation to /callback timed out
    Screenshot: screenshots/auth-fail-1.png

Screenshots saved to: test-results/screenshots/
Trace viewer: npx playwright show-trace trace.zip

调优建议

1. 并行执行：配置多 Worker 并行

// playwright.config.ts
export default defineConfig({
  workers: process.env.CI ? 4 : 2,
  fullyParallel: true
});

2. 重试策略：配置失败重试

export default defineConfig({
  retries: process.env.CI ? 2 : 0
});

3. 选择性执行：只运行相关测试

npm run e2e -- --grep "checkout"

9.8 Acceptance 标准

目的

验证任务特定的接受标准。

标准定义与验证

interface AcceptanceCriteria {
  items: AcceptanceItem[];
  custom?: CustomCriterion[];
}

interface AcceptanceItem {
  id: string;
  description: string;
  type: 'functional' | 'performance' | 'security' | 'ux';
  verification: VerificationMethod;
}

实际输出案例

成功输出：

✓ Acceptance Criteria Met
─────────────────────────────
Task: TASK-001 - User Authentication

Criteria:
  ✓ AC-001: User can register with email
  ✓ AC-002: Password must be at least 8 characters
  ✓ AC-003: Login returns JWT token
  ✓ AC-004: Token expires after 7 days
  ✓ AC-005: Logout invalidates token

Performance Criteria:
  ✓ P-001: Login response < 200ms (actual: 145ms)
  ✓ P-002: Registration < 500ms (actual: 320ms)

Security Criteria:
  ✓ S-001: Password hashed with bcrypt
  ✓ S-002: No sensitive data in logs
  ✓ S-003: Rate limiting enabled

UX Criteria:
  ✓ U-001: Clear error messages
  ✓ U-002: Password strength indicator

All 12 criteria verified ✓

失败输出：

✗ Acceptance Criteria Not Met
─────────────────────────────
Task: TASK-001 - User Authentication

Passed: 9/12

Failed Criteria:

[AC-003] Login returns JWT token
  Expected: JWT with 7 day expiry
  Actual: JWT with 1 day expiry
  Impact: High - affects user experience

[P-001] Login response < 200ms
  Expected: < 200ms
  Actual: 450ms
  Impact: Medium - performance issue

[S-002] No sensitive data in logs
  Issue: Password visible in debug logs
  Location: src/api/auth.ts:45
  Impact: Critical - security vulnerability

Remediation Required:
1. Update JWT expiry to 7 days
2. Optimize login query (add index)
3. Remove password from debug logs

9.9 AI Review

目的

使用 AI 进行代码质量审查。

审查维度与评分

$$R_{total}=\frac{R_{quality}+R_{practices}+R_{security}+R_{docs}}{4}$$

评分标准详解

实际输出案例

成功输出：

✓ AI Review Passed
─────────────────────────────
Model: Claude 3.5 Sonnet
Duration: 5.2s

Review Scores:
┌─────────────────┬───────┬───────────────────────────┐
│ Dimension       │ Score │ Notes                     │
├─────────────────┼───────┼───────────────────────────┤
│ Code Quality    │ 9/10  │ Well-structured           │
│ Best Practices  │ 8/10  │ Minor improvements needed │
│ Security        │ 8/10  │ Good validation           │
│ Documentation   │ 7/10  │ Could add more JSDoc      │
├─────────────────┼───────┼───────────────────────────┤
│ OVERALL         │ 8/10  │ APPROVED                  │
└─────────────────┴───────┴───────────────────────────┘

Strengths:
  ✓ Clear separation of concerns
  ✓ Proper error handling
  ✓ Consistent naming conventions
  ✓ Good test coverage

Improvements:
  → Add JSDoc for public methods (3 locations)
  → Consider extracting validation logic to utils
  → Add more inline comments for complex logic

Recommendation: Approve with minor improvements

失败输出：

✗ AI Review Failed
─────────────────────────────
Model: Claude 3.5 Sonnet
Duration: 4.8s

Review Scores:
┌─────────────────┬───────┬───────────────────────────┐
│ Dimension       │ Score │ Issues                    │
├─────────────────┼───────┼───────────────────────────┤
│ Code Quality    │ 4/10  │ Complex, hard to read     │
│ Best Practices  │ 5/10  │ Violates SOLID            │
│ Security        │ 3/10  │ SQL injection risk        │
│ Documentation   │ 2/10  │ No comments               │
├─────────────────┼───────┼───────────────────────────┤
│ OVERALL         │ 3.5/10│ NOT APPROVED              │
└─────────────────┴───────┴───────────────────────────┘

Blockers:
  ⛔ SQL injection vulnerability at auth.ts:45
  ⛔ Hardcoded credentials in config.ts:12
  ⛔ Missing input validation at user.ts:80

Required Changes:
  1. Use parameterized queries for SQL
  2. Move credentials to environment variables
  3. Add input validation middleware

Recommendation: Do not merge until blockers resolved

调优建议

1. 自定义规则：配置项目特定的审查规则

2. 审查历史：跟踪审查结果趋势

3. 集成 PR：自动评论到 PR

9.10 质量报告整合

综合质量报告

interface QualityReport {
  build: BuildResult;
  test: TestResult;
  coverage: CoverageResult;
  lint: LintResult;
  security: SecurityResult;
  e2e: E2EResult;
  acceptance: AcceptanceResult;
  aiReview: AIReviewResult;

  overallStatus: 'pass' | 'fail';
  qualityScore: number;  // 0-100
  passedGates: string[];
  failedGates: string[];
  summary: string;
}

完整报告示例

╔══════════════════════════════════════════════════════════════╗
║              OpenMatrix Quality Report                       ║
║              Task: TASK-001 - User Authentication            ║
╠══════════════════════════════════════════════════════════════╣
║ Configuration                                                ║
║   Quality Level: strict                                      ║
║   Threshold: 80%                                             ║
╠══════════════════════════════════════════════════════════════╣
║ Gate Results                                                 ║
╠══════════════════════════════════════════════════════════════╣
║ ✓ Build      │ PASS  │ 12.5s  │ 0 errors, 0 warnings       ║
║ ✓ Test       │ PASS  │ 3.5s   │ 156 passed                  ║
║ ✓ Coverage   │ PASS  │ -      │ 85.2% (threshold: 80%)     ║
║ ✓ Lint       │ PASS  │ 2.1s   │ 0 errors, 3 warnings       ║
║ ✓ Security   │ PASS  │ 1.2s   │ 0 vulnerabilities          ║
║ ○ E2E        │ SKIP  │ -      │ Not configured             ║
║ ✓ Acceptance │ PASS  │ -      │ 12/12 criteria met         ║
║ ✓ AI Review  │ PASS  │ 5.2s   │ Score: 8/10                ║
╠══════════════════════════════════════════════════════════════╣
║ Summary                                                      ║
║   Overall Status: ✓ PASS                                     ║
║   Quality Score: 87/100                                      ║
║   Passed Gates: 7/7                                          ║
║   Duration: 24.5s                                            ║
╠══════════════════════════════════════════════════════════════╣
║ Recommendations                                              ║
║   → Add JSDoc for public methods                             ║
║   → Consider E2E tests for critical flows                    ║
║   → Monitor coverage trend                                   ║
╚══════════════════════════════════════════════════════════════╝

下一章将详细讲解 工作流程 的完整执行过程。

第十章：工作流程详解

本章详细介绍 OpenMatrix 的完整工作流程。

10.1 完整执行流程

graph TD
    A[用户指令] --> B[初始化]
    B --> C[任务规划]
    C --> D[调度执行]
    D --> E[质量验证]
    E --> F[最终审查]
    F --> G[完成交付]

10.2 端到端完整案例：用户认证系统

下面是一个从 /om:start 到最终报告的完整运行实录，展示 strict 模式下的全流程。

第 1 步：启动

$ /om:start

╔══════════════════════════════════════════════════════════════╗
║                    OpenMatrix v0.1.98                        ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  No existing state found. Starting fresh execution.          ║
║                                                              ║
║  Step 1/4: Select Quality Level                              ║
║                                                              ║
║  > strict    — Full TDD, >80% coverage, strict lint          ║
║    balanced  — No TDD, >60% coverage, standard lint          ║
║    fast      — No quality gates                              ║
║                                                              ║
║  Your choice: strict                                         ║
║                                                              ║
║  Step 2/4: Select Execution Mode                             ║
║                                                              ║
║  > semi-auto  — Confirm critical points                      ║
║    interactive — Confirm every step                           ║
║    full-auto  — No interruptions                             ║
║                                                              ║
║  Your choice: semi-auto                                      ║
║                                                              ║
║  Step 3/4: Enable E2E Tests?                                 ║
║  > No                                                        ║
║                                                              ║
║  Step 4/4: Enter Task Instruction                            ║
║                                                              ║
║  > 实现用户认证系统：                                          ║
║      1. 用户注册（邮箱 + 密码）                                 ║
║      2. 用户登录（JWT token，7天有效期）                        ║
║      3. 密码使用 bcrypt 加密                                   ║
║      4. 登录 API 响应时间 < 200ms                              ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

第 2 步：AI 分析与任务规划

╔══════════════════════════════════════════════════════════════╗
║                  Task Planning                               ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  Analyzing project context...                                ║
║    - Framework: Express.js + TypeScript                      ║
║    - Test: Vitest                                            ║
║    - Lint: ESLint                                            ║
║                                                              ║
║  Generated Task Plan:                                        ║
║                                                              ║
║  ┌──────────┬────────────────────────┬──────┬──────┬────┐   ║
║  │ ID       │ Title                  │ Pri  │ Deps │ Cx │   ║
║  ├──────────┼────────────────────────┼──────┼──────┼────┤   ║
║  │ TASK-001 │ Create User model      │  10  │  -   │ L  │   ║
║  │ TASK-002 │ Implement bcrypt util  │   9  │  -   │ L  │   ║
║  │ TASK-003 │ Implement auth API     │   8  │ 1,2  │ M  │   ║
║  │ TASK-004 │ Add input validation   │   6  │ 1    │ L  │   ║
║  │ TASK-005 │ Add auth middleware    │   7  │ 3    │ M  │   ║
║  └──────────┴────────────────────────┴──────┴──────┴────┘   ║
║                                                              ║
║  Pri = Priority (1-10)  Deps = Dependencies  Cx = Complexity║
║                                                              ║
║  Approve this plan? [Y/n] Y                                  ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

第 3 步：执行 TASK-001（TDD → Develop → Verify → Accept）

════════════════════════════════════════════════════════════════
TASK-001: Create User model              [priority: 10]
Phase: TDD (RED)                         [agent: tester]
════════════════════════════════════════════════════════════════

Running Tester Agent...

  Creating test file: tests/models/user.test.ts

  Test cases written:
    ✓ "should create user with valid email"
    ✓ "should reject invalid email"
    ✓ "should hash password on create"
    ✓ "should validate password length >= 8"
    ✓ "should not store plain text password"

  Running tests...

  Tests: 5 failed (RED) ✓
  Duration: 0.8s

  TDD Phase PASSED — Tests are failing as expected (RED)

──────────────────────────────────────────────────────────────
Phase: Develop (GREEN)                   [agent: coder]
──────────────────────────────────────────────────────────────

Running Coder Agent...

  Reading test files...
  Analyzing test requirements...
  Creating implementation: src/models/user.ts

  Files created:
    - src/models/user.ts (82 lines)

  Running tests...

  Tests: 5 passed (GREEN) ✓
  Duration: 1.2s

  Develop Phase PASSED — All tests passing (GREEN)

──────────────────────────────────────────────────────────────
Phase: Verify (Quality Gates)            [agent: executor]
──────────────────────────────────────────────────────────────

Running quality gates (strict mode)...

  [1/7] Build Check     ✓ PASS    (12.5s, 0 errors)
  [2/7] Test Run        ✓ PASS    (3.5s, 5/5 passed)
  [3/7] Coverage        ✓ PASS    (line: 92%, threshold: 80%)
  [4/7] Lint            ✓ PASS    (0 errors, 1 warning)
  [5/7] Security        ✓ PASS    (0 vulnerabilities)
  [6/7] E2E             ○ SKIP    (not configured)
  [7/7] Acceptance      ✓ PASS    (4/4 criteria met)

  Quality Score: 92/100

  Verify Phase PASSED — All quality gates passed

──────────────────────────────────────────────────────────────
Phase: Accept (AI Review)                [agent: reviewer]
──────────────────────────────────────────────────────────────

Running Reviewer Agent...

  Review Scores:
    Code Quality:   9/10  (well-structured model)
    Best Practices:  8/10  (proper encapsulation)
    Security:        8/10  (bcrypt hashing)
    Documentation:   7/10  (add JSDoc for public methods)

  Overall Score: 8.0/10 — APPROVED ✓

  Accept Phase PASSED

  Git commit:
    feat(TASK-001): Create User model with validation

    - Define IUser interface with email, password fields
    - Add bcrypt password hashing on create
    - Add email and password validation

    Impact scope: Models
    Files changed: src/models/user.ts, tests/models/user.test.ts

    Co-Authored-By: OpenMatrix https://github.com/bigfish1913/openmatrix

TASK-001 COMPLETED ✓
════════════════════════════════════════════════════════════════

第 4 步：执行 TASK-002（并行，无依赖）

════════════════════════════════════════════════════════════════
TASK-002: Implement bcrypt util          [priority: 9]
Phase: TDD → Develop → Verify → Accept
════════════════════════════════════════════════════════════════

  TDD:      3 tests written, 3 failing (RED) ✓
  Develop:  src/utils/crypto.ts created, 3 tests passing (GREEN) ✓
  Verify:   Build ✓, Test ✓, Coverage 95% ✓, Lint ✓, Security ✓
  Accept:   Score 8.5/10 — APPROVED ✓

  Git commit: feat(TASK-002): Add bcrypt password utility

TASK-002 COMPLETED ✓
════════════════════════════════════════════════════════════════

第 5 步：执行 TASK-003（依赖 TASK-001 + TASK-002，遇到 Meeting）

════════════════════════════════════════════════════════════════
TASK-003: Implement auth API             [priority: 8]
════════════════════════════════════════════════════════════════

  TDD Phase...

  Running Tester Agent...

  Creating test file: tests/api/auth.test.ts

  ⚠ BLOCKED: Need to determine API structure

  Meeting MEETING-001 created:
  ┌──────────────────────────────────────────────────────────┐
  │ Type: decision                                           │
  │ Question: Which API structure to use?                    │
  │                                                          │
  │ Options:                                                 │
  │   1. RESTful (/api/auth/register, /api/auth/login)       │
  │   2. GraphQL (mutation { register }, mutation { login }) │
  │   3. tRPC (router procedure style)                       │
  │                                                          │
  │ Impact: Affects all API design decisions                 │
  └──────────────────────────────────────────────────────────┘

  TASK-003 status → waiting
  Continuing with other independent tasks...

════════════════════════════════════════════════════════════════

第 6 步：执行 TASK-004（独立任务，不依赖 TASK-003）

════════════════════════════════════════════════════════════════
TASK-004: Add input validation            [priority: 6]
════════════════════════════════════════════════════════════════

  TDD:      4 tests written (RED) ✓
  Develop:  src/utils/validators.ts created (GREEN) ✓
  Verify:   All gates passed ✓
  Accept:   Score 7.5/10 — APPROVED ✓

  Git commit: feat(TASK-004): Add input validation utilities

TASK-004 COMPLETED ✓
════════════════════════════════════════════════════════════════

All independent tasks completed. 1 meeting pending.

$ /om:meeting

Meeting MEETING-001: Which API structure to use?
Your choice [1-3]: 1

  Meeting resolved → TASK-003 status → scheduled

Resuming TASK-003 execution...

第 7 步：恢复 TASK-003 并完成

════════════════════════════════════════════════════════════════
TASK-003: Implement auth API             [priority: 8]
════════════════════════════════════════════════════════════════

  TDD:      8 tests written (RED) ✓
  Develop:  src/api/auth.ts, src/routes/auth.ts created ✓
  Verify:
    [1/7] Build     ✓ PASS    (15.2s)
    [2/7] Test      ✓ PASS    (5.1s, 8/8 passed)
    [3/7] Coverage  ✓ PASS    (line: 88%)
    [4/7] Lint      ✗ FAIL    (2 errors)

  Verify FAILED — Fixing lint errors...

  Auto-fix applied:
    - Removed unused variable 'temp' at auth.ts:45
    - Added return type annotation at auth.ts:80

  Re-running Verify...
    [4/7] Lint      ✓ PASS    (0 errors)

  [5/7] Security   ✓ PASS
  [7/7] Acceptance ✓ PASS    (4/4 criteria)
  Quality Score: 85/100

  Accept: Score 7.5/10 — APPROVED ✓

  Git commit: feat(TASK-003): Implement RESTful auth API

TASK-003 COMPLETED ✓
════════════════════════════════════════════════════════════════

第 8 步：执行 TASK-005（依赖 TASK-003）

════════════════════════════════════════════════════════════════
TASK-005: Add auth middleware             [priority: 7]
════════════════════════════════════════════════════════════════

  TDD:      5 tests written ✓
  Develop:  src/middleware/auth.ts created ✓
  Verify:   All gates passed, Coverage 91% ✓
  Accept:   Score 8.0/10 — APPROVED ✓

TASK-005 COMPLETED ✓
════════════════════════════════════════════════════════════════

最终报告

$ /om:report

╔══════════════════════════════════════════════════════════════╗
║             OpenMatrix Execution Report                      ║
║             Run ID: run-2024-04-06-001                       ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  Configuration                                               ║
║    Quality: strict    Mode: semi-auto                        ║
║    Started:  2024-04-06 14:32:15                             ║
║    Finished: 2024-04-06 16:45:22                             ║
║    Duration: 2h 13m 7s                                       ║
║                                                              ║
║  Task Statistics                                             ║
║  ┌──────────────────────────────────────┐                    ║
║  │ Total Tasks     5                    │                    ║
║  │ Completed       5 (100%)             │                    ║
║  │ Failed          0                    │                    ║
║  │ Blocked         1 (resolved)         │                    ║
║  └──────────────────────────────────────┘                    ║
║                                                              ║
║  Quality Metrics                                             ║
║  ┌──────────────────────────────────────┐                    ║
║  │ Avg Coverage    90.2%                │                    ║
║  │ Avg Review      7.9/10               │                    ║
║  │ Lint Errors     0 (2 auto-fixed)     │                    ║
║  │ Security        0 vulnerabilities    │                    ║
║  └──────────────────────────────────────┘                    ║
║                                                              ║
║  Task Timeline                                               ║
║  ┌──────────┬──────────────────────┬────────┬─────────┐      ║
║  │ Task     │ Title                │ Score  │ Time    │      ║
║  ├──────────┼──────────────────────┼────────┼─────────┤      ║
║  │ TASK-001 │ Create User model    │ 92/100 │ 25 min  │      ║
║  │ TASK-002 │ Implement bcrypt     │ 95/100 │ 18 min  │      ║
║  │ TASK-003 │ Implement auth API   │ 85/100 │ 42 min  │      ║
║  │ TASK-004 │ Add validation       │ 88/100 │ 20 min  │      ║
║  │ TASK-005 │ Add auth middleware  │ 91/100 │ 28 min  │      ║
║  └──────────┴──────────────────────┴────────┴─────────┘      ║
║                                                              ║
║  Git Commits                                                 ║
║    abc1234 feat(TASK-001): Create User model                 ║
║    def5678 feat(TASK-002): Add bcrypt password utility        ║
║    ghi9012 feat(TASK-003): Implement RESTful auth API         ║
║    jkl3456 feat(TASK-004): Add input validation               ║
║    mno7890 feat(TASK-005): Add auth middleware                ║
║                                                              ║
║  Meetings Resolved                                           ║
║    MEETING-001: API structure → RESTful (user decided)       ║
║                                                              ║
║  OVERALL: ✓ SUCCESS                                          ║
║  Quality Score: 90/100                                       ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

10.3 交互模式对比

10.4 状态持久化

step/complete 循环

# 获取下一个任务
openmatrix step --json

# 输出:
# {
#   "taskId": "TASK-003",
#   "phase": "develop",
#   "agentType": "coder",
#   "prompt": "...",
#   "timeout": 600000,
#   "context": "..."
# }

# Agent 执行...

# 完成任务
openmatrix complete TASK-003 --success \
  --summary "Implemented auth API with JWT" \
  --artifacts "src/api/auth.ts,src/routes/auth.ts"

状态恢复

# Context 压缩后恢复
/om:resume

# 从指定任务恢复
/om:resume --task TASK-004 --phase develop

10.5 Git 自动提交

Commit 格式

<type>(TASK-XXX): <subject>

<body>

Impact scope: Module name
Files changed: file1, file2

Co-Authored-By: OpenMatrix https://github.com/bigfish1913/openmatrix

Type 规范：feat, fix, test, refactor, docs, chore

下一章将介绍 最佳实践。

第十一章：最佳实践

本章介绍使用 OpenMatrix 的最佳实践。

11.1 质量等级选择

选择指南

11.2 任务指令编写

好的指令特点

1. 明确的目标
2. 清晰的范围
3. 可验证的结果

指令示例对比

不好的指令：

做一个用户系统

好的指令：

实现用户认证系统，包括：
1. 用户注册（邮箱验证）
2. 用户登录（JWT token）
3. 密码重置功能

技术要求：
- 使用 bcrypt 加密密码
- JWT 有效期 7 天

11.3 项目配置建议

.openmatrix 配置

{
  "defaultQuality": "balanced",
  "defaultMode": "semi-auto",
  "gates": {
    "coverage": { "threshold": 70 },
    "lint": { "config": ".eslintrc.js" },
    "security": { "ignore": [] }
  },
  "git": {
    "autoCommit": true
  }
}

11.4 CI/CD 集成

GitHub Actions 配置

name: OpenMatrix Quality Gate

on:
  pull_request:
    branches: [main]

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Install OpenMatrix
        run: npm install -g openmatrix
      - name: Run quality checks
        run: openmatrix auto --quality strict --bypass-approvals
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: quality-report
          path: .openmatrix/report.md

11.5 Meeting 处理建议

减少 Meeting 的方法

1. 详细的任务指令 - 减少信息型 Meeting
2. 明确的技术选型 - 减少决策型 Meetings
3. 完整的依赖准备 - 减少依赖型 Meetings

批量处理

# 查看所有 Meeting
/om:meeting

# 优先处理关键路径
/om:meeting MEETING-001 --answer '{"decision": "..."}'

11.6 团队协作

分支策略

main
├── develop
│   ├── feature/user-auth
│   ├── feature/payment
│   └── bugfix/session-issue
└── hotfix/critical-bug

提交规范

<type>(TASK-XXX): <subject>

<body>

Co-Authored-By: OpenMatrix https://github.com/bigfish1913/openmatrix

11.7 故障排查

常见问题

日志分析

# 查看执行日志
cat .openmatrix/logs/execution.log

# 查看任务上下文
cat .openmatrix/tasks/TASK-XXX/context.md

下一章将介绍 扩展开发。

第十二章：扩展开发

本章介绍如何扩展 OpenMatrix 的功能。

12.1 扩展点概览

OpenMatrix 提供以下扩展点：

12.2 自定义 Agent

Agent 基类

export abstract class BaseAgent {
    protected taskId: string;
    protected agentType: AgentType;

    abstract execute(): Promise<AgentResult>;

    protected readContext(): string;
    protected writeContext(content: string): void;
    protected logDecision(decision: Decision): void;
}

创建自定义 Agent

import { BaseAgent, AgentResult } from '../base-agent';

export class CustomAgent extends BaseAgent {
    constructor(taskId: string, context: AgentContext) {
        super(taskId, 'custom', context);
    }

    async execute(): Promise<AgentResult> {
        // 1. 读取上下文
        const context = this.readContext();

        // 2. 执行自定义逻辑
        const result = await this.performWork();

        // 3. 记录决策
        this.logDecision({
            description: 'Custom action performed',
            reason: 'Based on task requirements'
        });

        // 4. 返回结果
        return {
            taskId: this.taskId,
            agentType: 'custom',
            status: result.success ? 'success' : 'failed',
            output: {
                artifacts: result.files,
                contextUpdate: result.summary
            }
        };
    }
}

注册 Agent

const agentRegistry = {
    // ... 现有 Agent
    'custom': CustomAgent
};

12.3 自定义质量门禁

质量门禁接口

export interface QualityGate {
    name: string;
    check(context: GateContext): Promise<GateResult>;
    required: boolean;
    getSuggestions?(result: GateResult): string[];
}

创建自定义门禁

import { QualityGate, GateContext, GateResult } from './gate-interface';

export class CustomGate implements QualityGate {
    name = 'custom-check';
    required = true;

    async check(context: GateContext): Promise<GateResult> {
        const issues = await this.performCheck(context);

        return {
            status: issues.length === 0 ? 'pass' : 'fail',
            errors: issues
        };
    }

    getSuggestions(result: GateResult): string[] {
        return ['建议检查以下几点...'];
    }
}

12.4 自定义 Skill

Skill 文件格式

---
name: custom-skill
description: Custom skill description
---

# /om:custom-skill

Custom skill description.

## Usage

\`\`\`bash
/om:custom-skill [options]
\`\`\`

## Options

| Option | Type | Description |
|--------|------|-------------|
| --option1 | string | Option description |

## Examples

\`\`\`bash
/om:custom-skill --option1 value
\`\`\`

## Implementation

\`\`\`bash
openmatrix start --custom-option "$option"
\`\`\`

安装 Skill

cp custom-skill.md ~/.claude/commands/om/

12.5 插件系统

插件接口

export interface OpenMatrixPlugin {
    name: string;
    version: string;
    initialize(context: PluginContext): Promise<void>;
    agents?: AgentRegistration[];
    gates?: QualityGate[];
    hooks?: {
        beforeTaskStart?: (task: Task) => Promise<void>;
        afterTaskComplete?: (task: Task, result: AgentResult) => Promise<void>;
        onError?: (error: Error) => Promise<void>;
    };
}

创建插件

export class CustomPlugin implements OpenMatrixPlugin {
    name = 'custom-plugin';
    version = '1.0.0';

    async initialize(context: PluginContext): Promise<void> {
        // 初始化逻辑
    }

    agents = [
        { type: 'custom', factory: (id, ctx) => new CustomAgent(id, ctx) }
    ];

    gates = [new CustomGate()];

    hooks = {
        beforeTaskStart: async (task) => {
            console.log(`Starting: ${task.id}`);
        }
    };
}

12.6 开发环境

项目结构

openmatrix-extension/
├── src/
│   ├── agents/
│   │   └── custom-agent.ts
│   ├── gates/
│   │   └── custom-gate.ts
│   └── index.ts
├── tests/
│   └── agents/
├── package.json
└── tsconfig.json

测试扩展

import { describe, it, expect } from 'vitest';
import { CustomAgent } from '../../src/agents/custom-agent';

describe('CustomAgent', () => {
    it('should execute successfully', async () => {
        const agent = new CustomAgent('TASK-001', mockContext);
        const result = await agent.execute();
        expect(result.status).toBe('success');
    });
});

附录

下一章将提供 附录，包含类型定义、配置参考和常见问题解答。

附录 A：类型定义速查

本附录提供核心类型的快速索引。详细说明和设计原理请参考对应章节。

注意：Task、TaskStatus、AgentType 等核心类型的完整说明见 第二章：核心概念。

A.1 基础枚举

type TaskStatus =
  | 'pending' | 'scheduled' | 'in_progress'
  | 'blocked' | 'waiting' | 'verify' | 'accept'
  | 'completed' | 'failed' | 'retry_queue';

type AgentType =
  | 'planner' | 'coder' | 'tester'
  | 'reviewer' | 'researcher' | 'executor';

type PhaseType = 'tdd' | 'develop' | 'verify' | 'accept';
type QualityLevel = 'strict' | 'balanced' | 'fast';
type ExecutionMode = 'interactive' | 'semi-auto' | 'full-auto';
type MeetingType = 'information' | 'decision' | 'approval' | 'dependency';
type ApprovalType = 'plan' | 'merge' | 'deploy' | 'meeting';

A.2 数据结构索引

A.3 便捷类型

// 门禁结果
interface GateResult { status: 'pass' | 'fail'; details?: string }

// 覆盖率结果
interface CoverageResult extends GateResult {
  line: number; function: number; branch: number; threshold: number;
}

// 测试结果
interface TestResult extends GateResult {
  total: number; passed: number; failed: number; skipped: number;
}

// 上下文
interface AgentContext {
  taskId: string; task: Task; phase: PhaseType;
  accumulatedContext: string; projectContext: ProjectContext;
}

// 问题
interface Question {
  id: string; text: string;
  type: 'text' | 'choice' | 'boolean';
  options?: string[]; required: boolean;
}

附录 B：配置参考

本附录列出 OpenMatrix 的配置选项。

B.1 质量等级配置

strict 模式

{
  "quality": "strict",
  "tdd": true,
  "minCoverage": 80,
  "strictLint": true,
  "securityScan": true,
  "e2eTests": false,
  "aiReview": true
}

balanced 模式

{
  "quality": "balanced",
  "tdd": false,
  "minCoverage": 60,
  "strictLint": false,
  "securityScan": true,
  "e2eTests": false,
  "aiReview": true
}

fast 模式

{
  "quality": "fast",
  "tdd": false,
  "minCoverage": 0,
  "strictLint": false,
  "securityScan": false,
  "e2eTests": false,
  "aiReview": false
}

B.2 执行模式配置

interactive 模式

• 每步确认
• 全部审批
• 适合学习和调试

semi-auto 模式

• 关键点确认
• 关键审批
• 适合生产开发

full-auto 模式

• 无交互
• 无审批
• 适合 CI/CD

B.3 质量门禁配置

{
  "gates": {
    "build": {
      "enabled": true,
      "command": "npm run build"
    },
    "test": {
      "enabled": true,
      "command": "npm test",
      "framework": "vitest"
    },
    "coverage": {
      "enabled": true,
      "threshold": {
        "line": 80,
        "function": 80,
        "branch": 70
      },
      "exclude": [
        "**/*.d.ts",
        "**/dist/**",
        "**/node_modules/**"
      ]
    },
    "lint": {
      "enabled": true,
      "command": "npm run lint",
      "strict": true,
      "ignore": [".git", "node_modules"]
    },
    "security": {
      "enabled": true,
      "command": "npm audit",
      "maxVulnerabilities": {
        "critical": 0,
        "high": 0,
        "moderate": 5
      }
    },
    "e2e": {
      "enabled": false,
      "command": "npm run e2e",
      "tool": "playwright"
    }
  }
}

B.4 Git 配置

{
  "git": {
    "autoCommit": true,
    "commitPrefix": true,
    "commitFormat": "<type>(TASK-XXX): <subject>",
    "types": ["feat", "fix", "test", "refactor", "docs", "chore"]
  }
}

B.5 重试配置

{
  "retry": {
    "maxRetries": 3,
    "backoffStrategy": "exponential",
    "baseDelay": 1000,
    "maxDelay": 30000
  }
}

B.6 超时配置

{
  "timeouts": {
    "tdd": {
      "low": 180000,
      "medium": 300000,
      "high": 600000
    },
    "develop": {
      "low": 300000,
      "medium": 600000,
      "high": 1200000
    },
    "verify": 300000,
    "accept": 180000
  }
}

B.7 存储配置

{
  "storage": {
    "basePath": ".openmatrix",
    "lockTimeout": 30000,
    "backup": {
      "enabled": true,
      "maxBackups": 5
    }
  }
}

B.8 完整配置示例

{
  "quality": "balanced",
  "mode": "semi-auto",
  "gates": {
    "build": { "enabled": true },
    "test": { "enabled": true },
    "coverage": {
      "enabled": true,
      "threshold": { "line": 60 }
    },
    "lint": { "enabled": true },
    "security": { "enabled": true }
  },
  "git": {
    "autoCommit": true
  },
  "retry": {
    "maxRetries": 3
  },
  "storage": {
    "basePath": ".openmatrix"
  }
}

附录 C：API 参考

本附录列出 OpenMatrix 的主要 API。

C.1 Executor API

interface Executor {
  /**
   * 主执行入口
   */
  execute(input: TaskInput): Promise<ExecutionResult>;

  /**
   * 获取待执行的 SubagentTask 列表
   */
  getSubagentTasks(): SubagentTask[];

  /**
   * 处理任务完成
   */
  handleTaskComplete(taskId: string, result: AgentResult): void;

  /**
   * 获取当前执行状态
   */
  getStatus(): ExecutionStatus;
}

C.2 Scheduler API

interface Scheduler {
  /**
   * 获取下一个可执行任务
   */
  getNextTask(): Task | null;

  /**
   * 调度所有任务
   */
  scheduleAll(tasks: Task[]): void;

  /**
   * 检查任务依赖是否满足
   */
  checkDependencies(taskId: string): boolean;

  /**
   * 检测循环依赖
   */
  detectCircularDependency(): string[];

  /**
   * 检查是否有待执行任务
   */
  hasPendingTasks(): boolean;
}

C.3 StateManager API

interface StateManager {
  /**
   * 初始化存储
   */
  initialize(runId: string, input: TaskInput): void;

  /**
   * 获取全局状态
   */
  getState(): GlobalState;

  /**
   * 更新全局状态
   */
  updateState(updates: Partial<GlobalState>): void;

  /**
   * 获取任务
   */
  getTask(taskId: string): Task;

  /**
   * 获取所有任务
   */
  getAllTasks(): Task[];

  /**
   * 按状态获取任务
   */
  getTasksByStatus(status: TaskStatus): Task[];

  /**
   * 保存任务
   */
  saveTask(task: Task): void;

  /**
   * 更新任务状态
   */
  updateTaskStatus(taskId: string, status: TaskStatus): void;

  /**
   * 获取待处理 Meeting
   */
  getPendingMeetings(): Meeting[];

  /**
   * 获取待处理审批
   */
  getPendingApprovals(): Approval[];
}

C.4 FileStore API

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;
}

C.5 AgentRunner API

interface AgentRunner {
  /**
   * 准备 SubagentTask 配置
   */
  prepareSubagentTask(task: Task, phase: PhaseType): SubagentTask;

  /**
   * 构建 Agent 执行 Prompt
   */
  buildPrompt(task: Task, phase: PhaseType, context: string): string;

  /**
   * 确定超时时间
   */
  determineTimeout(phase: PhaseType, complexity: string): number;
}

C.6 PhaseExecutor API

interface PhaseExecutor {
  /**
   * 执行指定阶段
   */
  executePhase(taskId: string, phase: PhaseType): Promise<PhaseResult>;

  /**
   * 准备阶段执行配置
   */
  preparePhase(taskId: string, phase: PhaseType): SubagentTask;

  /**
   * 获取当前阶段
   */
  getCurrentPhase(taskId: string): PhaseType;

  /**
   * 确定下一阶段
   */
  getNextPhase(currentPhase: PhaseType, quality: QualityLevel): PhaseType | null;
}

C.7 MeetingManager API

interface MeetingManager {
  /**
   * 创建 Meeting
   */
  createMeeting(taskId: string, blockInfo: BlockInfo): Meeting;

  /**
   * 获取待处理 Meeting
   */
  getPendingMeetings(): Meeting[];

  /**
   * 解决 Meeting
   */
  resolveMeeting(meetingId: string, resolution: Resolution): void;

  /**
   * 跳过 Meeting
   */
  skipMeeting(meetingId: string): void;
}

C.8 ApprovalManager API

interface ApprovalManager {
  /**
   * 创建审批
   */
  createApproval(type: ApprovalType, content: any): Approval;

  /**
   * 获取待处理审批
   */
  getPendingApprovals(): Approval[];

  /**
   * 处理审批
   */
  processApproval(approvalId: string, decision: 'approve' | 'reject'): void;
}

C.9 BaseAgent API

abstract class BaseAgent {
  /**
   * Agent 执行入口（子类实现）
   */
  abstract execute(): Promise<AgentResult>;

  /**
   * 读取累积上下文
   */
  protected readContext(): string;

  /**
   * 写入上下文
   */
  protected writeContext(content: string): void;

  /**
   * 记录决策
   */
  protected logDecision(decision: Decision): void;

  /**
   * 记录文件变更
   */
  protected logFileChange(change: FileChange): void;
}

附录 D：常见问题

本附录列出 OpenMatrix 的常见问题及解答。

D.1 安装问题

Q: npm install openmatrix 失败？

A: 检查以下几点：

1. Node.js 版本 >= 18.0.0
2. npm 版本 >= 9.0.0
3. 网络连接正常

# 检查版本
node --version
npm --version

# 清除缓存后重试
npm cache clean --force
npm install openmatrix

Q: Skills 安装失败？

A: 确保 ~/.claude/commands/ 目录存在：

mkdir -p ~/.claude/commands/om
openmatrix install-skills --force

D.2 使用问题

Q: /om:start 没有反应？

A: 检查以下几点：

1. Skills 是否正确安装
2. 当前目录是否正确
3. 查看错误日志

# 验证 Skills 安装
ls ~/.claude/commands/om/

# 查看帮助
openmatrix --help

Q: 任务一直处于 pending 状态？

A: 可能原因：

1. 依赖任务未完成
2. 调度器问题

# 查看状态
/om:status --detailed

# 手动调度
openmatrix step --json

Q: Context 压缩后状态丢失？

A: 使用 resume 恢复：

/om:resume

D.3 质量门禁问题

Q: Coverage 检查失败？

A: 常见原因和解决方案：

Q: Lint 检查失败？

A: 常见原因：

# 查看 lint 错误
npm run lint

# 自动修复
npm run lint -- --fix

Q: Security 扫描发现漏洞？

A: 处理步骤：

# 查看漏洞详情
npm audit

# 自动修复
npm audit fix

# 强制修复（可能 breaking changes）
npm audit fix --force

D.4 Meeting 问题

Q: 如何减少 Meeting 数量？

A: 提供更详细的任务指令：

# 不好的指令
做一个用户系统

# 好的指令
实现用户认证系统：
- 使用 JWT token
- bcrypt 加密密码
- 支持 remember me

Q: Meeting 无法解决？

A: 检查问题类型：

D.5 性能问题

Q: 执行速度慢？

A: 优化建议：

1. 使用 fast 模式原型开发
2. 拆分大任务为小任务
3. 减少 E2E 测试

# 使用 fast 模式
/om:start --quality fast

Q: 磁盘空间不足？

A: 清理旧数据：

# 查看存储大小
du -sh .openmatrix/

# 清理旧执行记录
rm -rf .openmatrix/tasks/TASK-*

D.6 集成问题

Q: CI/CD 中如何使用？

A: 使用 full-auto 模式：

- name: Run OpenMatrix
  run: openmatrix auto --quality strict --bypass-approvals

Q: 与现有测试框架冲突？

A: 配置忽略：

{
  "gates": {
    "test": {
      "framework": "vitest",
      "config": "vitest.config.ts"
    }
  }
}

D.7 调试问题

Q: 如何查看详细日志？

A: 查看日志文件：

# 执行日志
cat .openmatrix/logs/execution.log

# 错误日志
cat .openmatrix/logs/errors.log

# Agent 上下文
cat .openmatrix/context.md

Q: 如何重置状态？

A: 删除状态目录：

# 警告：这将清除所有状态
rm -rf .openmatrix/

# 重新开始
/om:start

D.8 其他问题

Q: 支持哪些测试框架？

A: 支持：

• Vitest
• Jest
• Mocha
• 其他（自定义配置）

Q: 支持哪些 Lint 工具？

A: 支持：

• ESLint
• Biome
• Standard
• 其他（自定义配置）

Q: 如何贡献代码？

A: 步骤：

1. Fork 项目
2. 创建特性分支
3. 提交 PR
4. 等待 Code Review

Q: 如何报告 Bug？

A: 提交 Issue：

1. 描述问题
2. 复现步骤
3. 期望行为
4. 实际行为
5. 环境信息

附录 E：性能基准

本附录提供 OpenMatrix 在不同场景下的性能基准数据。

E.1 任务规划性能

规划时间 vs 任务数量

规划复杂度公式

$$T_{plan}=\alpha \cdot n+\beta \cdot d+\gamma \cdot n\cdot \log (n)$$

其中：

• $n$ = 任务数量
• $d$ = 依赖关系数量
• $\alpha \approx 0.25$s（单任务分析时间）
• $\beta \approx 0.08$s（单依赖分析时间）
• $\gamma \approx 0.01$s（排序因子）

E.2 Agent 执行性能

单任务执行时间

Agent 类型平均执行时间

E.3 质量门禁性能

各门禁执行时间

质量门禁总耗时

$$T_{verify}=\sum _{i=1}^7{T}_{gat{e}_i}+T_{overhead}$$

$$T_{overhead}\approx 2\text{s}$$

E.4 存储性能

文件操作延迟

状态文件大小

E.5 并发性能

并行任务执行

$$S(p)=\frac{T_1}{T_p}E(p)=\frac{S(p)}{p}$$

其中 $p$ 为并行度，$T_1$ 为串行时间，$T_p$ 为并行时间。

E.6 内存占用

运行时内存

内存 vs 任务数量

$$M(n)=M_{base}+k\cdot n$$

• $M_{base}\approx 50$ MB
• $k\approx 2$ MB/任务
• 50 任务预计内存：~150 MB

E.7 基准测试方法论

测试环境

测试项目

以上数据基于 v0.1.98 版本在标准测试环境下测量。实际性能受项目复杂度、网络延迟、LLM API 响应时间等因素影响。

附录 F：竞品对比

本附录对比 OpenMatrix 与主流 Agent 编排框架。

F.1 框架总览

F.2 架构对比

OpenMatrix：任务编排模型

graph TD
    A[用户指令] --> B[任务拆解]
    B --> C1[TASK-001]
    B --> C2[TASK-002]
    B --> C3[TASK-003]
    
    C1 --> D1[TDD → Dev → Verify → Accept]
    C2 --> D2[TDD → Dev → Verify → Accept]
    C3 --> D3[TDD → Dev → Verify → Accept]
    
    D1 --> E[质量门禁]
    D2 --> E
    D3 --> E

特点：以任务为中心，四阶段执行 + 质量门禁。

LangGraph：状态图模型

graph TD
    A[Start] --> B[Node A]
    B --> C{Conditional}
    C --> |"条件1"| D[Node B]
    C --> |"条件2"| E[Node C]
    D --> F[End]
    E --> F

特点：以状态转换为中心，图结构定义工作流。

CrewAI：多 Agent 协作模型

graph TD
    A[Crew] --> B[Agent 1: Researcher]
    A --> C[Agent 2: Writer]
    A --> D[Agent 3: Reviewer]
    
    B --> |"顺序/层级"| C
    C --> |"顺序/层级"| D

特点：以 Agent 角色为中心，定义团队协作流程。

AutoGen：多 Agent 对话模型

graph TD
    A[User Proxy] <--> B[Assistant Agent]
    B <--> C[Code Executor]
    A <--> C

特点：以对话为中心，Agent 之间自由交流。

F.3 功能详细对比

编排能力

质量保障

状态管理

错误处理

集成能力

F.4 适用场景对比

F.5 技术选型考量

选 OpenMatrix 当

• 你在使用 Claude Code 进行 AI 辅助开发
• 你需要自动化质量保障（TDD、覆盖率、安全扫描）
• 你需要任务级别的编排和调度
• 你需要状态持久化和 Context 恢复

选 LangGraph 当

• 你需要复杂的状态图工作流
• 你需要精细的条件分支和循环控制
• 你使用 Python 技术栈
• 你的工作流不是围绕代码生成

选 CrewAI 当

• 你需要多 Agent 角色协作
• 你的任务适合分解为不同专业角色
• 你使用 Python 技术栈
• 你不需要严格的质量门禁

选 AutoGen 当

• 你在研究 Agent 对话模式
• 你需要 Agent 之间的自由交流
• 你使用 Python 技术栈
• 你在做概念验证而非生产系统

F.6 互操作性

OpenMatrix 可以与其他框架互补：

graph TD
    subgraph "组合方案"
        OM[OpenMatrix<br/>任务编排 + 质量保障]
        LG[LangGraph<br/>复杂工作流]
        CA[CrewAI<br/>多角色协作]
    end

    OM --> |"内部使用"| LG
    OM --> |"内部使用"| CA

组合示例：

• OpenMatrix 编排 + LangGraph 实现内部工作流
• OpenMatrix 编排 + CrewAI 实现多 Agent 协作
• OpenMatrix 质量保障 + 任意框架执行

本对比基于各框架截至 2024 年初的公开文档和代码。框架在快速迭代中，具体功能请参考最新官方文档。