apache/maka

来源：https://github.com/apache/maka

Maka CI

许可证 文档

Maka —— 你的工作，你的代理。 一个为真实工作而构建的本地优先代理工作区。

Maka 不仅仅回答问题。凭借受控的权限，它可以检查项目、执行工具、生成制品，并将模型消息和工具调用作为可恢复的执行事实保存下来。桌面应用、终端 TUI、非交互式 CLI 以及 Maka 评估主体均通过运行时宿主执行。

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

为什么选择 Maka

• 本地优先而非托管优先：会话、设置和运行记录默认保留在您的机器上。您选择模型连接方式：云端 API、本地模型或兼容网关。
• 日志即运行时：模型消息、工具调用、工具结果和终止事实进入运行时事件日志。会话、UI、模型上下文和恢复是对该日志的投影。
• 上下文非历史：工具结果裁剪和 LLM 压缩改变了下次推理所见内容，但不会将记录的证据视为一次性上下文。
• 单一执行权威：运行时宿主拥有会话、轮次、代理生命周期、延续、工具和事件。评估仅拥有实验语义和结果。

阅读《Maka 后端架构》了解完整设计。

入口界面

当前能力

代理运行时

• 多种模型连接、流式输出、思考、用量统计和提供方错误规范化；
• 本地工具包括 Read、Write、Edit、Bash、Glob 和 Grep；
• 工具模式验证、动态可用性、权限策略、看门狗、中止和错误分类；
• 运行时事件日志、AgentRun 分类账、启动恢复、轮次证据、主动工具结果裁剪和历史压缩。

桌面工作区

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

评估

• 声明式多臂实验扩展为任务 × 重复 × 主体单元格；
• 不可变的单元格尝试，支持有针对性的基础设施替换和最早有效选择；
• 一个小型结果内核，包含分数、归一化用量、可归属成本、时长、状态、失败原因和制品；
• Maka 主体仅通过运行时宿主执行；外部竞争者使用通用的外部主体适配器。

快速开始

下载适用于 macOS 的桌面应用

经过签名和公证的桌面应用可从 GitHub Releases（https://github.com/apache/maka/releases/latest）获取，仅支持 Apple Silicon Mac（arm64）。

1. 下载 Maka--mac-arm64.dmg；
2. 打开 DMG 并将 Maka 拖到应用程序文件夹；
3. 使用 brew install ripgrep 安装 ripgrep 以启用运行时的 Grep 工具；
4. 启动 Maka 并在 设置 → 模型 下配置您自己的模型连接。

计算机使用功能未包含在此首次公开构建中。暂不支持 Intel Mac、Windows 和 Linux 包。

Windows x64 预览版

Windows 仍然是未签名的预览版，不是受支持的发布层级。当发布包含 Windows 资源时，请在运行 Maka--win-x64.exe 之前遵循 Windows 预览版安装和验证指南。SmartScreen 将识别安装程序来自未知发布者；除非下载的 SHA-256 与同一发布中公布的校验和匹配，否则请勿绕过该警告。

要求

• Node.js 22.19 或更新版本（CI 使用 Node.js 24）；
• npm（锁文件和脚本使用 npm；当前 packageManager 是 npm 11）；
• Git；
• ripgrep，由运行时的 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 不附带共享的模型账户。首次启动时：

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

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

终端入口点

有关公共 npm 包，请参阅 CLI 安装和使用指南。以下命令从源代码检出运行开发 CLI。 首先构建工作区：

npm run build

然后启动 TUI 或运行一次轮次：

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 <主题>。非交互式 --graph 运行会等待持久化图完成，然后打印最终监督者输出。

图实现操作符使用隔离的 Git 工作树，因此源项目必须是一个干净的 Git 工作树。仓库 CLI 使用与开发桌面构建相同的 Maka Dev 配置文件。已发布的 maka 二进制文件继续使用 Maka 配置文件；这两个配置文件不会自动复制或同步。

评估规范和适配器位于 packages/eval。

架构

后端主干是：

桌面 / TUI / CLI → 运行时宿主 → 会话管理器 → AgentRun
        ↓
