扩展规范 — eyai Extension v1.0

版本： 1.0.0-rc6  |  状态： 🔴 候选发布

本规范定义 eyai 扩展描述文件 extension.eyai-ext.yaml 的完整格式，以及规范包的文件结构。

扩展描述文件

每个 eyai 派生规范必须（MUST） 包含一个 extension.eyai-ext.yaml 文件：

# extension.eyai-ext.yaml
spec:
  id: "com.example.power"
  name: "电源测试规范"
  namespace: "com.example"
  version: "1.0.0"
  parent: "eyai/core@>=1.0.0"
  description: "电源测试实验协议规范"
  author: "Example Corp"

元信息字段

字段	必需	类型	说明
spec.id	必须	string	全局唯一标识符（如 com.example.power）
spec.name	必须	string	人类可读名称
spec.namespace	必须	string	顶层命名空间（如 electronics）
spec.version	必须	string	语义化版本号 MAJOR.MINOR.PATCH
spec.parent	必须	string	父规范引用
spec.description	必须	string	规范描述
spec.author	必须	string	作者

步骤类型声明

扩展可以声明新的步骤类型（step type），包括参数 schema、验证规则和能力要求：

step_types:
  - name: "apply_voltage"
    description: "施加电压到被测设备"
    parameters:
      voltage:
        description: "目标电压"
        type: "quantity.voltage"
        required: true
      current_limit:
        description: "电流限制"
        type: "quantity.current"
      duration:
        description: "持续时间"
        type: "quantity.time"
        required: true
    capabilities:
      - "power_supply"
      - "voltage_measurement"

对应的 JSON Schema 类型引用：

{
  "properties": {
    "voltage": { "$ref": "https://schemas.eyai.top/types/quantity.voltage" },
    "current_limit": { "$ref": "https://schemas.eyai.top/types/quantity.current" },
    "duration": { "$ref": "https://schemas.eyai.top/types/quantity.time" }
  }
}

数据类型声明

扩展可以声明新的数据类型，用于步骤参数的类型约束。

函数声明

扩展可以声明内置函数，供表达式引擎调用。

能力声明

扩展声明的能力契约表示执行该规范所需的设备能力。

依赖管理

dependencies:
  - ref: "com.example.common"
    version: "^1.0.0"

依赖解析规则：

1. 同一 ref 出现多次取最高版本约束
2. 无法满足版本约束时报错
3. 不删除父规范类型（仅追加或废弃）

规范包结构

com.example.power-v1.0.0/
├── extension.eyai-ext.yaml    # 必需：扩展描述文件
├── schemas/                   # 可选：JSON Schema 文件
│   ├── step_types/
│   ├── data_types/
│   └── functions/
├── examples/                  # 可选：示例协议
├── tests/                     # 可选：测试用例
├── docs/                      # 可选：文档
└── CHANGELOG.md               # 推荐：变更日志

版本约束

格式	含义
1.0.0	精确版本
^1.0.0	兼容版本（>=1.0.0, <2.0.0）
~1.0.0	近似版本（>=1.0.0, <1.1.0）
>=1.0.0	最低版本

全文

完整规范请查阅 GitHub 仓库。