# 機能設計書 74-サジェスチョン

## 概要

本ドキュメントは、Windows Terminalにおけるサジェスチョン機能の設計を記述する。コマンド履歴・タスク・クイックフィックスなどの複数ソースからサジェスチョン（提案）を収集し、SuggestionsControlに表示する機能である。

### 本機能の処理概要

Suggestionsアクションは、ターミナルのコンテキスト情報（コマンド履歴、現在のコマンドライン、作業ディレクトリ）を元に、ユーザーに対してコマンドの提案を表示する機能である。複数のソース（コマンド履歴、タスク、クイックフィックス、すべてのアクション）を組み合わせて候補を生成する。

**業務上の目的・背景**：頻繁に使用するコマンドの再入力を省力化し、エラー時の修正候補を即座に提供することで開発者の生産性を向上させる。シェル統合機能と連携して、コンテキストに応じた適切な提案を行う。

**機能の利用シーン**：過去に実行したコマンドを素早く再利用したい場合、エラー発生後に修正コマンドを提案してほしい場合、定義済みのタスク（sendInputアクション）を実行したい場合に利用される。

**主要な処理内容**：
1. Suggestionsアクションの受信とソース種別の判定
2. TermControlからコンテキスト情報（コマンド履歴、現在のコマンドライン）の取得
3. 各ソースからのコマンド収集（非同期処理）
4. コマンド一覧の統合とSuggestionsControlへの表示
5. ユーザーの選択に基づくコマンドのディスパッチ

**関連システム・外部連携**：シェル統合（OSCシーケンス）、TermControl（コマンド履歴コンテキスト）との連携。

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleSuggestionsによりサジェスチョンパネルを表示 |
| 11 | SuggestionsControl（サジェスト） | 主画面 | コマンド履歴・タスク・クイックフィックスからの候補表示 |

## 機能種別

UI制御 / コマンド提案

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | SuggestionsSource | Yes | 提案ソースのフラグ（CommandHistory, Tasks, QuickFixes, All等） | フラグ型の有効な組み合わせであること |
| UseCommandline | bool | No | 現在のコマンドラインでフィルタリングするかどうか | - |

### 入力データソース

キーバインドまたはコマンドパレットからのアクション発行。TermControlからのコマンド履歴コンテキスト、settings.jsonのタスク定義。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Commands | IVector<Command> | 提案コマンド一覧 |
| FilterText | hstring | 初期フィルタテキスト（UseCommandline時は現在のコマンドライン） |

### 出力先

SuggestionsControl UI

## 処理フロー

### 処理シーケンス

```
1. Suggestionsアクション受信
   └─ _HandleSuggestionsハンドラが呼び出される
2. SuggestionsArgs の取得
   └─ Source（ソースフラグ）とUseCommandlineの判定
3. _doHandleSuggestions コルーチンの開始
   └─ 非同期でコンテキスト取得とコマンド収集
4. コンテキスト情報の取得
   └─ アクティブコントロールからCommandHistory()を取得
5. 各ソースからのコマンド収集
   └─ CommandHistory / Tasks / QuickFixes / Actions から候補を収集
6. SuggestionsControl への表示
   └─ Open()メソッドでコマンド一覧を設定し表示
```

### フローチャート

