用途：在本地从源码安装、配置并启动 FireRed-OpenStoryline，或修复已有源码检出。适用于 macOS、Linux 或 WSL 的 POSIX shell。
主要能力：克隆 GitHub 仓库；创建 Python 环境；安装 Python 依赖；下载 .storyline 模型与 resource/ 资源；填充 config.toml；启动 MCP 和 Web 服务；解释常见安装与文档缺口。
前置条件：git、Python >= 3.11、ffmpeg、wget、unzip；docker、conda 为可选。缺少 ffmpeg、wget 或 unzip 时先用系统包管理器安装，例如 macOS：brew install ffmpeg wget unzip；Debian/Ubuntu：sudo apt-get update 和 sudo apt-get install -y ffmpeg wget unzip。无可用包管理器或权限时应停止并报告缺失依赖。
环境选择：优先使用已存在且通过版本检查的 Python（系统、conda 或 pyenv，需基础标准库可用），可用 /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 -m venv .venv。找到后始终创建仓库内 .venv，并用 .venv/bin/python 继续安装、校验和启动。
推荐安装路径（仓库根目录）：/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，至少填 llm.model、llm.base_url、llm.api_key 与 vlm.model、vlm.base_url、vlm.api_key；可选 search_media.pexels_api_key 和 generate_voiceover.providers.* 的 TTS 密钥（选一个提供方）。
验证：运行 .venv/bin/pip check；PYTHONPATH=src .venv/bin/python -c "from open_storyline.config import load_settings; load_settings('config.toml'); print('config_ok')"；确认 .storyline/models/transnetv2-pytorch-weights.pth 与 resource/bgms 存在。
启动：手动方式为 PYTHONPATH=src .venv/bin/python -m open_storyline.mcp.server，另开一个 shell 运行 PYTHONPATH=src .venv/bin/python -m uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005。服务为长驻进程，不要等待其正常退出，以启动日志或监听端口确认成功，必要时在不同 shell 中保持运行。
限制与常见问题：download.sh 慢或中断时让 wget 续传，并以解压结果而非进度条为准；Web/MCP 绑定 127.0.0.1 或 0.0.0.0 报 operation not permitted 时需申请本地监听端口权限，非必要优先 127.0.0.1。汇报时区分已安装、仍在下载、仍缺配置和监听地址，资源包未完成时不得声称安装完成。