Apache Maka (Incubating)

Apache Maka (Incubating) at The Apache Software Foundation Apache Maka (Incubating) 是 Apache 软件基金会（ASF）旗下的孵化项目。

A local-first Agent workspace built for real work. Maka inspects projects, runs tools under a sandbox boundary, and records model messages and tool calls as recoverable execution facts — on your machine, through one Runtime Host. 这是一个为实际工作构建的“本地优先”智能体（Agent）工作空间。Maka 能够检查项目，在沙盒边界内运行工具，并将模型消息和工具调用记录为可恢复的执行事实——所有操作均在您的机器上通过单一运行时主机（Runtime Host）完成。

Note 注意 Apache Maka (Incubating) is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision-making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. Apache Maka (Incubating) 是 Apache 软件基金会（ASF）正在孵化的项目，由 Apache Incubator PMC 赞助。所有新接收的项目都必须经过孵化，直到进一步审查表明其基础设施、沟通和决策流程已稳定，并与其他成功的 ASF 项目保持一致。虽然孵化状态并不一定反映代码的完整性或稳定性，但它确实表明该项目尚未得到 ASF 的全面认可。

DISCLAIMER-WIP records the issues the project is currently aware of. DISCLAIMER-WIP 记录了项目目前已知的问题。

Important 重要提示 Maka is under active development. The macOS Apple Silicon desktop build is an early public release; data formats, CLI commands, and experimental capabilities may still change. Maka 处于活跃开发阶段。macOS Apple Silicon 桌面版是早期公开版本；数据格式、CLI 命令和实验性功能仍可能发生变化。

Why Maka / 为什么选择 Maka

Your machine, your data. Sessions, settings, and run records stay local by default. 您的机器，您的数据。会话、设置和运行记录默认保留在本地。

You bring the model: a cloud API, a local model, or a compatible gateway. 模型由您提供：可以是云端 API、本地模型或兼容的网关。

The record is kept. Model messages, tool calls, tool results, and how a turn ended are written down. The UI and the next model call are views of that record, not the only copy. 记录会被保存。模型消息、工具调用、工具结果以及回合结束的方式都会被记录下来。UI 和下一次模型调用只是该记录的视图，而非唯一副本。

Shorter context is not deleted history. Maka can omit old tool output from the next prompt without throwing away the saved evidence. 较短的上下文并不意味着删除历史记录。Maka 可以在不丢弃已保存证据的情况下，从下一次提示词中省略旧的工具输出。

One place runs the agent. Desktop, the terminal, and Maka evaluation all go through Runtime Host. Eval only owns the experiment and its scores. Read Maka Backend Architecture for the design. 单一位置运行智能体。桌面端、终端和 Maka 评估全部通过运行时主机（Runtime Host）运行。评估（Eval）仅负责实验及其评分。请阅读《Maka 后端架构》以了解其设计。

Surfaces / 交互界面

Entry point	Best for	Current capability
入口点	适用场景	当前能力
Desktop	Daily interaction, file and Artifact workflows, model and permission setup	Electron + React with streaming sessions, tool timelines, branching, search, and recovery
桌面端	日常交互、文件和工件（Artifact）工作流、模型和权限设置	Electron + React，支持流式会话、工具时间线、分支、搜索和恢复
TUI / CLI	Using Maka in the current project directory or running one non-interactive Turn	maka, maka run; shares workspace and model connections with Desktop
TUI / CLI	在当前项目目录中使用 Maka 或运行非交互式回合	maka, maka run；与桌面端共享工作空间和模型连接
Eval	Reproducible benchmark experiments across Maka and external subjects	maka eval run <spec> --out <directory>
评估	跨 Maka 和外部对象的复现基准实验	maka eval run <spec> --out <directory>

Current capabilities / 当前能力

• Agent Runtime: Multiple model connections, streaming output, thinking, usage, and clearer provider errors; Built-in tools: Read, Write, Edit, Bash, Glob, Grep. 智能体运行时：支持多个模型连接、流式输出、思考过程、用量统计和更清晰的提供商错误信息；内置工具：Read, Write, Edit, Bash, Glob, Grep。
• Computer Use: Computer Use and catalog skills are optional and not on by default; Tools that leave the sandbox must be approved; runs can be aborted; failures are classified; A durable execution record, crash recovery, and optional resume of an interrupted turn. 计算机使用：计算机使用和目录技能是可选的，默认不开启；离开沙盒的工具必须经过批准；运行可以中止；故障会被分类；提供持久的执行记录、崩溃恢复以及中断回合的可选恢复功能。
• Desktop workspace: Create, archive, search, rename, retry, regenerate, and branch sessions from a Turn; Artifact lists and previews, workspace instructions, model settings, and sandbox settings; Local memory and web search when configured; Chat apps (IM bots) are experimental. 桌面工作空间：从回合中创建、归档、搜索、重命名、重试、重新生成和分支会话；工件列表和预览、工作空间指令、模型设置和沙盒设置；配置后支持本地记忆和网络搜索；聊天应用（IM 机器人）为实验性功能。
• Evaluation: Declarative multi-arm experiments expanded into task × repetition × subject cells; Immutable per-cell attempts with targeted infrastructure replacement and earliest-valid selection; A small result kernel for score, normalized usage, attributable cost, duration, status, failure reason, and artifacts; Maka subjects execute only through Runtime Host; external subjects use generic external subject adapters. 评估：声明式多臂实验，扩展为“任务 × 重复 × 对象”单元格；每个单元格的尝试不可变，支持针对性的基础设施替换和最早有效选择；包含评分、标准化用量、可归因成本、持续时间、状态、失败原因和工件的小型结果内核；Maka 对象仅通过运行时主机执行；外部对象使用通用的外部对象适配器。

Quick start / 快速开始

Releases and downloads 发布与下载 Apache Maka has not made an Apache release yet. Everything currently published from this repository or from a package registry was produced before or during incubation, is not an Apache Software Foundation release, and has not been reviewed or voted on by the Incubator PMC. Apache Maka 尚未进行 Apache 正式发布。目前从本仓库或包注册表发布的所有内容均在孵化前或孵化期间产生，不属于 Apache 软件基金会发布，也未经 Incubator PMC 审查或投票。

Once Apache releases exist, the official release is the source release published by the ASF and approved by the podling PPMC and the Incubator PMC. 一旦 Apache 正式发布，官方版本将是经 ASF 发布并由 podling PPMC 和 Incubator PMC 批准的源代码版本。

Build and run Maka from source 从源码构建并运行 Maka Desktop currently targets Apple Silicon Macs (arm64). Intel Macs and Linux are not supported yet. Windows is an unsigned preview, not a supported release tier. 桌面端目前针对 Apple Silicon Mac (arm64)。暂不支持 Intel Mac 和 Linux。Windows 版本为未签名的预览版，非受支持的发布级别。

Requirements 要求 Node.js 22.19 or newer; npm; Git; ripgrep. Node.js 22.19 或更高版本；npm；Git；ripgrep。

Start Desktop 启动桌面端

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

First run 首次运行 Maka does not bundle a shared model account. On first launch: Open Settings → Models; Add an API, local-model, or supported account connection; Test it and choose a default model; Return to the workspace and start a task. Maka 不捆绑共享模型账户。首次启动时：打开设置 → 模型；添加 API、本地模型或支持的账户连接；测试并选择默认模型；返回工作空间并开始任务。