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

# キャプチャ

> ステップの実行結果から値を抽出・保存します。

## 概要

**キャプチャ**はステップの実行結果から値を抽出し、後続のステップで使用する変数として保存します。任意のステップに `captures` 配列を追加できます。

## 例

```yaml theme={null}
steps:
  - ordinal: 0
    description: "注文ページに遷移"
    action:
      type: navigate
      url: "https://app.example.com/orders/123"
    url: "https://app.example.com/orders/123"
    riskLevel: low
    requiresConfirmation: false
    captures:
      - name: orderId
        strategy: url
        pattern: "/orders/(\\d+)"
        group: 1
      - name: pageTitle
        strategy: snapshot
        description: "ページの見出しテキスト"
      - name: totalAmount
        strategy: ai
        prompt: "ページに表示されている注文合計金額は？"
```

## キャプチャフィールド

| フィールド         | 型               |  必須 | 説明                                          |
| ------------- | --------------- | :-: | ------------------------------------------- |
| `name`        | string          | Yes | キャプチャ値を格納する変数名                              |
| `strategy`    | CaptureStrategy | Yes | 抽出方法（下記参照）                                  |
| `description` | string          |  No | 人が読める説明                                     |
| `required`    | boolean         |  No | `true` の場合、キャプチャが空だとステップが失敗（デフォルト: `false`） |
| `pattern`     | string          |  No | テキスト抽出用の正規表現パターン                            |
| `group`       | integer         |  No | 正規表現キャプチャグループのインデックス（0始まり）                  |
| `prompt`      | string          |  No | `ai` 戦略での AI プロンプト                          |
| `expression`  | string          |  No | `expression` 戦略でのテンプレート式                    |

## キャプチャ戦略

### `snapshot`

現在のページ DOM から値をキャプチャします。`pattern` で部分文字列を抽出できます。

```yaml theme={null}
captures:
  - name: confirmationCode
    strategy: snapshot
    description: "送信後に表示される確認コード"
    pattern: "Code:\\s*(\\w+)"
    group: 1
```

### `url`

現在のページ URL から抽出します。

```yaml theme={null}
captures:
  - name: orderId
    strategy: url
    pattern: "/orders/(\\d+)"
    group: 1
```

### `ai`

AI を使ってページから値を抽出します。抽出対象を説明する `prompt` を指定します。

```yaml theme={null}
captures:
  - name: statusMessage
    strategy: ai
    prompt: "アラートバナーに表示されているステータスメッセージは？"
```

### `expression`

テンプレート式を評価します。キャプチャした値の変換や結合に便利です。

```yaml theme={null}
captures:
  - name: fullUrl
    strategy: expression
    expression: "https://app.example.com/orders/{{orderId}}"
```

### `evaluate`

ページコンテキストで JavaScript を実行し、結果をキャプチャします。

```yaml theme={null}
captures:
  - name: itemCount
    strategy: evaluate
    expression: "document.querySelectorAll('.item-row').length.toString()"
```

## キャプチャした値の使用

キャプチャした値は後続のステップでテンプレート変数として使用できます：

```yaml theme={null}
steps:
  - ordinal: 0
    description: "URL から注文 ID を抽出"
    action:
      type: navigate
      url: "https://app.example.com/orders/123"
    url: "https://app.example.com/orders/123"
    riskLevel: low
    requiresConfirmation: false
    captures:
      - name: orderId
        strategy: url
        pattern: "/orders/(\\d+)"
        group: 1
  - ordinal: 1
    description: "注文詳細に遷移"
    action:
      type: navigate
      url: "https://app.example.com/orders/{{orderId}}/details"
    url: "https://app.example.com/orders/{{orderId}}/details"
    riskLevel: low
    requiresConfirmation: false
```

## 正規表現パターン

`pattern` を使用する場合、値は有効な正規表現である必要があります。`group` で特定のキャプチャグループを選択できます：

* `group: 0` — マッチ全体（デフォルト）
* `group: 1` — 最初のキャプチャグループ
* `group: 2` — 2番目のキャプチャグループ

```yaml theme={null}
captures:
  - name: price
    strategy: snapshot
    pattern: "\\$([\\d,]+\\.\\d{2})"
    group: 1
    # "$1,234.56" から "1,234.56" をキャプチャ
```