# 機能設計書 7-Summary エージェント

## 概要

本ドキュメントは、OpenCodeシステムにおけるSummary エージェントの機能設計を記述する。Summary エージェントは、セッション要約生成用の内部エージェントであり、会話内容をプルリクエストの説明のような形式で簡潔にまとめる。

### 本機能の処理概要

Summary エージェントは、セッション共有時やセッション終了時に呼び出され、会話で行われた作業内容を2-3文で簡潔に要約する。この要約は、セッション共有やセッション一覧での概要表示に使用される。

**業務上の目的・背景**：長時間のセッションや複雑な作業を行った後、その内容を他者に共有したり、後から振り返ったりする際に、簡潔な要約があると便利である。Summary エージェントは、会話全体を分析し、主要な変更点や作業内容を抽出して要約を生成する。

**機能の利用シーン**：セッション共有機能を使用する際、または作業完了後のセッション概要生成時に自動実行される。

**主要な処理内容**：
1. 会話履歴の分析
2. 主要な変更内容の抽出
3. プルリクエスト形式の要約生成（2-3文）
4. セッションへの要約保存

**関連システム・外部連携**：セッション共有機能（Session.share）と連携し、共有時の説明文として使用される。

**権限による制御**：Summary エージェントは、内部エージェントとして全ツール使用が禁止（*: deny）されている。テキスト生成のみを行う。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | シェアレイアウト | 補助機能 | セッション共有時の要約表示 |
| 23 | シェア詳細 | 補助機能 | 共有セッションの要約表示 |

## 機能種別

自動要約生成 / テキスト生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | エージェント名（"summary"固定） | 文字列型 |
| mode | "primary" | Yes | エージェントのモード | enum値 |
| native | boolean | Yes | ネイティブエージェントかどうか（true） | boolean型 |
| hidden | boolean | Yes | 非表示フラグ（true） | boolean型 |
| prompt | string | Yes | 要約生成用システムプロンプト（PROMPT_SUMMARY） | 任意の文字列 |
| permission | PermissionNext.Ruleset | Yes | 権限ルールセット（全ツールdeny） | 有効なルールセット配列 |

### 入力データソース

- セッションの会話履歴
- 実行されたツールと結果

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| summary | string | 生成された要約（2-3文） |

### 出力先

- セッションデータベース（summaryフィールド）

## 処理フロー

### 処理シーケンス

```
1. 要約要求の受信
   └─ セッション共有または要約生成トリガー
2. 会話履歴の分析
   └─ 全メッセージとツール結果の収集
3. 要約生成
   └─ PROMPT_SUMMARYに基づきLLMで要約生成
4. 要約保存
   └─ セッションに要約を設定
```

### フローチャート

```mermaid
flowchart TD
    A[要約要求] --> B[会話履歴収集]
    B --> C[変更内容分析]
    C --> D[Summaryエージェント実行]
    D --> E[要約生成]
    E --> F{2-3文以内?}
    F -->|Yes| G[要約保存]
    F -->|No| H[要約短縮]
    H --> G
    G --> I[完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 文量制限 | 要約は2-3文以内 | 常時 |
| BR-02 | 変更記述 | プロセスではなく変更内容を記述 | 常時 |
| BR-03 | 一人称使用 | "I added...", "I fixed..."のように一人称で記述 | 常時 |
| BR-04 | 検証省略 | テスト実行やビルド等の検証ステップは言及しない | 常時 |
| BR-05 | 要求省略 | ユーザーの要求内容は説明しない | 常時 |
| BR-06 | 質問保持 | 会話が未回答の質問で終わる場合はその質問を保持 | 質問終了時 |
| BR-07 | 命令保持 | 会話が命令文で終わる場合はその命令を含める | 命令終了時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 要約保存 | session | UPDATE | summaryフィールドの更新 |

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

#### session

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | summary | 生成された要約 | 2-3文 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 要約生成失敗 | LLM APIエラー | デフォルト要約使用 |

### リトライ仕様

要約生成は非クリティカルなため、エラー時はデフォルト要約で継続。

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

要約保存は単一のUPDATE操作。

## パフォーマンス要件

- 要約生成はバックグラウンドで非同期実行可能
- 共有操作時は同期的に実行

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

- 全ツールが禁止されており、ファイル操作等の副作用なし
- 共有時の要約にセンシティブな情報が含まれないよう注意

## 備考

Summary エージェントは、hiddenフラグがtrueのため、ユーザーからは直接選択できない。プルリクエストの説明文のような形式で、作業内容を簡潔にまとめる。

---

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

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

### 推奨読解順序

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

Summaryエージェントの設定と専用プロンプトを理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | agent.ts | `packages/opencode/src/agent/agent.ts` | summaryエージェント定義（188-202行目） |
| 1-2 | summary.txt | `packages/opencode/src/agent/prompt/summary.txt` | 要約生成用システムプロンプト |

**読解のコツ**: PROMPT_SUMMARYの内容を見ると、プルリクエスト形式の要約を生成することが明確になる。

#### Step 2: システムプロンプトを理解する

要約生成のルールとガイドラインを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | summary.txt | `packages/opencode/src/agent/prompt/summary.txt` | 要約生成ルールの詳細 |

**主要処理フロー**:
1. **1行目**: "Summarize what was done"というタスク定義
2. **3-4行目**: 2-3文以内の制限
3. **5行目**: 変更内容を記述（プロセスではなく）
4. **6行目**: テスト/ビルド等の検証ステップは言及しない
5. **7行目**: ユーザーの要求は説明しない
6. **8行目**: 一人称（I added..., I fixed...）で記述

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

```
Session.share() または SessionSummary [session/summary.ts]
    │
    └─ 要約生成が必要な場合
           │
           ├─ Agent.get("summary") [agent.ts]
           │      └─ Summaryエージェント設定取得
           │
           └─ LLM呼び出し
                  │
                  ├─ PROMPT_SUMMARY適用
                  │
                  └─ 要約生成
                         │
                         └─ session.summary保存
```

### データフロー図

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

会話履歴 ───▶ Summaryエージェント
    │                     │
    ├─ メッセージ         ├──▶ 変更内容分析
    │                     │
    └─ ツール結果         ├──▶ 要約生成
                          │        │
                          │        └─ 2-3文に制限
                          │
                          └──▶ セッション更新
                                    │
                                    └──▶ session.summary
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| agent.ts | `packages/opencode/src/agent/agent.ts` | ソース | Summaryエージェント定義（188-202行目） |
| summary.txt | `packages/opencode/src/agent/prompt/summary.txt` | テンプレート | 要約生成用システムプロンプト |
| summary.ts | `packages/opencode/src/session/summary.ts` | ソース | SessionSummary名前空間 |
| index.ts | `packages/opencode/src/session/index.ts` | ソース | Session.share()実装 |
