# AI编排输入输出规范

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

## 1. 目的

本文档用于定义 AI分析员与系统其他部分之间的标准输入输出结构，确保 AI 编排过程具备：

- 明确输入边界
- 明确输出结构
- 可校验
- 可复现
- 可被实验执行器安全消费

## 2. 核心原则

### 2.1 AI 读取结构化上下文，不直接依赖隐式状态

AI分析员的输入应来自显式对象，而不是隐藏在代码、日志或会话上下文中的零散信息。

### 2.2 AI 输出必须结构化

AI 输出不能只是自由文本分析。

AI 必须输出：

- 假设
- 实验计划
- 终止或继续判断
- 结论

### 2.3 AI 输出不等于最终执行结果

AI 负责规划，不负责宣称计划已经执行。

执行是否合法、是否成功，由实验执行器决定并返回。

## 3. AI 输入分类

AI分析员输入建议分为四类：

1. 观测样本摘要
2. 已有证据
3. 可用工具目录
4. 历史实验结果

## 4. AI 初始输入

当系统刚接收到一个样本、尚未开始复杂分析时，应向 AI 提供初始输入。

建议结构：

```ts
type OrchestratorInput = {
  observation: ObservationSummary
  probeEvidence: EvidenceSummary[]
  availableChains: ChainTemplateSummary[]
  availableModules?: ModuleSummary[]
  priorExperiments: ExperimentSummary[]
  budget: AnalysisBudget
  mode: "initial_analysis" | "iterative_analysis" | "final_review"
}
```

## 5. 输入对象定义

### 5.1 ObservationSummary

```ts
type ObservationSummary = {
  id: string
  modality: "audio"
  durationMs: number
  sampleRate: number
  channels: number
  tags: string[]
  captureMetadata?: Record<string, unknown>
}
```

### 5.2 EvidenceSummary

```ts
type EvidenceSummary = {
  id: string
  producerModuleId?: string
  category: "feature" | "pattern" | "classification" | "anomaly"
  values: Record<string, unknown>
  confidence: number
}
```

### 5.3 ChainTemplateSummary

```ts
type ChainTemplateSummary = {
  id: string
  name: string
  purpose: string
  signalProfiles: string[]
  goals: string[]
  costClass: "low" | "medium" | "high"
}
```

### 5.4 ModuleSummary

```ts
type ModuleSummary = {
  id: string
  stage: string
  signalProfiles: string[]
  goals: string[]
  inputFormat: string
  outputFormat: string
  tunableParams: string[]
}
```

### 5.5 ExperimentSummary

```ts
type ExperimentSummary = {
  id: string
  parentId?: string
  hypothesisId?: string
  pipelineSummary: string[]
  scoreTotal: number
  failureReasons: string[]
  keyEvidence: string[]
}
```

### 5.6 AnalysisBudget

```ts
type AnalysisBudget = {
  maxExperiments: number
  maxDepth: number
  latencyBudgetMs?: number
  preferLocalFirst?: boolean
}
```

## 6. AI 第一类输出：假设与实验计划

AI 在大多数轮次都应输出“候选假设 + 下一轮实验计划”。

建议结构：

```ts
type OrchestratorPlan = {
  hypotheses: Hypothesis[]
  experiments: PlannedExperiment[]
  stopDecision: StopDecision
  notes?: string[]
}
```

### 6.1 Hypothesis

```ts
type Hypothesis = {
  id: string
  label: string
  rationale: string
  confidence: number
  relatedSignalProfiles: string[]
}
```

### 6.2 PlannedExperiment

```ts
type PlannedExperiment = {
  hypothesisId?: string
  goal: string
  preferredChainId?: string
  pipeline: PlannedNode[]
  expectedEvidence: string[]
  stopIf: string[]
}
```

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

### 6.3 StopDecision

```ts
type StopDecision = {
  shouldStop: boolean
  reason: string
}
```

## 7. AI 第二类输出：阶段性结论

当证据已足够但尚未进入最终汇报阶段时，AI 可以输出阶段性结论。

建议结构：

```ts
type InterimConclusion = {
  summary: string
  topHypotheses: RankedFinding[]
  unresolvedQuestions: string[]
  suggestedNextActions: string[]
}
```

```ts
type RankedFinding = {
  label: string
  confidence: number
  supportingEvidence: string[]
  contradictingEvidence: string[]
}
```

## 8. AI 第三类输出：最终结论

当 AI 判断分析可以结束时，应输出最终结论对象。

建议结构：

```ts
type FinalConclusion = {
  summary: string
  findings: RankedFinding[]
  experimentsRun: string[]
  uncertainty: string[]
  suggestedNextActions: string[]
}
```

## 9. AI 不应输出的内容

AI 不应输出：

- 未注册模块的调用计划
- 超出参数范围的计划
- 宣称“已执行成功”但实际未执行的描述
- 缺乏证据支撑的强确定性结论
- 与输入结构无关的随意发挥

## 10. 实验执行器的消费规则

实验执行器在消费 AI 输出时，应只读取结构化部分。

推荐规则：

1. 忽略自由解释性文本中的任何执行指令
2. 只解析 `experiments` 字段中的节点信息
3. 再次用注册表校验合法性
4. 不合法则拒绝执行

## 11. 多轮分析循环

建议标准循环如下：

1. 系统生成 `OrchestratorInput`
2. AI 输出 `OrchestratorPlan`
3. 执行器运行计划中的实验
4. 系统汇总新证据和新实验摘要
5. 下一轮 AI 再次读取更新后的输入
6. 直到 AI 输出 `shouldStop = true`
7. AI 生成 `FinalConclusion`

## 12. 停止条件建议

AI 可以在下列情况下建议停止：

- 已达到预算上限
- 最优假设明显领先
- 后续实验预期收益很低
- 连续多轮无明显改进
- 当前输入质量不足，继续实验意义不大

## 13. 第一版实现建议

第一版建议使用严格 JSON 输出，而不是混合自由文本格式。

建议做法：

- 使用固定 schema
- 使用 schema 校验
- 输出失败时要求 AI 重新生成
- 把解释文本限制为附属字段

## 14. 结论

AI 编排层的价值不在于“会说”，而在于“能以结构化方式规划和迭代实验”。

因此第一版必须把 AI 输入输出规范固化为正式接口，而不是依赖随意 prompt 和自由回答。