# Miyabi A2A - UI/UX 改善提案書

**作成日**: 2025-10-21
**作成者**: Claude Code (UI担当Agent)
**対象**: Miyabi A2A Protocol v0.3.0 Live Interface

---

## 📊 現状分析

### 現在の実装 (v1.0 - 基本版)

**実装済み機能**:
- ✅ REST API テスト用インターフェース
- ✅ Message送信 → Task作成
- ✅ Taskリスト表示・詳細・キャンセル
- ✅ Agent Card閲覧

**現状の課題**:
- ❌ リアルタイム性がない（手動リフレッシュ必要）
- ❌ Agent間の連携が見えない
- ❌ Task依存関係（DAG）が可視化されていない
- ❌ ワークフロー全体の進行状況が不明
- ❌ エラー・警告が埋もれやすい
- ❌ デバッグ情報へのアクセスが困難

---

## 🎯 理想的なUI/UX像

### コンセプト: **"オーケストラの指揮者視点"**

Miyabi A2Aは複数のAgentが協調して動作する自律型システム。
ユーザーは**指揮者**として、各Agentの動きを俯瞰し、必要に応じて介入できるべき。

---

## 🚀 提案: 段階的UI進化プラン

### Phase 1: リアルタイム監視ダッシュボード (優先度: 🔥 High)

**目的**: システム全体の"今"を一目で把握

#### 1.1 Live Dashboard

```
┌─────────────────────────────────────────────────────────┐
│ 🎛️ Miyabi A2A - Live Dashboard                         │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  System Health: ✅ Healthy    Active Tasks: 5           │
│  Active Agents: 3/7           Queued: 2                 │
│                                                          │
│  ┌────────────────┐  ┌────────────────┐               │
│  │ 🟢 しきるん      │  │ 🟢 つくるん      │               │
│  │ Coordinator    │  │ CodeGen        │               │
│  │ Status: Active │  │ Status: Working│               │
│  │ Tasks: 2       │  │ Tasks: 1       │               │
│  └────────────────┘  └────────────────┘               │
│                                                          │
│  📊 Task Throughput: 12 tasks/hour                     │
│  ⏱️ Avg Completion Time: 5.2 minutes                   │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

**技術実装**:
- WebSocket接続 or Server-Sent Events (SSE)
- リアルタイムTask状態更新
- Agent稼働状況のハートビート
- メトリクス自動更新（5秒間隔）

**Rust側の変更**:
```rust
// crates/miyabi-a2a/src/streaming/manager.rs に実装済み
// SSEエンドポイントを活用
GET /v1/events/stream → SSEストリーム
```

---

#### 1.2 Event Timeline (イベントタイムライン)

```
┌─────────────────────────────────────────────────────────┐
│ 📜 Recent Events (Last 50)                              │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  12:34:56  🟢 Task #abc123 created                      │
│  12:35:01  🔵 しきるん assigned to Task #abc123          │
│  12:35:05  🟡 Task #abc123 → Working                    │
│  12:35:12  🟢 つくるん started execution                 │
│  12:36:45  🟢 Task #abc123 → Completed ✅               │
│  12:36:46  🔵 めだまん reviewing code...                 │
│                                                          │
│  [ Load More ] [ Export Log ]                           │
└─────────────────────────────────────────────────────────┘
```

**UI要素**:
- アイコン + 色分けで視認性向上
- クリックで詳細ポップアップ
- フィルター機能（Agent別、Task別、Error only）
- Export to JSON/CSV

**実装優先度**: 🔥🔥🔥 Critical

---

### Phase 2: Workflow可視化 (優先度: 🔥 High)

#### 2.1 DAG Visualizer (タスク依存関係グラフ)

```
┌─────────────────────────────────────────────────────────┐
│ 🔀 Workflow DAG - Issue #270                            │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   [Task A: Parse Spec] ──┐                             │
│            ✅             │                             │
│                          ├──▶ [Task C: Generate Code]  │
│   [Task B: Extract Data] ─┘        🔄 (Working)        │
│            ✅                       │                   │
│                                     │                   │
│                                     ▼                   │
│                            [Task D: Run Tests]          │
│                                 ⏸️ (Waiting)            │
│                                                          │
│  Legend: ✅ Completed  🔄 Working  ⏸️ Waiting  ❌ Failed │
└─────────────────────────────────────────────────────────┘
```

**技術スタック**:
- **D3.js** or **Cytoscape.js** (グラフ可視化)
- ドラッグ可能なノード配置
- ズーム・パン操作
- ノードクリックで詳細表示

**データソース**:
```json
// GET /v1/workflows/{workflowId}/dag
{
  "nodes": [
    {
      "id": "task-a",
      "label": "Parse Spec",
      "status": "completed",
      "agent": "CoordinatorAgent"
    }
  ],
  "edges": [
    {
      "from": "task-a",
      "to": "task-c",
      "type": "depends_on"
    }
  ]
}
```

**実装優先度**: 🔥🔥 High

---

#### 2.2 Agent Collaboration View (Agent連携ビュー)

```
┌─────────────────────────────────────────────────────────┐
│ 🤝 Agent Collaboration - Real-time                      │
├─────────────────────────────────────────────────────────┤
│                                                          │
│      [User]                                             │
│        │ Message                                         │
│        ▼                                                │
│   🔴 しきるん (Coordinator)                              │
│        │ Task Decomposition                             │
│        ├──────┬──────┬──────┐                          │
│        ▼      ▼      ▼      ▼                          │
│     🟢つくるん 🟢めだまん 🟡まとめるん 🟡はこぶん           │
│     CodeGen  Review  Docs   Deploy                     │
│        │      │      │      │                          │
│        └──────┴──────┴──────┘                          │
│                │                                         │
│                ▼                                        │
│            [User] ✅ Result                             │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

