Apache Maka: 本地优先的AI Agent工作空间

为真实工作而生的本地优先 Agent 工作空间。

Maka 不仅仅回答问题。凭借受控的权限，它能够审查项目、执行工具、生成产物，并将模型消息和 Tool Call 保留为可恢复的执行事实。Desktop、终端 TUI、非交互式 CLI 以及 Maka 评估主体都通过 Runtime Host 执行。

Maka 正在活跃开发中。macOS Apple Silicon Desktop 构建是早期公开版本；数据格式、CLI 命令和实验性功能可能仍会发生变化。

本地优先而非托管优先：会话、设置和运行记录默认保存在你的机器上。由你选择模型连接方式：云 API、本地模型或兼容的网关。

Log 即 Runtime：模型消息、Tool Call、Tool Result 和终止事实进入 Runtime Event Log。会话、UI、模型上下文和恢复都是对该 Log 的投射。

上下文不等于历史：Tool Result 剪枝和 LLM Compaction 改变了下一次推理所看到的内容，而不会将记录在案的证据视为可丢弃的上下文。

唯一执行权威：Runtime Host 拥有 Session、Turn、agent 生命周期、续体、工具和事件的所有权。Eval 仅拥有实验语义和结果。

阅读 Maka Backend Architecture 获取完整设计。

多模型连接、流式输出、thinking、用量统计，以及 provider 错误归一化；

本地工具包括 Read、Write、Edit、Bash、Glob 和 Grep；

工具 schema 验证、动态可用性、权限策略、看门狗、中止和错误分类；

Runtime Event Log、AgentRun 账本、启动恢复、Turn Evidence、活跃 Tool Result 剪枝和历史压缩。

从 Turn 创建、归档、搜索、重命名、重试、重生成和分支会话；

产物列表和预览、工作区指令、模型设置和权限设置；

本地记忆、网络搜索和 bot 入口点；

集成的配置相互独立，并非每个实验性入口都默认启用。

声明式多臂实验展开为 task × repetition × subject 单元格；

不可变的每单元格尝试，定向基础设施替换和最早有效选择；

一个小型结果内核，包含 score、normalized 用量、可归因成本、duration、status、failure reason 和 artifacts。

Maka 主体仅通过 Runtime Host 执行；外部竞争者使用通用外部主体适配器。

下载 macOS Desktop

签名并公证的 Desktop 应用仅适用于 Apple Silicon Mac（arm64），可从 GitHub Releases 下载。

下载Maka-<version>-mac-arm64.dmg；

打开 DMG 并将 Maka 拖入 Applications；

安装 ripgrep：brew install ripgrep，以启用 Runtime 的 Grep 工具；

启动 Maka，在 Settings → Models 下配置你自己的模型连接。

Computer Use 不包含在此首次公开构建中。Intel Mac、Windows 和 Linux 包尚未支持。

Windows 仍为未签名预览版，不属于支持的发布层级。当某版本包含 Windows 资产时，在运行 Maka-<version>-win-x64.exe 之前遵循 Windows 预览版安装和验证指南。SmartScreen 会将安装程序标识为来自未知发布者；除非下载的 SHA-256 与同版本发布的校验和匹配，否则不要绕过该警告。

环境要求

Node.js 22.19 或更高版本（CI 使用 Node.js 24）；

npm（lockfile 和脚本使用 npm；当前的 packageManager 是 npm 11）；

ripgrep，供 Runtime 的 Grep 工具使用。

快速开始

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

npm run dev 启动带有 HMR 的 Desktop 开发环境。如需在启动前构建每个工作区，使用：

npm run dev:full

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

node node_modules/electron/install.js

配置模型

Maka 不捆绑共享模型账户。初次启动时：

打开 Settings → Models；

添加 API、本地模型或支持账户的连接；

测试并选择默认模型；

返回工作区并开始任务。

应用区分 configured、send-ready 和 experimental 连接状态。未接入 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 使用与开发 Desktop 构建相同的Maka Dev profile。发布的 maka 二进制文件继续使用Maka profile；两个 profile 不会自动复制或同步。评估 spec 和适配器位于 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/      关于 Sessions、Events、Permissions 和 Connections 的纯合约
packages/storage/   SQLite 运营状态、配置和 payload 存储
packages/runtime/   AgentRun、模型适配器、工具、上下文和恢复
packages/eval/      实验单元格、尝试、结果和执行器/主体适配器
packages/cli/       TUI 和非交互式 CLI
packages/ui/        共享对话、Markdown、Artifact 和 UI 原语

docs/               架构、产品、安全、隐私和测试合约
scripts/            构建卫生、视觉检查、冒烟测试和发布辅助脚本

本地数据和安全边界

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 Policy 凭证，包括 Connection API/OAuth 材料、请求头、web-search 密钥和代理密码，以本地明文形式保存在 credential-vault.json 中，位于 OS 账户边界之后，并强制执行 POSIX 目录模式 0700 和文件模式 0600；

Runtime Host 客户端 profile 访问凭证是独立的，位于 <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 控制、核心执行状态、工作流状态、用量和定价、Artifact 元数据、Automations、Daily Review 以及 Runtime 续体记录。Artifact payload 字节仍是 artifacts/ 下的常规文件；连接、凭证、设置、MCP 配置、技能和设备身份仍是配置文件。

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

完整操作备份使用数据库所有者的在线 SQLite 备份 API，并在 Artifact 写入器锁下复制规范 Artifact payload。其清单按大小和 SHA-256 绑定每个文件。验证检查独立 SQLite 快照的完整性、外键、schema 注册表和必需表，解码规范 session-message 和 Artifact 记录，并在恢复前根据 SQLite 元数据验证 Artifact payload 大小。备份和恢复使用仅所有者文件模式、文件和目录同步、分阶段和原子发布。

Runtime 续体仍然是可选项：

MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 启用 Desktop 中断的 Turn Safe resume 操作、CLI/TUI /resume 和 Desktop 启动自动 resume。这些路径可能调用配置的模型 provider 并消耗 token。仅在明确需要该行为时才启用该标志。

第二阶段提供持久的写侧边界和 fail-closed 安全边界续体。第三阶段关于不确定工具副作用的协调尚未实现；模糊的工具结果被搁置而非重试。

开发和验证

发送更改前阅读 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

Desktop 真实窗口和视觉验证：

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

提交代码前，运行与更改成比例的 typecheck、build 和针对性测试，然后运行 git diff --check。

文档索引和权威地图

Maka 根据 Apache License 2.0 获得许可。参见 NOTICE 了解归属信息。第三方组件仍受其各自许可证和通知的约束。