Skip to content

Latest commit

 

History

History
424 lines (286 loc) · 13.3 KB

USAGE.md

File metadata and controls

424 lines (286 loc) · 13.3 KB

Usage

OpenCodeAppの使用方法について詳しく説明します。

アプリケーションの起動方法

基本的な起動

# デバッグビルドで実行
swift run

# またはビルド済みの実行ファイルを実行
./.build/arm64-apple-macosx/debug/OpenCodeApp

リリースビルドでの実行

# リリースビルド
swift build -c release

# 実行
./.build/arm64-apple-macosx/release/OpenCodeApp

バックグラウンドでの実行

# バックグラウンドで実行
./.build/arm64-apple-macosx/debug/OpenCodeApp &

# プロセスIDを確認
echo $!

アプリケーションの停止

# プロセスIDを使用して停止
kill <PID>

# または名前で停止
pkill OpenCodeApp

# 強制終了
kill -9 <PID>

メニューバーアプリの操作方法

アプリケーションの認識

起動すると、メニューバーにアイコンが表示されます：

  • アイコン: macOSウィンドウアイコン 🪟
  • 位置: メニューバーの右側（システム時計の近く）

ポップアップの開閉

ポップアップを開く

  1. メニューバーのアイコンをクリック
  2. ポップアップが開きます

ポップアップを閉じる

  1. ポップアップの外側をクリック
  2. または再度メニューバーアイコンをクリック

ポップアップのUI構成

ポップアップは以下のセクションで構成されています：

┌─────────────────────────────────┐
│ ヘッダー                         │
│ OpenCode          [アクティブ]   │
├─────────────────────────────────┤
│                                 │
│ メッセージ表示エリア            │
│ (スクロール可能)                │
│                                 │
│ [ユーザーメッセージ]            │
│ [アシスタントメッセージ]         │
│                                 │
├─────────────────────────────────┤
│ エラーメッセージ (エラー時)     │
├─────────────────────────────────┤
│ 入力エリア                       │
│ [テキスト入力] [送信] [📷]      │
│                                 │
│ [セッション作成] [クリア]         │
└─────────────────────────────────┘

各機能の詳細説明

1. セッション管理

セッションの作成

  1. 「セッション作成」ボタンをクリック
  2. 新しいセッションが作成されます
  3. ヘッダーのステータスが「非アクティブ」→「アクティブ」に変わります
  4. チャット履歴がクリアされます

セッションの状態確認

ヘッダーのステータスでセッション状態を確認できます：

  • アクティブ: セッションが有効
  • 非アクティブ: セッションが存在しない

セッションのクリア

  1. 「クリア」ボタンをクリック
  2. 現在のセッションが終了します
  3. チャット履歴がクリアされます
  4. 新しいセッションを作成するには「セッション作成」をクリック

2. メッセージの送信

基本的なメッセージ送信

  1. テキストフィールドにメッセージを入力
  2. Enterキーを押すか「送信」ボタンをクリック
  3. メッセージがOpenCode APIに送信されます

メッセージの表示

送信されたメッセージとレスポンスは以下のように表示されます：

ユーザーメッセージ:

  • 右側に青いバブルで表示
  • 送信時刻が表示されます

アシスタントメッセージ:

  • 左側に灰色のバブルで表示
  • 受信時刻が表示されます

メッセージのスクロール

メッセージが増えるとスクロールバーが表示されます：

  • マウススクロールで上下にスクロール
  • 最新のメッセージが下に表示されます

3. スクリーンショットの取得と送信

スクリーンショットの取得

  1. Shiftキーを押しながらマウスをドラッグ
  2. 矩形範囲を選択
  3. マウスを離すとスクリーンショットが取得され、入力ランチャーが開きます

スクリーンショットの送信

入力ランチャーで以下の手順で送信します：

  1. スクリーンショットが添付された状態で表示されます
  2. 必要に応じてテキストを入力します（テキストなしでも送信可能）
  3. Enterキーまたは「送信」ボタンをクリック
  4. 会話ログに結果が追加されます

4. エラーハンドリング

エラーメッセージの表示

エラーが発生した場合、入力エリアの上部に赤いテキストでエラーメッセージが表示されます。

一般的なエラーと対処法

「セッションが作成されていません」

原因: セッションを作成せずにメッセージを送信しようとした

対処法:

  1. 「セッション作成」ボタンをクリック
  2. セッションが作成された後にメッセージを送信
「認証に失敗しました」

原因: APIキーが無効または期限切れ

対処法:

  1. .config.jsonのAPIキーを確認
  2. APIキーが有効か確認
  3. 必要であれば新しいAPIキーを取得
「サーバーエラー (ステータスコード: xxx)」

原因: OpenCode APIサーバーでの問題

対処法:

  1. インターネット接続を確認
  2. OpenCode APIのステータスを確認
  3. しばらく待ってから再試行
「スクリーンショットの取得に失敗しました」

原因: スクリーンショット取得時のエラー

対処法:

  1. メイン画面が接続されているか確認
  2. macOSのプライバシー設定を確認
  3. アプリケーションを再起動

ワークフローの例

基本的なチャットワークフロー

  1. アプリケーションを起動
  2. メニューバーアイコンをクリック
  3. 「セッション作成」をクリック
  4. テキストフィールドにメッセージを入力
  5. Enterキーを押して送信
  6. レスポンスを確認

スクリーンショット共有ワークフロー

  1. アプリケーションを起動
  2. Shift+マウスドラッグで矩形範囲を選択
  3. 入力ランチャーが開いたら必要に応じてテキストを入力
  4. 送信してレスポンスを確認

