設定管理ガイド

MixSeek-Coreの統一設定管理システム（Configuration Manager）の完全ガイドです。

概要

MixSeek-Coreは、Pydantic Settingsベースの統一設定管理システムを提供します。すべての設定値を一元化し、複数のソースから優先順位に従って読み込みます。

主な機能

  • 統一設定管理: すべての設定値を Configuration Manager で一元管理

  • 優先順位チェーン: CLI > 環境変数 > .env > TOML > デフォルト値

  • トレーサビリティ: 各設定値の出所を追跡可能

  • Article 9準拠: Data Accuracy Mandate に完全準拠

優先順位チェーン

設定値は以下の優先順位で読み込まれます（高い順）：

1. CLI引数 (--config オプション等) ← 最高優先度
2. 環境変数 (MIXSEEK_* プレフィックス)
3. .env ファイル
4. TOML設定ファイル (config.toml, team.toml 等)
5. デフォルト値 (スキーマ定義) ← 最低優先度

優先順位の例:

# 例: timeout_per_team_seconds の設定

# 1. CLI引数で指定
mixseek exec "タスク" --config orch.toml --timeout 600  # → 600秒

# 2. 環境変数も設定されている場合
export MIXSEEK_TIMEOUT_PER_TEAM_SECONDS=300
mixseek exec "タスク" --config orch.toml --timeout 600  # → 600秒（CLI優先）

# 3. TOML設定ファイルにも記載されている場合
# orch.toml: timeout_per_team_seconds = 120
export MIXSEEK_TIMEOUT_PER_TEAM_SECONDS=300
mixseek exec "タスク" --config orch.toml  # → 300秒（環境変数優先）

# 4. すべて未指定の場合
mixseek exec "タスク" --config orch.toml  # → 120秒（TOML設定）

Configuration Manager

基本的な使い方

from pathlib import Path
from mixseek.config import ConfigurationManager, OrchestratorSettings

# Configuration Manager初期化
manager = ConfigurationManager(
    cli_args={"timeout_per_team_seconds": 600},
    workspace=Path("/workspace"),
    environment="prod"
)

# 設定読み込み
settings = manager.load_settings(OrchestratorSettings)

# 設定値の確認
print(f"Timeout: {settings.timeout_per_team_seconds}")

トレーサビリティ

各設定値の出所を追跡できます：

# 特定フィールドの出所を確認
trace = manager.get_trace_info(OrchestratorSettings, "timeout_per_team_seconds")
print(f"Value: {trace.value}")
print(f"Source: {trace.source_name}")  # cli/env/toml/default
print(f"Timestamp: {trace.timestamp}")

設定スキーマ一覧

Configuration Manager で管理される主要な設定スキーマ：

スキーマ名

説明

TOMLセクション

環境変数プレフィックス

OrchestratorSettings

ワークスペースとチーム並列実行

[orchestrator]

MIXSEEK_

LeaderAgentSettings

リーダーエージェント

[leader]

MIXSEEK_LEADER__

MemberAgentSettings

メンバーエージェント

[member]

MIXSEEK_MEMBER__

EvaluatorSettings

評価器

[evaluator]

MIXSEEK_EVALUATOR__

JudgmentSettings

ラウンド継続判定

[judgment]

MIXSEEK_JUDGMENT__

TeamSettings

チーム全体

[team]

MIXSEEK_TEAM__

UISettings

Streamlit UI

[ui]

MIXSEEK_UI__

詳細は 設定リファレンス を参照してください。

ユースケース

ユースケース1: 開発環境と本番環境の設定分離

開発環境 (.env.dev):

MIXSEEK_WORKSPACE=/home/dev/mixseek-workspace
MIXSEEK_LEADER__TIMEOUT_SECONDS=120
MIXSEEK_LEADER__MODEL=google-gla:gemini-2.5-flash-lite

本番環境 (.env.prod):

MIXSEEK_WORKSPACE=/var/mixseek/workspace
MIXSEEK_LEADER__TIMEOUT_SECONDS=600
MIXSEEK_LEADER__MODEL=anthropic:claude-sonnet-4-5

実行時に環境変数ファイルを切り替え：

# 開発環境
source .env.dev
mixseek team "タスク" --config team.toml

# 本番環境
source .env.prod
mixseek team "タスク" --config team.toml

ユースケース2: CI/CD環境での設定上書き

GitLab CI/CD で環境変数を設定：

# .gitlab-ci.yml
test:
  variables:
    MIXSEEK_WORKSPACE: /builds/workspace
    MIXSEEK_LEADER__TIMEOUT_SECONDS: "300"
    MIXSEEK_LEADER__MODEL: "google-gla:gemini-2.5-flash-lite"
  script:
    - mixseek team "テストタスク" --config team.toml

ユースケース3: デバッグ時の一時的な設定変更

デバッグ時に CLI 引数で一時的に設定を上書き：