模型 + 工具运行时 → 运行时事件日志
        ↓
上下文 / 会话 / UI 投影

实验 → 单元格 → 尝试 → 结果
        ↓
运行时宿主执行 Maka 主体

从 ARCHITECTURE.md 开始。它提供了系统地图、代码边界、面向问题的阅读路径和六个双语深度剖析。

仓库布局

apps/desktop/
  Electron 主进程 / 预加载脚本 / React 渲染器
packages/core/
  会话、事件、权限和连接的纯契约
packages/storage/
  SQLite 操作状态、配置和有效载荷存储
packages/runtime/
  AgentRun、模型适配器、工具、上下文和恢复
packages/eval/
  实验单元格、尝试、结果和执行器/主体适配器
packages/cli/
  TUI 和非交互式 CLI
packages/ui/
  共享对话、Markdown、制品和 UI 基元
docs/
  架构、产品、安全、隐私和测试契约
scripts/
  构建卫生、视觉检查、冒烟测试和发布辅助工具

本地数据和安全边界

Maka 默认将工作区数据存储在 Electron userData 下：

/workspaces/default/
  runtime.sqlite
  connection-catalog.json
  credential-vault.json
  settings.json
  artifacts/

当前重要的边界：

• 当前的连接目录是 connection-catalog.json。现有的 llm-connections.json 文件保留在磁盘上且不会被导入；
• 会话、消息、执行分类账、工作流、用量、自动化和每日回顾存在于 runtime.sqlite 中；
• 运行时策略凭证，包括连接 API/OAuth 材料、请求头、网络搜索密钥和代理密码，存在于本地明文 credential-vault.json 中，位于操作系统账户边界之后，并强制执行 POSIX 目录模式 0700 和文件模式 0600；
• 运行时宿主客户端配置文件访问凭证是独立的，位于 /runtime-host-client/credentials.json 下。 预先存在的 Electron safeStorage 凭证/令牌文件不会被导入；受影响的用户必须重新认证。
• 渲染器不会接收明文凭证。文件写入、Shell 和危险工具调用通过权限引擎传递。
• 评估不构造运行时或读取运行时存储。Maka 主体连接到现有的运行时宿主。

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

运行时存储和恢复

runtime.sqlite 是唯一的操作权威。它拥有运行时事件、会话元数据和消息历史、代理图控制、核心执行状态、工作流状态、用量和定价、制品元数据、自动化、每日回顾和运行时延续记录。制品有效载荷字节仍然是 artifacts/ 下的常规文件；连接、凭证、设置、MCP 配置、技能和设备身份仍然是配置文件。

此存储版本不导入先前的 File/JSONL 权威。在升级时，遗留会话标题可能仍可通过当前元数据发现，但仅存在于遗留转录文件中的对话历史不会被复制到 session_messages 中，并以空线程打开。同样，预先版本或 safeStorage 加密的凭证/令牌文件不会被迁移；仅拥有这些副本的用户必须重新认证。此数据丢失边界在此版本中是有意的，在升级现有工作区之前必须加以考虑。

完整的操作备份使用数据库所有者的在线 SQLite 备份 API，并在制品写入器锁下复制规范制品有效载荷。其清单通过大小和 SHA-256 绑定每个文件。验证检查独立 SQLite 快照的完整性、外键、模式注册表和所需表，解码规范会话消息和制品记录，并在恢复前根据 SQLite 元数据验证制品有效载荷大小。

备份和恢复使用仅限所有者的文件模式、文件和目录同步、暂存和原子发布。运行时延续仍然是可选的：

• MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 启用桌面中断轮次安全恢复操作、CLI/TUI /resume 和桌面启动自动恢复。这些路径可能会调用配置的模型提供方并消耗令牌。仅在明确需要该行为时启用该标志。

第二阶段提供持久化写入侧边界和失败关闭的安全边界延续。第三阶段对不确定工具副作用的协调尚未实现；模糊的工具结果仍保持挂起状态而非重试。

开发和验证

在提交更改之前，请阅读 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。第三方组件仍受其各自许可证和通知的约束。