massgen-develops-massgen

MassGen による MassGen の開発

このスキルでは、MassGen を使用して自身を開発・改善するためのガイダンスを提供します。テストする内容に応じて、適切なワークフローを選択してください。

2 つのワークフロー

1. 自動化モード - バックエンド機能、調整ロジック、エージェントの応答をテストします
2. ビジュアル評価 - ターミナル表示、色、レイアウト、UX をテストします

---

ワークフロー 1：自動化モード

視覚的な確認なしで機能をテストするには、このモードを使用します。プログラムによるテストに最適です。

自動化モードで MassGen を実行する

MassGen をバックグラウンドで実行します（正確な方法は使用するツールによって異なります）。

uv run massgen --automation --config massgen/configs/basic/multi/two_agents_gemini.yaml "What is 2+2?"

MassGen エージェントの場合：mcp__command_line__execute_command を対象に custom_tool__start_background_tool を使用してから、custom_tool__get_background_tool_status / custom_tool__get_background_tool_result でポーリングします。 Claude Code の場合：Bash ツールの run_in_background パラメーターを使用します。

自動化モードを使用する理由

機能	メリット
クリーンな出力	解析可能な約 10 行（ANSI コード 3,000 行以上に対して）
LOG_DIR の出力	最初の行にログディレクトリのパスが表示されます
status.json	リアルタイム監視用ファイル
終了コード	0=成功、1=設定、2=実行、3=タイムアウト、4=中断
ワークスペースの分離	安全な並列実行

想定される出力

LOG_DIR: .massgen/massgen_logs/log_20251120_143022_123456
STATUS: .massgen/massgen_logs/log_20251120_143022_123456/status.json

🤖 Multi-Agent Mode
Agents: gemini-2.5-pro1, gemini-2.5-pro2
Question: What is 2+2?

============================================================
QUESTION: What is 2+2?
[Coordination in progress - monitor status.json for real-time updates]

WINNER: gemini-2.5-pro1
DURATION: 33.4s
ANSWER_PREVIEW: The answer is 4.

COMPLETED: 2 agents, 35.2s total

最初の行から LOG_DIR を解析して、ログディレクトリを特定します。

進行状況の監視

status.json ファイルを読み取ります（2 秒ごとに更新されます）。

cat .massgen/massgen_logs/log_20251120_143022_123456/status.json

主なフィールド：

{
  "coordination": {
    "completion_percentage": 65,
    "phase": "enforcement"
  },
  "results": {
    "winner": null  // null = running, "agent_id" = done
  },
  "agents": {
    "agent_a": {
      "status": "streaming",
      "error": null
    }
  }
}

エージェントのステータス値： waiting、streaming、answered、voted、completed、error

結果の確認

完了後（終了コード 0）：

# Read final answer
cat [log_dir]/final/[winner]/answer.txt

所要時間の目安

• 標準タスク：2～10 分
• 複雑なタスク／メタタスク：10～30 分
• 停止しているか確認する場合：status.json を読み取ります。completion_percentage が増えていれば、処理は進行中です

詳細：複数のバックグラウンドモニター

メインの MassGen プロセスと並行して、独立して実行される複数のバックグラウンド監視タスクを作成できます。各モニターは異なる項目を追跡し、後で確認できるよう個別のログファイルに書き込めます。

方法

バックグラウンドシェルで実行する小さな Python スクリプトを作成します。各スクリプトは次の処理を行います。

• 特定の項目（トークン、エラー、進行状況、調整など）を監視します
• タイムスタンプ付きのデータを個別のログファイルに書き込みます
• sleep() 間隔を設けてループで実行します
• メインタスクをブロックせず、いつでも確認できます

モニタースクリプトの例

トークン使用量モニター（token_monitor.py）：

import json, time, sys
from pathlib import Path

log_dir = Path(sys.argv[1])  # Pass LOG_DIR as argument
while True:
    if (log_dir / "status.json").exists():
        with open(log_dir / "status.json") as f:
            data = json.load(f)
        with open("token_monitor.log", "a") as log:
            log.write(f"=== {time.strftime('%H:%M:%S')} ===\n")
            log.write(f"Tokens: {data.get('total_tokens_used', 0)}\n")
            log.write(f"Cost: ${data.get('total_cost', 0):.4f}\n\n")
    time.sleep(5)

エラーモニター（error_monitor.py）：

import time, sys
from pathlib import Path

