# 实验执行器设计

版本号：v0.1.0
最后更新：2026-04-04

## 1. 目的

本文档用于定义本项目中实验执行器的职责、输入输出、运行流程和记录机制。

实验执行器的作用是把 AI分析员生成的实验计划真正落地为可运行、可校验、可记录、可复现的实验过程。

## 2. 核心定位

实验执行器不是算法仓库，也不是 AI 决策器。

它在系统中的位置是：

- 接收实验计划
- 校验实验计划是否合法
- 按计划执行算法链
- 收集输出与运行信息
- 生成实验记录
- 返回结构化结果给 AI分析员

可以把实验执行器理解为：

`自动化实验运行底座`

## 3. 核心职责

实验执行器至少应承担以下职责：

1. 接收实验计划
2. 根据模块注册表校验计划
3. 构建可执行链路
4. 调用模块完成执行
5. 管理中间输出
6. 收集证据
7. 计算评分
8. 记录失败原因
9. 生成标准化实验结果

## 4. 为什么实验执行器必须独立存在

如果没有独立实验执行器，系统会退化成：

- AI 直接调代码
- 各模块输出结构不统一
- 无法复现一次分析过程
- 结果不可比较
- 失败归因不稳定

独立实验执行器的意义在于：

- 统一实验行为
- 统一结果结构
- 统一异常处理
- 为多轮分析提供稳定基础

## 5. 输入对象

实验执行器的核心输入是：

- `Observation`
- `ExperimentPlan`
- 模块注册表
- 链模板注册表

### 5.1 Observation

表示本次实验所针对的样本。

### 5.2 ExperimentPlan

表示 AI分析员提出的一次具体实验计划。

建议结构如下：

```ts
type ExperimentPlan = {
  id: string
  observationId: string
  hypothesisId?: string
  pipeline: PlannedNode[]
  budget?: ExecutionBudget
  notes?: string[]
}
```

```ts
type PlannedNode = {
  moduleId: string
  params: Record<string, unknown>
}
```

```ts
type ExecutionBudget = {
  maxLatencyMs?: number
  maxMemoryMb?: number
  preferLocal?: boolean
}
```

## 6. 运行前校验

实验执行器在运行前必须做计划校验。

至少包括：

1. `observationId` 是否存在
2. 所有 `moduleId` 是否已注册
3. 节点顺序是否兼容
4. 输入输出格式是否匹配
5. 参数是否在允许范围内
6. 参数是否允许 AI 调整
7. 所需运行位置是否可用
8. 模块是否启用
9. 模块信任等级是否满足当前模式

如果任何一项失败，应直接拒绝执行，并生成结构化错误返回。

## 7. 执行模式

第一版建议支持两类执行模式：

### 7.1 本地执行

适用于：

- 轻量探针
- 低延迟分析
- 手机端可承受计算

### 7.2 远端执行

适用于：

- 重型特征提取
- 重型验证链
- 声源分离
- 更高成本模型调用

实验执行器不一定自己完成所有计算，但必须负责协调这些执行位置。

## 8. 执行流程

建议标准执行流程如下：

1. 读取 `Observation`
2. 校验 `ExperimentPlan`
3. 构造运行上下文
4. 按顺序执行各节点
5. 保存阶段输出
6. 收集中间证据
7. 汇总最终证据
8. 计算评分
9. 记录失败原因
10. 生成 `Experiment`

## 9. 运行上下文

为了支持模块间协作，执行器应维护统一运行上下文。

建议结构：

```ts
type ExecutionContext = {
  observationId: string
  inputRef: string
  workingSet: Record<string, unknown>
  intermediateOutputs: StageOutput[]
  evidenceBuffer: Evidence[]
  warnings: string[]
}
```

其中：

- `workingSet` 用于保存当前执行状态
- `intermediateOutputs` 记录阶段输出
- `evidenceBuffer` 累积本次实验证据
- `warnings` 记录非致命问题

## 10. 阶段输出管理

每个节点执行后，执行器应记录输出，而不是只保留最后结果。

建议结构：

```ts
type StageOutput = {
  stage: string
  moduleId: string
  format: string
  payloadRef: string
  metadata?: Record<string, unknown>
}
```

