maka

一般青年的任务，尤其是共产主义青年团及其他一切组织的任务，可以用一句话来表示，就是要学习。—— 列宁

Apache Maka：把智能代理的每一次行动，留在自己的机器上

当 AI Agent 开始进入真实工作流，人们关心的早已不只是“它能不能回答问题”。

更重要的问题是：它做过什么，它调用了什么工具，它读过哪些内容，它写下了什么结果，它为何停止，它在中断之后还能不能被找回。

Apache Maka 给出的回答很直接：让这些过程成为可以保存、可以恢复、可以查看的执行事实。

Apache Maka 是一个以本地优先为核心的 AI Agent 工作空间。它将模型消息、工具调用、工具结果、权限决策与终止事件记录为追加式日志，让代理运行过程不只停留在一段临时对话里，而是成为保存在本机上的工作记录。

项目地址：https://github.com/apache/maka

一台机器，一个持续运行的 Agent 工作空间

Maka 的出发点并不复杂，却很有分量。

它把用户的机器视作工作发生的主要地点。会话、设置和运行记录默认保留在本地，用户可以自行接入云端 API、本地模型，或兼容的网关连接。模型并不是一个被平台统一托管的黑盒入口，而是由用户带入 Maka 工作空间的能力来源。

这让 Maka 的工作方式更像一间属于自己的工作室。

任务在这里发起，模型在这里响应，工具在这里执行，运行记录也在这里落地。桌面端、终端与评测能力并不是各自独立的一套系统，它们都会经过同一个 Runtime Host。无论从哪个入口进入，Agent 的运行都会回到同一条执行主线。

在 Maka 的设计中，界面不是唯一的记忆载体。

模型消息、工具调用、工具结果，以及一次对话如何结束，都会被写入记录。界面展示的是这些记录，下一次模型调用所获得的上下文，同样也是这些记录的一种视图。真正留存下来的，不只是看得见的聊天气泡，而是一次次运行留下的执行证据。

历史可以缩短，上下文不必失忆

AI Agent 的上下文总会面临长度问题。

随着任务推进，工具输出会越来越多，历史内容会越来越长。如果所有信息都持续塞进后续提示词，上下文会变得沉重。如果直接删去旧内容，又可能让关键过程消失得无影无踪。

Maka 在这里强调了一个清晰的原则：更短的上下文，不等于被删除的历史。

它可以在下一次提示中省略较早的工具输出，同时仍然保留已经保存的证据。也就是说，模型不必始终携带全部旧输出继续前行，但此前发生过的执行过程并不会因此被抹掉。

这让一次长任务拥有了更稳妥的节奏。

上下文可以保持更聚焦，记录仍然能够完整存在。模型面向的是适合继续处理任务的信息，用户面对的则是能够回溯的执行事实。两者不必互相牺牲。

Runtime Host：让不同入口汇入同一条运行脊梁

Maka 的核心结构围绕 Runtime Host 展开。

桌面端、TUI、CLI 都会经过 Runtime Host，再进入 SessionManager 与 AgentRun。模型与工具运行时会持续产生 Runtime Event Log，而这些事件又进一步形成上下文、会话与界面上的不同呈现。

整体路径可以概括为：

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

这条结构让 Maka 的多个使用入口拥有共同的运行基础。

桌面端负责日常交互，终端适合在当前项目目录中直接使用，CLI 也可以执行单次非交互任务。它们的外观和使用方式不同，但运行并不分散。无论是打开桌面工作区，还是在命令行中启动一个任务，执行过程都会穿过同一个 Runtime Host。

对于评测来说，Runtime Host 同样是关键节点。评测负责实验与评分，而 Maka 作为评测对象时，依然只通过 Runtime Host 执行。这样一来，真实工作流与评测运行并不是两套互不相干的路径，而是在核心执行层保持一致。

桌面、终端与评测，三种不同的工作表面

Maka 提供了三个主要入口。

桌面端面向日常交互，适合处理文件、Artifact 工作流、模型配置与权限设置。它基于 Electron 与 React 构建，支持流式会话、工具时间线、分支、搜索与恢复。

