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