openstoryline-install

OpenStoryline 安装

当任务是安装或修复 FireRed-OpenStoryline 的本地源代码检出版本时，使用此技能。

保持工作流具有确定性：

1. 确认仓库路径，并读取当前的 README.md 和 config.toml。
2. 在进行任何更改前，检测本地前置条件。
3. 除非用户明确要求使用 Docker 或 conda，否则优先使用本地 venv 安装。
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，请先通过操作系统的软件包管理器安装，再继续。

示例：

• 使用 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 提供商密钥（选择一个提供商）

验证

在表示安装完成前，运行以下检查：

.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

启动服务

有两种常见方式。这些进程会持续运行。不要等待它们正常退出。将成功启动日志或已确认的监听端口视为成功，并根据需要在不同的 shell/会话中让服务持续运行。

手动启动：

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

预期输出

成功安装后：

• .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 沙箱中，请求开放本地监听端口的权限
• 除非需要外部访问，否则优先使用 127.0.0.1 而不是 0.0.0.0

响应模式

向用户报告状态时，应分别说明：

• 已安装的内容
• 仍在下载的内容
• 仍缺少的配置
• 服务正在监听的地址

如果只安装了 Python 包，但资源包仍然缺失，就不要说“安装完成”。