OpenStoryline 安装

当任务是安装或修复本地 FireRed-OpenStoryline 源码副本时，请使用此技能。

保持工作流的确定性：

1. 确认仓库路径，并读取当前的 README.md 和 config.toml 文件。
2. 在执行任何变更前，先检测本地前置依赖项。
3. 默认优先采用本地 venv 安装方式；仅当用户明确要求时，才使用 Docker 或 conda。
4. 仅在 Python 依赖成功安装后，才下载资源文件。
5. 在声明安装成功前，必须验证模块导入和配置加载是否正常。
6. 本技能假设运行环境为 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（使用 Homebrew）：

  brew install ffmpeg wget unzip
  

• Debian/Ubuntu：

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

若无可用的受支持包管理器，或无权限执行安装，请立即中止并清晰报告缺失的系统依赖项。

Python 解释器选择

优先选用已存在且满足版本要求的解释器：

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 单独重复其余工作流步骤。

克隆仓库

若尚未拥有本地仓库，请首先克隆：

git clone https://github.com/FireRedTeam/FireRed-OpenStoryline.git
cd FireRed-OpenStoryline

推荐安装路径

从仓库根目录执行：

/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 提供商密钥（任选其一）

验证

在声明安装完成前，请执行以下检查：

.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

启动服务

有两种常见启动方式。这些是长期运行的进程，请勿等待其自然退出。以日志中出现成功启动提示、或确认端口已监听作为成功标志；必要时，请在独立终端/会话中保持服务持续运行。

手动启动 MCP 服务：

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

在另一个终端中启动 Web 服务：

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

解决方法：

• 在 agent sandbox 环境中，需申请本地监听端口的开放权限
• 除非需要外部访问，否则优先使用 127.0.0.1 而非 0.0.0.0

响应模式

向用户汇报状态时，请明确区分以下几类信息：

• 已完成安装的内容
• 仍在下载中的内容
• 仍缺失的配置项
• 服务实际监听的地址与端口

若仅完成了 Python 包安装，而资源包仍未下载完成，则不得声明“安装完成”。