opensquilla

环境要求

• Python 3.12+（使用 uv 安装时会自动管理 Python，无需系统 Python）
• 支持 Windows、macOS、Linux
• 首次安装需要网络访问，以下载 release wheel 及 ONNX Runtime、LightGBM、NumPy、tokenizers 等依赖
• 若选择源码安装：需要 Git、Git LFS 和 Node.js/npm 环境
• 若选择桌面版：macOS Apple Silicon 或 Windows x64

安装与启动步骤

1. 1安装 uv

   uv 会把 OpenSquilla 装进独立环境并自管 Python。若 uv --version 已可用则跳过本步。Windows 用 PowerShell 安装。

   curl -LsSf https://astral.sh/uv/install.sh | sh
   . "$HOME/.local/bin/env"

   复制

2. 2安装 OpenSquilla

   从 GitHub Release 安装 0.5.4 的正式 wheel，默认 recommended 额外依赖含 SquillaRouter 运行时，需联网下载。

   uv tool install --python 3.12 "opensquilla[recommended] @ https://github.com/TokenRhythm/opensquilla/releases/download/v0.5.4/opensquilla-0.5.4-py3-none-any.whl"

   复制

3. 3初始化配置

   运行引导流程完成初始配置。若提示找不到 opensquilla 命令，请新开一个终端或重跑上一步的 PATH 命令。

   opensquilla onboard

   复制

4. 4启动网关

   启动 OpenSquilla 网关运行时，即 README 给出的正式启动方式。保持该终端窗口运行。

   opensquilla gateway run

   复制

5. 5可选：源码安装

   想跟随 main 分支、从本地检出运行而不修改代码时使用。需先装 Git LFS，克隆后拉取模型资源，再跑安装脚本。

   git lfs install
   git clone https://github.com/TokenRhythm/opensquilla.git
   cd opensquilla
   git lfs pull --include="src/opensquilla/squilla_router/models/**"
   bash scripts/install_source.sh

   复制

如何确认成功

执行 opensquilla gateway run 后网关进程保持运行且无原生库加载报错；桌面版可正常打开并加载控制器界面。

常见问题

注意事项

• 正式版 wheel 和桌面安装包已内置 Vue 控制台，无需安装 Node.js 或 npm。
• 源码安装每次都会在 opensquilla-webui 里执行 npm ci 和 npm run build，首次依赖下载量最大。
• 终端安装的 ~/.opensquilla 与桌面版 profile 相互独立，如需迁移须在 Settings 中显式操作。
• v0.5.4 的 Windows 安装包仍未签名，SmartScreen 可能需要时间建立发布者信誉。