总纲 — eyai Core v1.0

版本： 1.0.0-rc5  |  状态： ✅ 候选发布  |  最后更新： 2026-06-25

本规范是 eyai 规范生态的总纲（Core），定义了 eyai 实验协议语言的核心语法、语义和类型系统。所有派生规范必须（MUST） 遵循本规范。

1. 文件结构

一个 eyai 协议文件由以下核心部分构成：

format: "eyai/1.0"           # 必须：格式标识
schema: "https://schemas.eyai.top/core/v1.0"  # 可选：JSON Schema URL
metadata:                     # 必须：元数据
  id: "experiment-id"
  title: "实验标题"
  version: "1.0.0"
  language: "zh-CN"
workflow:                     # 必须：工作流步骤
  - type: "step-type"
    id: "step-id"
    # ...

顶层字段	必需	说明
format	必须	eyai 格式标识，格式为 eyai/MAJOR.MINOR
schema	可选	JSON Schema 验证 URL
metadata	必须	协议元信息
description	可选	协议描述
variables	可选	全局变量声明
workflow	必须	工作流步骤数组（至少 1 个）
extensions	可选	扩展规范引用
ai_context	可选	AI 辅助上下文

2. 步骤类型

2.1 通用步骤

所有步骤共享的基础字段：

- type: "action"       # 必须：步骤类型（非控制流关键字）
  id: "step-id"        # 必须：唯一标识符
  title: "步骤标题"     # 可选
  description: "..."   # 可选
  parameters: {}       # 可选：输入参数
  outputs: {}          # 可选：输出声明
  on-error: "stop"     # 可选：错误处理策略
  timeout: "30s"       # 可选：超时
  capabilities: []     # 可选：所需设备能力
  ai: {}               # 可选：AI 元数据
  safety: {}           # 可选：安全约束

2.2 控制流步骤

步骤	说明
if	条件分支，支持 elif / else
for	变量遍历循环
while	条件循环，支持 max_iterations
parallel	并行执行组
try	异常捕获，do + catch

2.3 错误处理

on-error 支持以下策略：

值	说明
"stop"	停止整个协议
"skip"	跳过当前步骤，继续执行
"retry:N"	重试最多 N 次
{action, max_attempts, interval}	结构化重试配置

3. AI 原生设计

eyai 语言结构的每个层级都包含 AI 元数据字段，使 AI 模型能更好地理解和生成协议：

ai_context（协议级）

ai_context:
  domain: "pcr"              # 实验领域
  complexity: "advanced"     # beginnner | intermediate | advanced
  critical-steps:            # 关键步骤列表
    - "denaturation"
    - "annealing"
  safety-notes: "注意高温"   # 安全提示
  intent: "DNA片段扩增"      # 实验意图

step.ai（步骤级）

- type: "temperature"
  id: "annealing"
  ai:
    intent: "引物与模板DNA结合"
    rationale: "退火温度根据引物Tm值计算"
    sensitivity:
      temperature: "critical"
    optimization_hints: "梯度PCR: 54-60°C"
    common_mistakes:
      - "退火温度过高导致无扩增"
      - "时间不足导致结合不完全"
    risk_level: "medium"
    confidence: 0.95
    skill_level: "intermediate"
    typical_duration: "30s"

4. 变量与表达式

变量声明

variables:
  - name: "sample_count"
    value: 24
    unit: "个"
    description: "样品数量"
    min: 1
    max: 96

变量引用

使用 $variable_name 语法在参数中引用变量。

5. JSON Schema

完整 JSON Schema 托管在：

https://schemas.eyai.top/core/v1.0

CLI 验证命令：

eyai validate protocol.eyai.yaml

全文

完整规范全文请查阅 GitHub 仓库。