openstoryline-install

OpenStoryline のインストール

FireRed-OpenStoryline のローカルソースチェックアウトをインストールまたは修復するタスクでは、このスキルを使用してください。

ワークフローは決定論的に進めてください。

1. リポジトリのパスを確認し、現在の README.md と config.toml を読みます。
2. 変更を加える前に、ローカルの前提条件を確認します。
3. ユーザーから Docker または conda の指定がない限り、ローカルの venv を使ったインストールを優先します。
4. Python の依存関係のインストールに成功してから、リソースをダウンロードします。
5. 成功を報告する前に、インポートと設定の読み込みを検証します。
6. このスキルでは、POSIX シェルを使用する macOS、Linux、または WSL を前提としています。

このスキルの対象範囲

• 必要に応じて GitHub リポジトリをクローンする
• Python 環境を作成する
• Python の依存関係をインストールする
• .storyline モデルと resource/ アセットをダウンロードする
• config.toml のモデル設定を入力する
• MCP サーバーと Web サーバーを起動する
• インストールやドキュメントに関する一般的な不足点を説明する

前提条件

まず、次の項目を確認します。

• git
• Python >= 3.11
• ffmpeg
• wget
• unzip

任意：

• docker
• conda

ffmpeg、wget、または unzip がない場合は、続行する前に OS のパッケージマネージャーを使ってインストールしてください。

例：

• Homebrew を使う macOS：

  brew install ffmpeg wget unzip
  

• Debian/Ubuntu：

  sudo apt-get update
  sudo apt-get install -y ffmpeg wget unzip
  

対応するパッケージマネージャーがない、または使用権限がない場合は、作業を中止し、不足しているシステム依存関係を明確に報告してください。

インタープリターの選択

まず、すでに存在し、バージョンチェックに合格するインタープリターを優先します。

1. システムにインストール済みの Python >= 3.11
2. すでに利用可能な conda の Python >= 3.11
3. すでに利用可能な pyenv の Python >= 3.11。ただし、基本的な標準ライブラリモジュールが動作する場合に限ります。

使用前に、候補となるインタープリターを検証してください。

/path/to/python -c "import ssl, sqlite3, venv; print('stdlib_ok')"

対応するインタープリターが見つからない場合は、conda によるフォールバックを優先します。

conda create -y -n openstoryline-py311 python=3.11
conda run -n openstoryline-py311 python --version
conda run -n openstoryline-py311 python -m venv .venv

対応するインタープリターが見つかったら、必ずリポジトリ内に .venv を作成し、インストール、設定の検証、サービスの起動には .venv/bin/python を使い続けてください。

ユーザーから conda 環境内にとどまるよう明示的な指定がない限り、pyenv または conda 用にワークフローの残りを重複して実行しないでください。

推奨するインストール方法

リポジトリのルートから実行します。

/path/to/python -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
bash download.sh

注意：

• download.sh はモデルの重みと大容量のリソースアーカイブの両方を取得します。時間がかかることがあり、ネットワークが切断された後に再開する場合があります。
• Python パッケージのインストールだけでなく、ローカルで完全に実行するにはリソースのダウンロードが必要です。

設定

アプリを起動する前に、config.toml を更新してください。

scripts/update_config.py を使用できます。

最低限、次の項目を入力します。

.venv/bin/python scripts/update_config.py --config ./config.toml --set llm.model=REPLACE_WITH_REAL_MODEL
.venv/bin/python scripts/update_config.py --config ./config.toml --set llm.base_url=REPLACE_WITH_REAL_URL
.venv/bin/python scripts/update_config.py --config ./config.toml --set llm.api_key=sk-REPLACE_WITH_REAL_KEY

.venv/bin/python scripts/update_config.py --config ./config.toml --set vlm.model=REPLACE_WITH_REAL_MODEL
.venv/bin/python scripts/update_config.py --config ./config.toml --set vlm.base_url=REPLACE_WITH_REAL_URL
.venv/bin/python scripts/update_config.py --config ./config.toml --set vlm.api_key=sk-REPLACE_WITH_REAL_KEY

任意ですが、よく使われる設定：

• メディア検索用の search_media.pexels_api_key
• generate_voiceover.providers.* の下にある TTS プロバイダーキー（いずれか 1 つのプロバイダーを選択）

検証

インストール完了を報告する前に、次のチェックを実行してください。

.venv/bin/pip check
PYTHONPATH=src .venv/bin/python -c "from open_storyline.config import load_settings; load_settings('config.toml'); print('config_ok')"

また、主要なリソースが存在することを確認します。

test -f .storyline/models/transnetv2-pytorch-weights.pth
test -d resource/bgms

サービスの起動

一般的な方法は 2 つあります。これらは長時間実行されるプロセスです。正常に終了するまで待たないでください。起動成功を示すログ行、またはポートのリッスンを確認できたら成功と判断し、必要に応じて別々のシェルやセッションでサービスを実行し続けてください。

手動で起動する場合：

PYTHONPATH=src .venv/bin/python -m open_storyline.mcp.server

2 つ目のシェルで実行します。

PYTHONPATH=src .venv/bin/python -m uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005

想定される出力

インストールが成功すると、次の状態になります。

• .venv/ が存在する
• MCP が設定されたローカルポート（通常は 127.0.0.1:8001）でリッスンする
• Web が設定された Web ポート（通常は 127.0.0.1:8005。ただし、run.sh のデフォルトは異なる場合があります）でリッスンする

よくある問題

download.sh が遅い、または中断される

症状：

• 大容量のダウンロードが停止したり、再接続を繰り返したりする

対処方法：

• wget の処理を続けます。この場合、ダウンロードの再開に対応しています。
• 進捗表示をそのまま信用せず、展開されたファイルを確認します。

Web/MCP サーバーがバインドに失敗する

症状：

• 127.0.0.1 または 0.0.0.0 へのバインド時に operation not permitted が発生する

対処方法：

• エージェントのサンドボックスでは、ローカルのリッスンポートを開く権限を要求します。
• 外部アクセスが必要でない限り、0.0.0.0 より 127.0.0.1 を優先します。

応答パターン

ユーザーにステータスを報告する際は、以下を分けて伝えてください。

• インストール済みのもの
• ダウンロード中のもの
• まだ不足している設定
• サービスがリッスンしているアドレス

Python パッケージがインストール済みでも、リソースバンドルがまだない場合は、「インストール完了」と言わないでください。