开源项目 GitHub Trending 2026-08-22T00:01 正文 ok 1567 words

Apache Maka(孵化中):本地优先的 AI Agent 工作空间

英文标题:🔥 apache/maka

Apache Maka(Incubating)是一款本地优先的 AI Agent 工作空间,将模型消息、工具调用、工具结果、权限决策和终止事件记录为可恢复的追加式执行日志。其 Desktop、TUI、非交互式 CLI 以及评测主体均通过 Runtime Host 执行,统一管理 Session、Turn、Agent 生命周期、工具和事件。项目目前提供 macOS Apple Silicon 的已签名公测版,Windows 仍处于未签名预览阶段,Intel Mac、Linux 和 Computer Use 尚未支持。对开发者而言,Maka 提供本地工具调用、权限控制、上下文压缩、运行恢复、可复现实验评测及 SQLite 备份恢复机制,但现有数据格式、CLI 命令和实验性功能仍可能变动。
打开原文相关 3 · 机会 4
media2.2 KB media1.3 KB media2.8 KB media1.5 MB media59.8 KB

中文

CI 许可证 文档

Maka——你的工作,你的 Agent。

为实际工作构建的本地优先 Agent 工作空间。

Maka 不止能回答问题。在受控权限下,它能够检查项目、执行工具、产出制品,并将模型消息和工具调用保留为可恢复的执行事实。Desktop、终端 TUI、非交互式 CLI 以及 Maka 评测主体,均通过 Runtime Host 执行。

重要说明

Maka 正处于积极开发阶段。macOS Apple Silicon Desktop 构建版本是早期公开发布版本;数据格式、CLI 命令和实验性能力仍可能发生变化。

  • 本地优先,而非托管优先:默认情况下,Session、设置和运行记录均保留在你的设备上。你可自行选择模型连接方式:云端 API、本地模型或兼容网关。
  • 日志即 Runtime:模型消息、Tool Calls、Tool Results 和终止事实均会进入 Runtime Event Log。Session、UI、模型上下文和恢复功能,都是这一日志上的投影。
  • 上下文不等于历史:Tool Result 裁剪和 LLM Compaction 会改变下一次推理可见的内容,但不会将已记录的证据视为可丢弃的上下文。
  • 单一执行权威:Runtime Host 负责 Session、Turn、Agent 生命周期、续接、工具和事件。Eval 仅负责实验语义和结果。

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

入口 最适合场景 当前能力
Desktop 日常交互、文件和 Artifact 工作流、模型及权限设置 基于 Electron + React,提供流式 Session、工具时间线、分支、搜索和恢复功能
TUI / CLI 在当前项目目录中使用 Maka,或运行单个非交互式 Turn maka、maka run;与 Desktop 共享工作空间和模型连接
Eval 跨 Maka 及外部主体执行可复现的基准实验 maka eval run <spec> --out <directory>
  • 多个模型连接、流式输出、思考过程、用量统计和 Provider 错误归一化;

  • 包括 Read、Write、Edit、Bash、Glob 和 Grep 在内的本地工具;

  • 工具 Schema 验证、动态可用性、权限策略、看门狗机制、中止和错误分类;

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

  • 从一个 Turn 创建、归档、搜索、重命名、重试、重新生成和分支 Session;

  • Artifact 列表与预览、工作空间说明、模型设置和权限设置;

  • 本地记忆、网页搜索和机器人入口;

  • 集成可独立配置,且并非所有实验性入口都默认可用。

  • 声明式多分支实验,会展开为任务 × 重复次数 × 主体单元;

  • 不可变的逐单元尝试,支持定向基础设施替换和最早有效结果选择;

  • 一个用于评分、归一化用量、可归因成本、时长、状态、失败原因和 Artifact 的小型结果内核;

  • Maka 主体仅通过 Runtime Host 执行;外部竞争产品使用通用外部主体适配器。

下载 macOS Desktop 版

