Apache Maka：本地优先的 AI Agent 工作台

Maka 桌面版界面 — 模型消息、工具调用、工具结果以追加日志形式持久化

---

痛点切入：当云端 Agent 遇上断网、数据主权和账单恐惧

深夜 11 点，你正在赶一个重要项目的上线。Cloud AI Agent 突然弹出提示：「API 配额已用尽，请升级套餐」。就在这个节骨眼上，你的代码库恰好在一个断网的内网环境里，所有 API 调用都指向墙外的服务器。这是一个真实到让开发者窒息的场景——云端优先（Cloud-first）的 Agent 架构，将你的生产力与网络连接、外部定价策略牢牢绑定在了一起。

Apache Maka 正是为解决这个矛盾而生的。它来自 Apache 软件基金会孵化项目，提出了一个更激进的理念：本地优先（Local-first）——你的会话数据、设置、运行记录默认保留在本地机器上。你自己选择连接什么模型：云端 API、本地模型（如 Ollama），还是兼容的网关。这意味着，即使没有网络连接，只要本地有模型推理能力，Agent 依然可以正常工作。

项目背景：Apache 孵化器的 AI Agent 实验

Maka 由 Apache 软件基金会孵化，这意味着它遵循 Apache License 2.0，项目治理和开源规范有可靠保障。项目的核心设计理念围绕一个关键词：Log is Runtime——模型消息、工具调用、工具结果和终止事件全部被记录为只追加的运行时事件日志（Runtime Event Log）。会话、UI、模型上下文和恢复机制，都是对这个日志的投影（Projection），而非日志本身。

这个设计选择非常关键：它将 AI Agent 的执行状态从"大模型的上下文窗口"中解放出来——不再依赖不断扩大的上下文来维持会话连续性，而是通过持久化的结构化日志来支撑会话恢复、历史搜索和分支操作。

技术架构：Monorepo + TypeScript + 事件溯源

分层模块设计

Maka 采用了 Node.js Monorepo 架构，使用 npm workspaces 组织多个子包，核心依赖 Node.js >= 22.19.0。项目包含以下核心模块：

模块	职责
@maka/core	核心抽象层，包含类型定义和基础接口
@maka/runtime	Agent Runtime 引擎：多模型连接、流式输出、思考过程（thinking）
@maka/runtime-host	运行时主机：会话生命周期、权限策略、工具注册、事件日志写入
@maka/storage	数据持久化层，负责交互式运行时状态管理
@maka/cli	命令行工具，提供 maka 和 maka run 子命令
@maka/ui	共享 React 组件库
@maka/desktop	Electron 桌面应用：会话管理、Artifact 预览、权限设置界面
@maka/mcp	MCP（Model Context Protocol）服务器集成
@maka/computer-use	Computer Use 能力封装
@maka/eval	可复现的基准测试框架：Experiment → Cell → Attempt → Results

从架构图可以看出，Runtime Host 是唯一的事实执行权威。Desktop、TUI、CLI、Bot 和 Eval 客户端都向 Runtime Host 发起工作请求，没有任何一个组件拥有第二个 Runtime。这种设计消除了分布式系统中常见的执行权威冲突问题。

事件溯源架构

Runtime Event Log 是所有执行证据的规范来源。当上下文窗口需要进行压缩时（如 Tool Result 修剪或 LLM Compaction），这些操作改变的是下次推理时模型看到的输入投影，而不是把已记录的执行证据当作可丢弃的上下文。这种"日志即真相"的哲学，使会话具备天然的恢复能力——即使 Agent 崩溃或用户重启应用，也可以从日志中重建完整的执行状态。

前端技术栈

桌面版使用 Electron + React 构建，设计系统定义在 DESIGN.md 中，采用 OKLCH 色彩空间，支持亮色/暗色模式。TUI/CLI 则通过 Node.js 终端实现，共享同一套 Runtime Host。

核心功能：从"问答机器人"到"可信赖的工作搭档"

本地工具集（Local Tools）

Maka 内置了一套经过权限控制的本地工具，Agent 在执行这些操作前需要用户授权：

• Read / Write / Edit：文件系统操作，支持按行编辑
• Bash：执行本地命令，带权限确认
• Glob / Grep：代码库模式匹配和文本搜索

工具注册采用动态可用性机制，配合 Schema 验证和权限策略，确保 Agent 在用户可控的范围内执行操作，不会出现未授权访问文件或执行危险命令的情况。