这有三个重要用途：

- 回放和复核
- 调试失败链路
- 支持后续复用中间结果

## 11. 证据收集机制

实验执行器应负责从模块输出中收集标准化证据。

第一版建议由模块返回两类内容：

1. 主输出
2. 可选证据条目

执行器将这些内容统一整理为 `Evidence`。

建议 `Evidence` 至少包含：

- 产生它的模块
- 所属实验
- 分类
- 值
- 置信度
- 追踪引用

## 12. 评分机制

实验执行器不一定拥有最复杂的评分逻辑，但必须支持标准评分接口。

建议评分至少包括：

- 结果质量
- 结构稳定性
- 模式清晰度
- 成本惩罚

建议结构：

```ts
type ScoreCard = {
  total: number
  components: Record<string, number>
  penalties?: Record<string, number>
  notes?: string[]
}
```

评分器可以是执行器内部组件，也可以是被调用的独立服务，但结果必须由执行器统一归档。

## 13. 失败归因

实验执行器不能只返回“失败”。

必须尽可能输出结构化失败原因，供 AI分析员后续决策使用。

建议分为三类失败：

### 13.1 计划非法

例如：

- `module_not_registered`
- `format_mismatch`
- `param_out_of_range`

### 13.2 运行失败

例如：

- `remote_worker_unavailable`
- `module_runtime_error`
- `resource_budget_exceeded`

### 13.3 结果无效或弱结果

例如：

- `no_clear_periodicity`
- `unstable_segmentation`
- `classifier_confidence_collapsed`
- `insufficient_signal_structure`

这类失败尤其重要，因为它们会直接影响 AI 的下一轮选择。

## 14. 实验记录对象

执行完成后，实验执行器应生成标准化 `Experiment` 对象。

建议结构：

```ts
type Experiment = {
  id: string
  observationId: string
  parentId?: string
  hypothesisId?: string
  pipeline: PipelineNode[]
  status: "pending" | "running" | "done" | "failed" | "cancelled"
  outputs: StageOutput[]
  evidenceIds: string[]
  score: ScoreCard
  failureReasons: string[]
  runtimeStats?: RuntimeStats
  createdAt: string
  startedAt?: string
  finishedAt?: string
}
```

```ts
type RuntimeStats = {
  elapsedMs: number
  cpuMs?: number
  peakMemoryMb?: number
  location?: "local_mobile" | "remote_host" | "mixed"
}
```

## 15. 父子实验关系

实验执行器必须支持实验之间的继承关系。

这是因为 AI分析员不会只跑一次实验，而会基于上一次结果继续调整。

例如：

- 第一次跑通用探针链
- 第二次基于周期假设跑验证链
- 第三次调整参数重跑验证链

因此 `Experiment.parentId` 非常关键，它能帮助系统形成实验树。

## 16. 与 AI分析员的协作方式

实验执行器与 AI分析员之间应形成闭环：

1. AI分析员生成实验计划
2. 实验执行器校验并执行
3. 实验执行器返回结构化结果
4. AI分析员分析结果并决定下一步

AI 不应直接调用模块。
AI 应始终通过实验执行器来使用算法能力。

## 17. 停止条件支持

实验执行器本身不决定最终何时停止分析，但应支持停止条件相关信息的输出。

例如：

- 当前实验已接近预算上限
- 连续三次参数调整无明显改善
- 某条链的结果稳定低分

这些信息可以帮助 AI分析员更理性地结束或切换分析路径。

## 18. 第一版实现建议

第一版实验执行器建议先做成简单、稳定、可复现的形式。

建议优先支持：

- 串行节点执行
- 本地与远端两种运行位置
- 中间输出记录
- 基础证据收集
- 基础评分
- 结构化失败原因

第一版可以暂不支持：

- 并行执行复杂调度
- 自动缓存重用
- 大规模分布式实验树

## 19. 结论

实验执行器是本项目从“有算法模块”走向“可自动化实验分析系统”的关键一步。

它的核心价值在于：

- 把实验计划变成真正可运行的链路
- 把执行结果变成结构化实验记录
- 为 AI分析员提供可信、统一、可迭代的反馈基础

没有实验执行器，AI 无法真正替代使用者完成系统化分析流程。