> ## Documentation Index
> Fetch the complete documentation index at: https://automationlaboratoryprotocol.mimedal.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 技能库

> 保存通过评估的设备技能描述、函数式技能和版本关系

## 作用

合格设备技能库向实验编排代理提供经过质量检查的设备技能。它是 FSP 完整技能定义、设备技能描述、质量报告和函数式技能之间的可追溯集合，不另行定义设备事实。

## 准入输入

每次准入至少包含：

```text theme={null}
FSP 设备标识和能力修订号
设备技能描述
质量评估报告
由技能描述生成的函数式技能
```

函数式技能必须保留准入版本中的函数签名、前置条件、约束、状态变化、返回值和异常说明。

### 输入示例

| 输入产物   | 示例值                                                 | 作用            |
| ------ | --------------------------------------------------- | ------------- |
| 设备标识   | `2002186824385539`                                  | 关联真实设备        |
| 能力修订号  | `12`                                                | 固定能力事实版本      |
| 设备技能描述 | 包含开盖、加液、关盖三条操作的 MDX 内容                              | 供阅读、检索和质量评估   |
| 质量报告   | `total_score=95.0`、`passed=true`、`threshold=60`     | 决定是否准入并记录缺陷   |
| 函数式技能  | `open_caps`、`add_liquid_with_material`、`close_caps` | 供方法生成、静态检查和仿真 |

## 库中能力产物

每个准入版本必须同时保存两类等价表达：

| 产物      | 必需内容                                   | 主要用途         |
| ------- | -------------------------------------- | ------------ |
| 设备技能描述  | 身份、技能标识、请求分类、对象/控制/系统三个维度、参数、状态变化和验证规则 | 人员与模型阅读、质量评估 |
| 函数式技能定义 | 函数签名、类型、前置条件、强制约束、状态变化、返回值和诊断          | 方法生成、静态检查和仿真 |

函数式技能至少应提供以下三个部分：

```text theme={null}
公共数据类型
设备命名空间及操作函数
统一结果与诊断类型
```

非规范性函数签名示例：

```python theme={null}
def open_caps(
    container_type,
    container_count,
    container_ids,
    open_cap_bottle_ids,
    keep_cap
) -> StepResult:
    ...

def close_caps(
    container_type,
    container_count,
    container_ids,
    close_cap_bottle_ids
) -> StepResult:
    ...

def add_liquid_with_material(
    container_type,
    container_count,
    container_ids,
    dispensing_plan
) -> StepResult:
    ...
```

三个函数的完整参数、状态和约束分别见[操作](/specification/fsp/operations)与[实验方法](/specification/methods/overview)。实现可以使用文件、数据库或远程服务存储，但对外语义必须与准入通过的设备技能描述和函数式技能定义一致。

## 函数式技能契约

每个操作函数必须包含：

| 内容    | 要求                            |
| ----- | ----------------------------- |
| 函数名称  | 与能力定义中的 `command_id` 建立唯一映射   |
| 参数    | 名称、类型、必填性、默认值、单位、范围、枚举和嵌套结构完整 |
| 前置条件  | 描述允许调用的容器、样品和系统状态             |
| 强制约束  | 使用可计算表达式，并关联稳定诊断编码            |
| 状态变化  | 列出成功后改变与保持不变的字段               |
| 返回值   | 字段、类型、单位和语义确定                 |
| 异常或诊断 | 说明失败原因、影响字段和是否可重试             |

## 函数定义格式

每个已准入操作都必须有一份可解析的函数定义。该定义只描述调用契约，不承载设备驱动实现；设备实际控制仍通过 FSP 接口完成。

函数定义由函数签名和固定顺序的八个说明区块组成：

```text theme={null}
Summary
Preconditions
Cautions
Args
Constraints
State Changes
Returns
Example
```

| 区块              | 必需内容                      | 用途             |
| --------------- | ------------------------- | -------------- |
| `Summary`       | 一句话说明操作目的                 | 便于检索和选择操作      |
| `Preconditions` | 调用前必须满足的对象、样品和系统状态        | 阻止状态不满足的调用     |
| `Cautions`      | 跨步骤注意事项和设备差异              | 保持多步方法的上下文一致   |
| `Args`          | 参数名称、类型、单位、范围、枚举、默认值和嵌套结构 | 构造可验证的调用参数     |
| `Constraints`   | 可计算的单参数或跨参数规则，以及硬性或建议级别   | 为仿真和执行提供统一判断依据 |
| `State Changes` | 每个状态字段的执行前后值，包含保持不变的字段    | 让状态仿真与实际结果可以比对 |
| `Returns`       | 成功结果的字段、类型、单位和含义          | 让后续步骤消费确定结果    |
| `Example`       | 一组合法参数、调用方式和结果使用方式        | 用于调用生成与人工核对    |