# 通常実行
mixseek team "タスク" --config team.toml

# デバッグ: タイムアウトを延長
mixseek team "タスク" --config team.toml --workspace /tmp/debug-ws

# デバッグ: 詳細ログ
export MIXSEEK_LOG_LEVEL=DEBUG
mixseek team "タスク" --config team.toml --verbose

CLIコマンド

config init - テンプレート生成

TOML設定ファイルのテンプレートを生成します。

オプション:

  • --component / -c: コンポーネント名（orchestrator, team, evaluator, judgment, prompt_builder）

  • --workspace / -w: ワークスペースパス（省略時は MIXSEEK_WORKSPACE 環境変数を使用）

  • --output-path / -o: 出力ファイルパス（絶対パスまたはworkspaceからの相対パス、デフォルト: workspace/configs/<component>.toml）

  • --force / -f: 既存ファイルを上書き

基本的な使用例:

# デフォルトパス: workspace/configs/config.toml
mixseek config init --workspace /path/to/workspace

# コンポーネント別テンプレート（workspace/configs/<component>.toml）
mixseek config init --component orchestrator --workspace /path/to/workspace
mixseek config init --component team --workspace /path/to/workspace
mixseek config init --component evaluator --workspace /path/to/workspace

# 環境変数を使用
export MIXSEEK_WORKSPACE=/path/to/workspace
mixseek config init --component orchestrator

出力先のカスタマイズ:

# カスタム相対パス: workspace/my-configs/orchestrator.toml
mixseek config init --component orchestrator \
  --output-path my-configs/orchestrator.toml \
  --workspace /path/to/workspace

# 絶対パス: /tmp/orchestrator.toml
mixseek config init --component orchestrator \
  --output-path /tmp/orchestrator.toml

# 強制上書き
mixseek config init --component orchestrator \
  --workspace /path/to/workspace \
  --force

config show - 設定値表示

現在の設定値を階層形式で表示します。

必須オプション:

  • --config / -c: orchestrator TOML ファイルパス（必須）

オプション:

  • --workspace / -w: ワークスペースパス（省略時は MIXSEEK_WORKSPACE 環境変数を使用）

  • --output-format / -f: 出力形式（text/json、デフォルト: text）

  • --environment / -e: 環境（dev/staging/prod）

表示される Settings:

  • OrchestratorSettings - オーケストレーション全体の設定

  • TeamSettings - Team設定（Leader + Members）

  • MemberAgentSettings - Member Agentの設定

  • EvaluatorSettings - 評価器の設定（orchestrator.evaluator_config で指定）

  • JudgmentSettings - 継続判定の設定（orchestrator.judgment_config で指定）

  • PromptBuilderSettings - プロンプトビルダーの設定（configs/prompt_builder.toml）

# 全設定値を表示（階層形式、デフォルト）
mixseek config show --config orchestrator.toml --workspace /path/to/workspace

# MIXSEEK_WORKSPACE 環境変数を使用
export MIXSEEK_WORKSPACE=/path/to/workspace
mixseek config show --config orchestrator.toml

# 特定フィールドを表示
mixseek config show timeout_per_team_seconds --config orchestrator.toml --workspace /path/to/workspace

# JSON形式で表示（プログラム用）
mixseek config show --config orchestrator.toml --workspace /path/to/workspace --output-format json

出力形式 (--output-format / -f):

  • text: 階層的インデント表示（デフォルト）

    • orchestrator レベル: インデントなし

    • team レベル: 2スペースインデント

    • member レベル: 4スペースインデント

  • json: JSON形式（階層構造を JSON オブジェクトとして出力）

    • 全設定表示時:

      {
  "orchestrator": {
    "source_file": "/path/to/orchestrator.toml",
    "settings": {"timeout_per_team_seconds": 600, ...}
  },
  "teams": [
    {
      "source_file": "/path/to/team.toml",
      "settings": {...},
      "members": [
        {
          "source_file": "/path/to/member.toml",
          "settings": {...}
        }
      ]
    }
  ],
  "evaluator": {
    "source_file": "/path/to/evaluator.toml",
    "settings": {...}
  },
  "judgment": {
    "source_file": "/path/to/judgment.toml",
    "settings": {...}
  },
  "prompt_builder": {
    "source_file": "/path/to/prompt_builder.toml",
    "settings": {...}
  }
}

    • 特定キー指定時:

      {
  "class": "OrchestratorSettings",
  "key": "timeout_per_team_seconds",
  "current_value": "600",
  "default_value": "300",
  "source": "TOML",
  "source_type": "toml",
  "type": "int",
  "overridden": true
}

安全機能:

  • 循環参照検出（エラー時に参照パスを表示）

  • 最大再帰深度制限（10レベル）

config list - 設定項目一覧

利用可能な設定項目のスキーマ情報をリスト表示します。

