| name | mixseek-debug |
| description | MixSeek-Plusのデバッグ機能を有効化し、ログ出力を制御します。「デバッグモードを有効化」「verbose」「ログを出力」「ログレベル」「デバッグ設定」といった依頼で使用してください。 |
| license | Apache-2.0 |
| compatibility | Requires mixseek-core or mixseek-plus. Python 3.13+, uv recommended. |
| metadata | {"author":"mixseek","version":"1.0.0"} |
MixSeek デバッグ機能
概要
MixSeek-Plusは複数のデバッグ用環境変数を提供しています。これらを使用して、エージェント実行時の詳細なログ出力を有効化し、問題の診断や動作確認を行うことができます。
環境変数一覧
| 環境変数 | 値 | 効果 | スコープ |
|---|
MIXSEEK_VERBOSE | 1 または true | 統合デバッグモード | MCPツールログ + mixseek.member_agents(DEBUG) + claudecode_model(DEBUG) |
CLAUDECODE_MODEL_LOG_LEVEL | DEBUG | claudecode-model単体のログ | claudecode-modelパッケージのみ |
MIXSEEK_LOGFIRE | 1 または true | Logfireインストルメンテーション | pydantic-ai トレース（要Logfire設定） |
推奨設定
通常のデバッグには MIXSEEK_VERBOSE=1 のみで十分です。
MIXSEEK_VERBOSE=1 を設定すると、以下のログが有効化されます：
- MCPツール呼び出しの開始/完了ログ
mixseek.member_agents ロガーのDEBUGレベル出力claudecode_model ロガーのDEBUGレベル出力
使用方法
Step 1: 環境変数の確認
現在の環境変数設定を確認するには、以下のスクリプトを実行してください：
bash skills/mixseek-debug/scripts/check-debug-env.sh
Step 2: CLI実行時の使用
方法A: 環境変数を設定してCLI実行
MIXSEEK_VERBOSE=1 uv run mskp team "タスク" --config configs/agents/team.toml
CLAUDECODE_MODEL_LOG_LEVEL=DEBUG uv run mskp team "タスク" --config configs/agents/team.toml
MIXSEEK_VERBOSE=1 MIXSEEK_LOGFIRE=1 uv run mskp team "タスク" --config configs/agents/team.toml
方法B: シェルセッション全体に設定
export MIXSEEK_VERBOSE=1
uv run mskp team "タスク" --config configs/agents/team.toml
unset MIXSEEK_VERBOSE
Step 3: Python APIでの使用
import mixseek_plus
mixseek_plus.enable_verbose_mode()
mixseek_plus.patch_core()
mixseek_plus.disable_verbose_mode()
import os
import mixseek_plus
os.environ["MIXSEEK_VERBOSE"] = "1"
mixseek_plus.patch_core()
os.environ["MIXSEEK_VERBOSE"] = "1"
try:
pass
finally:
del os.environ["MIXSEEK_VERBOSE"]
ログ出力先
コンソール出力
MIXSEEK_VERBOSE=1 時、以下のフォーマットでコンソールに出力されます：
[Tool Start] <tool_name>: <params>
[Tool Done] <tool_name>: <status> in <time>ms
[Tool Result Preview] <result_preview>
例:
[Tool Start] fetch_page: url=https://example.com/docs
[Tool Done] fetch_page: success in 2345ms
[Tool Result Preview] # Documentation\n\nWelcome to...
ファイル出力
Member Agentのログは以下のファイルに出力されます：
$MIXSEEK_WORKSPACE/logs/member-agent-YYYY-MM-DD.log
出力内容:
- ツール呼び出しの詳細（パラメータ、実行時間、ステータス）
- エージェント実行のトレース情報
- エラーとスタックトレース
claudecode_model ログ
MIXSEEK_VERBOSE=1 時、claudecode_model ロガーも自動的にDEBUGレベルに設定され、以下が出力されます：
claudecode_model - DEBUG - <message>
組み合わせ例
1. 基本的なデバッグ（最も一般的）
MIXSEEK_VERBOSE=1 uv run mskp team "Webページを取得して要約して" --config configs/agents/team.toml
2. Logfireトレースを追加
MIXSEEK_VERBOSE=1 MIXSEEK_LOGFIRE=1 uv run mskp team "タスク" --config configs/agents/team.toml
3. claudecode-model単体のデバッグ
他のログを抑制してclaudecode-modelのみをデバッグしたい場合：
CLAUDECODE_MODEL_LOG_LEVEL=DEBUG uv run mskp team "タスク" --config configs/agents/team.toml
トラブルシューティング
ログが出力されない
原因1: 環境変数が正しく設定されていない
echo $MIXSEEK_VERBOSE
export MIXSEEK_VERBOSE=1
原因2: patch_core()が呼び出されていない
Python APIを使用する場合、patch_core() を呼び出す必要があります：
import mixseek_plus
mixseek_plus.enable_verbose_mode()
mixseek_plus.patch_core()
原因3: ログハンドラーが設定されていない
Pythonのロギング設定を確認してください：
import logging
logging.basicConfig(level=logging.DEBUG)
ファイルログが見つからない
原因: MIXSEEK_WORKSPACEが設定されていない
echo $MIXSEEK_WORKSPACE
export MIXSEEK_WORKSPACE=/path/to/workspace
ls -la $MIXSEEK_WORKSPACE/logs/
ログ出力が多すぎる
MIXSEEK_VERBOSE=1 は多くのログを出力します。特定のコンポーネントのみをデバッグしたい場合：
CLAUDECODE_MODEL_LOG_LEVEL=DEBUG uv run mskp team "タスク" --config configs/agents/team.toml
または、Pythonでロガーレベルを個別に制御：
import logging
logging.getLogger("claudecode_model").setLevel(logging.DEBUG)
logging.getLogger("mixseek.member_agents").setLevel(logging.INFO)
Logfireトレースが表示されない
原因: Logfireが設定されていない
Logfireを使用するには、事前に設定が必要です：
import logfire
logfire.configure()
詳細は Logfire公式ドキュメント を参照してください。
関連ドキュメント
次のステップ
デバッグが完了したら、環境変数を削除または無効化してください：
unset MIXSEEK_VERBOSE
unset CLAUDECODE_MODEL_LOG_LEVEL
unset MIXSEEK_LOGFIRE
または、Python APIで：
import mixseek_plus
mixseek_plus.disable_verbose_mode()