```mermaid
flowchart TD
    A[Suggestionsアクション受信] --> B[SuggestionsArgs取得]
    B --> C{shouldGetContext?}
    C -->|Yes| D[TermControlからコンテキスト取得]
    C -->|No| E[コンテキストなしで続行]
    D --> F[CommandHistory/CurrentCommandline取得]
    F --> G{Sourceフラグ判定}
    E --> G
    G -->|CommandHistory| H[コマンド履歴からCommand生成]
    G -->|Tasks| I[settings.jsonのタスクから取得]
    G -->|QuickFixes| J[QuickFixesからCommand生成]
    G -->|All| K[全アクションを取得]
    H --> L[コマンド一覧を統合]
    I --> L
    J --> L
    K --> L
    L --> M[SuggestionsControl.Open で表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-74-01 | コンテキスト取得条件 | UseCommandlineがtrue、またはCommandHistory/QuickFixesソースが指定された場合にコンテキストを取得 | shouldGetContextの計算 |
| BR-74-02 | 非同期処理 | コマンド収集は非同期コルーチンで行い、UIスレッドをブロックしない | _doHandleSuggestions |
| BR-74-03 | フィルタリング | UseCommandline指定時、現在のコマンドラインをフィルタテキストとして使用 | SuggestionsControl.Open呼び出し時 |
| BR-74-04 | ソース複合指定 | Sourceはフラグ型のため、複数ソースを同時指定可能 | WI_IsAnyFlagSetでフラグチェック |

### 計算ロジック

特になし。

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

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

本機能にデータベース操作はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ウィークリファレンス解決失敗 | コルーチン再開時にオブジェクトが破棄済み | co_return で処理を中止 |
| - | コンテキスト取得失敗 | アクティブコントロールが存在しない場合 | コンテキストなしで続行 |

### リトライ仕様

リトライは不要。

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

本機能にトランザクション処理はない。

## パフォーマンス要件

コンテキスト取得とコマンド収集はバックグラウンドスレッドで非同期実行される。UIへの表示はメインスレッドに復帰して行う。

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

コマンド履歴にはユーザーが入力した機密情報（パスワード等）が含まれる可能性がある。メモリ上での管理に注意。

## 備考

- QuickFixesソースはシェル統合と連携し、コマンド実行エラー時に自動的に修正候補（例: wingetコマンド）を生成する
- 「Tasks」ソースはsettings.jsonのsendInputアクションを候補として表示する
- SuggestionsControlはCommandPaletteと似たUIだが、コンテキスト依存の候補表示に特化している

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SuggestionsControl.h | `src/cascadia/TerminalApp/SuggestionsControl.h` | SuggestionsMode（74行目）、Open()メソッド（42-47行目）、FilteredActions |
| 1-2 | SuggestionsControl.idl | `src/cascadia/TerminalApp/SuggestionsControl.idl` | SuggestionsMode列挙型、SuggestionsDirection列挙型 |
| 1-3 | ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | SuggestionsArgs、SuggestionsSource フラグ定義 |

**読解のコツ**: SuggestionsSourceはフラグ型列挙で、WI_IsAnyFlagSetマクロで複数ソースの同時指定をチェックする。safe_void_coroutineはWinRTのコルーチンパターン。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | _HandleSuggestions（1447-1458行目）、_doHandleSuggestions（1460行目以降） |

**主要処理フロー**:
1. **1447-1458行目**: _HandleSuggestions - SuggestionsArgsのキャストと_doHandleSuggestions呼び出し
2. **1460行目**: _doHandleSuggestions コルーチン開始
3. **1464行目**: Source取得
4. **1474-1475行目**: shouldGetContext計算 - UseCommandlineまたはCommandHistory/QuickFixesソースの場合
5. **1476-1488行目**: アクティブコントロールからコンテキスト情報を取得

#### Step 3: SuggestionsControl UIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SuggestionsControl.cpp | `src/cascadia/TerminalApp/SuggestionsControl.cpp` | Open()メソッド、_dispatchCommand、QuickFixSuggestionUsedテレメトリ（736-745行目） |
| 3-2 | SuggestionsControl.xaml | `src/cascadia/TerminalApp/SuggestionsControl.xaml` | UIレイアウト定義 |

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

```
TerminalPage::_HandleSuggestions (AppActionHandlers.cpp:1447)
    │
    └─ TerminalPage::_doHandleSuggestions (AppActionHandlers.cpp:1460)
           │
           ├─ TermControl::CommandHistory() [コンテキスト取得]
           │      └─ CommandHistoryContext (currentCommandline, quickFixes)
           │
           ├─ コマンド収集（ソース別）
           │      ├─ CommandHistory → sendInput Command生成
           │      ├─ Tasks → settings.json のタスク取得
           │      ├─ QuickFixes → キャッシュ済みクイックフィックス
           │      └─ All → ActionMapから全アクション取得
           │
           └─ SuggestionsControl::Open(mode, commands, filterText, anchor, space, charHeight)
                  │
                  ├─ SetCommands()
                  ├─ _updateFilteredActions()
                  └─ Visibility(Visible)
```

### データフロー図

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

SuggestionsArgs ──────▶ _HandleSuggestions
(Source, UseCommandline)       │
                               ▼
TermControl ───────────▶ _doHandleSuggestions
(CommandHistory,               │
 CurrentCommandline,           ├─ CommandHistory取得
 QuickFixes)                   ├─ Tasks取得
                               ├─ QuickFixes取得
                               └─ Actions取得
                                      │
                                      ▼
                               SuggestionsControl ──▶ サジェスチョンUI
                               (commands, filterText)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | アクションハンドラと非同期コマンド収集 |
| SuggestionsControl.h | `src/cascadia/TerminalApp/SuggestionsControl.h` | ヘッダー | SuggestionsControlクラス定義 |
| SuggestionsControl.cpp | `src/cascadia/TerminalApp/SuggestionsControl.cpp` | ソース | サジェスチョンUI実装 |
| SuggestionsControl.xaml | `src/cascadia/TerminalApp/SuggestionsControl.xaml` | XAML | サジェスチョンUIレイアウト |
| SuggestionsControl.idl | `src/cascadia/TerminalApp/SuggestionsControl.idl` | IDL | WinRTインターフェース定義 |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース | SuggestionsElement管理 |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | CommandHistory()、QuickFixesAvailable() |
| ActionArgs.idl | `src/cascadia/TerminalSettingsModel/ActionArgs.idl` | IDL | SuggestionsArgs定義 |