**アニメーション**:
- データフローを矢印で表現
- アクティブなAgentが脈動（pulse animation）
- 完了したAgentにチェックマーク

**実装優先度**: 🔥 Medium

---

### Phase 3: デバッグ・トラブルシューティング (優先度: 🔥 High)

#### 3.1 Error Dashboard

```
┌─────────────────────────────────────────────────────────┐
│ ⚠️ Errors & Warnings                                    │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  🔴 CRITICAL (1)                                        │
│    ├─ Task #xyz789 failed: API timeout                 │
│    │  Agent: DeploymentAgent                           │
│    │  Time: 12:40:15                                   │
│    └─ [View Details] [Retry] [Cancel Workflow]        │
│                                                          │
│  🟡 WARNING (3)                                         │
│    ├─ Task #abc123 slow response (>2min)               │
│    ├─ Agent めだまん high memory usage (85%)            │
│    └─ Rate limit approaching (80/100 req/min)          │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

**通知機能**:
- ブラウザ通知 (Notifications API)
- 音声アラート（重大エラー時）
- Slackウェブフック連携（オプション）

**実装優先度**: 🔥🔥🔥 Critical

---

#### 3.2 Detailed Logs Viewer

```
┌─────────────────────────────────────────────────────────┐
│ 📝 Task Logs - #abc123                                  │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  [INFO]  12:35:01  Task created by user                │
│  [DEBUG] 12:35:02  Assigned to CoordinatorAgent        │
│  [INFO]  12:35:05  Status: submitted → working         │
│  [DEBUG] 12:35:10  Executing task decomposition...     │
│  [WARN]  12:35:15  Dependency resolution took 5s       │
│  [INFO]  12:36:45  Task completed successfully         │
│                                                          │
│  Filters: [ All ] [ ERROR ] [ WARN ] [ INFO ] [ DEBUG ]│
│  Download: [ JSON ] [ CSV ] [ Text ]                   │
└─────────────────────────────────────────────────────────┘
```

**機能**:
- ログレベルフィルター
- 検索機能（正規表現対応）
- シンタックスハイライト
- タイムスタンプでソート

**実装優先度**: 🔥 Medium

---

### Phase 4: 高度な操作・制御 (優先度: 🟡 Medium)

#### 4.1 Interactive Control Panel

```
┌─────────────────────────────────────────────────────────┐
│ 🎛️ System Controls                                      │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  🔄 Auto-refresh: [ON] [OFF]    Interval: [5s] ▼       │
│                                                          │
│  🚦 Agent Management:                                   │
│    ├─ [Pause All]  [Resume All]                        │
│    ├─ [Restart Agent] ▼                                │
│    └─ [Enable/Disable Agent] ▼                         │
│                                                          │
│  🔧 Advanced:                                           │
│    ├─ [Clear Task Queue]                               │
│    ├─ [Export System State]                            │
│    └─ [Import Workflow]                                │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

