README

Apache Maka (Incubating)


Apache Maka（孵化中）是一个高性能的 Agent 工作台，并完整记录它做过的每一件事。


  官网 ·
  文档 ·
  下载 ·
  English



  
  
  



  
  


 什么是 Maka

Agent harness 的本职就是把任务做完。衡量它的标准只有一条：完成了多少，花了多少。我们公开每一次运行：同一个模型，同一个官方验证器，逐任务的完整记录。

- 靠测量，不靠宣称。 Maka 与其他 harness 在同一个模型、同一个官方验证器下对比跑分，每份报告都附逐任务结果，见 docs/eval/。
- 日志就是运行时。 每条模型消息、工具调用、权限决定和终止都是一条只追加的 RuntimeEvent。界面、下一轮 prompt 和崩溃恢复都是这份日志的投影，从不是唯一副本。旧的工具输出可以不进下一轮 prompt，但不会从日志里消失。
- 数据在你的机器上，模型由你接。 会话、设置和运行记录保存在本机；云 API、本地模型或兼容网关都可以。
- 一个 Runtime Host。 Desktop、TUI 和 CLI、Eval 都是瘦客户端，执行只由这一个 Runtime Host 说了算；Eval 只负责实验和分数。

官网演示了日志中的一轮，并链接到公开的运行结果。系统地图见 ARCHITECTURE.zh-CN.md。

 获取 Maka

Apache Releases：最新的 Apache release 是 0.2.2（孵化中）。带签名的源码包才是正式 release，其他渠道分发的包属于便利构建。候选版本的准入标准、签名路径与验包步骤见下载页面与 .github/ASF_SOURCE_RELEASE.md。

开发测试：如果希望贡献代码或协助测试尚未发布的改动，请阅读贡献指南并关注开发邮件列表。开发构建不是获批的 Apache 正式版本。

从源码构建：要从源码 checkout 直接构建并运行 Desktop、TUI 或 CLI，见下方的从源码构建一节。

 从源码构建

 环境要求

- Node.js 22.19 或更高的 22.x 版本，或 Node.js 24 及以上（CI 使用 Node.js 24；不支持 Node.js 23）；
- npm（仓库 lockfile 和 scripts 以 npm 为准，packageManager 当前为 npm 11）；
- Git；
- ripgrep，供 Runtime 的 Grep 工具使用。

 启动 Desktop

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


npm run dev 启动带 HMR 的 Desktop 开发环境。需要先完整构建再启动 Electron 时使用：

sh
npm run dev:full


开发 Direct Peer 和 Peer Mesh 还需要 Rust stable 1.98 或更高版本及平台 linker
（macOS 使用 Xcode Command Line Tools，Windows 使用 MSVC Build Tools）。使用 Peer 开发入口，
Desktop 会在启动前构建原生 addon：

sh
npm run dev:peer        HMR
npm run dev:full:peer   完整构建


如果安装时设置过 ELECTRON_SKIP_BINARY_DOWNLOAD=1，启动前需要补装 Electron 平台二进制：

sh
node node_modules/electron/install.js


 第一次运行

Maka 不内置共享模型账号。第一次打开时：

1. 进入 设置 → 模型；
2. 添加一个 API、本地模型或已经接通的账号连接；
3. 测试连接并选择默认模型；
4. 返回工作台开始任务。

应用会根据真实连接状态区分“已配置”“可发送”和“实验入口”，不会把没有接入 Runtime 的账号展示成可用模型。

 使用终端入口

公共 npm 包的安装和使用方式请查看 CLI 中文指南。下面的命令
用于从源码 checkout 运行开发版 CLI。

先构建 workspace：

sh
npm run build


然后可以启动 TUI 或执行单次 Turn：

sh
npm run cli:dev
npm run cli:dev -- run "总结当前仓库并指出最重要的风险"
npm run cli:dev -- run --graph "并行实现两个切片，完成集成，然后独立审查"
npm run cli:dev -- --help


TUI 同时支持 /graph on、/graph off 和 /graph 。非交互
--graph 会等待持久化 Graph 真正结束，再输出 supervisor 的最终结果。
Graph 的 implementation operator 使用隔离的 Git worktree，因此源项目必须是干净的
Git worktree。

仓库 CLI 使用与开发版 Desktop 构建相同的 Maka Dev profile；发布版 maka 二进制仍使用
Maka profile，二者不会自动复制或同步。评测 spec 和 adapter 位于 packages/eval。

 架构

Maka 后端可以用一条主线概括：

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

Experiment → Cells → Attempts → Results
                    ↓
       Runtime Host 执行 Maka subjects


从 ARCHITECTURE.zh-CN.md 开始阅读。它提供总体架构图、代码边界、按问题组织的阅读路径，以及 docs/architecture/ 下深度文章的链接。

 仓库结构

text
apps/desktop/          Electron main / preload / React renderer

packages/core/         Session、Event、Permission、Connection 等纯 contracts
pa