# 機能設計書 19-CodeSearch ツール

## 概要

本ドキュメントは、OpenCodeのCodeSearch ツール機能の設計仕様を定義する。CodeSearch ツールは、Exa AIのMCP APIを使用してプログラミング関連のコンテキスト（コード例、ドキュメント、API リファレンス）を検索する機能を担う。

### 本機能の処理概要

CodeSearch ツールは、指定されたクエリでプログラミング関連の情報を検索し、コードスニペット、ドキュメント、APIリファレンスなどを取得する機能である。ライブラリ、SDK、APIに関する最新かつ高品質なコンテキストを提供する。

**業務上の目的・背景**：AIエージェントがプログラミングタスクを支援する際、最新のライブラリドキュメントやコード例にアクセスすることで、より正確で実用的な回答を提供できる。本ツールにより、エージェントは特定のフレームワークやライブラリの使用方法を調査できる。

**機能の利用シーン**：
- React、Vue等のフレームワークのフック使用例検索
- ライブラリのAPI使用方法検索
- 特定のプログラミングパターンの検索
- エラー解決のためのコード例検索
- SDK統合方法の調査

**主要な処理内容**：
1. 検索権限の確認
2. MCPリクエストの構築
3. Exa AI APIへのリクエスト送信
4. SSEレスポンスの解析
5. 検索結果の返却

**関連システム・外部連携**：
- Exa AI MCP API（https://mcp.exa.ai/mcp）：コード検索エンジン

**権限による制御**：
- `codesearch`権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 直接的な画面関連なし |

## 機能種別

外部API連携 / コード検索

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| query | string | Yes | 検索クエリ（ライブラリ、SDK、API関連） | 空文字列不可 |
| tokensNum | number | No | 返却するトークン数（デフォルト: 5000、範囲: 1000-50000） | 1000以上50000以下 |

### 入力データソース

- ユーザー入力（検索クエリ）
- 実行コンテキスト（セッションID、メッセージID等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| title | string | "Code search: {クエリ}" |
| output | string | 検索結果のテキスト内容 |
| metadata | object | 空オブジェクト |

### 出力先

- エージェントへのレスポンス（ツール実行結果）

## 処理フロー

### 処理シーケンス

```
1. コード検索権限確認
   └─ ctx.askでcodesearch権限を要求

2. MCPリクエスト構築
   └─ JSON-RPC 2.0形式でリクエストを構築

3. タイムアウト設定
   └─ 30秒のタイムアウトを設定

4. Exa AI APIリクエスト
   └─ POSTリクエストを送信

5. レスポンス解析
   └─ SSE形式のレスポンスを解析

6. 結果返却
   └─ 検索結果または"No results"メッセージを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[コード検索権限確認]
    B --> C[MCPリクエスト構築]
    C --> D[タイムアウト設定 30秒]
    D --> E[Exa AI APIリクエスト]
    E --> F{レスポンスOK?}
    F -->|No| ERROR1[エラー: Code search error]
    F -->|Yes| G[SSEレスポンス解析]
    G --> H{結果あり?}
    H -->|Yes| I[検索結果返却]
    H -->|No| J[No results返却]
    I --> OUTPUT[結果返却]
    J --> OUTPUT

    E -->|タイムアウト| ERROR2[エラー: Code search request timed out]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | デフォルトトークン数 | トークン数はデフォルト5000 | tokensNum未指定時 |
| BR-02 | トークン数下限 | 最小トークン数は1000 | 常時 |
| BR-03 | トークン数上限 | 最大トークン数は50000 | 常時 |
| BR-04 | タイムアウト | リクエストは30秒でタイムアウト | 常時 |

### 計算ロジック

**MCPリクエスト構築**：
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_code_context_exa",
    "arguments": {
      "query": "<検索クエリ>",
      "tokensNum": 5000
    }
  }
}
```

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

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

本機能は外部APIとの通信のみを行い、データベースへの直接的な操作は行わない。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | TimeoutError | 30秒以内にレスポンスがない | クエリを簡潔にする、再試行する |
| - | APIError | Exa AI APIがエラーを返却 | クエリを修正する、時間をおいて再試行 |
| - | PermissionError | codesearch権限がない | 適切な権限を付与 |

### リトライ仕様

本機能はリトライ処理を行わない。エラー発生時は即座にエラーを返却する。

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

外部API通信のため、トランザクション管理は行わない。

## パフォーマンス要件

- タイムアウト: 30秒
- AbortSignalによるキャンセル対応

## セキュリティ考慮事項

- codesearch権限による実行制御
- 外部APIへの通信はHTTPSで暗号化

## 備考

- WebSearch ツールとは異なり、プログラミングに特化した検索結果を返却
- トークン数を調整することで、簡潔な回答から詳細なドキュメントまで取得可能
- クエリ例: 'React useState hook examples', 'Python pandas dataframe filtering', 'Express.js middleware'

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

ツールの入出力パラメータとAPIリクエスト/レスポンスの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | codesearch.ts | `packages/opencode/src/tool/codesearch.ts` | McpCodeRequest型（13-24行目）とMcpCodeResponse型（26-34行目）を確認 |

**読解のコツ**: JSON-RPC 2.0形式のMCPプロトコルを使用。toolsのnameが"get_code_context_exa"であることに注目。WebSearchとはツール名が異なる。

#### Step 2: エントリーポイントを理解する

CodeSearch ツールの本体実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | codesearch.ts | `packages/opencode/src/tool/codesearch.ts` | execute関数の全体フロー（53-131行目） |

**主要処理フロー**:
1. **36-52行目**: パラメータスキーマ定義（query, tokensNum）
2. **54-62行目**: 権限確認
3. **64-75行目**: MCPリクエスト構築
4. **77行目**: 30秒タイムアウト設定
5. **79-90行目**: APIリクエスト送信
6. **99-114行目**: SSEレスポンス解析
7. **116-130行目**: 結果返却またはエラーハンドリング

### プログラム呼び出し階層図

```
CodeSearchTool.execute
    │
    ├─ ctx.ask (codesearch権限要求)
    │
    ├─ abortAfterAny (タイムアウト設定)
    │      └─ abortAfter (内部タイマー)
    │
    └─ fetch (Exa AI APIリクエスト)
           └─ SSEレスポンス解析
```

### データフロー図

```
[入力]                        [処理]                              [出力]

query ────────────────────▶ クエリ検証
                                │
tokensNum ────────────────────▶ MCPリクエスト構築
                                │
                                ▼
                           Exa AI API
                           (mcp.exa.ai)
                           get_code_context_exa
                                │
                                ▼
                           SSEレスポンス解析
                                │
                                ▼
                           結果返却 ─────────▶ title
                                              output
                                              metadata
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| codesearch.ts | `packages/opencode/src/tool/codesearch.ts` | ソース | CodeSearch ツール本体 |
| codesearch.txt | `packages/opencode/src/tool/codesearch.txt` | テンプレート | ツール説明文 |
| tool.ts | `packages/opencode/src/tool/tool.ts` | ソース | ツール基盤定義 |
| abort.ts | `packages/opencode/src/util/abort.ts` | ソース | タイムアウトユーティリティ |
