機能仕様書: コンソール管理機能

[akiojin]

Spec

機能仕様書: コンソール管理機能

機能ID: SPEC-2e6d9a3b
作成日: 2025-10-17
ステータス: 完了
入力: Unity Consoleのログ読み取り、クリア、フィルタリング、自動クリア設定

実行フロー (main)

1. 入力からコンソール操作要件を解析
   → 操作タイプ（読み取り/クリア/設定変更）の特定
2. コンソールログの読み取り（読み取り操作時）
   → フィルタ条件（ログタイプ、テキスト、時間範囲）の適用
   → 件数、ソート順、出力形式の指定
   → グループ化オプション（タイプ/ファイル/時間別）
3. コンソールのクリア（クリア操作時）
   → 保護オプション（エラー/警告を保持）の適用
   → 自動クリア設定の更新（Play/Build/Recompile時）
4. ログのフォーマット
   → 出力形式（detailed/compact/json/plain）の適用
   → スタックトレースの含有制御
5. 結果の返却
   → フィルタ/グループ化されたログ情報
6. 戻り値: SUCCESS（ログ情報またはクリア結果）

---

⚡ クイックガイドライン

• ✅ デバッグログの効率的な管理とAIエージェントによるログ分析の必要性に焦点
• ❌ 内部的なUnityのログシステムやコンソールウィンドウの実装詳細は避ける
• 👥 ゲーム開発者・QAエンジニア・AIエージェント向けに記述

---

ユーザーシナリオ＆テスト

主要ユーザーストーリー

開発者として、デバッグ情報を効率的に確認するために、コンソールログをプログラムで読み取り・フィルタリングしたい。AIエージェントとして、エラーログを分析し、問題解決の提案をしたい。

受け入れシナリオ

1. 前提 コンソールにログが表示されている、実行 最新100件のログ取得、結果 最新100件のログが返される
2. 前提 エラーのみ確認したい、実行 ログタイプでフィルタ（Error）、結果 エラーログのみが返される
3. 前提 特定の文字列を含むログを探したい、実行 テキストフィルタを適用、結果 マッチするログのみが返される
4. 前提 特定時間以降のログを確認したい、実行 時間範囲フィルタを適用、結果 指定時間以降のログが返される
5. 前提 ログをタイプ別にグループ化したい、実行 groupBy=typeで読み取り、結果 タイプ別にグループ化されたログが返される
6. 前提 コンソールをクリアしたい、実行 クリア要求、結果 全ログがクリアされる
7. 前提 エラーは残してクリアしたい、実行 preserveErrors=trueでクリア、結果 エラー以外がクリアされる
8. 前提 Play時に自動クリアしたい、実行 clearOnPlay=trueで設定、結果 Play開始時に自動クリアされる

エッジケース

• ログが存在しない場合、何が返されるか? → 空の配列とログ数0を返す
• フィルタ条件にマッチするログがない場合、どう処理するか? → 空の結果とフィルタ条件の説明を返す
• スタックトレースを含むと大量のデータになる場合、どうなるか? → デフォルトではスタックトレースを含まない。必要な場合は明示的にincludeStackTrace=trueを指定する
• 自動クリア設定が競合する場合（保護とクリアの両方）、どう処理するか? → 保護が優先され、警告を返す
• コンソールが1000件以上のログを含む場合、パフォーマンスは? → 最大1000件に制限し、警告を返す

要件

機能要件

• FR-001: ユーザーはコンソールログを読み取ることができる必要がある
• FR-002: システムは取得するログの最大件数を指定できる必要がある（1-1000、デフォルト100）
• FR-003: ユーザーはログタイプ（Info/Warning/Error/All）でフィルタリングできる必要がある
• FR-004: ユーザーはテキスト検索（大文字小文字を区別しない）でフィルタリングできる必要がある
• FR-005: ユーザーは時間範囲（sinceTimestamp/untilTimestamp）でフィルタリングできる必要がある
• FR-006: システムはログのソート順（newest/oldest）を指定できる必要がある
• FR-007: システムは4種類の出力形式（detailed/compact/json/plain）をサポートする必要がある
• FR-008: ユーザーはスタックトレースの含有を制御できる必要がある
• FR-009: ユーザーはログをグループ化できる必要がある（none/type/file/time別）
• FR-010: ユーザーはコンソールをクリアできる必要がある
• FR-011: システムはクリア時にエラーを保護するオプションをサポートする必要がある
• FR-012: システムはクリア時に警告を保護するオプションをサポートする必要がある
• FR-013: ユーザーはPlay時の自動クリアを設定できる必要がある
• FR-014: ユーザーはBuild時の自動クリアを設定できる必要がある
• FR-015: ユーザーはRecompile時の自動クリアを設定できる必要がある

非機能要件