# 全設定項目をリスト表示（テーブル形式）
mixseek config list

# テキスト形式で詳細表示
mixseek config list --output-format text

# JSON形式（プログラム用）
mixseek config list --output-format json

表示内容:

  • テーブル形式: Key, Default, Type, Description の列を表示

  • テキスト形式: Required/Optional でグループ化し、各項目の詳細を表示

  • JSON形式: プログラムで処理可能な JSON 配列形式で出力（key, class_name, raw_key, default, type, description を含む）

注意: このコマンドはスキーマ情報（デフォルト値、型、説明）のみを表示します。実際の設定値や設定ソースを確認するには config show を使用してください。

環境変数設定

環境変数命名規則

環境変数名は以下の規則に従います：

  • プレフィックス: MIXSEEK_

  • ネスト: ダブルアンダースコア (__) で区切る

  • 大文字: すべて大文字

例:

# フラットな設定
export MIXSEEK_WORKSPACE=/path/to/workspace

# ネストされた設定
export MIXSEEK_LEADER__MODEL=openai:gpt-4o
export MIXSEEK_LEADER__TIMEOUT_SECONDS=600
export MIXSEEK_MEMBER__MODEL=google-gla:gemini-2.5-flash-lite

.env ファイル

.env ファイルで環境変数を管理できます：

# .env
MIXSEEK_WORKSPACE=/home/user/workspace
MIXSEEK_LEADER__MODEL=openai:gpt-4o
MIXSEEK_LEADER__TIMEOUT_SECONDS=600

.env ファイルの読み込み：

# 自動読み込み（プロジェクトルートに配置）
mixseek team "タスク" --config team.toml

# 手動読み込み
source .env
mixseek team "タスク" --config team.toml

Article 9 準拠

Configuration Manager は Article 9 (Data Accuracy Mandate) に完全準拠しています：

準拠ポイント

  1. 明示的なデータソース: すべての設定値は明示的なソース（CLI、環境変数、TOML等）から取得

  2. 暗黙的デフォルトなし: ハードコードされたデフォルト値を排除

  3. 適切なエラー伝播: 無効な設定時に明確なエラーメッセージを表示

  4. トレーサビリティ: すべての設定値の出所を追跡可能

実装例

from mixseek.config import ConfigurationManager, OrchestratorSettings

manager = ConfigurationManager()

# 設定読み込み（Article 9準拠）
settings = manager.load_settings(OrchestratorSettings)

# エラーが発生した場合、明確なメッセージが表示される
# 例: "MIXSEEK_WORKSPACE environment variable is not set"

トラブルシューティング

環境変数が反映されない

症状: 環境変数を設定しても反映されない

原因:

  • 環境変数名の誤り

  • 環境変数のスコープ（シェルセッション限定）

解決方法:

# 環境変数の確認
echo $MIXSEEK_WORKSPACE

# 設定されていない場合は設定
export MIXSEEK_WORKSPACE=/path/to/workspace

# 永続化（~/.bashrc または ~/.zshrc に追加）
echo 'export MIXSEEK_WORKSPACE=/path/to/workspace' >> ~/.bashrc
source ~/.bashrc

TOML設定が読み込まれない

症状: TOML設定ファイルが読み込まれない

原因:

  • ファイルパスの誤り

  • TOML構文エラー

解決方法:

# ファイルの存在確認
ls -la team.toml

# TOML構文の検証（Python）
python -c "import tomllib; tomllib.load(open('team.toml', 'rb'))"

優先順位が不明確

症状: どの設定値が使われているか分からない

解決方法:

# 設定値の出所を確認
mixseek config show workspace_path

# デバッグ情報を表示
mixseek team "タスク" --config team.toml --verbose

セキュリティ

機密情報の取り扱い

設定値を表示する際、以下のフィールド名パターンを含む設定は自動的にマスクされます：

  • api_key

  • password

  • secret

  • token

  • credential

  • private_key

  • access_key

Article 9準拠: 機密情報フィールドは明示的なパターンリストで定義されています（暗黙的な推測は行いません）。

例

# 機密情報を含む設定の表示
$ mixseek config show
api_key: [REDACTED]
model: gemini-2.5-flash-lite
workspace_path: /path/to/workspace

機密情報の保護

推奨事項:

  1. 環境変数の使用: API キーやパスワードは環境変数で管理してください

  2. TOMLファイルのGit除外: 機密情報を含む.tomlファイルは.gitignoreに追加してください

  3. アクセス権限の設定: TOMLファイルのパーミッションを適切に制限してください（例: chmod 600 config.toml）

# 良い例: 環境変数で管理
export MIXSEEK_API_KEY="your-secret-key"
mixseek team "タスク" --config team.toml

# 避けるべき: TOMLファイルに直接記載
# [bad] team.toml:
# api_key = "your-secret-key"  # Git履歴に残る可能性

関連ドキュメント