log_dir = Path(sys.argv[1])
while True:
    if log_dir.exists():
        with open("error_monitor.log", "a") as log:
            log.write(f"=== {time.strftime('%H:%M:%S')} ===\n")
            errors = []
            for logfile in log_dir.glob("*.log"):
                with open(logfile) as f:
                    for line in f:
                        if any(x in line.lower() for x in ['error', 'warning', 'failed']):
                            errors.append(line.strip())
            log.write('\n'.join(errors[-5:]) if errors else "No errors\n")
            log.write("\n")
    time.sleep(5)

進行状況モニター（progress_monitor.py）：

import json, time, sys
from pathlib import Path

log_dir = Path(sys.argv[1])
while True:
    if (log_dir / "status.json").exists():
        with open(log_dir / "status.json") as f:
            data = json.load(f)
        with open("progress_monitor.log", "a") as log:
            log.write(f"=== {time.strftime('%H:%M:%S')} ===\n")
            progress = data.get('completion_percentage', 0)
            active = sum(1 for a in data.get('agents', {}).values()
                        if a.get('status') == 'active')
            log.write(f"Progress: {progress}% Active agents: {active}\n\n")
    time.sleep(5)

調整モニター（coordination_monitor.py）：

import json, time, sys
from pathlib import Path

log_dir = Path(sys.argv[1])
while True:
    if (log_dir / "status.json").exists():
        with open(log_dir / "status.json") as f:
            data = json.load(f)
        coord = data.get('coordination', {})
        with open("coordination_monitor.log", "a") as log:
            log.write(f"=== {time.strftime('%H:%M:%S')} ===\n")
            log.write(f"Phase: {coord.get('phase', 'unknown')}\n")
            log.write(f"Round: {coord.get('round', 0)}\n")
            log.write(f"Total answers: {coord.get('total_answers', 0)}\n\n")
    time.sleep(5)

ワークフロー

1. メインタスクを起動し、出力から LOG_DIR を解析します
2. 必要に応じてモニタースクリプトを作成します（Python ファイルを作成）
3. バックグラウンドシェルでモニターを起動します：python3 token_monitor.py [LOG_DIR] &
4. .log ファイルを読み取り、いつでもモニターログを確認できます
5. 完了したら、モニタープロセスを終了してログを分析します

カスタムモニター

追跡したい指標に応じて、任意のモニターを作成できます。

• モデル固有のパフォーマンス指標
• メモリ／コンテキストの使用パターン
• リアルタイムのコスト累積
• 回答品質の傾向
• エージェントの調整パターン
• 特定のエラーカテゴリー

メリット：

• 必要に応じて特定の指標を非ブロッキングで確認できます
• 実行後の分析に利用できる履歴データを記録できます
• 項目ごとに独立した監視ストリームを利用できます
• 設定を変更せずに新しいモニターを簡単に追加できます

---

ワークフロー 2：ビジュアル評価

MassGen のターミナル表示品質を分析・改善するには、このモードを使用します。custom_tools/_multimodal_tools/ のツールが必要です。

重要： このワークフローではリッチなターミナル表示を記録するため、実際の記録では --automation モードを使用しません。ただし、必ず事前に --automation でテストしてください。

前提条件

ワークスペースで次のツールを使用できる必要があります。

• run_massgen_with_recording - ターミナルセッションを動画として記録します
• understand_video - GPT-4.1 vision で動画のフレームを分析します

ステップ 0：自動化による事前テスト（必須）

動画を録画する前に、設定が機能し、API キーが有効であることを確認してください。

# Start with --automation to verify everything works
uv run massgen --automation --config [config_path] "[question]"

30～60 秒待って（API キーの確認、設定の解析、ツールの初期化に十分な時間です）、その後プロセスを終了します。

これが重要な理由：

• 録画時間を無駄にする前に、設定エラーを検出できます
• API キーが設定され、機能していることを確認できます
• ツールが正しく初期化されることを確認できます
• 問題のあるセッションを録画するのを防げます

自動テストに失敗した場合は、録画に進む前に問題を修正してください。

ステップ 1：MassGen セッションを録画する

自動化による事前テストが成功した後、画面上のセッションを録画します。

from custom_tools._multimodal_tools.run_massgen_with_recording import run_massgen_with_recording

