用途定位
OpenSquilla 是一款“令牌高效（token-efficient）的微内核 AI 智能体”，官方口号是“同样的预算，更高的智能密度”。它面向 CLI、Web UI 与各类聊天渠道，目标是在给定预算下用更少的令牌完成更多任务。
主要能力
- 本地模型路由：由本地模型路由器把每一轮请求发送给能够处理它的最便宜模型，从而在保持能力的同时控制成本。
- 统一回合循环：Web UI、CLI 和聊天渠道等所有入口都走同一套 turn loop，使工具调度、重试与决策日志在各入口保持一致。
- 持久记忆与分层沙箱：内置持久记忆与分层沙箱机制。
- 内置网页搜索与端侧嵌入：提供内置 web search 与 on-device embeddings。
- 多提供商支持：可插拔的 provider 层可对接 TokenRhythm、OpenRouter、OpenAI、Anthropic、Ollama、DeepSeek、Gemini、Qwen/DashScope 等 20+ LLM 提供商，无需更改代码或配置架构。
- SquillaRouter：OpenSquilla 的端侧模型路由器，默认推荐配置会安装它及其模型资产。
- 可插拔聊天渠道：基础安装即可支持 Feishu、Telegram、DingTalk、QQ、WeCom、Slack、Discord 等渠道；可选 extras 包括 Matrix 渠道、带端到端加密的 Matrix 渠道，以及通过 WeasyPrint 生成 PDF 的 document-extras。
- 技术报告：官方发布过关于 Agentic Routing 的技术报告，以及 2026-08-22 上线的英文与中文技术报告（引用方式见仓库 Citation）。
使用方式
当前稳定版本为 OpenSquilla 0.5.6，运行平台为 Windows、macOS 与 Linux。官方给出的安装路径包括：
- 桌面安装包：macOS（Apple Silicon）与 Windows x64 分别提供安装程序，0.5.6 桌面安装包把 Vue 控制台与 gateway 运行时打包在 Electron 外壳中。中国大陆下载可使用 OSS 直链别名。升级前需退出正在运行的桌面应用；Windows 从 RC3 升级到 RC4 或更高版本时，应直接运行新安装程序覆盖安装，不要先卸载 RC3，并提前备份 %APPDATA%\OpenSquilla。
- 快速终端安装：使用 uv 将 OpenSquilla 安装到独立环境并自管 Python，无需系统 Python；适用于已发布的 release。安装后运行配置与启动命令。
- 从源码安装：使用 git clone（含 Git LFS）并运行 scripts/install_source.sh 或 scripts/install_source.ps1。该脚本会通过 uv tool install 安装 .[recommended]（含 SquillaRouter、记忆与本地模型），并在 opensquilla-webui 中执行 npm ci 与 npm run build。首次运行通常依赖下载量最大。
- 从源码开发：适用于修改源码、运行测试或调试；需要 uv，使用 uv sync 创建仓库本地 .venv，并以 uv run 执行命令。修改 Web UI 源码后需重新运行 npm run build。
卸载：使用 opensquilla uninstall，默认保留数据，仅移除程序；如需同时删除数据需显式选择。删除前会先排空并停止运行中的 gateway，删除范围限于 OpenSquilla home 目录；Docker/桌面安装会给出引导式移除步骤。桌面或操作系统级应用移除仍依平台而定。
可选安装项方面，多数渠道在基础安装下可用；Matrix 渠道、Matrix 端到端加密（需要 libolm）、WeasyPrint PDF 生成属于需要显式启用的 extras。安装环境变量可参考仓库说明；若 opensquilla 不在 PATH 中，可用 uv tool update-shell 后打开新终端。
适用场景
- 希望在同预算下提升模型使用效率、减少不必要高成本模型调用的个人或团队。
- 需要在 CLI、Web UI、IM/聊天渠道等多个入口使用统一行为的智能体场景。
- 需要对接多个 LLM 提供商、不希望因换模型而改动代码或配置的用户。
- 需要本地或端侧模型路由、持久记忆与沙箱能力的本地化部署场景。
限制与注意事项
- 默认推荐 profile 会安装 SquillaRouter 及其模型资产；core profile 会省略这些依赖。另有 --router disabled 可在保留依赖的情况下于运行时关闭路由器。
- Windows 上 SquillaRouter 自带的 ONNX runtime 还需要 Visual C++ 运行时；源码 PowerShell 安装器会自动经 winget 安装，而快速终端安装（uv tool install）不会。若启动日志出现 DLL load failed 错误需手动安装；在安装完成前，OpenSquilla 会以直接单模型路由继续运行。
- macOS 终端安装中，SquillaRouter 的 LightGBM 运行时可能还需要系统 OpenMP 库。桌面应用自带所需运行时，但快速终端安装不会安装 Homebrew/系统库。若日志出现 Library not loaded: @rpath/libomp.dylib，可执行 brew install libomp 后重启 gateway；安装前同样以直接单模型路由继续运行。
- 本地 checkout 只有在 Web UI 构建完成后才能工作；VCS URL checkout 没有生成产物，会被有意拒绝。
- 隐私方面：OpenSquilla 对 V1 统计与两个 V2 统计流使用既有的 Network 上报开关。上报默认开启，可在隐私设置中关闭，无单独的 onboarding 选项或同意弹窗。可靠性诊断记录应用与 Gateway 启动、崩溃、回合、工具、文件解析、更新与会话性能等有界的操作结果；产品与增长分析记录客户端启动、产品活动以及一次性获取、onboarding、应用就绪、注册与首次成功回合等里程碑。两路数据保留各自的会话/旅程标识、持久队列、上传端点与保留策略。应用事件还携带由本地 OS 机器标识派生的一次性、应用专属 device_id，用于按设备去重统计。
