maka

本地优先的 AI Agent 工作空间，将模型消息、工具调用、工具结果、权限决策和终止事件全部记录为 append-only 的 Runtime Event Log，桌面端/TUI/CLI 三种入口共享同一套 agent runtime。亮点是把日志当作运行时本身，支持会话分支、跨进程恢复、工具结果裁剪和上下文压缩，并内置可复现的 eval 实验框架；适合想要完全掌控数据、偏好本地运行的 agent 用户。仍处于 Apache 孵化阶段，尚未发布正式 release，且当前仅支持 macOS Apple Silicon，升级旧工作区时存在明确的数据迁移边界。

README

Apache Maka（孵化中）

![许可证](https://api.ai-feeds.com/r/gh/apache/maka/96ae2a5e24552c3ad0ae57f54f830caf5c102e876107d8c52e5821a3bf5d513a.svg ![文档](https://api.ai-feeds.com/r/gh/apache/maka/a6d7804fcbf6eb08be815e7bfe0d508318c4f9efe3d2eb4e54ac4d24db664899.svg

Maka — 你的工作。你的 Agent。

一个为真实工作而构建的本地优先（local-first）Agent 工作区。

Maka 不只是回答问题。借助受控权限，它可以检查项目、执行工具、产出工件（Artifact），并将模型消息和工具调用（Tool Call）保存为可恢复的执行事实。桌面端、终端 TUI、非交互式 CLI 和 Maka 评测实体全部通过 Runtime Host 执行。

[!NOTE] Apache Maka（孵化中）是 Apache 软件基金会（ASF）正在孵化中的项目，由 Apache Incubator PMC 赞助。所有新接受的项目都必须经过孵化期，直到进一步审查表明其基础设施、沟通和决策流程已稳定到与其他成功的 ASF 项目一致的水平。孵化状态不一定反映代码的完整性或稳定性，但它确实表明该项目尚未获得 ASF 的完全认可。DISCLAIMER-WIP 记录了项目当前已知的问题。

[!IMPORTANT] Maka 正在积极开发中。macOS Apple Silicon 桌面构建是早期公开版本；数据格式、CLI 命令和实验性能力可能仍会发生变化。

为什么选择 Maka

本地优先而非托管优先：会话、设置和运行记录默认保存在你的机器上。你选择模型连接方式：云 API、本地模型或兼容网关。
日志即 Runtime：模型消息、工具调用（Tool Call）、工具结果（Tool Result）和终止事实都会进入 Runtime 事件日志。会话、UI、模型上下文和恢复都是该日志的投影（projection）。
上下文不等于历史：工具结果剪枝（Tool Result pruning）和 LLM 压缩（Compaction）会改变下一次推理所能看到的内容，但不会把已记录的证据当作可丢弃的上下文。
唯一的执行权威：Runtime Host 拥有 Session、Turn、Agent 生命周期、续跑（continuation）、工具和事件的所有权。Eval 只拥有实验语义和结果。

完整设计请阅读 Maka 后端架构。

使用入口

入口	最适合	当前能力
桌面端	日常交互、文件和工件工作流、模型和权限设置	Electron + React，支持流式会话、工具时间线、分支、搜索和恢复
TUI / CLI	在当前项目目录中使用 Maka，或运行一个非交互式 Turn	`maka`、`maka run`；与桌面端共享工作区和模型连接
Eval	在 Maka 和外部评测对象之间进行可复现的基准实验	`maka eval run <spec> --out <directory>`

当前能力

Agent Runtime

多模型连接、流式输出、思考过程、用量统计和 provider 错误归一化；
本地工具，包括 Read、Write、Edit、Bash、Glob 和 Grep；
工具 schema 校验、动态可用性、权限策略、看门狗（watchdog）、中止和错误分类；
Runtime 事件日志、AgentRun 账本、启动恢复、Turn 证据、主动工具结果剪枝和历史压缩。

桌面工作区

从 Turn 创建、归档、搜索、重命名、重试、重新生成和分支会话；
工件列表和预览、工作区指令、模型设置和权限设置；
本地记忆、Web 搜索和机器人入口；
集成是独立配置的，并非每个实验入口都默认可用。

评测（Evaluation）

声明式多臂实验，展开为任务 × 重复 × 评测对象单元格；
每个单元格尝试不可变，支持定向基础设施替换和最早有效选择；
小型结果内核，包含分数、归一化用量、可归属成本、持续时间、状态、失败原因和工件；
Maka 评测对象只能通过 Runtime Host 执行；外部评测方使用通用外部评测对象适配器。

快速开始

版本和下载

Apache Maka 尚未发布 Apache 正式版本。当前从本仓库或软件包仓库发布的所有内容都是在孵化前或孵化期间产生的，不是 Apache 软件基金会发布版本，也未经过 Incubator PMC 的审查或投票。

一旦 Apache 正式版本存在，官方发布版就是由 ASF 发布并经 podling PPMC 和 Incubator PMC 批准的资源发布版。基于该资源构建并通过其他渠道（例如软件包仓库或桌面安装程序）分发的软件包仅是便捷工件，而非发布版本身，并且只有基于已批准的官方资源发布版构建时才有效。.github/ASF_SOURCE_RELEASE.md 记录了候选合同、签名路径和验证步骤。

在存在已批准的官方资源发布版之前，本 README 不建议下载任何预构建版本。请按照下文说明从源码构建并运行 Maka。桌面端当前面向 Apple Silicon Mac（arm64）；Intel Mac、Windows 和 Linux 尚不支持，Windows 支持仍是无签名的预览版，而非受支持的发布层级。

环境要求

Node.js 22.19 或更新版本（CI 使用 Node.js 24）；
npm（lockfile 和脚本使用 npm；当前 packageManager 为 npm 11）；
Git；
ripgrep，Runtime 的 Grep 工具使用。

启动桌面端

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

npm run dev 以 HMR 启动桌面端开发环境。要在启动 Electron 前构建所有工作区，请使用：

npm run dev:full

如果依赖是在 ELECTRON_SKIP_BINARY_DOWNLOAD=1 的情况下安装的，请先安装 Electron 平台二进制文件：

node node_modules/electron/install.js

首次运行

Maka 不捆绑共享模型账号。首次启动时：

打开 设置 → 模型；
添加 API、本地模型或支持的账号连接；
测试并选择默认模型；
返回工作区并开始任务。

应用会区分已配置、可发送和有实验性的连接状态。未接入 Runtime 的账号流程不会显示为可用模型。

终端入口

有关公共 npm 包，请参阅 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。

仓库 CLI 使用与开发版桌面端相同的 Maka Dev 配置文件。发布版 maka 二进制继续使用 Maka 配置文件；这两个配置不会自动复制或同步。评测规格和适配器位于 packages/eval。

架构

后端主干为：

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

从 ARCHITECTURE.md 开始阅读。它提供了系统地图、代码边界、按问题导向的阅读路径，以及六个双语深度解析。

仓库结构

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 默认将工作区数据存储在 Electron userData 下：

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

当前重要的边界：

当前连接目录为 connection-catalog.json。已有的 llm-connections.json 文件会保留在磁盘上，但不会被导入；
会话、消息、执行账本、工作流、用量、Automations 和 Daily Review 都保存在 runtime.sqlite 中；
Runtime 策略凭据（包括连接 API/OAuth 材料、请求头、Web 搜索密钥和代理密码）以本地明文 credential-vault.json 保存，受操作系统账户边界保护，并强制使用 POSIX 目录模式 0700 和文件模式 0600；
Runtime Host 客户端配置文件访问凭据单独存储，位于 <Electron userData>/runtime-host-client/credentials.json 下。已有的 Electron safeStorage 凭据/令牌文件不会被导入；受影响的用户必须重新认证；
Renderer 不会收到明文凭据。文件写入、Shell 和危险工具调用都通过权限引擎；
Eval 不构建 Runtime，也不读取 Runtime 存储。Maka 评测对象连接到已有的 Runtime Host。

安全报告和策略请阅读 SECURITY.md，当前的隐私和沙箱契约请阅读 docs/README.md。

Runtime 存储和恢复

runtime.sqlite 是唯一的运行权威。它拥有 RuntimeEvents、会话元数据和消息历史、Agent Graph 控制、核心执行状态、工作流状态、用量和价格、工件元数据、Automations、Daily Review 以及 Runtime 续跑记录。工件载荷字节仍是 artifacts/ 下的普通文件；连接、凭据、设置、MCP 配置、技能和设备身份仍为配置文件。

本代存储不会导入早期的 File/JSONL 权威数据。升级后，旧会话标题可能仍可通过当前元数据发现，但仅存在于旧版 transcript 文件中的对话历史不会被复制到 session_messages，打开后将显示为空线程。同样，早期版本或 safeStorage 加密的凭据/令牌文件也不会迁移；只有这些副本的用户必须重新认证。这一数据丢失边界是本版本的刻意设计，升级现有工作区之前必须考虑到这一点。

完整操作备份使用数据库属主的在线 SQLite 备份 API，并在工件写入锁下复制规范工件载荷。其清单按大小和 SHA-256 绑定每个文件。验证会检查独立 SQLite 快照的完整性、外键、schema 注册表和必需表，解码规范的会话消息和工件记录，并在恢复前对照 SQLite 元数据验证工件载荷大小。备份和恢复使用属主专属文件模式、文件和目录同步、暂存以及原子发布。

Runtime 续跑仍为选择启用：

MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 启用桌面端中断 Turn 的 安全续跑操作、CLI/TUI /resume 以及桌面端启动自动续跑。这些路径可能调用已配置的模型 provider 并消耗 token。仅在明确需要该行为时启用此标志。

阶段 2 提供持久化写入侧边界和失败关闭（fail-closed）的安全边界续跑。阶段 3 对不确定工具副作用的对账尚未实现；模糊的工具结果会保持暂停状态，不会重试。

开发和验证

提交更改之前，请阅读 CONTRIBUTING.md。

常用仓库级命令：

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

使用以下命令可以从 models.dev 更新 packages/core/src/model-metadata.generated.ts 并运行相关测试。访问路径专属的覆盖配置请保留在 model-metadata.ts 中；不要手动编辑生成文件。

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

桌面端真实窗口和视觉验证：

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

提交代码前，请运行与更改规模相称的类型检查、构建和聚焦测试，随后执行 git diff --check。

文档

许可证

Maka 采用 Apache License 2.0 许可证。参见 NOTICE 了解版权归属信息。第三方组件仍受其各自许可证和声明约束。

Apache Maka、Maka、Apache、Apache 羽毛标志和 Apache Maka 项目徽标是 Apache 软件基金会的注册商标或商标。

开源项目apache2026-08-22原文

打开互动版