从零构建本地AI编程助手：Mervelas的隐私优先架构与Bun技术栈实践

1. 项目概述一个为开发者主权而生的本地AI编程助手如果你和我一样对市面上那些“全家桶”式的AI编程助手感到厌倦——它们要么偷偷收集你的代码数据要么把你锁死在某个特定的云服务里用起来总感觉束手束脚——那么Mervelas的出现可能会让你眼前一亮。这不是又一个在现有框架上修修补补的“魔改版”而是一个从零开始用Bun构建以“自由、隐私、极致性能”为第一性原理的原生CLI工具。它的核心承诺很简单你的代码、你的终端会话、你和AI的每一次对话都百分百属于你运行在你的机器上不产生任何遥测数据。在当前这个数据隐私愈发敏感、开发者工具日益平台化的时代这种纯粹性本身就是一种稀缺价值。简单来说Mervelas是一个运行在终端里的AI结对编程伙伴。但它不像某些工具那样只是一个调用远程API的“壳”。它被设计成一个本地优先Local-First的架构。这意味着你的对话历史、项目上下文、乃至整个应用的状态都优先存储和处理在你的本地磁盘上。这种设计哲学带来的直接好处是极致的响应速度和绝对的隐私控制。当你敲下回车等待AI回应时延迟主要来自网络请求如果你使用云端模型而UI渲染、历史记录查询这些操作几乎是在瞬间完成的因为它不依赖任何远程服务来管理你的会话状态。我最初被它吸引正是因为它在GitHub仓库简介里那句略显“硬核”的宣言“Built for developers who demand complete sovereignty over their workflows.”为那些要求完全掌控自己工作流的开发者而构建。在实际编译、配置并深度使用了几周后我发现它确实在努力践行这一承诺。它不仅支持从OpenAI、Anthropic Claude到开源模型via OpenRouter、甚至本地部署的NVIDIA NIM或Qwen在内的多种后端更重要的是它将这种多模型支持与一套高度优化、无缝集成的本地命令系统结合了起来。你可以通过/config快速切换模型供应商用/context实时查看token消耗和上下文窗口状态甚至用/agents创建针对不同编程语言或任务的专属AI代理。这一切操作都发生在一个CPU占用几乎为零、启动飞快的终端界面里这种流畅且可控的体验是很多笨重的GUI工具或资源黑洞式的Electron应用无法比拟的。2. 核心设计理念与架构解析2.1 为何选择“从零构建”与Bun技术栈很多开源AI工具会选择基于某个成熟的终端UI框架如Ink或打包工具如Webpack进行开发。Mervelas团队则选择了一条更激进但也更彻底的道路从零开始并用Bun作为核心工具链。这个决策背后有深刻的性能与架构考量。首先“从零构建”是为了绝对的掌控权。许多基于Electron或甚至某些Node.js CLI框架的工具在启动时就会加载大量不必要的模块引入潜在的依赖冲突并且难以彻底杜绝遥测或非预期的网络调用。Mervelas通过自行控制从依赖加载、UI渲染到事件循环的每一个环节确保了没有“黑箱”操作。例如在它的贡献规范中明确禁止直接import ink from ink而是要求通过项目内部的src/ink.ts抽象层来使用UI组件。这虽然增加了初期的开发成本但换来了长期的架构稳定性和性能可预测性。其次选择Bun而非传统的Node.js npm/yarn组合是追求极致的轻量与速度。Bun不仅仅是一个JavaScript运行时它还是一个打包器、任务运行器和包管理器。对于Mervelas这样一个CLI工具来说Bun带来的优势是立竿见影的冷启动速度Bun的启动时间远低于Node.js这对于一个需要频繁在终端中唤起的工具来说体验提升非常明显。依赖安装与构建速度bun install的速度极快并且项目使用Bun内置的打包器进行编译bun run scripts/build.ts整个构建流程高度一体化减少了外部工具链的复杂度。资源占用项目宣称的“几乎零空闲CPU占用”很大程度上得益于Bun运行时本身的高效以及基于此设计的惰性加载架构。应用核心被编译为原生代码只有在真正需要时如执行一个命令才会加载相应的模块。这种技术选型决定了Mervelas的“基因”它生来就是为了追求极限性能和简洁依赖这与它的产品目标——做一个不打扰开发者、随用随走的敏捷工具——完美契合。2.2 本地优先架构与隐私实现细节“本地优先”不是一句空话它在Mervelas的架构中体现在以下几个关键层面1. 会话历史的本地化存储你的所有对话记录包括AI的回复、你提供的上下文代码片段都会被安全地写入本地文件系统。具体路径是~/.mervelas/projects/目录下。它没有使用简单的JSON文件而是采用了JSONLJSON Lines格式。这种格式每行是一个完整的JSON对象对应一次交互或一个会话片段。它的好处在于易于追加新的对话可以简单地追加到文件末尾无需读入整个文件再重写效率高且安全。便于流式处理如果需要开发历史记录查看或搜索功能可以逐行读取内存友好。抗损坏即使文件在写入过程中意外中断未损坏的前几行数据依然可读。这意味着只要你没有主动将API密钥配置为某个会记录历史的云服务并且该服务有此功能你的所有编程思路、未完成的代码草稿、甚至可能包含敏感信息的错误日志都只存在于你自己的硬盘上。2. 惰性加载与纯净运行时为了兑现“零空闲占用”的承诺Mervelas采用了严格的惰性加载策略。在它的开发规范中明确要求禁止在文件加载时就实例化阻塞性的单例或执行文件读取操作。所有工具Tools和执行循环execute loops都必须使用load: () import(...)这样的动态导入抽象。简单来说就是“按需加载”。CLI程序启动后其内存占用几乎就是一个空壳直到你输入第一个命令比如/config相应的配置模块才会被动态加载到内存中。执行完毕后如果内存管理得当这些模块还可能被回收。这种设计确保了Mervelas在后台静默时对系统资源的消耗微乎其微。3. 去中心化的配置与状态管理配置API密钥、模型选择通过环境变量或交互式的/config命令在本地完成。项目状态、上下文管理也完全在本地处理。这种设计避免了传统SaaS工具中常见的“中心化配置服务”从根本上杜绝了因为服务端配置同步延迟或失败导致的工作流中断。注意虽然会话历史本地存储但如果你使用的是云端AI模型如GPT-4你的提示词Prompt和代码片段仍然会被发送到对应的API服务提供商如OpenAI。Mervelas保障的是“在它这一环”的隐私即它不会额外收集你的数据。模型提供商的数据政策仍需用户自行了解和评估。这也是为什么项目也大力支持本地模型如通过Ollama部署的原因那才是真正的端到端隐私。3. 从零开始编译、配置与初体验3.1 环境准备与源码编译实战目前Mervelas尚未发布到NPM这意味着我们需要从源码编译。别担心整个过程在Bun的加持下非常顺畅。以下是步步为营的实操指南第一步安装Bun如果你的系统还没有Bun需要先安装它。Bun的安装器是一段Shell脚本通常从官方源获取是最安全快捷的方式。# 使用官方安装脚本建议先查看脚本内容 curl -fsSL https://bun.sh/install | bash安装完成后重启你的终端运行bun --version确认安装成功。你会看到类似1.1.17的版本号。第二步克隆仓库与安装依赖# 克隆项目到本地 git clone https://github.com/swadhinbiswas/Mervelas.git cd Mervelas # 使用Bun安装项目依赖 bun install这里bun install会读取package.json并飞速地安装所有必要的依赖包。你会注意到依赖列表非常精简这得益于其自研的UI系统和Bun的高效模块管理。第三步编译项目Mervelas没有使用常见的npm run build而是有一个自定义的构建脚本。# 执行内部打包脚本将TypeScript源码编译打包 bun run scripts/build.ts这个命令会启动项目内的scripts/build.ts文件。这个脚本很可能利用了Bun的Bun.build()API进行打包将分散的模块打包成一个或几个优化后的文件输出到dist/目录。编译过程通常很快。第四步运行Mervelas编译完成后可以直接运行生成的可执行入口点。# 运行编译后的CLI程序 node dist/cli.mjs首次运行你应该会看到一个简洁的终端界面这就是Mervelas的主交互界面了。实操心得在编译过程中我遇到过因Node.js版本与Bun内置特性不匹配导致的罕见错误。如果你的环境比较复杂一个干净的解决方法是使用bun upgrade --canary将Bun升级到最新的Canary版本或者确保你的项目路径没有特殊字符。另外编译后生成的dist目录包含了所有运行所需资源你可以将其复制到系统PATH包含的目录如/usr/local/bin并创建一个软链接方便全局调用例如ln -s $(pwd)/dist/cli.mjs /usr/local/bin/mervelas。3.2 核心配置详解连接你的AI大脑Mervelas的强大之处在于其多模型支持。首次使用你需要通过/config命令来告诉它使用哪个AI服务。交互式配置推荐给初学者在Mervelas CLI界面中直接键入/config并回车。你会进入一个交互式的配置菜单。通常你需要选择Provider供应商比如openai,openrouter,anthropic,nvidia-nim,qwen等。选择后系统会提示你输入对应的API Key。这个密钥需要你到相应服务的官网去申请。OpenAI: 前往 platform.openai.com 创建API Key。OpenRouter: 前往 openrouter.ai 创建Key它提供了聚合众多模型包括Claude、Gemini等的访问。本地模型如果你部署了Ollama或LocalAI可能需要选择custom或local选项并配置本地API的Base URL如http://localhost:11434/v1。接下来你可能需要选择默认使用的Model例如gpt-4-turbo-preview,claude-3-opus-20240229,qwen-72b-chat等。配置完成后通常按CtrlS或遵循界面提示进行保存。配置信息会被加密或明文取决于实现保存在~/.mervelas/下的某个配置文件中。环境变量配置适合高级用户与CI/CD对于喜欢自动化或需要在无头服务器上使用的场景Mervelas支持通过环境变量预配置这样启动后无需交互即可直接使用。# 示例1配置使用OpenAI export MERVELAS_API_PROVIDERopenai export OPENAI_API_KEYsk-your-openai-key-here export OPENAI_BASE_URLhttps://api.openai.com/v1 # 默认值可省略 # 示例2配置使用OpenRouter export MERVELAS_API_PROVIDERopenrouter export OPENROUTER_API_KEYyour-openrouter-key-here # OpenRouter的Base URL通常是固定的无需额外设置 # 然后启动Mervelas node dist/cli.mjs启动后Mervelas会优先读取这些环境变量如果配置有效你将直接进入对话界面。注意事项API密钥是高度敏感信息。务必确保不要将包含密钥的环境变量配置文件提交到Git仓库。建议使用.env文件配合dotenv等工具在开发时加载并在生产环境使用安全的密钥管理服务。Mervelas的本地存储虽然相对安全但也要注意~/.mervelas/目录的权限避免其他用户读取。3.3 首次对话与基础命令尝鲜配置成功后你就可以开始和Mervelas对话了。它的界面通常是一个光标在底部闪烁的输入区。你可以像在ChatGPT中一样直接输入自然语言问题例如“帮我写一个Python函数用于递归遍历目录并列出所有.md文件。”或者你可以使用它的核心特色斜杠命令Slash Commands。输入/后它可能会给出命令补全提示。我们来详解几个最常用的/config 我们已经用过用于管理所有供应商和模型的设置。你可以随时回来添加新密钥、切换默认模型或调整高级参数如温度、最大token数。/context这是一个极其有用的命令。AI模型有上下文窗口限制如128K tokens。这个命令会以可视化方式可能是进度条或数字清晰展示当前会话已使用了多少token距离上限还有多少。它能帮助你判断是否需要开启一个新会话来“重置”上下文或者删除一些旧消息以节省空间。/agents Mervelas允许你创建“代理”。这不是指另一个AI而是一组预设的指令System Prompt和配置。例如你可以创建一个“Python代码审查代理”其系统指令被设定为“你是一个严格的Python代码审查员专注于发现潜在bug和安全问题...”。创建后通过/agents switch [代理名]快速切换让AI进入不同的角色。/mcp模型上下文协议Model Context Protocol是Anthropic提出的一种标准允许AI模型安全地访问外部工具和数据源如数据库、文件系统、日历。通过此命令你可以集成本地运行的MCP服务器极大地扩展AI的能力边界。例如连接一个文件系统MCP服务器后你可以直接让AI“读取当前目录下config.yaml文件的内容并分析”。/status 查看当前会话状态、资源使用情况如果实现或连接状态。/login 一个快速命令用于在已配置的不同供应商或账户间切换比进入完整的/config菜单更快捷。初次使用时建议花几分钟时间把每个命令都点开看看熟悉一下界面和操作逻辑。你会发现这些命令的设计都是为了让你在不离开对话流的情况下高效地管理这个强大的AI助手。4. 深度使用高级功能与自定义工作流4.1 打造专属AI代理超越通用聊天Mervelas的/agents功能是将它从一个普通的聊天接口提升为可编程工作流工具的关键。通用AI助手在回答不同领域问题时需要你在每次对话中反复说明背景和要求。而代理Agent允许你将这些“背景和要求”固化下来一键切换。创建你的第一个代理在CLI中输入/agents create。系统会引导你输入代理名称如my-python-helper、描述。最关键的一步编写系统提示词System Prompt。这是定义代理行为的核心。例如对于一个Python调试代理你可以输入你是一个经验丰富的Python开发者专门帮助调试和优化代码。你的回答应遵循以下规则 1. 首先分析我提供的错误信息或代码片段。 2. 给出最可能的原因并按可能性排序。 3. 提供修复方案并附上修改后的代码。 4. 解释修复方案为何有效。 5. 始终使用简洁、专业的语气。你还可以为这个代理关联特定的模型、设置温度等参数。完成后保存。使用与切换代理创建后输入/agents list查看所有可用代理。输入/agents switch my-python-helper切换到刚创建的代理。现在你的每一次提问都会在后台附加上那段详细的系统提示词AI的回答会立刻变得更具针对性。高级代理用例设想代码审查代理系统提示词包含公司编码规范、安全红线。文档撰写代理提示词要求以特定格式如Google Style Docstrings生成函数文档。学习伙伴代理提示词要求以苏格拉底式提问引导用户思考而非直接给出答案。多语言代理为不同编程语言创建专属代理每个代理都预置了该语言的最佳实践和常用库知识。通过代理你实质上是在为不同的任务场景“训练”了一个专用的AI微调版本而无需付出真正的微调成本。4.2 利用MCP协议扩展AI能力边界/mcp命令打开的是一扇通往更广阔自动化世界的大门。MCP协议的核心思想是让AI模型能够安全、可控地调用外部工具。在Mervelas中集成MCP意味着你的AI助手可以直接读写本地文件在授权范围内。执行安全的Shell命令如运行测试、启动服务。查询数据库。与第三方API交互如Jira、GitHub。如何集成一个MCP服务器假设你已经在本地运行了一个提供“文件系统访问”功能的MCP服务器例如使用modelcontextprotocol/server-filesystem。在Mervelas中输入/mcp。选择添加Add或连接Connect新服务器。输入服务器的连接信息。这通常是一个本地Socket路径、HTTP地址或命令行指令。例如可能是stdio:///path/to/mcp-server-binary或http://localhost:8080。连接成功后Mervelas会在后台将该服务器提供的“工具”列表告知AI模型。实际应用场景连接文件系统MCP后你可以直接对AI说“请读取当前项目根目录下的package.json文件告诉我其中dependencies和devDependencies的区别并建议哪些devDependencies可以移到dependencies中。”AI模型会通过MCP调用“读文件”工具获取文件内容然后进行分析和回答。这比手动复制粘贴文件内容要高效和自然得多。重要提示MCP功能非常强大但也带来了安全风险。务必只连接你完全信任的MCP服务器。恶意的MCP服务器可能被用来执行破坏性命令或窃取数据。Mervelas作为一个本地工具将访问控制的责任交给了用户自身因此需要使用者具备基本的安全意识。4.3 上下文管理与高效对话策略AI模型的上下文窗口是宝贵的资源。虽然现代模型支持很长的上下文如128K、200K但无节制地堆积历史对话会导致Token消耗增加许多API按输入输出的总Token数收费。响应速度变慢模型需要处理更长的序列。模型性能下降关键信息可能被淹没在冗长的历史中导致AI“遗忘”或混淆。Mervelas的/context命令是你管理上下文的仪表盘。你需要形成主动管理上下文的习惯策略一适时开启新会话当一个特定任务如调试一个复杂模块完成后如果接下来要开始一个完全不相关的新任务最好的做法是直接重启Mervelas或使用“新会话”功能如果提供。这相当于给AI一个干净的黑板。策略二主动清理无关历史对于长周期任务如设计一个系统架构你可以手动删除对话历史中那些已经解决、不再需要的中间问答。在Mervelas中可能需要通过界面操作或命令来删除特定轮次的消息以腾出上下文空间给更重要的最新讨论。策略三利用“摘要”功能一些高级的用法是在对话进行到一定阶段后你可以要求AI对之前的讨论要点做一个总结然后将这个总结作为新对话的起点并清空旧历史。这样既保留了核心信息又大幅节约了Token。策略四关注Token消耗图表经常使用/context命令观察Token使用量的增长趋势。如果你发现一次简单的问答就消耗了数千Token可能是你无意中附带了大量代码或日志。考虑是否可以用更简洁的方式提供信息例如“函数X在输入Y时返回Z错误相关代码在src/utils.js的第10-25行”而不是粘贴整个文件。5. 开发贡献指南与深度定制5.1 理解项目结构与贡献边界如果你对Mervelas的代码感兴趣甚至想为其添加功能或修复Bug首先需要理解它的项目结构并严格遵守其开发哲学尤其是避免“架构回归”。典型的项目结构可能如下Mervelas/ ├── src/ │ ├── cli.mts # CLI主入口处理参数解析和启动 │ ├── app/ # 主应用逻辑状态管理事件循环 │ ├── ink.ts # **核心UI抽象层**自定义的React Ink封装 │ ├── providers/ # 各AI供应商OpenAI, Anthropic等的适配器 │ ├── commands/ # /config, /agents 等命令的实现 │ ├── mcp/ # MCP协议客户端集成代码 │ └── storage/ # 本地会话历史、配置的读写模块 ├── scripts/ │ └── build.ts # 自定义的Bun打包脚本 ├── dist/ # 编译输出目录 └── package.json贡献时必须牢记的核心规则摘自项目文档严禁直接引入ink所有UI组件必须通过项目自有的src/ink.ts抽象层导入。这是为了保证UI行为的一致性和可维护性避免因直接依赖外部UI库的版本更新导致不可预测的破坏。惰性加载是铁律任何工具、命令模块都不能在文件顶层模块加载时执行副作用操作如读取大文件、初始化网络连接、创建全局状态。必须封装在函数或load: () Promise...这样的结构中确保CLI启动速度不受影响。严格的类型检查项目使用TypeScript并追求严格的类型安全。在提交代码前务必运行bun run typecheck通常对应tsc --noEmit确保没有类型错误。这有助于维护代码质量避免运行时错误。开发工作流建议Fork并克隆仓库后先运行bun install安装依赖。使用bun run scripts/build.ts --watch可能可以启动监听模式在修改源码时自动重编译。使用node dist/cli.mjs测试你的修改。对于UI或交互逻辑的修改可能需要频繁重启CLI来查看效果。添加新功能时优先考虑在现有架构下扩展。例如添加一个新的AI供应商应在src/providers/下创建新的适配器类并遵循统一的接口。5.2 添加新的AI模型供应商假设你想添加对一个名为“AwesomeAI”的新兴模型API的支持以下是逻辑步骤研究API首先你需要了解AwesomeAI的API端点、认证方式通常是Bearer Token、请求/响应格式是否兼容OpenAI格式以及可用的模型列表。创建供应商适配器在src/providers/目录下创建一个新文件例如awesome-ai-provider.ts。这个文件应该导出一个类实现项目定义的LLMProvider接口这个接口需要你从现有代码中推断。// 伪代码示例 import type { LLMProvider, ChatMessage, CompletionOptions } from ../types; export class AwesomeAIProvider implements LLMProvider { name awesomeai; baseURL: string; apiKey: string; constructor(config: { baseURL?: string; apiKey: string }) { this.baseURL config.baseURL || https://api.awesome.ai/v1; this.apiKey config.apiKey; } async createChatCompletion(messages: ChatMessage[], options: CompletionOptions) { // 构建符合AwesomeAI API格式的请求体 const body { model: options.model, messages: this.formatMessages(messages), temperature: options.temperature, max_tokens: options.maxTokens, // ... 其他参数 }; const response await fetch(${this.baseURL}/chat/completions, { method: POST, headers: { Authorization: Bearer ${this.apiKey}, Content-Type: application/json, }, body: JSON.stringify(body), }); if (!response.ok) { throw new Error(AwesomeAI API error: ${response.statusText}); } const data await response.json(); // 解析响应提取AI回复内容并格式化为Mervelas内部统一的格式 return this.parseResponse(data); } private formatMessages(messages: ChatMessage[]) { ... } private parseResponse(data: any) { ... } }注册供应商你需要在一个中心化的注册点可能是src/providers/index.ts将你的新Provider添加进去使其出现在/config的命令列表里。更新类型定义如果引入了新的配置项需要更新相关的TypeScript类型定义文件。测试编写测试用例如果项目有测试框架并手动通过/config配置你的AwesomeAI密钥和端点进行完整的聊天测试。通过这种方式你可以将Mervelas连接到任何提供HTTP API的AI服务极大地扩展了其可用性。5.3 性能调优与问题排查即使Mervelas本身已经过高度优化在实际使用中你可能还是会遇到一些性能或连接问题。以下是一些排查思路1. 启动缓慢或卡顿检查网络代理如果Mervelas在启动时尝试检查更新或预加载某些资源网络代理设置不当可能导致延迟。确保你的网络连接正常。检查~/.mervelas/目录如果会话历史文件JSONL变得非常大比如超过100MB读取时可能会有延迟。可以考虑定期归档或清理旧项目的历史文件。禁用不必要的MCP服务器如果配置了多个MCP服务器且某些服务器启动慢或无法连接可能会拖慢Mervelas的初始化。尝试暂时禁用它们。2. AI响应速度慢区分网络延迟与处理延迟使用/status或类似命令查看状态。如果显示“等待响应...”那延迟主要来自AI服务提供商。你可以尝试切换到不同区域或更稳定的供应商。检查上下文长度使用/context命令。如果上下文已接近满载模型处理长上下文本身就需要更多时间。考虑开启新会话。模型选择更大的模型如GPT-4 vs GPT-3.5-Turbo通常响应更慢但质量更高。根据任务需求权衡。3. 命令不响应或报错查看终端错误信息Mervelas可能会将运行时错误输出到终端。仔细阅读错误堆栈。检查配置完整性运行/config确认API密钥和端点配置正确无误没有过期。查阅项目Issue在GitHub仓库的Issues页面搜索是否有类似问题。由于项目处于活跃开发阶段一些边界情况可能尚未覆盖。4. 编译或运行时报TypeScript错误确保你使用的是项目要求的Bun和TypeScript版本。运行bun --version和npx tsc --version如果有本地tsc进行核对。尝试清除Bun的缓存和编译输出rm -rf dist node_modules/.cache然后重新执行bun install和bun run scripts/build.ts。维护一个像Mervelas这样追求极致的工具需要开发者对性能、内存和架构有敏锐的感知。作为用户理解其设计原则能帮助你更好地使用它作为贡献者遵守这些原则则是你对这个开源社区最好的尊重。