> ## 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.

# 实验方法

> 使用准入函数式技能生成可计算、可验证的代码式实验方案

## 定义

函数式实验方法把研究对象状态、参数、约束和可用设备能力组合成可计算程序：

```text theme={null}
M: (Sₜ, θ, C, R) → (Sₜ₊₁, E, D)
```

方法必须由技能库中已经准入的函数组成，不能直接调用未声明设备能力。

## 输入

方法生成输入包括：

```text theme={null}
用户实验需求
研究对象和当前状态
容器与样品状态
合格设备技能库
函数式技能签名
参数和状态约束
```

### 输入示例

```json theme={null}
{
  "requirement": {
    "name": "两份样品加液并进行紫外可见光谱表征",
    "goal": "分别制备试剂A和试剂B样品，获得200至800nm光谱"
  },
  "research_objects": [
    {
      "object_id": "sample-1",
      "container_type": "离心瓶",
      "container_id": 1,
      "container_status": "有盖",
      "sample_status": "空"
    },
    {
      "object_id": "sample-2",
      "container_type": "离心瓶",
      "container_id": 2,
      "container_status": "有盖",
      "sample_status": "空"
    }
  ],
  "required_functions": [
    "open_caps",
    "add_liquid_with_material",
    "close_caps",
    "uv_vis_spectrum_test"
  ],
  "constraints": {
    "container_count": 2,
    "single_transfer_max_mL": 1.0,
    "single_solution_total_max_mL": 3.0
  },
  "capability_revisions": {
    "2002186824385539": "12",
    "1664783667397632": "5"
  }
}
```

| 输入字段                   | 作用                       |
| ---------------------- | ------------------------ |
| `requirement`          | 描述方法要实现的实验目标，不直接指定底层设备调用 |
| `research_objects[]`   | 提供每个研究对象的标识、容器和初始样品状态    |
| `required_functions[]` | 表达目标所需函数，用于查询合格设备技能库     |
| `constraints`          | 汇总本次方法必须遵守的已知参数和物理限制     |
| `capability_revisions` | 固定生成、仿真和绑定使用的设备能力版本      |

## 生成实现逻辑

函数式方法生成器把实验目标转换为已准入函数的调用图，而不是直接产生不可检查的自然语言步骤。其最小实现逻辑为：

1. 根据研究对象、容器状态和目标查询合格设备技能库，只选择来源修订号一致的函数；
2. 为每个函数填入已声明参数，按类型、单位、范围、枚举和跨参数约束构造实参；
3. 依据前置条件和状态变化连接调用顺序：一个操作的输出状态必须满足下一操作的前置状态；
4. 将顺序、条件、并行或有限重复写为可解析的调用结构，并固定本次使用的设备与能力版本；
5. 生成候选方法和其依赖清单，交给验证阶段；生成阶段本身不提交任何对象状态。

```text theme={null}
实验目标与初始状态
  → 查询已准入函数
  → 参数实例化与约束检查
  → 用状态前后关系连接调用
  → 冻结版本快照
  → 候选方法
```

当找不到函数、参数无法满足约束或状态链无法连接时，生成器必须返回缺少的能力或冲突条件，不能用未注册函数补全方案。

## 代码式方法契约

代码式方法必须：

* 定义 `generate_recipe()` 入口；
* 使用设备命名空间调用物理能力；
* 从公共类型模块导入参数数据类；
* 循环中的设备调用显式展开；
* 在转换前完成优化和仿真。

```python theme={null}
def generate_recipe():
    Liquid_Handling_Station_1ml_V2.open_caps(
        container_type="离心瓶",
        container_count=2,
        container_ids=[1, 2],
        open_cap_bottle_ids=[
            OpenCapBottle(bottle_id=1),
            OpenCapBottle(bottle_id=2),
        ],
        keep_cap=1,
    )

    Liquid_Handling_Station_1ml_V2.add_liquid_with_material(
        container_type="离心瓶",
        container_count=2,
        container_ids=[1],
        dispensing_plan=[
            DispensingPlan(
                sample_bottle_id=1,
                source_bottle=SourceBottle(
                    ingredient_name="试剂A",
                    source_volume_mL=0.5,
                    source_bottle_id=1,
                ),
            )
        ],
    )
```

函数、参数结构和状态约束来自准入通过的函数式技能定义，不由方法生成器重新命名。

## 技能函数的完整信息

方法生成器在使用一个技能前，必须获得以下信息：

```text theme={null}
设备标识与命名空间
函数名称与 command_id
请求分类 request_class
对象、控制和系统三个完整维度
参数名称、类型、单位、范围、枚举、默认值和嵌套结构
前置容器、样品和系统状态
强制约束与注意事项
成功后的状态变化
返回字段与诊断
同步或异步执行模式
```

下列非规范性签名说明同一设备的三项技能如何进入方法生成环境：

```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:
    """要求容器有盖；成功后容器状态变为无盖。"""
    ...

def add_liquid_with_material(
    container_type: Literal["离心瓶", "50ml耐热瓶"],
    container_count: int,
    container_ids: list[int],
    dispensing_plan: list[DispensingPlan],
) -> StepResult:
    """要求容器无盖；校验瓶号、液量和总体积后更新样品状态。"""
    ...

def close_caps(
    container_type: Literal["离心瓶", "50ml耐热瓶"],
    container_count: int,
    container_ids: list[int],
    close_cap_bottle_ids: list[CloseCapBottle],
) -> StepResult:
    """要求容器无盖；成功后容器状态变为有盖。"""
    ...
```

这些签名只说明结构。类型中的容器枚举、数量范围、请求分类和强制约束必须来自对应完整技能版本。

## 方法组合

函数式实验方法支持以下组合能力：

* 顺序执行；
* 显式展开的有限重复；
* 条件选择；
* 并行分支与汇合；
* 受保护资源区间。

并行组合使用 `parallel_execution` 和 `branch`。循环必须显式展开，避免转换后产生无法解析的变量占位符。

## 转换输出

仿真通过后，方法转换器生成：

```text theme={null}
实验名称
plan_name
实验流程
涉及设备
path
steps
unknown_steps
```

`steps` 的字段固定为：

```text theme={null}
step_number
id
device_name
command_id
request_class
operation
parameters
```

完整输出见[执行](/specification/methods/execution)。

### 输出作用

| 输出     | 作用                                 |
| ------ | ---------------------------------- |
| 代码式方法  | 以 `generate_recipe()` 表达可计算的函数调用序列 |
| 仿真报告   | 证明函数、参数、状态链和版本快照通过机器检查             |
| 最终执行计划 | 将验证后的方法转换为设备、操作、参数和路径组成的 JSON      |