TUI 和 CLI 面向终端场景。用户可以在当前项目目录中使用 Maka，也可以运行一次非交互式 Turn。它与桌面端共享工作区和模型连接，让图形界面与命令行之间不必各自建立孤立的配置体系。

Eval 则面向可复现的基准实验。它可以在 Maka 与外部参与者之间开展实验运行，并将实验展开为任务、重复次数与测试对象组成的单元。

三种入口像是三扇通往同一运行核心的门。

桌面端适合持续地看、管、查与恢复。

终端适合贴近项目目录发起任务。

评测适合用声明式实验描述方式组织和比较运行结果。

它们的关注点不同，但都围绕同一个目标展开：让 Agent 的运行不只是发生一次，而是能够被执行、被记录、被理解。

Agent Runtime：工具不是随意伸出的手

一个能够完成真实工作的 Agent，往往需要读文件、写文件、编辑内容、执行命令、搜索目录与检索文本。

Maka 内置了多种工具：

• Read
• Write
• Edit
• Bash
• Glob
• Grep

其中，Read、Write、Edit、Bash、Glob 与 Grep 构成了运行时内置工具集。Computer Use 与目录技能属于可选能力，默认不会开启。

工具能力越接近真实环境，边界就越重要。

Maka 为工具执行设置了沙箱边界。任何需要离开沙箱的工具都必须经过批准。文件写入与 Shell 执行也需要先通过这一边界。这样一来，Agent 并不是获得无限制的执行权，而是在明确的权限与边界之内行动。

运行过程中可以中止执行，失败也会被分类记录。

这让工具运行不再像一段无法追问的自动过程。每一次调用、每一个结果、每一类失败，都可以回到记录中被查看。Agent 在任务中走过的路径，不只是结果背后模糊的影子，而是具有可见轮廓的过程。

一次中断之后，工作仍有机会继续

长任务最怕的，往往不是难，而是中断。

应用崩溃、执行被打断、任务尚未结束，都会让人担心此前的工作是否已经消失。Maka 将耐久执行记录、崩溃恢复与中断 Turn 的可选恢复能力放进运行时能力之中。

运行记录不仅服务于回顾，也服务于恢复。

当一段任务被打断，已有的执行过程不会只存在于瞬时内存中。Maka 的运行记录可以成为重新理解任务状态的依据。中断后的 Turn 可以选择恢复，而是否启用安全边界恢复，则由环境变量控制。

MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1

启用后，桌面端的 Safe resume、CLI 中的 /resume 与启动时自动恢复会使用相应的恢复能力。

恢复并不意味着忽略边界。README 明确指出，这些调用会触及已保存的运行记录与恢复流程。Maka 在记录、恢复与沙箱之间保持着清晰的分工：工作可以继续，但继续之前发生过什么，依然应当被保留下来。

会话不只是一串聊天消息

Maka 的桌面工作区提供了一组围绕会话展开的能力。

用户可以创建、归档、搜索、重命名会话，也可以从一个 Turn 重新尝试、重新生成，或创建分支。这样一来，Agent 工作过程不必被固定在单一路径上。

一次任务可能需要重试。

一段输出可能需要重新生成。

一个关键节点可能值得从原处延伸出新的分支。

会话在这里不只是对话历史，更像是可持续整理的工作轨迹。用户可以从不同 Turn 出发，保留原有路径，也探索新的方向。

桌面端还提供 Artifact 列表与预览、工作区指令、模型设置与沙箱设置。对于已经在执行中产生文件、内容或其他成果的任务而言，Artifact 能力为这些产物提供了一个更明确的观察入口。

本地记忆与网络搜索也可以在完成配置后使用。

聊天应用机器人属于实验性能力。它说明 Maka 的工作表面并不只局限于传统桌面与终端入口，但这一能力仍处于实验阶段。

从模型连接开始，决定谁来回应任务

Maka 不会捆绑一个共享模型账户。

第一次启动后，用户需要进入模型设置，添加 API、本地模型或受支持的账户连接，测试连接，并选择默认模型。完成这些步骤后，便可以返回工作区开始任务。

启动路径可以概括为：

