openstoryline-install
Install, configure, and start FireRed-OpenStoryline from source on a local machine. Use when a user asks to set up OpenStoryline, troubleshoot installation, download required resources, fill config.toml API keys, or launch the MCP and web services, as well as Chinese requests like “安装 OpenStoryline”, “配置 OpenStoryline”, “启动 OpenStoryline”, “把 OpenStoryline 跑起来”, “修复 OpenStoryline 安装问题”, or “排查 OpenStoryline 启动失败”.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- openstoryline-install
- description
- Install, configure, and start FireRed-OpenStoryline from source on a local machine. Use when a user asks to set up OpenStoryline, troubleshoot installation, download required resources, fill config.toml API keys, or launch the MCP and web services, as well as Chinese requests like “安装 OpenStoryline”, “配置 OpenStoryline”, “启动 OpenStoryline”, “把 OpenStoryline 跑起来”, “修复 OpenStoryline 安装问题”, or “排查 OpenStoryline 启动失败”.
03 SKILL.md 正文
OpenStoryline Install
Use this skill when the task is to install or repair a local source checkout of FireRed-OpenStoryline.
Keep the workflow deterministic:
- Confirm the repo path and read the current README.md and config.toml.
- Detect local prerequisites before changing anything.
- Prefer a local
venvinstall unless the user explicitly asks for Docker orconda. - Download resources only after Python dependencies succeed.
- Validate imports and config loading before claiming success.
- This skill assumes macOS, Linux, or WSL with a POSIX shell.
What This Skill Covers
- Clone the GitHub repo if needed
- Create a Python environment
- Install Python dependencies
- Download
.storylinemodels andresource/assets - Fill
config.tomlmodel settings - Start MCP and web servers
- Explain common installation/documentation gaps
Preconditions
Check these first:
git- Python
>= 3.11 ffmpegwgetunzip
Optional:
dockerconda
If ffmpeg, wget, or unzip are missing, install them through the OS package manager before continuing.
Examples:
-
macOS with Homebrew:
brew install ffmpeg wget unzip -
Debian/Ubuntu:
sudo apt-get update sudo apt-get install -y ffmpeg wget unzip
If no supported package manager or permission is available, stop and report the missing system dependency clearly.
Interpreter selection
First prefer any interpreter that already exists and passes version checks:
- A system Python
>= 3.11 - An already available conda Python
>= 3.11 - An already available pyenv Python
>= 3.11, but only if basic stdlib modules work
Validate candidate interpreters before using them:
/path/to/python -c "import ssl, sqlite3, venv; print('stdlib_ok')"
If no supported interpreter already exists, peferr conda fallback:
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
After a supported interpreter is found, always create a repo-local .venv and continue using .venv/bin/python for install, config validation, and service startup.
Do not duplicate the rest of the workflow for pyenv or conda unless the user explicitly asks to stay inside a conda environment.
Preferred Install Path
From the repo root:
/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
Notes:
download.shpulls both model weights and a large resource archive. It can take a long time and may resume after network drops.- The resource download is required for a full local run, not just the Python package install.
Configuration
Before starting the app, update config.toml.
You can use scripts/update_config.py.
At minimum, fill:
.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
Optional but common:
search_media.pexels_api_keyfor searching media- TTS provider keys under
generate_voiceover.providers.*(choose one provider)
Verification
Run these checks before saying installation is complete:
.venv/bin/pip check
PYTHONPATH=src .venv/bin/python -c "from open_storyline.config import load_settings; load_settings('config.toml'); print('config_ok')"
Also confirm key resources exist:
test -f .storyline/models/transnetv2-pytorch-weights.pth
test -d resource/bgms
Start Services
There are two common paths. These are long-running processes. Do not wait for them to exit normally. Treat successful startup log lines or confirmed listening ports as success, and keep the services running in separate shells/sessions as needed.
Manual start:
PYTHONPATH=src .venv/bin/python -m open_storyline.mcp.server
In a second shell:
PYTHONPATH=src .venv/bin/python -m uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005
Expected Outputs
After a successful install:
.venv/exists- MCP listens on the configured local port (commonly
127.0.0.1:8001) - Web listens on the configured web port (commonly
127.0.0.1:8005, thoughrun.shdefaults may differ)
Common Problems
download.sh is slow or interrupted
Symptom:
- Large downloads stall or reconnect
Fix:
- Let
wgetcontinue; it supports resume behavior here - Verify extracted outputs instead of trusting the progress meter
Web/MCP server fails to bind
Symptom:
operation not permittedwhile binding127.0.0.1or0.0.0.0
Fix:
- In agent sandboxes, request permission to open local listening ports
- Prefer
127.0.0.1over0.0.0.0unless external access is required
Response Pattern
When reporting status to the user, separate:
- what is installed
- what is still downloading
- what config is still missing
- what address the service is listening on
Do not say "installation complete" if only the Python packages are installed but the resource bundle is still missing.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.