已签名并完成公证的 Desktop 应用可从 GitHub Releases 获取,仅支持 Apple Silicon Mac(arm64)。

  1. 下载 Maka-<version>-mac-arm64.dmg;
  2. 打开 DMG,并将 Maka 拖入 Applications;
  3. 通过 brew install ripgrep 安装 ripgrep,以启用 Runtime 的 Grep 工具;
  4. 启动 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(锁文件和脚本使用 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 的 Desktop 开发环境。若要在启动 Electron 前构建所有工作空间,请使用:

如果依赖通过 ELECTRON_SKIP_BINARY_DOWNLOAD=1 安装,请在启动前安装 Electron 平台二进制文件:

node node_modules/electron/install.js

Maka 不会捆绑共享模型账户。首次启动时:

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

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

有关公开 npm 包,请参阅 CLI 安装和使用指南。以下命令会从源代码检出版本运行开发 CLI。

请先构建工作空间:

然后启动 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 配置文件。已发布的 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 主进程 / preload / React 渲染器

packages/core/      Session、Event、Permission 和 Connection 的纯契约
packages/storage/   SQLite 运行状态、配置和载荷存储
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 文件会保留在磁盘上,但不会被导入;
  • Session、消息、执行台账、工作流、用量、Automations 和 Daily Review 存储在 runtime.sqlite 中;
  • Runtime Policy 凭据,包括 Connection API/OAuth 材料、请求头、网页搜索密钥和代理密码,存储在本地明文 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、Session 元数据和消息历史、Agent Graph 控制、核心执行状态、工作流状态、用量和定价、Artifact 元数据、Automations、Daily Review 以及 Runtime 续接记录。Artifact 载荷字节仍以普通文件形式保存在 artifacts/ 下;连接、凭据、设置、MCP 配置、技能和设备身份则保留在配置文件中。

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

完整的运行备份使用数据库所有者的在线 SQLite 备份 API,并在 Artifact 写入器锁定期间复制规范 Artifact 载荷。其清单通过文件大小和 SHA-256 绑定每个文件。验证会检查独立 SQLite 快照的完整性、外键、Schema 注册表及必需表,解码规范 Session 消息和 Artifact 记录,并在恢复前根据 SQLite 元数据验证 Artifact 载荷大小。备份和恢复采用仅所有者可访问的文件模式、文件及目录同步、暂存和原子发布。

Runtime 续接仍为选择启用:

  • MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 会启用 Desktop 中断 Turn 的 安全续接 操作、CLI/TUI 的 /resume 以及 Desktop 启动时自动续接。这些路径可能调用已配置的模型 Provider 并消耗 token。仅当明确希望启用该行为时才设置此标志。

Phase 2 提供了持久化写入侧边界和故障关闭式安全边界续接。用于处理不确定工具副作用的 Phase 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

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。第三方组件仍受各自许可证和声明约束。

English / 原文

CI License docs

Maka — Your work. Your agent.

A local-first Agent workspace built for real work.

Maka does more than answer questions. With controlled permissions, it can inspect projects, execute tools, produce artifacts, and preserve model messages and tool calls as recoverable execution facts. Desktop, the terminal TUI, the non-interactive CLI, and Maka evaluation subjects all execute through Runtime Host.

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.

  • Local-first instead of hosted-first : sessions, settings, and run records stay on your machine by default. You choose the model connection: cloud API, local model, or compatible gateway.
  • Log is the Runtime : model messages, Tool Calls, Tool Results, and termination facts enter Runtime Event Log. Sessions, UI, model context, and recovery are projections over that log.
  • Context is not history : Tool Result pruning and LLM Compaction change what the next inference sees without treating recorded evidence as disposable context.
  • One execution authority : Runtime Host owns Session, Turn, agent lifecycle, continuation, tools, and events. Eval owns only experiment semantics and results.

Read Maka Backend Architecture for the complete design.

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
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
Eval Reproducible benchmark experiments across Maka and external subjects maka eval run <spec> --out <directory>
  • Multiple model connections, streaming output, thinking, usage accounting, and provider-error normalization;

  • Local tools including Read, Write, Edit, Bash, Glob, and Grep;

  • Tool schema validation, dynamic availability, permission policy, watchdogs, abort, and error classification;

  • Runtime Event Log, AgentRun ledger, startup recovery, Turn Evidence, active Tool Result pruning, and history compaction.

  • Create, archive, search, rename, retry, regenerate, and branch sessions from a Turn;

  • Artifact lists and previews, workspace instructions, model settings, and permission settings;

  • Local memory, web search, and bot entry points;

  • Integrations are configured independently, and not every experimental entry is available by default.

  • 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 competitors use generic external subject adapters.

Download Desktop for macOS

The signed and notarized Desktop app is available from GitHub Releases for Apple Silicon Macs only (arm64).

  1. Download Maka-<version>-mac-arm64.dmg;
  2. Open the DMG and drag Maka to Applications;
  3. Install ripgrep with brew install ripgrep to enable Runtime's Grep tool;
  4. Launch Maka and configure your own model connection under Settings → Models.

Computer Use is not included in this first public build. Intel Macs, Windows, and Linux packages are not supported yet.

Windows is still an unsigned preview, not a supported release tier. When a release includes Windows assets, follow the Windows preview installation and verification guide before running Maka-<version>-win-x64.exe. SmartScreen will identify the installer as coming from an unknown publisher; do not bypass that warning unless the downloaded SHA-256 matches the checksum published with the same release.

  • Node.js 22.19 or newer (CI uses Node.js 24);

  • npm (the lockfile and scripts use npm; the current packageManager is npm 11);

  • Git;

  • ripgrep, used by Runtime's Grep tool.

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

npm run dev starts the Desktop development environment with HMR. To build every workspace before starting Electron, use:

If dependencies were installed with ELECTRON_SKIP_BINARY_DOWNLOAD=1, install the Electron platform binary before starting:

node node_modules/electron/install.js

Maka does not bundle a shared model account. On first launch:

  1. Open Settings → Models;
  2. Add an API, local-model, or supported account connection;
  3. Test it and choose a default model;
  4. Return to the workspace and start a task.

The app distinguishes configured, send-ready, and experimental connection states. An account flow that is not wired into Runtime is not presented as a usable model.

For the public npm package, see the CLI installation and usage guide. The commands below run the development CLI from a source checkout.

Build the workspaces first:

Then start the TUI or run one 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

The TUI also accepts /graph on, /graph off, and /graph <task>. Non-interactive --graph runs wait for the durable Graph to finish before printing the final supervisor output. Graph implementation operators use isolated Git worktrees, so the source project must be a clean Git worktree.

The repository CLI uses the same Maka Dev profile as a development Desktop build. The released maka binary continues to use the Maka profile; the two profiles are not copied or synchronized automatically. Evaluation specs and adapters live in packages/eval.

The backend spine is:

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

Start with ARCHITECTURE.md. It provides the system map, code boundaries, problem-oriented reading paths, and six bilingual deep dives.

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

Local data and security boundary

Maka stores workspace data under Electron userData by default:

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

Current boundaries that matter:

  • The current connection catalog is connection-catalog.json. Existing llm-connections.json files stay on disk and are not imported;
  • Sessions, messages, execution ledgers, workflows, usage, Automations, and Daily Review live in runtime.sqlite;
  • Runtime Policy credentials, including Connection API/OAuth material, request headers, web-search keys, and proxy passwords, live in local plaintext credential-vault.json, behind the OS account boundary, with POSIX directory mode 0700 and file mode 0600 enforced;
  • Runtime Host client profile access credentials are separate and live under <Electron userData>/runtime-host-client/credentials.json. Pre-existing Electron safeStorage credential/token files are not imported; affected users must re-authenticate;
  • Renderer does not receive plaintext credentials. File writes, Shell, and dangerous tool calls pass through the permission engine;
  • Eval does not construct Runtime or read Runtime storage. Maka subjects connect to an existing Runtime Host.

Read SECURITY.md for security reporting and policy, and docs/README.md for current privacy and sandbox contracts.

Runtime storage and recovery

runtime.sqlite is the sole operational authority. It owns RuntimeEvents, session metadata and message history, Agent Graph control, core execution state, workflow state, usage and pricing, Artifact metadata, Automations, Daily Review, and Runtime continuation records. Artifact payload bytes remain regular files under artifacts/; connections, credentials, settings, MCP configuration, skills, and device identity remain configuration files.

This storage generation does not import earlier File/JSONL authorities. On upgrade, legacy session titles may still be discoverable through current metadata, but conversation history that exists only in legacy transcript files is not copied into session_messages and opens as an empty thread. Likewise, pre-version or safeStorage-encrypted credential/token files are not migrated; users with only those copies must re-authenticate. This data-loss boundary is intentional for this release and must be considered before upgrading an existing workspace.

Full operational backup uses the database owner's online SQLite backup API and copies canonical Artifact payloads under the Artifact writer lock. Its manifest binds every file by size and SHA-256. Validation checks the standalone SQLite snapshot's integrity, foreign keys, schema registry and required tables, decodes canonical session-message and Artifact records, and verifies Artifact payload sizes against SQLite metadata before restore. Backup and restore use owner-only file modes, file and directory synchronization, staging, and atomic publication.

Runtime continuation remains opt-in:

  • MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 enables the Desktop interrupted-turn Safe resume action, CLI/TUI /resume, and Desktop startup auto-resume. These paths may call the configured model provider and consume tokens. Enable the flag only when that behavior is explicitly desired.

Phase 2 provides the durable write-side boundary and fail-closed safe-boundary continuation. Phase 3 reconciliation for indeterminate tool side effects is not implemented yet; ambiguous tool outcomes remain parked rather than retried.

Development and verification

Before sending a change, read CONTRIBUTING.md.

Common repository-level commands:

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

Run one workspace in isolation:

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

Use the following commands to update packages/core/src/model-metadata.generated.ts from models.dev and run the focused tests. Keep access-path-specific overrides in model-metadata.ts; do not edit the generated file by hand.

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

Desktop real-window and visual verification:

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

Before submitting code, run typecheck, build, and focused tests proportionate to the change, followed by git diff --check.

Maka is licensed under the Apache License 2.0. See NOTICE for attribution information. Third-party components remain subject to their respective licenses and notices.