1. 项目概述Vellium一个桌面端的AI创作与对话工作台如果你和我一样既沉迷于与AI进行深度角色扮演和创意对话又需要它来辅助严肃的写作项目同时还在为如何有效管理自己的知识库和插件而头疼那么Vellium的出现可能就是我们一直在寻找的“瑞士军刀”。这不是一个简单的聊天客户端而是一个集成了AI对话、角色扮演、长篇写作、知识库管理和插件扩展的桌面级工作台。它基于我们熟悉的Electron、React和SQLite技术栈构建将本地优先的理念贯彻到底让你在享受云端大模型强大能力的同时也能牢牢掌控自己的数据和工作流。简单来说Vellium试图解决一个核心矛盾我们手头的AI工具往往功能单一。聊天工具只管聊天写作工具只管写作知识管理又是另一套系统。当你想把一次精彩的RP对话灵感扩展成小说章节或者想引用自己知识库里的设定时就不得不在多个应用间反复横跳、复制粘贴。Vellium的野心就是把这些环节无缝地整合在一个界面里。它支持多角色自动轮转的聊天、带有分支的对话历史、与SillyTavern兼容的LoreBook导入也提供了从项目、章节到场景的完整写作工作流甚至还内置了RAG检索增强生成引擎让你能基于自己的文档库进行问答和创作。更吸引开发者的是它提供了一个真实可扩展的插件系统。你可以通过插件添加工具栏标签、在聊天或写作界面嵌入小组件、创建自定义操作甚至集成非标准的大模型后端。这意味着Vellium不仅仅是一个“成品”应用更是一个可以按照你心意深度定制的创作环境。接下来我将从一个实际使用者和轻度开发者的角度带你深入拆解Vellium的设计、部署、核心功能的使用以及那些官方文档可能没细说的“坑”和技巧。2. 技术栈选型与架构设计解析Vellium的技术选型清晰地反映了其“功能强大但保持轻量、本地优先且可深度定制”的产品定位。理解这套技术栈不仅能帮我们更好地使用它也能在遇到问题时知道该从哪个层面去排查。2.1 前端与UI层React TypeScript Vite Tailwind CSS前端采用了目前业界非常主流的React TypeScript组合。TypeScript的引入对于这样一个功能复杂的应用至关重要它能在开发阶段就捕获大量的类型错误尤其是对于插件API、数据模型这类需要严格定义接口的地方能极大提升代码的健壮性和开发体验。构建工具选择了Vite而非传统的Create React App或Webpack这带来了极快的热更新速度对于需要频繁调整UI的开发者来说体验提升明显。UI样式方面Tailwind CSS的使用使得构建和维护一套复杂且一致的界面变得高效。从项目截图来看Vellium的界面风格现代且紧凑Tailwind的效用类Utility-First模式非常适合快速实现这种设计。同时Tailwind也为主题系统打下了良好基础内置的深色/浅色主题以及Catppuccin等主题包都可以通过覆盖一套设计令牌Design Tokens来实现并能够通过插件机制进行扩展。2.2 后端与数据层Express SQLite better-sqlite3这是Vellium架构中非常关键且有趣的部分。它没有采用纯粹的客户端存储如IndexedDB而是在本地运行了一个小型的Express API服务器。这个设计带来了几个显著优势职责分离前端渲染层与后端业务逻辑、数据持久化层分离架构清晰。前端通过HTTP API与后端通信这与开发Web应用的模式一致降低了理解成本。插件支持本地API服务器为插件提供了稳定的后端接入点。插件不仅可以操作UI还可以通过权限控制的API访问核心数据和服务这为实现功能强大的插件如自定义知识库处理流程提供了可能。开发友好在开发模式下你可以分别启动前端npm run dev:frontend和后端npm run dev:server独立进行调试。数据存储选择了SQLite并通过better-sqlite3这个原生模块进行访问。SQLite是一个服务器端的数据库它将所有数据存储在一个单一的磁盘文件中非常适合Vellium这种桌面应用。它能提供关系型数据库的强大查询能力用于管理复杂的聊天分支、写作项目结构、知识库索引等同时保持零配置和轻量级。better-sqlite3相比Node.js标准的sqlite3包性能通常更好API也更同步化但代价是它是一个原生模块Native Addon。重要提示关于better-sqlite3的“坑”原生模块需要针对特定的Node.js版本和操作系统进行编译。这是Vellium安装和跨环境迁移时最容易出问题的地方。如果你在运行时报错ERR_DLOPEN_FAILED或提示NODE_MODULE_VERSION不匹配几乎可以肯定是这个模块的二进制文件与当前Node.js环境不兼容。此时必须执行npm run rebuild:native来重新编译它。在切换Node.js版本后也建议先删除node_modules文件夹再重新执行npm install和重建命令。2.3 桌面外壳ElectronElectron负责将Web技术构建的应用打包成跨平台的桌面应用。它提供了访问操作系统原生API如文件系统、系统托盘、菜单栏的能力这是实现真正“桌面应用”体验的基础。Vellium利用Electron来管理应用窗口、处理应用生命周期如关闭时保存数据并定义了开发和生产环境下的不同数据存储路径。在开发中npm run dev:electron命令会启动一个完整的流程先构建Electron的入口文件然后启动本地API服务器和Vite开发服务器等待健康检查通过后最后启动Electron窗口。这个过程模拟了打包后的应用运行环境是测试插件、本地API等完整功能的最佳方式。2.4 整体数据流与通信理解了各层技术我们就能勾勒出Vellium运行时的大致数据流用户操作在Electron窗口中用户与React前端界面交互如发送消息、保存文档。前端请求React组件通过封装好的函数或SDK向http://localhost:3001开发时发起API请求。后端处理本地Express服务器接收到请求执行相应的业务逻辑如调用AI接口、读写SQLite数据库、处理知识库文档。数据持久化业务逻辑通过better-sqlite3驱动读写本地的SQLite数据库文件。响应返回Express服务器将处理结果如AI回复、查询到的数据以JSON格式返回给前端。UI更新React前端收到响应后更新状态并重新渲染界面。对于插件它们可以“注入”到前端作为UI组件和后端通过扩展API。前端插件通过Vellium提供的Hooks和上下文来渲染UI和触发动作后端插件则可以通过权限系统访问vellium.generate()等核心SDK功能实现自定义的逻辑。3. 从零开始环境搭建与首次运行虽然项目提供了便捷的一键脚本但了解手动步骤能让你在脚本失效或需要自定义时心里有底。我们以macOS/Linux环境为例Windows下的命令逻辑类似只是路径和终端有所区别。3.1 基础环境准备首先你需要确保系统上安装了正确版本的Node.js和Python。Node.js npmVellium推荐使用Node.js LTS长期支持版本。你可以通过 nvm Node Version Manager来安装和管理多个Node版本这是最推荐的方式。# 安装nvm如果尚未安装 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新打开终端或运行 source ~/.bashrc (或 ~/.zshrc) # 安装最新的Node.js LTS版本 nvm install --lts nvm use --lts # 验证安装 node --version npm --versionPython 3 Pillow项目中的图标生成脚本依赖Python 3和Pillow库。macOS通常自带Python 3但可能需要单独安装Pillow。# 使用pip3安装Pillow pip3 install pillow # 如果系统没有pip3可能需要先安装brew install python33.2 获取项目与安装依赖接下来克隆项目代码并安装依赖。# 克隆项目假设你有GitHub访问权限 git clone 项目仓库地址 cd vellium # 安装Node.js依赖 npm installnpm install这一步会下载所有JavaScript依赖并编译原生模块主要是better-sqlite3。根据你的网络和机器性能这可能需要几分钟时间。如果在此步骤报错最常见的原因就是编译环境问题比如缺少C编译工具链。在macOS上你可能需要安装Xcode Command Line Toolsxcode-select --install3.3 启动开发模式依赖安装成功后最简单的启动方式是使用项目提供的开发脚本。# 方式一使用一键脚本macOS/Linux ./setup-and-run-dev.sh # 方式二手动启动标准开发模式 npm run devnpm run dev命令会同时启动前端开发服务器Vite和后端API服务器Express。启动完成后控制台会输出类似下面的信息VITE v5.x.x ready in xxx ms ➜ Local: http://localhost:1420/ ➜ Network: use --host to expose ➜ press h enter to show help Server running on http://localhost:3001此时在浏览器中打开http://localhost:1420即可访问Vellium的Web界面。注意后端API运行在3001端口前端通过代理将/api开头的请求转发到后端。开发模式与生产模式的区别在开发模式下前端代码是未打包的支持热模块替换HMR你修改前端代码后浏览器会即时更新。后端代码也是直接运行server/index.js。所有数据默认存储在项目根目录下的data/文件夹里。而在打包后的桌面应用中前端是优化打包的后端代码被捆绑成单个的server-bundle.mjs文件数据存储路径会指向Electron的userData目录下的data文件夹。3.4 以桌面应用形式运行开发版如果你想测试更接近最终用户的使用体验特别是插件和主题的完整功能应该使用Electron开发模式。npm run dev:electron这个命令会执行一个更复杂的流程编译Electron的主进程和预加载脚本。启动后端API服务器端口3001。启动Vite前端开发服务器端口1420。等待两个服务器健康检查通过。最后启动Electron应用窗口。此时你将看到一个独立的桌面应用窗口而不是浏览器标签页。这是测试插件系统、本地文件访问等依赖Electron环境功能的最佳方式。4. 核心功能深度体验与配置指南成功运行Vellium后我们终于可以深入其核心功能。它的界面可能初看有些复杂但一旦理解其设计逻辑就会发现其强大之处。4.1 聊天与角色扮演系统这是Vellium最吸引人的功能之一它远不止一个简单的聊天框。分支对话历史传统的聊天记录是线性的。而在深度对话或创作中我们常常想尝试不同的回复方向。Vellium允许你在任意一条消息处创建“分支”从而衍生出不同的对话路径。这就像游戏中的对话树非常适合探索不同的剧情走向。在界面中寻找消息旁边的“分支”或“更多选项”图标即可使用此功能。多角色聊天与自动轮转你可以创建多个“角色”Character每个角色有自己的名称、头像、背景故事和对话风格。在聊天中你可以同时让多个角色加入。Vellium支持自动轮转即系统会根据你设定的顺序或规则自动选择下一个应该发言的角色并模拟其口吻生成回复。这对于进行多人场景的角色扮演或者模拟一场会议非常有用。配置角色时仔细填写“系统提示词”System Prompt和“初始消息”Greeting是获得高质量回复的关键。RP控制面板这是高级玩家的利器。它通常以一个侧边栏或下拉区域的形式存在包含以下核心控件提示词堆栈允许你分层管理影响AI行为的提示词。例如底层是角色设定中层是当前场景规则顶层是临时指令。你可以灵活启用或禁用某一层。作者笔记一种只对AI可见、不会显示在对话中的笔记。你可以在这里写下对剧情走向的规划、对角色心理的暗示等隐秘地引导AI。场景状态用来记录当前场景的客观信息如时间、地点、环境、在场人物等帮助AI保持上下文一致性。预设与人格可以保存一套完整的RP参数如温度、重复惩罚等和提示词组合方便在不同类型的对话间快速切换。LoreBook / 世界信息这是维持长对话一致性的基石。你可以创建一个“世界信息”库定义人物、地点、组织、概念等条目。每个条目包含名称、描述以及关键的触发关键词。当对话中出现了这些关键词对应的条目描述就会自动插入到给AI的上下文提示中。Vellium支持导入/导出与SillyTavern兼容的格式这意味着你可以从那个庞大的社区分享中获取丰富的设定库。推理支持与结构化输出Vellium支持类似think.../think的标记解析。这意味着你可以要求AI在回复中将推理过程、内心独白等内容放在特定标记内而Vellium的前端可以选择性地隐藏或高亮这些内容让对话界面更整洁。这对于使用具有强推理能力的大模型如Claude 3, GPT-4进行复杂问题求解时非常有用。4.2 写作工作流Vellium的写作模块不是简单的文本编辑器而是一个为长篇叙事设计的项目管理系统。项目结构采用“项目 - 章节 - 场景”的三级结构。这很适合小说、剧本的创作。你可以在项目级别设定总纲、人物表在章节级别规划剧情梗概在场景级别进行具体写作。AI辅助写作工具摘要与改写/扩展你可以选中一段文字让AI对其进行总结、润色、扩写或精简。这在修改草稿时非常高效。一致性工具写作时可以随时唤出“一致性检查”面板它会基于你已写的内容和设定的LoreBook提示可能存在的矛盾如人物特征前后不一、时间线错误等。角色感知写作在写作编辑器中你可以关联一个或多个聊天中的角色。当你使用AI辅助功能时系统会考虑这些角色的视角和口吻使生成的文本更符合角色设定。导入与导出支持导入DOCX文档方便你将现有稿件迁移进来。完成写作后可以导出为格式良好的Markdown或DOCX文件便于后续的排版或发布。写作侧RAG这是写作模块的杀手级功能。你可以为写作项目单独创建或关联一个“知识集合”。当你写作到某个历史场景时相关的历史资料会自动作为参考背景提供给AI确保细节准确当你描写一个专业领域时相关的技术文档也能被检索引用提升文本的专业性。4.3 知识库与RAG系统RAG功能被深度集成到了聊天和写作中但其管理后台是独立的。创建知识集合在“知识”模块你可以创建一个新的集合为其命名并选择嵌入模型。Vellium支持OpenAI兼容的嵌入模型也允许你配置本地部署的模型端点。文档摄取支持多种格式——纯文本、Markdown、PDF、DOCX等。上传文档后Vellium会对其进行分块Chunking、生成嵌入向量Embedding并存储到向量数据库中基于SQLite和可能的扩展。你可以配置分块的大小和重叠度这对检索效果有重要影响。检索与重排序在聊天或写作中启用RAG后当用户输入查询时系统会将查询文本转换为向量。在向量数据库中进行相似性搜索召回最相关的若干个文本块。可选使用一个“重排序”模型对召回的结果进行精排选出最相关的几个最后将它们作为上下文连同你的问题一起发送给大模型生成答案。混合检索基础这意味着Vellium的RAG系统设计上不仅支持向量检索也为未来集成关键词检索如BM25等传统方法留出了空间以构建更鲁棒的混合检索系统。4.4 模型提供商与端点配置Vellium的核心是与AI模型对话因此灵活地配置模型端点至关重要。OpenAI兼容提供商这是最主流的支持方式。你只需要填入API Base URL如https://api.openai.com/v1或你的反向代理地址和API Key就可以使用GPT系列、Claude如果其API兼容OpenAI格式等模型。许多开源的模型服务框架如OpenAI的官方库、vLLM、text-generation-webui的OpenAI扩展都提供了兼容的接口。KoboldCpp支持对于在本地运行大型语言模型的用户KoboldCpp是一个流行的选择。Vellium可以直接连接到KoboldCpp的API端点使用你本地加载的模型进行对话和生成完全免费且隐私无忧。自定义端点适配器这是通过插件系统实现的强大功能。如果你的后端既不兼容OpenAI也不兼容KoboldCpp例如使用自定义协议的国产大模型平台你可以编写一个“端点适配器”插件。这个插件负责将Vellium内部的请求格式转换成你后端能理解的格式并将后端的响应转换回来。这极大地扩展了Vellium的模型兼容性。分离的模型配置Vellium允许你为不同的任务指定不同的模型。例如主聊天模型GPT-4用于追求高质量的对话和创作。翻译/压缩模型更小、更快的模型如GPT-3.5-Turbo用于实时翻译消息或总结长文本以节省成本和提升速度。TTS模型专门用于语音合成的端点。RAG模型用于生成嵌入向量的文本嵌入模型。5. 插件系统释放无限可能Vellium的插件系统是其从“优秀工具”迈向“生态平台”的关键。它不是一个简单的脚本注入而是一个具有完整生命周期、权限控制和UI集成能力的运行时扩展框架。5.1 插件能做什么一个Vellium插件可以拥有以下一种或多种能力工具栏标签在应用主工具栏添加一个新的标签页就像内置的“聊天”、“写作”、“知识”一样。你可以在这里构建一个完全自定义的管理界面比如一个专门的故事灵感看板或者一个模型性能监控面板。插槽小部件在聊天窗口的侧边栏、消息气泡旁边、写作编辑器的特定区域“插入”一个UI组件。例如一个在聊天时显示角色实时情绪状态的小组件或者在写作时显示章节字数统计的悬浮窗。操作在工具栏、消息菜单、输入框右键菜单、写作编辑器菜单中添加新的操作按钮。点击后可以触发插件定义的逻辑比如“将当前对话导出为小说片段”、“调用外部API分析文本情绪”。插件本地存储与设置每个插件都有自己独立的存储空间可以保存用户配置和状态数据。用户可以在“设置 - 插件”中管理每个插件的开关和权限。主题插件可以提供全新的UI主题改变整个应用的颜色、字体、间距等样式。自定义检查器字段为角色、场景、知识条目等对象添加额外的属性字段。比如为“角色”添加一个“生日”字段为“知识条目”添加一个“可信度评分”字段。自定义端点适配器如前所述用于集成非标准的大模型后端。5.2 插件开发入门虽然完整的插件开发指南需要查阅项目的/docs/plugins/README.md但了解其基本概念有助于我们更好地使用社区插件或尝试自己制作简单插件。插件结构一个典型的插件是一个文件夹包含以下核心文件manifest.json: 插件的“身份证”定义了插件名称、版本、作者、描述、权限要求以及它声明提供的各种能力如哪个工具栏标签、哪个小部件。main.js或index.js: 插件的主入口文件包含插件的初始化逻辑和主要功能代码。可选styles.css: 插件的私有样式。可选components/: 存放React组件的文件夹。Pluginfile——便携的插件包这是Vellium插件分发的格式。它本质上是一个将上述插件文件夹打包压缩后的单一文件通常是.plugin后缀。你可以通过“设置 - 插件 - 安装Pluginfile”来安装它也可以将已安装的插件导出为Pluginfile进行分享。插件的位置用户插件安装在用户数据目录/data/plugins下。在开发模式下通常是项目根目录的data/plugins。捆绑插件应用自带的插件位于用户数据目录/data/bundled-plugins。这些插件通常作为示例或提供核心扩展功能。5.3 安全使用插件的注意事项Vellium的插件系统设计理念是“本地扩展”而非“开放市场”。这意味着信任来源只安装你信任的来源提供的插件。因为插件代码在本地拥有与Vellium主应用相似的权限取决于其申请的权限。审查权限在启用一个插件前务必在“设置 - 插件”中查看它申请了哪些权限。特别是“写入数据”、“访问外部网络”、“执行系统命令”这类高权限操作需要保持警惕。隔离性插件运行在相对隔离的上下文中但通过SDK可以访问到Vellium的核心功能。一个设计不良的插件可能导致应用不稳定或数据损坏。及时更新与卸载关注插件的更新修复可能的安全漏洞。对于不再使用的插件及时禁用或卸载。6. 构建、分发与故障排查当你完成了功能的开发或定制可能想要分享给朋友或者为自己构建一个独立的可执行文件。Vellium使用electron-builder进行打包。6.1 构建桌面应用构建命令非常直观# 构建所有平台的包根据你的系统环境 npm run dist # 仅构建macOS应用 npm run dist:mac # 仅构建Windows应用 npm run dist:win构建过程会将React前端代码打包优化。将Node.js后端服务器代码捆绑成单个server-bundle.mjs文件。使用electron-builder将前端资源、后端捆绑文件、Electron外壳以及所有依赖打包成对应平台的可安装包如macOS的.dmg或.appWindows的.exe。输出文件位于release/目录下。需要注意的是通过GitHub Actions或本地默认脚本构建的包是未签名的。在macOS上打开未签名的应用时系统会弹出安全警告需要在“系统设置 - 隐私与安全性”中手动允许。Windows系统也可能有类似的SmartScreen拦截。6.2 持续集成与自动发布项目自带的.github/workflows/build-desktop.yml文件定义了一个GitHub Actions工作流。当你推送一个带有v*标签如v1.0.0的提交时这个工作流会自动触发并执行以下操作在云端同时为macOS (Intel和Apple Silicon) 和Windows (x64) 构建应用包。将构建产物作为工作流构件上传。在GitHub仓库的“Releases”页面创建一个新的发布版本并将构建好的应用包作为资产附加上去。这对于项目的维护者来说实现了自动化的版本发布。6.3 常见问题与解决方案实录在实际使用和构建Vellium的过程中我遇到并总结了一些典型问题及其解决方法。问题一启动时出现ERR_DLOPEN_FAILED或NODE_MODULE_VERSION错误现象运行npm run dev或启动打包后的应用时控制台或弹窗报错提示原生模块加载失败。原因better-sqlite3或其他原生模块的二进制文件与当前运行的Node.js版本不匹配。这常发生在切换Node版本后或者将开发环境的node_modules文件夹复制到另一台机器时。解决在项目根目录运行npm run rebuild:native。这个命令会强制重新编译所有原生模块。如果上述步骤无效最彻底的方法是删除整个node_modules文件夹和package-lock.json文件然后重新运行npm install。rm -rf node_modules package-lock.json npm install问题二端口3001被占用导致API服务器启动失败现象运行npm run dev时提示EADDRINUSE: address already in use :::3001。原因之前的开发进程没有正确退出占用了3001端口。解决找到占用端口的进程ID并结束它。# 在macOS/Linux上 lsof -nP -iTCP:3001 -sTCP:LISTEN # 命令会输出进程ID(PID)例如 12345 kill -TERM 12345如果经常遇到可以考虑修改server的启动端口但这需要同时修改前端代理和Electron主进程的配置不推荐新手操作。问题三打包后的应用打开是空白窗口或启动时间极长现象运行打包好的.app或.exe文件窗口空白或者启动后长时间无响应。排查确认你是使用npm run dist:mac等命令进行的完整桌面构建而不是仅仅构建了前端 (npm run build)。检查构建输出目录release/中的应用包内是否包含server-bundle.mjs文件。这个文件是后端服务器的代码缺失会导致应用无法启动。对于macOS可以尝试从终端启动应用查看输出日志。# 进入应用包内部 cd /Applications/Vellium.app/Contents/MacOS # 运行可执行文件 ./Vellium观察终端是否有错误输出常见的可能是找不到SQLite数据库文件路径权限问题或原生模块问题。问题四插件安装后不显示或无法工作现象安装了.plugin文件但在界面上看不到插件添加的标签或组件。排查步骤检查插件是否启用进入“设置 - 插件”列表找到你安装的插件确保其开关是打开状态。检查权限在插件设置中查看该插件是否请求了必要的权限如“访问聊天数据”、“添加UI组件”并确保你已经授权。重新加载插件在“设置 - 插件”页面通常有一个“重新加载插件”或“刷新插件列表”的按钮。点击它这会让Vellium重新读取并初始化所有插件。重启应用如果你修改了插件的代码或者更新了Vellium的SDK仅仅重新加载插件可能不够需要完全重启Vellium应用特别是npm run dev:electron进程。查看开发者工具在Electron开发模式下你可以打开开发者工具通常快捷键是CmdOptionI或CtrlShiftI在控制台Console中查看是否有插件加载或运行的错误信息。问题五图标生成失败现象运行npm run build:icons时报错提示缺少Python模块或无法生成图片。原因图标生成脚本依赖Python的Pillow库。解决确保已安装Python 3。使用pip3 install pillow安装Pillow库。如果系统中有多个Python版本请确认pip3对应的是Python 3。如果仍失败可以检查scripts/目录下的图标生成脚本看其是否硬编码了特定的Python路径尝试手动使用正确的Python解释器运行它。经过以上几个部分的拆解从技术架构到功能使用从插件开发到问题排查相信你已经对Vellium这个强大的桌面AI工作台有了比较全面的认识。它的设计理念在于整合与自由将分散的AI能力通过一个高度可扩展的平台统一起来。无论是用于沉浸式的角色扮演、严肃的文学创作还是作为研究AI交互的开发者平台Vellium都提供了一个坚实且充满可能性的起点。