Apache Maka 开源解读：local-first Agent 工作台的事件日志架构与上手指南

Maka 是 Apache 基金会孵化器里的一个本地优先（local-first）AI Agent 工作台：会话数据、设置与运行记录默认留在本机，模型由使用者自行接入，云端 API、本地模型或兼容网关均可。桌面端、终端 TUI、非交互 CLI 与评测框架共用同一个执行引擎 Runtime Host，所有模型消息、工具调用、工具结果与终止事件以只追加（append-only）日志的形式落盘。项目 2026 年 5 月底创建，三个月内 GitHub star 数达到 2800+，代码以 TypeScript 为主，采用 Apache License 2.0 协议。

要解决的四个问题

README 把 Maka 的设计动机归纳为四点，每一点都指向当前云绑定 Agent 产品的一个具体痛点。

数据归属。 会话、设置、运行记录默认保存在本地 Electron userData 目录下，没有任何云端账户强制绑定。模型连接由用户自己配置，Maka 不附带共享模型账户，首次启动需要在 Settings → Models 里添加 API、本地模型或受支持的账户连接，测试通过后选定默认模型。应用区分「已配置」「可发送」「实验性」三种连接状态，没有接入 Runtime 的账户流程不会伪装成可用模型。

执行记录的持久性。 模型消息、工具调用、工具结果以及每个 Turn 的结束方式都被写入记录，UI 展示和下一次模型调用的输入都只是这份记录的投影。界面崩溃或会话丢失后，事实记录仍然可以恢复。

上下文裁剪与历史保留的解耦。 为了控制 token 消耗，Agent 产品普遍会裁剪旧的工具输出。Maka 的做法是只修改发给模型的输入投影，已保存的证据不受影响，裁剪过的历史随时可以回查。

执行入口的统一。 桌面端、TUI、CLI 和评测系统全部通过 Runtime Host 执行，没有任何一个入口私建第二套运行时。评测系统只拥有实验与分数的语义。

架构：单一执行权威 + 事件日志

后端的调用链路是：

Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun
                                            ↓
                      Model + Tool Runtime → Runtime Event Log
                                            ↓
                           Context / Session / UI projections

Experiment → Cells → Attempts → Results
                      ↓
         Runtime Host executes Maka subjects

Runtime Host 是唯一的执行权威，负责会话与 Turn 的身份管理、Agent 生命周期、续跑、工具、权限和事件。整个系统分四层：

1. Runtime Event Log 是模型消息、工具调用、工具结果和终止事实的规范数据源，上下文裁剪与压缩只改变 provider 输入投影，历史记录本身不动。
2. SessionManager 与 AgentRun 负责执行生命周期，Runtime Host 负责准入、客户端能力、交互与公共协议。
3. Agent Graph 用子会话调度依赖任务，每次激活都经过同一个 Runtime。
4. Storage 只管交互式运行时状态，不含任何评测专属的根目录、任务账本或实验结果权限。

这种事件溯源（event-sourcing）设计在数据库选型上体现得具体：本地状态保存在一个 runtime.sqlite 文件里，仓库 topics 也明确标注了 event-sourcing。

仓库结构与包边界

代码组织成清晰的职责边界，六个 package 各管一段：

本地数据目录结构如下：

<Electron userData>/workspaces/default/
  runtime.sqlite
  connection-catalog.json
  credential-vault.json
  settings.json
  artifacts/

credential-vault.json 是一个本机明文文件，仅操作系统账户可读，渲染进程接触不到密钥。写入文件或执行 shell 的工具必须先通过沙箱边界审批。

三个入口

桌面端支持从任意 Turn 创建、归档、搜索、重命名、重试、重新生成和分支会话；Artifact 列表与预览、工作区指令、模型设置与沙箱设置都在界面内配置。本地记忆和网页搜索在配置后可用，IM 聊天机器人（bot）目前是实验特性。

CLI 有一个 --graph 参数，用隔离的 Git worktree 执行并行任务图，例如 maka run --graph "Implement two independent slices, integrate them, then review the result"。非交互的 graph 运行会等待持久化 Graph 完成后输出最终结果。源码仓库的 CLI 使用 Maka Dev profile，发布版二进制使用 Maka profile，两者不会自动同步。

内置工具与沙箱模型

内置工具集是编码 Agent 的标准六件套：Read、Write、Edit、Bash、Glob、Grep，其中 Grep 依赖系统安装的 ripgrep。Computer Use 和技能目录（catalog skills）默认关闭，需要显式开启。离开沙箱的工具调用必须经过审批，运行可以中止，失败会被分类记录。

崩溃恢复与中断续跑是可选项：默认关闭，设置 MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 后开启桌面端 Safe resume、CLI /resume 与启动自动恢复，这些操作会真实调用模型并消耗 token。

Eval 子系统：把实验语义从运行时里剥离

评测模块的设计有几个少见的严格约束。一个实验由 benchmark、executor、被测对象、任务与重复次数声明式展开，每个单元格（Cell）是 task × repetition × subject 的组合；同一单元格的基础设施重试会产生多个不可变的尝试（attempt），结果选取规则固定为「最早有效尝试」，操作者无法挑选对自己有利的结果。结果内核只包含分数、归一化用量、可归因成本、时长、状态、失败原因与 Artifact。

Maka 自己的被测对象必须跨过 Runtime Host 的公共协议边界执行，外部竞品则通过通用外部适配器接入。Harbor 和 Pier 是执行器适配器，属于同一套工作流的不同实现。

从源码构建上手

Maka 尚未发布 Apache 正式版本，仓库当前发布的所有产物（含包注册表里的内容）都属于孵化前或孵化期产物，未经 Incubator PMC 审查投票。README 明确建议先不下载预构建包，从源码构建运行：

git clone https://github.com/apache/maka.git
cd maka
npm ci
npm run dev

环境要求：Node.js 22.19 或更新版本（CI 用 Node.js 24）、npm 11、Git，以及 ripgrep。桌面端目前只支持 Apple Silicon（arm64）的 macOS，Intel Mac 与 Linux 暂不支持，Windows 是未签名预览版。

构建所有工作区后可以启动 TUI 或跑单个任务：

npm run build
npm run cli:dev
npm run cli:dev -- run "Summarize this repository and identify its most important risk"

开发常用校验命令包括 npm run typecheck、npm test、npm run check:release，单个工作区可以用 npm --workspace @maka/runtime test 这样的形式独立跑测试。模型目录数据来自 models.dev，刷新脚本在任一已提交模型、能力、provider 覆盖或价格字段消失时会主动失败（fail closed），需要人工确认后加 --accept-upstream-removals 才能继续。

现状与边界

处于活跃开发期是当前使用 Maka 需要接受的前提：数据格式、CLI 命令与实验性能力都可能变动；旧版 JSONL 会话记录与 Electron safeStorage 凭据不迁移，升级后旧会话可能显示为空，密钥需要重新录入。IM bot、Computer Use、目录技能都还停在实验或默认关闭状态。

在 Agent 工具普遍以云端账户为中心的格局里，Maka 选了一条不同的路线：执行引擎、数据、模型连接全部本地化，把 Agent 的每一次工具调用都变成可审计、可恢复的本地事实。对需要在自有环境里跑 Agent、且关心执行过程可追溯的团队，这份架构文档值得从头读一遍；对普通开发者，等它出第一个 Apache 正式版本再上手也不迟。

来源：apache/maka README · ARCHITECTURE.md · Apache Incubator 项目页