1. 打开 Settings → Models
2. 添加 API、本地模型或受支持的账户连接
3. 测试连接并选择默认模型
4. 返回工作区并开始任务

Maka 会区分已经配置、已经可以发送请求与实验性连接等不同状态。

这种区分让模型连接不只是一个是否填写了密钥的问题。一个连接是否真正接入 Runtime，是否能够承担实际任务，会影响它在界面中如何被呈现。没有接入 Runtime 的账户流程，不会被当作可用模型展示。

模型连接因此拥有了更清晰的状态边界。

配置完成，不代表一定能发送。

能够发送，不代表一定属于稳定能力。

处于实验阶段，也不会被伪装成已经完全可用的入口。

从源码启动桌面工作区

当前 README 建议从源码构建并运行 Maka。

桌面端当前面向 Apple Silicon Mac，也就是 arm64。Windows 提供未签名的预览构建，Linux 尚未支持。Maka 仍在积极开发中，数据格式、CLI 命令与实验性能力都可能继续变化。

在开始之前，需要准备以下环境：

• Node.js 22.19 或更高版本
• npm
• Git
• ripgrep

其中，ripgrep 被 Runtime 的 Grep 工具使用。

启动桌面开发环境可以执行：

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

npm run dev 会启动带有热模块替换能力的桌面开发环境。

如果希望在启动 Electron 之前先构建全部工作区，可以使用：

npm run dev:full

如果依赖安装时使用了 ELECTRON_SKIP_BINARY_DOWNLOAD=1，则需要在启动前安装 Electron 平台二进制文件：

node node_modules/electron/install.js

这些命令描绘出 Maka 的第一段工作旅程。

克隆源码。

安装依赖。

启动桌面环境。

连接模型。

然后，让第一项任务走进自己的本地工作空间。

在终端里运行一个 Turn

对于偏好终端的用户，Maka 同样提供 TUI 与 CLI 入口。

在源码检出目录中运行开发版 CLI 前，需要先构建工作区：

npm run build

随后可以启动 TUI，或者运行一次非交互式 Turn：

npm run cli:dev
npm run cli:dev -- run "Summarize this repository and identify its most important risk"
npm run cli:dev -- run --graph "Implement two independent slices, integrate them, then review the result"
npm run cli:dev -- --help

TUI 支持 /graph on、/graph off 与 /graph <task>。

非交互式的 --graph 运行会等待持久化 Graph 完成，再输出最终的 supervisor 内容。Graph 中的实现操作会使用隔离的 Git worktree，因此源项目需要是一个干净的 Git worktree。

终端入口让 Maka 更贴近项目目录本身。

不必总是打开图形界面，也可以在正在工作的代码库中直接发起一个任务。模型连接与工作区依然可以与桌面端共享，但任务的触发方式变得更接近开发者平时使用命令行的节奏。

Eval：把实验拆成可追踪的单元

Maka 的 Eval 能力关注可复现的基准实验。

它支持声明式的多分支实验描述，并将实验展开为由任务、重复次数与测试对象组成的单元。每个单元拥有不可变的尝试记录，并支持针对性的基础设施替换与最早有效结果选择。

评测结果包含一组小而明确的结果核心：

• 分数
• 归一化使用量
• 可归属成本
• 持续时间
• 状态
• 失败原因
• Artifact

Maka 作为实验对象时，只能通过 Runtime Host 执行。外部测试对象则通过通用外部对象适配器接入。

这让评测不只是一次输出结果的比较。

实验被拆分为明确的 Cells。

每个 Cell 形成 Attempts。

Attempts 再沉淀为 Results。

任务、重复、对象、状态、失败与产物之间的关系，都可以在这条实验链路中拥有自己的位置。

本地数据：工作记录住在哪里

Maka 的工作区数据默认保存在 Electron 的 userData 目录之下。

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

其中，runtime.sqlite 是实时运行记录。

模型连接目录、凭据存储、设置与 Artifact 目录共同构成了本地工作区的基础内容。API 密钥和类似机密信息保存在本地明文文件 credential-vault.json 中，只有当前操作系统账户可以读取，渲染进程无法看到这些内容。

README 也明确了旧记录的处理边界。