### 参数与结果类型

函数签名不得把结构化参数简化为无约束字典。数组中的对象、嵌套参数和操作返回值必须有稳定名称和可检查字段。公共类型至少包括：

```text theme={null}
容器类型与状态枚举
嵌套操作参数类型
StepResult：操作结果、状态变化与诊断
```

`StepResult` 至少应包含以下字段：

```json theme={null}
{
  "status": "succeeded",
  "result": {
    "containers": []
  },
  "state_changes": [],
  "diagnostics": []
}
```

| 字段              | 作用                      |
| --------------- | ----------------------- |
| `status`        | 标识成功、失败、取消或结果未知         |
| `result`        | 保存与操作 `returns` 一致的结果字段 |
| `state_changes` | 保存设备确认或仿真确认的实际状态变化      |
| `diagnostics`   | 保存失败原因、影响字段和可处理建议       |

### 函数定义示例

以下非规范性示例以开盖操作说明完整契约。函数体使用 `...` 表示定义文件不实现设备控制逻辑。

```python theme={null}
def open_caps(
    container_type: Literal["离心瓶", "50ml耐热瓶"],
    container_count: int,
    container_ids: list[int],
    open_cap_bottle_ids: list[OpenCapBottle],
    keep_cap: int = 1,
) -> StepResult:
    """
    Summary:
        打开指定容器的瓶盖。

    Preconditions:
        容器状态必须为“有盖”。

    Cautions:
        后续关盖操作必须使用本次保留的瓶盖。

    Args:
        container_count: 范围为 1..10。
        container_ids: 最大编号不得大于 container_count。
        keep_cap: 枚举值为 0 或 1。

    Constraints:
        MUST: 1 <= container_count <= 10；违反类别为参数范围错误。
        MUST: max(container_ids) <= container_count；违反类别为容器约束错误。
        MUST: 每个 bottle_id 属于 container_ids；违反类别为容器约束错误。

    State Changes:
        container_status: 有盖 → 无盖。
        sample_status: 保持不变。

    Returns:
        返回已开盖容器编号、容器状态、样品状态和诊断。

    Example:
        对 1、2 号离心瓶调用，返回 opened_bottles=[1, 2]。
    """
    ...
```

## 校验与状态提交

`MUST` 表示物理安全、状态正确性或数据完整性的硬性条件；任一 `MUST` 失败都必须阻断执行并进入 `diagnostics`。`SHOULD` 表示不会破坏安全性的建议；违反时写入 `warnings`，不单独阻断执行。

校验和状态更新必须使用两阶段顺序：

```text theme={null}
第一阶段：检查全部 MUST 与 SHOULD 条件，记录 errors[] 与 warnings[]
第二阶段：仅当 errors[] 为空时，写入声明的 State Changes 并生成结果
```

不得边校验边更新状态，也不得在发现第一项失败后写入部分成功状态。函数定义中的每条硬性约束必须能在仿真或实际执行诊断中找到对应结果。

## 版本规则

* FSP 能力修订号是设备事实版本；
* 自然语言能力说明必须记录其来源修订号；
* 函数式技能必须与设备技能描述和公共类型使用同一版本快照；
* 任一层变化都必须使依赖它的实验方法重新验证；
* 版本不一致时不得生成下游执行 JSON。

## 查询输出

实验编排代理查询能力库时至少需要获得：

```text theme={null}
设备编码
设备名称
技能说明
可用技能及请求分类
函数签名
适用容器和状态
参数约束
来源修订号
质量评估结果
```

查询实现可以是文件索引、数据库或远程服务，ALL 不规定内部存储方式。

### 查询输出示例

```json theme={null}
{
  "device_id": "2002186824385539",
  "device_name": "Liquid_Handling_Station_1ml_V2",
  "revision": "12",
  "quality": {"score": 95.0, "passed": true, "threshold": 60},
  "skills": [
    {"command_id": "open_caps", "request_class": "invoke", "function_name": "open_caps"},
    {"command_id": "add_liquid_with_material", "request_class": "invoke", "function_name": "add_liquid_with_material"},
    {"command_id": "close_caps", "request_class": "invoke", "function_name": "close_caps"}
  ],
  "object_types": ["container.sample_vial"]
}
```

| 输出字段                      | 作用                    |
| ------------------------- | --------------------- |
| `device_id`、`device_name` | 标识可绑定设备               |
| `revision`                | 约束方法与能力使用同一版本         |
| `quality`                 | 表示准入结果和评分依据           |
| `skills[]`                | 建立设备技能、请求分类与函数名称的确定映射 |
| `object_types[]`          | 用于筛选设备可处理的对象类型        |