textual-screenshot

Textual のスクリーンショット

Textual のヘッドレステストハーネスで実際のアプリを描画し、要求された状態まで操作して、構成されたターミナルを SVG として保存します。ブラウザー自動化や OS レベルのスクリーンショットツールより、こちらを優先してください。

キャプチャの手順

1. App クラスを特定し、目的の UI を表示するための、最短で信頼できるローカルのセットアップを確認します。
2. リポジトリの外部に一時的な Python スクリプトを作成します。ユーザーからコミットする成果物を明示的に求められない限り、生成したスクリーンショットはリポジトリの外部に保存します。
3. app.run_test(size=(columns, rows)) を使って、ターミナルのサイズを固定してアプリを起動します。
4. 起動後、および表示状態を変更する操作を行った後は毎回、await pilot.pause() を呼び出します。可能であれば、現実的な操作手順として pilot.press(...) を使用します。特定の状態をプレビューする場合は、アプリのメソッドを直接呼び出してもかまいません。
5. 目的の状態が表示されている間に app.save_screenshot(output_path) を呼び出します。パスには .svg を使用してください。
6. 生成された SVG を確認し、共有する前にファイルサイズが妥当であることを確認します。
7. 一時スクリプトとキャプチャは不要になったら削除します。

最小限の deepagents-code の例：

import asyncio
import os
from pathlib import Path
from tempfile import TemporaryDirectory
from unittest.mock import AsyncMock, MagicMock, patch


async def main() -> None:
    output = Path("/tmp/dcode-ui.svg")
    with TemporaryDirectory() as profile:
        os.environ["DEEPAGENTS_HOME"] = profile
        from deepagents_code.app import DeepAgentsApp

        app = DeepAgentsApp(agent=MagicMock())
        with patch.object(app, "_post_paint_init", new=AsyncMock()):
            async with app.run_test(size=(110, 36)) as pilot:
                await pilot.pause()
                await app._handle_command("/model")
                await pilot.pause()
                app.save_screenshot(output)
    print(output)


asyncio.run(main())

プロジェクトの環境と編集可能なパッケージを解決できるよう、libs/code から実行します。

uv run python /tmp/capture_dcode_ui.py

アプリのコンストラクターと目的の状態を開く操作だけを変更します。スタンドアロンの Textual アプリの場合は、その App サブクラスをインポートし、同じ run_test／save_screenshot の手順を使用します。

信頼性と安全性

• 信頼できるローカルアプリケーションのコードだけを使用してください。ヘッドレスアプリでも、起動フックやサブプロセス、ネットワーク呼び出しが実行される場合があります。DeepAgentsApp では、deepagents_code をインポートする前に DEEPAGENTS_HOME を一時ディレクトリに設定し、マウント前に _post_paint_init をモックしてください。エージェントだけを差し替えても、起動時の副作用は遮断されません。
• 秘密情報、認証情報、非公開の会話内容、無関係なユーザーデータはキャプチャしないでください。プレビューに必要な合成コンテンツだけを用意してください。
• ターミナルのサイズは適切な範囲に制限してください。まず (110, 36) から始め、目的の内容が切れる場合や、余白が大きすぎる場合にのみ調整します。
• ワーカー、アニメーション、モーダルの遷移が落ち着くまで待ってください。適当な時間のスリープを使うのではなく、await pilot.pause() を追加してください。
• 生成された SVG を、操作が機能する証拠として扱わないでください。動作確認には通常の Textual テストを使い、スクリーンショットは視覚的な確認に使ってください。
• SVG を手作業で編集しないでください。目的のアプリ状態を再現し、もう一度キャプチャしてください。