**安全機能**:
- 危険な操作には確認ダイアログ
- 操作ログの記録
- ロールベースアクセス制御 (RBAC)

**実装優先度**: 🟡 Medium

---

#### 4.2 Workflow Builder (ワークフロービルダー)

```
┌─────────────────────────────────────────────────────────┐
│ 🛠️ Workflow Builder                                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Drag & Drop Agents:                                    │
│  ┌────────────────────────────────────────────────┐    │
│  │  📦 Agent Palette                              │    │
│  │  ├─ 🔴 しきるん (Coordinator)                   │    │
│  │  ├─ 🟢 つくるん (CodeGen)                      │    │
│  │  ├─ 🟢 めだまん (Review)                       │    │
│  │  └─ 🟡 はこぶん (Deploy)                       │    │
│  └────────────────────────────────────────────────┘    │
│                                                          │
│  Canvas:                                                │
│  ┌────────────────────────────────────────────────┐    │
│  │                                                 │    │
│  │   [Start] ─▶ [しきるん] ─┬─▶ [つくるん]         │    │
│  │                          └─▶ [めだまん]         │    │
│  │                                                 │    │
│  └────────────────────────────────────────────────┘    │
│                                                          │
│  [Save Workflow] [Run] [Test]                          │
└─────────────────────────────────────────────────────────┘
```

**用途**:
- カスタムワークフロー定義
- A/Bテスト用の複数パターン作成
- 繰り返しタスクの自動化

**実装優先度**: 🟡 Low (将来機能)

---

## 🎨 デザインシステム

### カラーパレット

```css
/* Primary Colors */
--miyabi-primary: #6366f1;      /* 紫 - メインアクション */
--miyabi-success: #10b981;      /* 緑 - 成功・完了 */
--miyabi-warning: #f59e0b;      /* 橙 - 警告・待機 */
--miyabi-error: #ef4444;        /* 赤 - エラー・失敗 */
--miyabi-info: #3b82f6;         /* 青 - 情報 */

/* Agent Colors */
--agent-leader: #ef4444;        /* 🔴 リーダー (しきるん) */
--agent-executor: #10b981;      /* 🟢 実行役 (つくるん, めだまん) */
--agent-analyst: #3b82f6;       /* 🔵 分析役 (みつけるん) */
--agent-support: #f59e0b;       /* 🟡 サポート役 (まとめるん) */

/* Task Status Colors */
--status-submitted: #94a3b8;    /* グレー */
--status-working: #6366f1;      /* 紫 */
--status-completed: #10b981;    /* 緑 */
--status-failed: #ef4444;       /* 赤 */
--status-cancelled: #64748b;    /* ダークグレー */
```

### タイポグラフィ

```css
/* Font Stack */
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI',
             'Noto Sans JP', 'Helvetica Neue', Arial, sans-serif;

/* Font Sizes */
--text-xs: 0.75rem;   /* 12px - メタ情報 */
--text-sm: 0.875rem;  /* 14px - 補足テキスト */
--text-base: 1rem;    /* 16px - 本文 */
--text-lg: 1.125rem;  /* 18px - 小見出し */
--text-xl: 1.25rem;   /* 20px - 見出し */
--text-2xl: 1.5rem;   /* 24px - 大見出し */
```

---

## 📱 レスポンシブ対応

### ブレークポイント

```css
/* Mobile First */
--breakpoint-sm: 640px;   /* タブレット縦 */
--breakpoint-md: 768px;   /* タブレット横 */
--breakpoint-lg: 1024px;  /* ノートPC */
--breakpoint-xl: 1280px;  /* デスクトップ */
```

### レイアウト戦略

- **Mobile (< 640px)**: 単一カラム、タブ切り替え
- **Tablet (640-1024px)**: 2カラム、サイドバー折りたたみ
- **Desktop (> 1024px)**: 3カラム、全機能表示

---

## 🔧 技術スタック推奨

### フロントエンド

| 用途 | 推奨技術 | 理由 |
|------|---------|------|
| **UIフレームワーク** | React 18 or Vue 3 | 複雑な状態管理・リアルタイム更新 |
| **グラフ可視化** | Cytoscape.js | DAG表示に最適、軽量 |
| **リアルタイム通信** | Server-Sent Events (SSE) | 実装済み (`/v1/events/stream`) |
| **スタイリング** | Tailwind CSS | 高速開発、カスタマイズ容易 |
| **状態管理** | Zustand (React) / Pinia (Vue) | 軽量、学習コスト低 |
| **チャート** | Chart.js or Apache ECharts | メトリクス表示 |