多模型连接

Runtime 支持同时配置多个模型连接，支持流式输出和 thinking 模式（o3/o4 系列模型的推理过程输出）。此外，Maka 还内置了用量计费（usage accounting）和提供商错误规范化，确保不同 API 提供商返回的错误格式被统一处理，降低开发者的适配成本。

会话管理

桌面版提供完整的会话管理界面：创建、归档、搜索、重试、从某个 Turn 生成分支。所有会话默认存储在本地 SQLite 数据库中，用户完全掌控自己的数据，不上传到任何云端服务。

Benchmark 框架（@maka/eval）

这是一个容易被忽视的亮点：@maka/eval 允许研究者和开发者定义可复现的基准实验，跨越不同 Agent 系统进行比较。实验定义包含 Subject（被测系统）、Task（任务）、Repetition（重复次数）和 Cell（task × repetition × subject），每个 Cell 产生的 Attempt 是不可变的，最终结果可被选择和汇总。这对于 AI Agent 领域的学术研究和工程评估非常有价值。

上手门槛：桌面版 vs CLI 版

桌面版（Electron）目前仅提供 macOS Apple Silicon 的 DMG 安装包，Windows 和 Linux 桌面版仍在开发中。对于想要体验完整 GUI 的用户，这是目前的主要门槛。

CLI/TUI 版要求 Node.js >= 22.19.0，在 Linux、macOS 和 Windows 的 WSL 环境下均可运行。安装过程通过 npm 全局安装：

npm install -g @maka/cli
maka run "帮我分析当前目录的代码结构"

由于 CLI 和 Desktop 共享 Workspace 和模型连接配置，用户可以在 Desktop 中配置好连接后，直接在终端使用相同配置，体验一致。

局限与争议

平台支持不完整

截至目前，Desktop 仅 macOS Apple Silicon 可用。Linux 和 Windows 用户无法体验完整的桌面 UI，只能使用 CLI。这对于一个以"本地优先"为核心理念的项目来说，是一个较大的遗憾——本地优先的用户恰恰可能分布在各种操作系统上。

缺乏容器化

项目未提供 Dockerfile 或 docker-compose 配置。对于希望在服务器端部署或进行 CI/CD 集成的开发者来说，只能通过 Node.js 运行时自行包装，门槛较高。

生态系统尚处早期

作为 Apache 孵化项目，Maka 的第三方集成、主题插件、社区工具等生态还在建设阶段。相比之下，Open Interpreter、Claude Code 等竞品已有较为丰富的插件生态。

隐私边界的平衡

虽然数据默认存储本地，但"本地优先"不等于"完全隔离"——用户仍然需要通过 API 连接到云端模型（OpenAI、Anthropic 等），这些请求的数据处理遵循各提供商的隐私政策。如果用户对数据主权有极高要求，使用本地模型（如通过 Ollama）才是彻底的本地方案。

行业意义：重新定义 Agent 的可靠性

从"上下文即记忆"到"日志即真相"

云端 Agent 的一个根本局限在于，模型的"记忆"完全依赖于上下文窗口——一旦上下文被截断，历史交互就彻底丢失。Maka 的事件溯源架构从根本上解决了这个问题：会话可以随时从日志重建，不依赖上下文大小。这对于需要长时间、多轮、复杂任务的 Agent 场景意义重大。

Agent 评估的基础设施价值

@maka/eval 模块代表了另一个重要方向——Agent 系统的可评估性。随着 AI Agent 在生产环境中的广泛应用，如何科学地评估不同 Agent 系统的能力边界成为行业刚需。一个结构化、可复现的 Benchmark 框架，是推动 Agent 技术进步的基础设施。

Local-first 运动的一环

Maka 加入了 Ollama、LM Studio、Jan 等工具组成的 Local-first AI 生态。这不仅是隐私驱动的选择，也反映了 AI 推理成本结构的变化——随着本地推理性能提升和成本下降，在本地运行模型的经济性正在改善。

增长态势

项目于 2026 年进入活跃开发阶段，GitHub 社区正在增长。虽然桌面端平台支持受限，但其独特的架构设计和 Apache 基金会的背书，使其在 AI Agent 基础设施领域具备长期价值。MCP 协议集成和 Eval 基准测试框架是当前的两个技术亮点，值得关注后续发展。

---

本报告基于 apache/maka GitHub 仓库 v0.1.11 版本生成。