result = await run_massgen_with_recording(
    config_path="massgen/configs/basic/multi/two_agents_gemini.yaml",
    question="What is 2+2?",
    output_format="mp4",  # ALWAYS use mp4 for maximum compatibility
    timeout_seconds=120,
    width=1920,
    height=1080
)

形式に関する推奨事項：互換性を最大限に高めるため、常に "mp4" を使用してください。GIF と WebM もサポートされていますが、MP4 を推奨します。

録画される内容：色付きのリッチなターミナル表示、ステータスインジケーター、連携の可視化（--automation フラグなし）。

ステップ 2：録画を分析する

understand_video を使用して MP4 録画を分析します。 少なくとも 1 回呼び出してください。さまざまな側面を分析するために、複数回呼び出すこともできます。

from custom_tools._multimodal_tools.understand_video import understand_video

# Overall UX evaluation
ux_eval = await understand_video(
    video_path=result["video_path"],  # The MP4 file from Step 1
    prompt="Evaluate the overall terminal display quality, clarity, and usability",
    num_frames=12
)

# Focused on coordination
coordination_eval = await understand_video(
    video_path=result["video_path"],
    prompt="How clearly does the display show agent coordination phases and voting?",
    num_frames=8
)

# Status indicators
status_eval = await understand_video(
    video_path=result["video_path"],
    prompt="Are status indicators (streaming, answered, voted) clear and visually distinct?",
    num_frames=8
)

重要なポイント：

• 録画ツールは動画をワークスペースに保存します。分析にはそのパスを使用してください
• 同じ動画に対して、異なるプロンプトを指定して understand_video を複数回呼び出せます
• 呼び出すたびに、UX、連携、ステータス、色など、特定の側面に焦点を当てます

評価基準

ターミナル表示を分析する際は、次の点を評価してください。

1. 視覚的な明瞭さ - コントラスト、色、フォントの描画、ANSI の処理、間隔
2. 情報の整理 - レイアウト、情報密度、ストリーミング表示、スクロール処理
3. ステータスインジケーター - エージェントの状態、進捗状況の追跡、フェーズの移行、勝者の選択
4. ユーザーエクスペリエンス - リアルタイムのフィードバック、エラーの見やすさ、認知負荷、情報の階層

出力形式に関する推奨事項

デフォルトでは MP4 を使用してください。互換性と品質を最大限に高められます。

形式	用途	備考
MP4	デフォルト — すべてに使用	最高の品質、幅広いサポート、詳細な分析に最適
GIF	ファイルサイズを抑えたい場合、簡単に埋め込みたい場合	品質が低く、想定よりファイルが大きくなるため、サイズに制約がある場合を除き使用しないでください
WebM	最新のウェブでの公開	品質は良好ですが、幅広くサポートされているわけではありません

目安：特別な理由がない限り MP4 を使用してください。

フレーム数の目安

フレーム数	用途
4-8	簡易評価
8-12	標準的な評価
12-16+	詳細な分析

---

テストする設定

モデル選択のガイドライン

設定を生成する場合や実験を実施する場合は、デフォルトで中位クラスのモデルを選んでください。開発やテストにおいて、コスト、速度、性能のバランスが最も優れています。

重要：必ず今日の日付を基準にモデルの新しさを確認してください。 リリースから 6～12 か月以上経過したモデルは、古くなっていると見なしてください。

モデルの選び方

ステップ 1：バックエンドのファイルを読み、リリース日を確認する

# Check Gemini models and their release dates
grep -A 5 "model.*2\." massgen/backend/gemini.py

# Check OpenAI models and their release dates
grep -A 5 "model.*gpt" massgen/backend/openai.py

# Check Claude models and their release dates
grep -A 5 "model.*claude" massgen/backend/claude.py

ステップ 2：トークンのコストを確認する

cat docs/source/reference/token_budget.rst | grep -A 3 "gemini\|gpt\|claude"

ステップ 3：リリース日を今日の日付と比較する

• リリースからの月数を計算します：（今日の年月）-（モデルのリリース年月）
• 12 か月を超える場合：モデルは古くなっています
• 6～12 か月の場合：モデルは新しさを失いつつあります。利用可能なら新しいモデルを優先してください
• 6 か月未満の場合：モデルは現行です

モデル選択の例

✅ 適切（最近のミッドティアのパターン）：

• Gemini：gemini-2.5-pro、gemini-2.5-flash（2.x シリーズ、2025）
• OpenAI：gpt-5-mini、gpt-4o-mini（GPT-5 世代）
• Claude：claude-sonnet-4-*（4.x シリーズ、2025）