問題解決ワークフロー

  1. アプリケーションを起動
  2. 問題のある画面を表示
  3. Shift+マウスドラッグで矩形範囲を選択
  4. 入力ランチャーで問題を説明して送信（テキストなしでも送信可）
  5. 解決策を確認

キーボードショートカット

グローバルキーボードショートカット

以下のショートカットはアプリ全体で利用可能です：

  • Cmd+Shift+O: チャットウィンドウの表示/非表示切り替え
  • Cmd+Shift+I: 入力ランチャーを表示

矩形選択時のショートカット

  • Shift+マウスドラッグ: 矩形選択スクリーンショット（入力ランチャーに添付）
  • ESC: 選択キャンセル

ポップアップ内のショートカット

  • Enter: メッセージの送信
  • Tab: 入力フィールド間の移動

メニューバー右クリックメニューのショートカット

  • Cmd+O: チャットウィンドウを表示
  • Cmd+I: 入力ランチャーを表示
  • Cmd+Q: 終了

ウィンドウ機能

フローティングチャットウィンドウ

フローティングチャットウィンドウは、独立したチャットインターフェースを提供します。

特徴

  • サイズ: 初期サイズは340x600ピクセル
  • リサイズ可能: ウィンドウの端をドラッグしてサイズ変更可能
  • 配置: 画面左側に配置
  • レベル: フローティングレベルで最前面に表示
  • 表示方法:
    • メニューバーをクリックして「チャットウィンドウを表示」を選択
    • グローバルショートカット Cmd+Shift+O を使用
  • 非表示方法: ウィンドウを閉じるボタンをクリック、または再度 Cmd+Shift+O を押下

使用シナリオ

  • 長いチャットセッション中にメニューバーのポップアップが閉じてしまう場合
  • 複数のアプリを同時に操作しながらチャットを継続する場合
  • 画面スペースを確保しながらチャットを表示する場合

入力ランチャー

入力ランチャーは、クイックメッセージ送信用の簡易ウィンドウです。

特徴

  • サイズ: 560x320ピクセル
  • 配置: 画面中央に表示
  • 動作:
    • メッセージ送信後、自動的にクローズ
    • キャンセルボタンまたはEscキーでクローズ
    • 表示時にテキストフィールドに自動フォーカス
    • セッション未作成でも自動作成して送信
    • スクリーンショット添付時はテキストなしでも送信可能
  • 表示方法:
    • メニューバーをクリックして「入力ランチャーを表示」を選択
    • グローバルショートカット Cmd+Shift+I を使用

使用シナリオ

  • 短いメッセージを素早く送信したい場合
  • チャット履歴を見る必要がない場合
  • 他の作業を中断せずに素早く質問したい場合

ウィンドウの排他制御

入力ランチャーとチャットウィンドウは排他的に動作します：

  • 入力ランチャーを表示すると、チャットウィンドウが自動的に非表示になります
  • チャットウィンドウを表示すると、入力ランチャーが自動的に非表示になります

メニューバーメニュー

メニューバーアイコンをクリックすることで、以下の機能にアクセスできます：

メニューアイテム

  1. チャットウィンドウを表示 (Cmd+O)

    • フローティングチャットウィンドウを表示します
    • 既に表示されている場合は前面に表示されます

  2. 入力ランチャーを表示 (Cmd+I)

    • 入力ランチャーウィンドウを表示します
    • 画面中央に簡易入力ウィンドウが表示されます

  3. 再起動

    • アプリケーションを再起動します
    • 設定ファイルの変更を反映させる場合などに使用

  4. 終了 (Cmd+Q)

    • アプリケーションを終了します
    • すべてのウィンドウが閉じられます

ヒントとコツ

効率的な使用方法

  1. セッションの目的を明確に: 最初のメッセージで目的を明確に伝える
  2. スクリーンショットを活用: 視覚的な情報を含めると回答の精度が向上
  3. 具体的な質問: 曖昧な質問は避け、具体的にする

パフォーマンスの最適化

  1. 古いセッションのクリア: メッセージが多くなるとパフォーマンスが低下
  2. 定期的な再起動: 長時間の使用後はアプリケーションを再起動

トラブルシューティング

アプリケーションが応答しない

  1. アプリケーションを強制終了
  2. 再起動
  3. 問題が続く場合は、.config.jsonを確認

メッセージが送信されない

  1. セッションが作成されているか確認
  2. インターネット接続を確認
  3. APIキーが有効か確認

スクリーンショットが正しく表示されない

  1. 画面の解像度を確認
  2. 複数ディスプレイの場合、メイン画面を確認
  3. アプリケーションを再起動

ログとデバッグ

ログファイルの確認

ログファイルは以下のパスに保存されます：

~/github/chrome-to-opencode/opencode_app.log

ログには以下の情報が含まれます：

  • アプリケーション初期化のステータス
  • API通信の詳細
  • ウィンドウ操作のログ
  • エラーメッセージとスタックトレース

ログの確認方法

# 最新のログを表示
tail -50 ~/github/chrome-to-opencode/opencode_app.log

# ログを監視
tail -f ~/github/chrome-to-opencode/opencode_app.log

デバッグモードでの実行

デバッグ情報を表示して実行：

swift run

またはビルド済みの実行ファイル：

./.build/arm64-apple-macosx/debug/OpenCodeMenuApp

エラーの報告

バグを報告する場合、以下の情報を含めてください：

  1. macOSのバージョン
  2. アプリケーションのバージョン
  3. エラーメッセージ
  4. 再現手順
  5. ログファイル

次のステップ

使用方法を理解したら：

  1. 設定方法を確認してAPIキーを設定
  2. アーキテクチャで内部設計を理解する
  3. 開発ガイドで開発環境のセットアップ