### バックエンド追加API

```rust
// 必要な追加エンドポイント

// 1. DAG取得
GET /v1/workflows/{workflow_id}/dag
Response: { nodes: [...], edges: [...] }

// 2. リアルタイムイベントストリーム (実装済み)
GET /v1/events/stream
Response: Server-Sent Events

// 3. Agent状態取得
GET /v1/agents
Response: [{ id, name, status, current_task, health }]

// 4. メトリクス取得
GET /v1/metrics
Response: { tasks_per_hour, avg_completion_time, active_agents }

// 5. ログ取得
GET /v1/tasks/{task_id}/logs
Response: [{ level, timestamp, message }]
```

---

## 🚀 実装ロードマップ

### Sprint 1 (2週間) - リアルタイム監視基盤

- [x] SSEエンドポイント (`/v1/events/stream`) - **実装済み**
- [ ] Live Dashboard UI作成
- [ ] Event Timeline実装
- [ ] Auto-refresh機能

**成果物**: リアルタイムでTask状態が更新されるダッシュボード

---

### Sprint 2 (2週間) - Workflow可視化

- [ ] DAG Visualizer実装 (Cytoscape.js)
- [ ] GET /v1/workflows/{id}/dag エンドポイント追加
- [ ] Agent Collaboration View実装
- [ ] ノードクリックで詳細表示

**成果物**: Task依存関係を視覚的に理解できるグラフUI

---

### Sprint 3 (1週間) - デバッグ機能

- [ ] Error Dashboard実装
- [ ] GET /v1/tasks/{id}/logs エンドポイント追加
- [ ] Log Viewer実装
- [ ] ブラウザ通知機能

**成果物**: エラー追跡とデバッグが容易になるツール

---

### Sprint 4 (1週間) - 制御機能

- [ ] Control Panel実装
- [ ] Agent管理API (`POST /v1/agents/{id}/pause`)
- [ ] Task Queue管理機能
- [ ] System State Export

**成果物**: Agentとタスクを手動制御できる管理画面

---

### Sprint 5 (将来) - 高度な機能

- [ ] Workflow Builder (Drag & Drop)
- [ ] カスタムワークフロー保存
- [ ] A/Bテスト機能
- [ ] Slack/Discord連携

**成果物**: コードレスでワークフロー構築可能なビルダー

---

## 📊 成功指標 (KPI)

| 指標 | 目標 | 測定方法 |
|------|------|---------|
| **タスク可視性** | ユーザーが全タスクの状態を5秒以内に把握 | ユーザーテスト |
| **エラー検出時間** | エラー発生から検知まで10秒以内 | システムメトリクス |
| **操作レスポンス** | ボタンクリックから反応まで200ms以内 | パフォーマンステスト |
| **学習コスト** | 初めてのユーザーが基本操作を30分で習得 | ユーザーテスト |
| **ダウンタイム削減** | デバッグ時間を50%削減 | ビフォーアフター比較 |

---

## 🎯 まとめ

### 現在の実装 (v1.0)
✅ **基本的なAPI Testing UI** - 動作確認可能

### 推奨される進化パス

```
v1.0 (Current)
  │
  ├─ Sprint 1: リアルタイム監視 ─┐
  │                            │
  ├─ Sprint 2: Workflow可視化  ├─▶ v2.0 (Production Ready)
  │                            │
  └─ Sprint 3: デバッグ機能 ────┘

  └─ Sprint 4: 制御機能 ───────▶ v3.0 (Advanced)

  └─ Sprint 5: Workflow Builder ─▶ v4.0 (Enterprise)
```

### 最優先で実装すべき機能 (Top 3)

1. **🔥 Live Dashboard** - システムの"今"を可視化
2. **🔥 Event Timeline** - 何が起きたかを追跡
3. **🔥 Error Dashboard** - 問題を即座に発見・対処

これらを実装すれば、Miyabi A2Aの運用性が**劇的に向上**します。

---

**次のアクション**: Sprint 1の実装を開始しますか？

```bash
# 次のステップ
cargo run --example ui_server_v2  # 新バージョンUI起動
```

---

**作成者**: Claude Code (UI担当Agent)
**連絡先**: miyabi-dev-team@example.com
**最終更新**: 2025-10-21