⚠️ 不適切（古いパターン - 日付を確認してください！）：

• ❌ gpt-4o（2024 年リリース - 12 か月以上前の可能性があります）
• ❌ gpt-4-turbo（2023～2024 年頃）
• ❌ gemini-1.5-pro（2.x によって廃止された 1.x シリーズ）
• ❌ claude-3.5-sonnet（4.x が存在する場合の 3.x シリーズ）

選択基準：

• 新しさ：過去 6～12 か月以内にリリース（必ずバックエンドのファイルで日付を確認してください）
• 中価格帯：最上位（高価）でも最下位（安価）でもない
• 一般提供：安定版リリースであり、実験版／プレビュー版／アルファ版ではない
• バージョン番号：メジャーバージョンが大きいほど新しい（gemini-2.x > gemini-1.x、gpt-5 > gpt-4、claude-4 > claude-3）

例外を設ける場合：

• プレミアムモデル：モデルの限界性能をテストする場合（例：gpt-5、claude-opus-4、gemini-3-pro）
• 低価格モデル：コスト最適化の実験を行う場合（例：gpt-5-mini、gemini-2.5-flash）
• 旧モデルのテスト：古いモデルとの後方互換性を検証する場合

Config の生成（エージェント向け）

プログラムで config を生成するには、--generate-config を使用します。

# WORKFLOW:
# 1. Read backend file to find recent mid-tier models
# 2. Verify release date (< 12 months old)
# 3. Check pricing tier (mid-range)
# 4. Use model in --config-model flag

# Example: Generate 2-agent config
massgen --generate-config ./test_config.yaml \
  --config-backend gemini \
  --config-model gemini-2.5-pro \  # (example - always verify this is current!)
  --config-agents 2 \
  --config-docker

# With context path
massgen --generate-config ./test_config.yaml \
  --config-backend openai \
  --config-model gpt-5-mini \  # (example - always verify this is current!)
  --config-context-path /path/to/project

重要：上記のモデル名は例です。必ず現在の日付を基準に、バックエンドのファイルで最新のモデルを確認してください。

これにより、コードベースのツール、スキル、タスク計画が有効になった、すべての機能を備えた config が作成されます。

特定の機能のテスト

生成された config を変更して、機能を有効化／無効化します。

コード実行：

agents:
  - backend:
      enable_mcp_command_line: true
      command_line_execution_mode: "docker"

カスタムツール：

agents:
  - backend:
      enable_code_based_tools: true
      auto_discover_custom_tools: true

エージェントごとに異なるモデルを指定：

agents:
  - backend: {type: "gemini", model: "gemini-2.5-pro"}
  - backend: {type: "openai", model: "gpt-5-mini"}

一般的なパラメーター：enable_code_based_tools、enable_mcp_command_line、command_line_execution_mode、auto_discover_custom_tools、timeout_settings

---

Docker に関する考慮事項

Docker の自動検出

MassGen は、Docker コンテナ内で実行されていることを自動的に検出します。config に command_line_execution_mode: "docker" が設定されている場合、MassGen は次の処理を行います。

1. コンテナ環境を検出します（/.dockerenv を使用）
2. 実行モードを自動的に "local" に切り替えます
3. 「すでに Docker コンテナ内で実行されています - 実行モードを local に切り替えています」とログに記録します

この仕組みが機能する理由： 外側のコンテナによって、すでに分離が確保されています。そのコンテナ内で「ローカル」に実行しても安全であり、サンドボックス化されています。

手動での設定は不要です。Docker モードの config は、コンテナ内で実行するだけで動作します。

トレードオフ

ローカル実行に自動切り替えする場合：

• ✅ ホストから引き続きサンドボックス化されています
• ✅ すべての機能が動作します（VHS、MassGen、ツールはコンテナ内にあります）
• ⚠️ ツール呼び出しごとの実行分離はありません
• ⚠️ 状態はコンテナのセッション内に保持されます

---

参考ファイル

• ステータスファイルのドキュメント：docs/source/reference/status_file.rst
• ターミナル評価のドキュメント：docs/source/user_guide/terminal_evaluation.rst
• 設定例：massgen/configs/basic/、massgen/configs/meta/
• 録画ツール：massgen/tool/_multimodal_tools/run_massgen_with_recording.py
• 動画分析ツール：massgen/tool/_multimodal_tools/understand_video.py