• NFR-001: ログ読み取りは2秒以内に完了する必要がある（1000件以下の場合）
• NFR-002: ログフィルタリングは1秒以内に完了する必要がある
• NFR-003: コンソールクリアは500ms以内に完了する必要がある
• NFR-004: グループ化処理は3秒以内に完了する必要がある（1000件以下の場合）
• NFR-005: 自動クリア設定の更新は100ms以内に完了する必要がある
• NFR-006: Unity MCP接続は標準運用時に受信コマンドをUnityコンソールへ逐次出力しない（ノイズ抑制と可読性を維持する）。

主要エンティティ

• ConsoleLog: ログメッセージ、タイプ、タイムスタンプ、ファイル、行番号、スタックトレースを含むログ情報
• LogFilter: ログタイプ、テキスト、時間範囲を含むフィルタ条件
• LogReadOptions: 件数、ソート順、出力形式、グループ化、スタックトレース含有を含む読み取りオプション
• ClearOptions: エラー保護、警告保護、自動クリア設定を含むクリアオプション
• LogGroup: グループ化キー、ログリスト、カウントを含むグループ情報

---

レビュー＆受け入れチェックリスト

コンテンツ品質

• 実装詳細なし（言語、フレームワーク、API）
• ユーザー価値とビジネスニーズに焦点
• 非技術関係者向けに記述
• すべての必須セクション完成

要件完全性

• [要明確化]マーカーが残っていない
• 要件はテスト可能で曖昧さがない
• 成功基準は測定可能
• スコープが明確に境界付けられている
• 依存関係と前提条件が識別されている

---

実行ステータス

• ユーザー説明を解析済み
• 主要概念を抽出済み
• 曖昧さをマーク済み
• ユーザーシナリオを定義済み
• 要件を生成済み
• エンティティを識別済み
• レビューチェックリスト合格

---

参考実装

実装ファイル

• unity-cli/src/handlers/console/ConsoleReadToolHandler.js
• unity-cli/src/handlers/console/ConsoleClearToolHandler.js
• UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/ConsoleHandler.cs

技術詳細

• UnityEditor.LogEntriesによるログ取得
• Reflectionによるコンソール内部状態へのアクセス
• ISO 8601形式でのタイムスタンプ処理
• 出力形式のカスタマイズとグループ化処理
• 自動クリア設定のEditorPrefs保存

Plan

実装計画: コンソール管理機能

機能ID: SPEC-2e6d9a3b | ステータス: 実装完了

概要

本機能は既に実装済みです。このplan.mdは実装完了後に作成されました。

実装状況

• ✅ Phase 0: Research完了
• ✅ Phase 1: Design完了
• ✅ Phase 2: Task planning完了
• ✅ Phase 3: Tasks実装完了
• ✅ Phase 4: 実装完了
• ✅ Phase 5: テスト完了

参考実装

実装詳細については spec.md の「参考実装」セクションを参照してください。

---

本ドキュメントは実装完了後に作成されました

Tasks

タスク: コンソール管理機能

機能ID: SPEC-2e6d9a3b | ステータス: 改善中

実装状況

本機能は既に実装済みですが、パフォーマンス改善のため追加タスクを実施中です。

完了済みタスク

• 機能設計
• コア実装
• テスト実装
• ドキュメント作成

改善タスク（2025-11-06）

背景

ログのスタックトレース含有時にレスポンスサイズが5-20MBになる問題を改善。デフォルトでスタックトレースを含めないことで、約10-40倍のサイズ削減を実現。

タスク一覧

• [TASK-001] テストケース更新: includeStackTraceのデフォルト値をfalseに変更

  • ファイル: unity-cli/tests/unit/handlers/console/ConsoleReadToolHandler.test.js
  • 期待動作: デフォルトでincludeStackTrace=falseになることを確認

• [TASK-002] ハンドラ修正: includeStackTraceのデフォルト値をfalseに変更

  • ファイル: unity-cli/src/handlers/console/ConsoleReadToolHandler.js
  • 変更内容: スキーマ定義のデフォルト値をtrueからfalseに変更

• [TASK-003] ドキュメント更新: ツール説明文を更新

  • ファイル: unity-cli/src/handlers/console/ConsoleReadToolHandler.js
  • 内容: スタックトレースがデフォルトで含まれないことを明記

• [TASK-004] 動作確認とコミット

  • 実施内容: ユニットテストの実行、変更内容のコミット

参考

実装詳細については spec.md および plan.md を参照してください。

---

本ドキュメントは実装完了後に作成されました（2025年10月）
改善タスクを追加しました（2025年11月）

TDD

TODO

Research

TODO

Data Model

TODO

Quickstart

TODO

Contracts

Artifact files under contracts/ are managed in issue comments with contract:<name> entries.

Checklists

Artifact files under checklists/ are managed in issue comments with checklist:<name> entries.

Acceptance Checklist

• Add acceptance checklist

[akiojin]

gwt-spec ドメイン再編により #154 に統合