vellium

# 维利姆 — 本地优先的 AI 工作台，适用于聊天、角色扮演和写作 [](https://github.com/tg-prplx/vellium/releases/latest) [](https://github.com/tg-prplx/vellium/releases) [](https://github.com/tg-prplx/vellium/stargazers) [](./LICENSE) <img width="1440" height="913" alt="image" src="https://github.com/user-attachments/assets/b81aeaa9-7f40-44e0-b739-deb6d91b8edf" /> <p align="center"><strong>一个桌面应用程序，用于角色聊天、多角色角色扮演、长篇写作、RAG、MCP 工具、插件和本地模型。</strong></p> 维利姆是一个免费、开源的桌面 AI 工作空间，与 OpenAI 兼容的 API、OpenRouter、LM Studio、Ollama、KoboldCpp 和自定义端点一起工作。您的聊天、角色、项目和知识保留在本地 SQLite 数据库中。 <p align="center"> <a href="https://github.com/tg-prplx/vellium/releases/latest"><strong>下载适用于 macOS、Windows 或 Linux 的版本</strong></a> · <a href="./docs/vellium/getting-started.md">快速入门</a> · <a href="./docs/vellium/README.md">用户指南</a> </p> <img width="1440" height="911" alt="image" src="https://github.com/user-attachments/assets/54f90253-b51a-4652-bd6e-5023f078f9a8" /> ## 当前版本 - 最新版本：[`v1.0.0`](https://github.com/tg-prplx/vellium/releases/tag/v1.0.0) - 桌面构建：macOS (`arm64`, `x64`), Windows (`x64`), Linux (`x64` AppImage). - 发布构建未签名。macOS 和 Windows 可能需要在第一次启动时进行手动确认。 - 该应用程序日常可用，但仍在快速迭代。预计在代理、工具调用和提供商兼容性方面会有积极的迭代。 ## 为什么选择维利姆？ - **自带模型。** 使用云 API 或本地模型，而不将工作空间锁定到一个提供商。 - **为故事而建，而不仅仅是提示。** 角色、人物、LoreBooks、场景状态、分支对话和自动多角色回合生活在一起。 - **超越聊天。** 组织项目、章节和场景；重写、扩展、总结和导出到 DOCX 或 Markdown。 - **给予模型有用的上下文。** 通过 RAG 和脚本世界事实连接知识集合。 - **本地扩展。** 添加 MCP 工具、插件选项卡、部件、主题、端点适配器和桌面宠物。 - **保持控制。** 本地存储、仅本地联网模式和强大的工具的显式安全门。 ## 用户文档 - 详细用户指南：[`docs/vellium/README.md`](./docs/vellium/README.md) ## 重要 - 使用 `npm run dev` 进行日常开发。 - 使用 `npm run dev:electron` 测试真正的桌面外壳。 - 使用 `npm run dist:mac`、`npm run dist:win` 或 `npm run dist:linux` 进行平台捆绑。 - CI 在推送 `v*` 标签时发布 GitHub Release 资产。 - 在开发过程中，本地数据存储在 `data/` 中，在打包构建中存储在 Electron 用户数据目录中。 ## 技术栈 - Electron - React + TypeScript + Vite - Express - SQLite + `better-sqlite3` - Tailwind CSS ## 核心功能 ### 代理 - 专门的 `Agents` 工作空间，包含询问、构建和研究模式。 - 用于列出、读取、搜索、编辑、移动、删除和差异文件的空间工具。 - 用于测试/构建的可选命令执行，带有单独的安全门控，用于 shell 类命令、网络命令、破坏性文件操作和 git 写入。 - 当支持时，使用 JSON-schema 响应进行 OpenAI 兼容的结构化规划。 - 运行中修正、终止/恢复/重试、事件跟踪、推理跟踪和部分响应恢复。 - 长代理线程的上下文管理，包括自动压缩、继续提示、重复只读调用保护和编辑/删除后的过期运行清理。 ### 聊天 / 角色扮演 - 分支聊天历史。 - 编辑、删除、重新发送、重新生成。 - 带有自动回合的多角色聊天。 - 角色扮演控制：提示堆栈、作者备注、场景状态、预设、角色。 - LoreBook / 世界信息支持，包括 SillyTavern 兼容的世界信息导入/导出。 - 推理支持，包括流式推理字段和 `<think>...</think>` 解析。 - 视觉附件和聊天附件。 - OpenAI 兼容的聊天/补全提供商的 MCP 工具调用，具有文本工具调用回退解析，不适用于干净地发出原生工具调用的提供商。 ### 写作 - 项目、章节、场景、大纲。 - 摘要、重写/扩展流程、一致性工具。 - 角色感知写作工作流。 - DOCX 导入和 DOCX / Markdown 导出。 - 写作侧 RAG 支持。 ### 知识 / RAG - 知识集合和摄入。 - 聊天和写作的 RAG 绑定。 - 嵌入和重新排序模型设置。 - 基于检索的混合基础。 ### 提供商 - OpenAI 兼容的提供商。 - KoboldCpp 支持。 - 非 OpenAI / 非 Kobold 后端的自定义端点适配器。 - OpenAI、LM Studio、Ollama、KoboldCpp、OpenRouter 和自定义 OpenAI 兼容端点的预设。 - 提供商的 `/models` 端点缺失、为空或提供商特定的手动回退模型。 - 用于翻译/压缩/TTS/RAG 的独立模型。 - 提供商拒绝不支持的采样字段的 API 参数转发控制。 ### 本地化 - 内置 UI 翻译：英语、俄语、日语和中文。 - 在 `设置` 中选择语言，默认为英语。 ### 桌面宠物 - 可选的始终置顶的桌面伴侣窗口。 - 动画状态（空闲、跳跃、弹出、摇摆、旋转、摇晃、弹跳）带有可配置的状态预设。 - 直接从桌面与宠物聊天，包括附件和可配置的上下文令牌限制。 ### 插件 / 扩展 - 插件的工具栏选项卡。 - 聊天、写作和设置插槽中的插件小部件。 - 工具栏、消息、作曲家和写作中的插件操作。 - 插件设置、权限、插件本地存储。 - `Pluginfile` 安装/导出。 - 插件主题。 - 自定义检查字段。 - 自定义端点适配器。 ## 需求 - Node.js + npm。建议使用 Node.js 20+，因为 CI 构建使用 Node 20。 - Python 3 + Pillow 用于图标生成： ```bash pip install pillow ``` 注意： - `better-sqlite3` 是原生的。请保持开发/构建 Node 版本的一致性。 - 如果原生 ABI 损坏，请运行 `npm run rebuild:native`。 ## 快速入门 1. 安装依赖： ```bash npm install ``` 2. 启动前端 + 本地 API： ```bash npm run dev ``` 3. 打开： `http://localhost:1420` ## Electron 开发 ```bash npm run dev:electron ``` 这会构建 Electron 入口点，启动本地服务器，启动 Vite，等待健康检查，然后启动 Electron。 ## 一键引导 macOS： ```bash ./setup-and-run-dev.sh ``` Windows： ```bat setup-and-run-dev.bat ``` 这些脚本尝试： - 安装 Node.js LTS， - 运行 `npm install`， - 启动 `npm run dev`。 ## 构建桌面应用程序 所有桌面目标： ```bash npm run dist ``` macOS 独有： ```bash npm run dist:mac ``` Windows 独有： ```bash npm run dist:win ``` Linux AppImage 独有： ```bash npm run dist:linux ``` 构建输出将转到 `release/`。 ## GitHub Actions 工作流： - `.github/workflows/build-desktop.yml` 它的作用： - 构建 macOS（`x64`，`arm64`）、Windows（`x64`）和 Linux（`x64` AppImage）捆绑包， - 上传工作流工件， - 在 `v*` 标签推送时发布 GitHub Release 资产。 ## 插件 维利姆现在有一个真正的插件系统。 插件功能： - 工具栏选项卡， - 插槽小部件， - 模态和内联操作， - 插件本地设置， - 权限控制的 API 访问， - 插件主题， - `Pluginfile` 导入/导出。 有用文档： - [`docs/plugins/README.md`](./docs/plugins/README.md) 运行时插件位置： - 用户插件：`data/plugins` - 捆绑插件：`data/bundled-plugins` 重要： - 插件是本地扩展，而不是受信任的公共插件市场模型， - 插件权限应在启用写入访问之前进行审查， - 插件设置和权限在 `设置 -> 插件` 中管理。 ### Pluginfile `Pluginfile` 是便携式单文件插件包格式。 您可以： - 从 `设置 -> 插件 -> 安装 Pluginfile` 安装插件， - 从 `设置 -> 插件 -> 导出 Pluginfile` 导出现有插件。 捆绑插件也可以导出为 `Pluginfile`。 ## 主题 维利姆支持： - 内置深色/浅色主题， - 插件提供的主题。 捆绑主题包： - Catppuccin - Latte - Frappe - Macchiato - Mocha 主题插件也会传播到插件 UI 工具包样式。 ## 扩展 API 维利姆包含一个超出正常插件的扩展层： - 自定义检查字段， - 自定义端点适配器， - 通过 `vellium.generate(...)` 和相关 SDK 命名空间的统一插件端后端访问。 这使得以下成为可能： - 添加检查控件， - 集成非 OpenAI / 非 Kobold 后端， - 构建针对稳定主机端契约的工作流插件。 ## TTS 维利姆支持 OpenAI 兼容的 TTS： - 可配置的端点， - 模型选择， - 语音选择， - 每条消息的 TTS 操作。 ## 应用程序图标 生成图标： ```bash npm run build:icons ``` 生成的文件： - `build/icon.png` - `build/icon.icns` - `build/icon.ico` ## 有用的脚本 - `npm run dev` — 前端 + 服务器。 - `npm run dev:frontend` — 仅 Vite。 - `npm run dev:server` — 仅 Express API。 - `npm run dev:electron` — Electron + 前端 + 服务器。 - `npm run build` — 前端生产构建。 - `npm run build:server` — 捆绑服务器构建。 - `npm run build:desktop` — 完整的桌面构建管道，无发布。 - `npm run dist` — 打包当前主机/CI 运行器支持的所有桌面目标。 - `npm run dist:mac` / `npm run dist:win` / `npm run dist:linux` — 打包特定桌面目标。 - `npm run rebuild:native` — 重建 `better-sqlite3`。 - `npm run test` — Vitest。 ## 数据存储 - 开发环境：本地 `data/` - 打包应用程序：`SLV_DATA_DIR` 映射到 Electron `userData/data` ## 故障排除 ### `ERR_DLOPEN_FAILED` / `NODE_MODULE_VERSION ...` 原因：`better-sqlite3` 是针对不同的 Node ABI 构建的。 解决方法： ```bash npm run rebuild:native ``` 如果需要，删除 `node_modules` 并重新安装。 ### `EADDRINUSE: address already in use :::3001` 原因：旧的服务器进程仍然存在。 解决方法： ```bash lsof -nP -iTCP:3001 -sTCP:LISTEN kill -TERM <pid> ``` ### 打包构建中的空白窗口或长时间启动 检查： - 使用完整的桌面构建， - `server-bundle.mjs` 存在， - 捆绑服务器到达 `/api/health`。 ### 插件不加载 检查： - 插件在 `设置 -> 插件` 中启用， - 授予所需的权限， - 更改插件文件后，使用 `重新加载插件`， - 更改 SDK/运行时后，重启 `npm run dev:electron`。 ## 项目结构 - `src/` — React 前端 - `server/` — Express API - `electron/` — Electron 主进程 + 预加载 - `scripts/` — 构建/开发辅助脚本 - `docs/` — 文档、插件文档、资产 - `data/` — 运行时数据、用户插件、捆绑插件 - `build/` — electron-builder 资源 - `release/` — 打包桌面输出