Tricoder/doc/平台设计/实验执行器设计.md

实验执行器设计

版本号：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分析员提出的一次具体实验计划。

建议结构如下：

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

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

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. 运行上下文

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

建议结构：

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

其中：

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

10. 阶段输出管理

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

建议结构：

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

这有三个重要用途：

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

11. 证据收集机制

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

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

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

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

建议 Evidence 至少包含：

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

12. 评分机制

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

建议评分至少包括：

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

建议结构：

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 对象。

建议结构：

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
}

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 无法真正替代使用者完成系统化分析流程。