旧的 JSONL 转录记录与 Electron safeStorage 凭据文件不会被导入。升级后的工作区可能显示为空线程，而此前的凭据需要重新处理。这种界限让本地数据状态保持清楚：当前运行记录以 runtime.sqlite 为核心，旧格式并不会被自动混入新的工作区。

从代码组织看 Maka 的边界

Maka 的仓库结构将不同职责拆分为多个位置。

apps/desktop/       Electron main / preload / React renderer

packages/core/      Pure contracts for Sessions, Events, Permissions, and Connections
packages/storage/   SQLite operational state, configuration, and payload stores
packages/runtime/   AgentRun, model adapters, tools, context, and recovery
packages/eval/      Experiment cells, attempts, results, and executor/subject adapters
packages/cli/       TUI and non-interactive CLI
packages/ui/        Shared conversation, Markdown, Artifact, and UI primitives

docs/               Architecture, product, security, privacy, and test contracts
scripts/            Build hygiene, visual checks, smoke tests, and release helpers

从这份结构中，可以看到 Maka 对边界的重视。

packages/core 存放会话、事件、权限与连接相关的纯契约。

packages/storage 负责 SQLite 运行状态、配置与负载存储。

packages/runtime 聚集 AgentRun、模型适配器、工具、上下文与恢复能力。

packages/eval 处理实验单元、尝试记录、结果与执行器、测试对象适配器。

packages/cli 服务于 TUI 与非交互式 CLI。

packages/ui 承担共享的会话、Markdown、Artifact 与界面基础能力。

桌面应用、运行时、存储、评测、命令行与界面并没有被揉成难以区分的一团。它们各自承担角色，也在 Runtime Host 的运行路径中相互连接。

面向开发过程的构建与验证

Maka 在仓库层面提供了常用的构建与验证命令。

npm run build
npm run typecheck
npm test
npm run check:release

也可以单独运行某个工作区的测试：

npm --workspace @maka/runtime test
npm --workspace @maka/eval test
npm --workspace @maka/desktop test

模型元数据可以通过 refresh:model-metadata 进行刷新。该流程会从 models.dev 获取当前目录，更新提交快照，并重新生成派生的 TypeScript 文件。

npm run refresh:model-metadata
npm --workspace @maka/core test

桌面端还提供真实窗口与视觉验证相关命令：

npm --workspace @maka/desktop run e2e
npm --workspace @maka/desktop run smoke:real-window

在提交代码之前，README 建议根据变更范围运行类型检查、构建与聚焦测试，并执行：

git diff --check

这些命令让开发过程不仅围绕功能实现，也围绕构建、类型、测试、真实窗口与视觉检查逐步展开。

Apache Maka 正在孵化，也仍在成长

Apache Maka 当前处于 Apache 软件基金会孵化阶段。

它还没有发布 Apache 正式版本。README 指出，目前从仓库或包注册表获得的内容，均产生于孵化之前或孵化期间，并不构成 Apache 软件基金会正式发布版本。在获得获批的源码发布之前，README 不建议使用预构建下载，而是推荐从源码构建并运行。

这也意味着，Maka 并不是一个已经停止变化的工具。

它仍在积极开发中。

macOS Apple Silicon 的桌面构建属于早期公开版本。

数据格式、CLI 命令与实验性能力仍可能变化。

但正因为如此，Maka 的核心方向显得更加清晰：它正在构建一个以本地为中心、以运行记录为基础、以 Runtime Host 为统一执行核心的 AI Agent 工作空间。

结语

AI Agent 真正进入工作现场之后，最重要的并不只是它生成了什么。

还有它如何生成。

它调用了哪些工具。

它在何处遇到失败。

它执行到哪一步被中断。

它留下了哪些内容。

它是否可以被恢复。

Apache Maka 将这些问题放进一个本地优先的工作空间中处理。它让桌面端、终端、CLI 与评测能力汇入统一的 Runtime Host，让模型消息、工具调用、工具结果、权限决策与终止事件留下追加式记录，也让一次次 Agent 运行不再只是一段短暂的交互。

在 Maka 的世界里，任务不是飘过屏幕的一次回答。

它是一段被执行的过程。

而过程，值得被保留下来。