第一章：项目概述

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 类型、质量门禁等。