什么是 maxOS

maxOS 是 ООО «Гарипофф» 公司开发的一款基于本地模型运行的开源 AI-native 平台。它的开源核心是一个智能体（Agent）：它能读取并修改项目中的文件，并在终端中执行命令，而这一切都是通过您本地机器上运行的语言模型实现的。无论是代码、查询请求还是文件内容，都不会流向第三方的云端。

核心代码以 Apache-2.0 许可证开源：github.com/LLC-Garipoff/maxos。我们就从它开始讲起。

是智能体，而非自动补全

自动补全只能提示下一行代码。而智能体则能完整地解决任务：理解项目结构、修改多个文件、运行构建和测试、读取输出并继续下一步。

maxOS 的内部是一个简单的循环。系统会将任务和可用工具的描述传递给模型。模型返回的不是普通文本，而是调用工具的决策。这里共有四个工具：

• read_file — 读取文件；
• list_dir — 查看目录内容；
• write_file — 创建或重写文件；
• run_bash — 在 Shell 中执行命令（构建、测试、启动）。

maxOS 在工作目录中执行调用，并将结果返回给模型，如此循环往复，直到模型停止调用工具并给出最终结果。所有路径都限制在工作文件夹内——任何试图超出该范围的调用都会被拒绝。在写入文件和执行命令之前，maxOS 默认会请求用户确认。

这就是全部的原理。没有隐藏的云端编排器——循环、工具和提示词（Prompt）仅用几百行代码即可实现，且没有任何运行时依赖。

仅限本地模型

maxOS 本身不进行神经网络计算。它将推理任务委托给具有 OpenAI 兼容 API 的本地运行时——例如 Ollama 或 llama.cpp。您可以在本地部署模型：

ollama pull qwen2.5-coder:7b

——而 maxOS 会通过 http://localhost 与其通信。整个架构中完全没有云端端点：只要您的机器能跑得动模型，智能体就可以完全离线工作。

这里有一个技术细节，为此我们不得不编写了一个单独的适配层。部分本地模型会严格按照 OpenAI 兼容协议的要求，在结构化字段 tool_calls 中返回工具调用。但许多模型——包括 qwen2.5-coder——则会直接在响应中以 JSON 文本的形式写入调用。maxOS 能够识别这两种情况：如果没有结构化字段，它会从文本中提取调用（包括带有 <tool_call> 标签的格式）并继续循环。因此，该框架不仅能与某一款“完美”的模型配合，还能兼容各种不同的模型。

编程模型连接到哪里

maxOS 是一个编排器：包含提示词、工具、循环、沙箱和确认机制。代码本身的编写和修改是由连接的模型完成的。为了进行编程，运行时中会安装专门的模型——如 qwen2.5-coder、llama3.1 等具备工具调用能力的模型。更换模型只需修改一行参数（--model）或设置环境变量，智能体的其他部分保持不变。

这种职责划分是深思熟虑的结果。智能体的循环瓶颈在于磁盘和网络，而非计算，因此它采用 TypeScript 编写——便于快速迭代和轻松安装。而对于尚未实现的高性能和系统级模块，我们计划将其移至基于 Rust 的原生核心中：例如大型仓库的索引和搜索、无需依赖 Node 的单一二进制文件。其逻辑是一致的——针对特定需求选择合适的工具，而不是盲目用 Rust 去重写那些瓶颈在于输入输出（I/O）的部分。

这与 SpotMax 有何关系

SpotMax 是我们团队开发的一款桌面应用程序，源自于同一个理念：辅助你的模型应该运行在你的身边，而不是别人的数据中心里。它的名字本身就是 Spotlight + max 的结合：一个深度嵌入操作系统、随时触手可及的工具。

我们最初是为销售场景开发它的——用于我们自己的演示和路演：助手能听到对话并进行实时提示，以维持思路和上下文。事实证明，它的用途更为广泛——对求职者和 HR 同样大有裨益。如今，它越来越多地被用于与外方合作伙伴的谈判中：SpotMax 直接在设备上识别并转录语音，帮助用户顺畅沟通而不偏离主题。关于它如何监听通话、转录语音并提供提示的详细工作原理，我们在另一篇文章中进行了剖析：SpotMax 如何工作：通话期间的转录、翻译和提示。

语音识别和说话人分离均在本地运行——这些正是运行在设备上的模型。maxOS 则是这一切的通用开源基石：我们将智能体层开源，以便大家阅读、验证和改进。

为什么选择本地

云端代码智能体会将您的源码、查询请求以及终端输出发送到第三方服务器。对于大部分工作——如私有代码、受监管的数据、保密协议（NDA），甚至仅仅是网络状况不佳——这都是不可接受的。maxOS 将本地化作为唯一的路径：由于代码是开源的，您可以直接通过源码来验证这一点。

代码、Bug 报告和改进建议请提交至 GitHub：github.com/LLC-Garipoff/maxos。此外，针对本地模型的具体改进，我们还设有悬赏计划。