drillan/mixseek-debug

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単体のデバッグ
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

# 以降のコマンドはすべてverboseモードで実行される
uv run mskp team "タスク" --config configs/agents/team.toml

# 無効化
unset MIXSEEK_VERBOSE

Step 3: Python APIでの使用

import mixseek_plus

# 方法A: enable_verbose_mode()を使用（推奨）
mixseek_plus.enable_verbose_mode()
mixseek_plus.patch_core()

# これ以降のClaudeCodeエージェントはverboseログを出力
# コンソール出力例:
# [Tool Start] fetch_page: url=https://example.com
# [Tool Done] fetch_page: success in 1234ms

# ファイル出力先: $WORKSPACE/logs/member-agent-YYYY-MM-DD.log

# verboseモードを無効化
mixseek_plus.disable_verbose_mode()

import os
import mixseek_plus

# 方法B: 環境変数を直接設定
os.environ["MIXSEEK_VERBOSE"] = "1"
mixseek_plus.patch_core()

# 方法C: 一時的に有効化（コンテキストマネージャは非提供、手動管理）
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トレースを追加

# 事前に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単体のみ
CLAUDECODE_MODEL_LOG_LEVEL=DEBUG uv run mskp team "タスク" --config configs/agents/team.toml

または、Pythonでロガーレベルを個別に制御：

import logging

# 特定のロガーのみDEBUGに
logging.getLogger("claudecode_model").setLevel(logging.DEBUG)

# 他はINFOに抑制
logging.getLogger("mixseek.member_agents").setLevel(logging.INFO)

Logfireトレースが表示されない

原因: Logfireが設定されていない

Logfireを使用するには、事前に設定が必要です：

import logfire
logfire.configure()

詳細は Logfire公式ドキュメント を参照してください。

関連ドキュメント

• MixSeek-Plus README
• ClaudeCode Provider
• Member Agent ログ

次のステップ

デバッグが完了したら、環境変数を削除または無効化してください：

unset MIXSEEK_VERBOSE
unset CLAUDECODE_MODEL_LOG_LEVEL
unset MIXSEEK_LOGFIRE

または、Python APIで：

import mixseek_plus
mixseek_plus.disable_verbose_mode()