Tricoder/doc/平台设计/AI编排输入输出规范.md

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 提供初始输入。

建议结构：

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

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

5.2 EvidenceSummary

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

5.3 ChainTemplateSummary

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

5.4 ModuleSummary

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

5.5 ExperimentSummary

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

5.6 AnalysisBudget

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

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

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

建议结构：

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

6.1 Hypothesis

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

6.2 PlannedExperiment

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

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

6.3 StopDecision

type StopDecision = {
  shouldStop: boolean
  reason: string
}

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

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

建议结构：

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

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

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

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

建议结构：

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 和自由回答。