# バッチ設計書 21-BatchTool

## 概要

本ドキュメントは、opencode CLIツールにおける複数ツール並列実行機能（BatchTool）の設計を記載したバッチ設計書です。

### 本バッチの処理概要

BatchToolは、複数の独立したツール呼び出しを並列に実行し、処理効率を大幅に向上させるための内部ツールです。AIエージェントがファイル読み取り、検索、コマンド実行などの複数操作を同時に行う際に、レイテンシを削減し、ユーザー体験を向上させます。

**業務上の目的・背景**：AIエージェントによるコード解析・編集作業では、複数のファイル読み取りやgrep検索、bash コマンド実行が頻繁に発生します。これらを逐次実行すると待ち時間が累積し、ユーザー体験が低下します。BatchToolは並列実行により2〜5倍の効率向上を実現し、応答性の高いインタラクティブな開発体験を提供します。

**バッチの実行タイミング**：AIエージェントが複数の独立したツール呼び出しを行う際にリアルタイムで実行されます。ユーザーからのプロンプトに応じて、エージェントが自動的にBatchToolを活用します。

**主要な処理内容**：
1. ツール呼び出し配列の受け取りと検証（最大25件）
2. 禁止ツール（batch自身）のフィルタリング
3. 各ツールの並列実行とSession状態の更新
4. 実行結果の集約と成功/失敗カウントの算出
5. 25件超過分のエラー処理

**前後の処理との関連**：AIエージェントのメッセージ処理フロー内で呼び出されます。ToolRegistryから利用可能なツール一覧を取得し、Session APIを通じて実行状態を管理します。

**影響範囲**：opencode CLIのツール実行システム全体に影響し、ファイル操作、検索、コマンド実行などあらゆる内部ツールの実行効率に関わります。

## バッチ種別

ツール実行オーケストレーション / 並列処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リアルタイム） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | AIエージェントによるツール呼び出し |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| セッション存在 | 有効なセッションIDとメッセージIDが必要 |
| ツールレジストリ | ToolRegistryが初期化されていること |
| ツール呼び出し配列 | 1件以上のツール呼び出しが含まれること |

### 実行可否判定

- tool_calls配列が空でないこと
- 各ツール呼び出しにtoolとparametersが含まれること
- zodスキーマによるパラメータ検証をパス

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| tool_calls | array | Yes | - | ツール呼び出しの配列（1-25件） |
| tool_calls[].tool | string | Yes | - | 実行するツール名 |
| tool_calls[].parameters | object | Yes | - | ツールに渡すパラメータ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| ToolRegistry | Runtime | 利用可能なツール一覧 |
| Session | Runtime | セッション・メッセージコンテキスト |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Session.Part | Runtime | 各ツール実行結果のパート情報 |
| 戻り値 | Object | 実行結果サマリー |

### 出力ファイル仕様

ファイル出力なし（ランタイム応答のみ）

| 項目 | 内容 |
|-----|------|
| ファイル名 | - |
| 出力先 | - |
| 文字コード | - |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ zodスキーマでtool_calls配列を検証
2. ツール呼び出しの分割
   └─ 先頭25件を処理対象、超過分は破棄リストへ
3. ToolRegistryからツール一覧取得
   └─ 利用可能なツールをMapに格納
4. 並列実行
   └─ Promise.allで全ツールを同時実行
   └─ 各ツールについて:
      - 禁止ツールチェック（batch自身を除外）
      - ツール存在チェック
      - パラメータ検証
      - Session.updatePartで実行開始を記録
      - tool.execute()実行
      - Session.updatePartで実行完了/エラーを記録
5. 超過分のエラー処理
   └─ 26件目以降をエラーとして記録
6. 結果集約
   └─ 成功/失敗件数をカウントして返却
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[パラメータ検証]
    B --> C{検証OK?}
    C -->|No| D[エラー返却]
    C -->|Yes| E[ツール呼び出し分割]
    E --> F[ToolRegistry取得]
    F --> G[Promise.all並列実行]
    G --> H{各ツール実行}
    H --> I{禁止ツール?}
    I -->|Yes| J[エラー記録]
    I -->|No| K{ツール存在?}
    K -->|No| J
    K -->|Yes| L[パラメータ検証]
    L --> M{検証OK?}
    M -->|No| J
    M -->|Yes| N[Session更新:running]
    N --> O[ツール実行]
    O --> P{成功?}
    P -->|Yes| Q[Session更新:completed]
    P -->|No| R[Session更新:error]
    Q --> S[結果集約]
    R --> S
    J --> S
    S --> T[超過分エラー処理]
    T --> U[サマリー返却]
    U --> V[バッチ終了]
    D --> V
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベースを直接操作しません。Session APIを経由して状態を管理します。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | - |

### テーブル別操作詳細

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 禁止ツールエラー | batchツール自身を呼び出した場合 | エラーを記録し他のツールは継続 |
| - | ツール不存在 | 指定ツールがレジストリにない場合 | エラーを記録し他のツールは継続 |
| - | パラメータ検証エラー | ツールパラメータが不正な場合 | エラーを記録し他のツールは継続 |
| - | 上限超過 | 26件以上のツール呼び出し | 超過分をエラーとして記録 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

- 個別ツールのエラーは他のツール実行に影響しない
- 部分的な失敗でも成功したツールの結果は返却
- エージェントがエラー内容を確認し必要に応じて再実行

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | ツール単位（各ツールは独立） |
| コミットタイミング | 各ツール実行完了時 |
| ロールバック条件 | 個別ツールのエラーでロールバックなし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1-25件/回 |
| 目標処理時間 | 最長ツールの実行時間に依存 |
| メモリ使用量上限 | 制限なし（ツール依存） |

## 排他制御

- 同一セッション内での複数BatchTool呼び出しは許可
- batch内でbatchを呼び出すことは禁止（DISALLOWED設定）
- 各ツールは独立して並列実行

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各ツール実行開始時 | Session.updatePart（status: running） |
| 進捗ログ | - | - |
| 終了ログ | 各ツール実行完了時 | Session.updatePart（status: completed） |
| エラーログ | エラー発生時 | Session.updatePart（status: error、エラーメッセージ） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| - | - | - |

## 備考

- 2-5倍の効率向上が期待できる
- 外部ツール（MCP、環境ツール）はバッチ実行不可（直接呼び出しが必要）
- FILTERED_FROM_SUGGESTIONSにはinvalid、patch、batchが含まれる
