官方中文正文为项目官方提供的中文文档（原文转载），本站未作翻译、未改动文字，仅剔除图片与无关章节。

Apache Maka（孵化中）

Apache Maka（孵化中）是一个高性能的 Agent 工作台，并完整记录它做过的每一件事。

官网 · 文档 · 下载 · English

What is Maka

Agent harness 的本职就是把任务做完。衡量它的标准只有一条：完成了多少，花了多少。我们公开每一次运行：同一个模型，同一个官方验证器，逐任务的完整记录。

• 靠测量，不靠宣称。 Maka 与其他 harness 在同一个模型、同一个官方验证器下对比跑分，每份报告都附逐任务结果，见 docs/eval/。
• 日志就是运行时。 每条模型消息、工具调用、权限决定和终止都是一条只追加的 RuntimeEvent。界面、下一轮 prompt 和崩溃恢复都是这份日志的投影，从不是唯一副本。旧的工具输出可以不进下一轮 prompt，但不会从日志里消失。
• 数据在你的机器上，模型由你接。 会话、设置和运行记录保存在本机；云 API、本地模型或兼容网关都可以。
• 一个 Runtime Host。 Desktop、TUI 和 CLI、Eval 都是瘦客户端，执行只由这一个 Runtime Host 说了算；Eval 只负责实验和分数。

官网演示了日志中的一轮，并链接到公开的运行结果。系统地图见 ARCHITECTURE.zh-CN.md。

Get Maka

Apache Releases：最新的 Apache release 是 0.2.0（孵化中）。带签名的源码包才是正式 release，其他渠道分发的包属于便利构建。候选版本的准入标准、签名路径与验包步骤见下载页面与 .github/ASF_SOURCE_RELEASE.md。

开发测试：如果希望贡献代码或协助测试尚未发布的改动，请阅读贡献指南并关注开发邮件列表。开发构建不是获批的 Apache 正式版本。

从源码构建：要从源码 checkout 直接构建并运行 Desktop、TUI 或 CLI，见下方的从源码构建一节。

从源码构建

环境要求

• Node.js 22.19 或更高的 22.x 版本，或 Node.js 24 及以上（CI 使用 Node.js 24；不支持 Node.js 23）；
• npm（仓库 lockfile 和 scripts 以 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 时使用：

npm run dev:full

开发 Direct Peer 和 Peer Mesh 还需要 Rust stable 1.98 或更高版本及平台 linker （macOS 使用 Xcode Command Line Tools，Windows 使用 MSVC Build Tools）。使用 Peer 开发入口， Desktop 会在启动前构建原生 addon：

npm run dev:peer       # HMR
npm run dev:full:peer  # 完整构建

如果安装时设置过 ELECTRON_SKIP_BINARY_DOWNLOAD=1，启动前需要补装 Electron 平台二进制：

node node_modules/electron/install.js

第一次运行

Maka 不内置共享模型账号。第一次打开时：

1. 进入 设置 → 模型；
2. 添加一个 API、本地模型或已经接通的账号连接；
3. 测试连接并选择默认模型；
4. 返回工作台开始任务。

应用会根据真实连接状态区分“已配置”“可发送”和“实验入口”，不会把没有接入 Runtime 的账号展示成可用模型。

使用终端入口

公共 npm 包的安装和使用方式请查看 CLI 中文指南。下面的命令 用于从源码 checkout 运行开发版 CLI。

先构建工作区：

npm run build

然后可以启动 TUI 或执行单次 Turn：

npm run cli:dev
npm run cli:dev -- run "总结当前仓库并指出最重要的风险"
npm run cli:dev -- run --graph "并行实现两个切片，完成集成，然后独立审查"
npm run cli:dev -- --help

TUI 同时支持 /graph on、/graph off 和 /graph <任务>。非交互 --graph 会等待持久化 Graph 真正结束，再输出 supervisor 的最终结果。 Graph 的 implementation operator 使用隔离的 Git worktree，因此源项目必须是干净的 Git worktree。

仓库 CLI 使用与开发版 Desktop 构建相同的 Maka Dev profile；发布版 maka 二进制仍使用 Maka profile，二者不会自动复制或同步。评测 spec 和 adapter 位于 packages/eval。

架构

Maka 后端可以用一条主线概括：

Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun
                                             ↓
                         Model + Tool Runtime → Runtime Event Log
                                             ↓
                              Context / Session / UI projections

Experiment → Cells → Attempts → Results
                    ↓
       Runtime Host 执行 Maka subjects

从 ARCHITECTURE.zh-CN.md 开始阅读。它提供总体架构图、代码边界、按问题组织的阅读路径，以及 docs/architecture/ 下深度文章的链接。

仓库结构

apps/desktop/          Electron main / preload / React renderer

packages/core/         Session、Event、Permission、Connection 等纯 contracts
packages/storage/      SQLite 运行状态、配置与 payload stores
packages/mcp/          与提供商无关的 Model Context Protocol 客户端集成
packages/runtime/      AgentRun、模型适配、工具、上下文和恢复
packages/runtime-host/ 单一所有者的 Runtime Host 生命周期、协议和客户端启动
packages/eval/         Experiment cell、attempt、result 与 executor/subject adapter
packages/computer-use/ Computer Use 后端选择、Host 生命周期和协议适配
packages/cli/          TUI 和非交互 CLI
packages/ui/           共享对话、Markdown、Artifact 与 UI primitives
native/                Rust：Runtime Host 的 direct-peer addon 与 Windows task launcher，以及 gitoxide helper
website/               maka.apache.org 的 Astro 源码

docs/                  架构、产品、安全、隐私和测试契约
scripts/               Build hygiene、视觉检查、smoke 和 release helpers
skills/                随仓库分发的 agent skill
patches/               安装时应用到 npm 依赖的补丁
experiments/           平台实验，目前是 Windows 沙箱 smoke 脚本

本地数据与恢复

Workspace 数据默认放在 Electron userData 下：

<Electron userData>/workspaces/default/
  runtime.sqlite
  settings.json                  # 界面与工作区偏好
  connection-catalog.json        # 提供商与模型元数据
  credential-vault.json          # 本地提供商密钥
  artifacts/

• 手动编辑 settings.json 或 mcp.json 时，请保存为 UTF-8（建议不带 BOM；也支持 UTF-8 BOM）。Maka 不会猜测无 BOM 文件的其他编码，也不会自动转换 UTF-16；请先在编辑器中显式转换为 UTF-8，再使用这些文件。
• API key 一类的机密存在本地明文文件（credential-vault.json），只有你的系统账号能读。界面进程拿不到明文。
• 写文件、跑 Shell 的工具必须先过沙箱边界。
• runtime.sqlite 是当前生效的那份记录。更早的 JSONL transcript 和 Electron safeStorage 凭据不会导入；升级后会话可能是空的，那些凭据需要重新填写。
• Desktop 与 CLI/TUI /resume 默认可以显式恢复中断回合；成功续跑会请求模型并消耗 token。设置 MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=0 可关闭新的 resume planning；设置 =1 会额外开启 activation 和 WorkHub 的自动 resume。默认情况下，即使 activation 使用已有 Session，也会处理这次新的 stimulus。启动恢复只修复已经 admission 的 continuation，不会自动选择普通的 failed 或 cancelled Turn。

For details, see SECURITY.md, Privacy, Resume.

开发与验证

提交改动前请先阅读 CONTRIBUTING.zh-CN.md。

常用仓库级命令：

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

针对单个 workspace：

npm --workspace @maka/runtime run test:dist
npm --workspace @maka/eval run test:dist
npm --workspace @maka/desktop run test:dist

用 refresh:model-metadata 从 models.dev 获取当前目录、更新仓库内快照，并重新生成派生的 TypeScript 文件。已提交的模型、能力、provider override 或 pricing 字段消失时，refresh 会 fail closed；审查确认上游确实有意删除后，用 npm run refresh:model-metadata -- --accept-upstream-removals 显式确认。sync:model-metadata 刻意保持离线，只会从已提交快照重新生成这些文件。访问路径特有的 override 写在 model-metadata.ts，不要手动修改生成文件。

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

Desktop 的真实窗口与视觉验证：

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

提交代码前至少运行与改动范围相称的 typecheck、build 和 focused tests，并执行 git diff --check。

文档入口

• 官网
• 文档索引与权威来源说明
• 后端架构总览
• 产品设计
• 贡献指南
• 安全政策
• DeepWiki，第三方 AI 生成文档，不由项目维护

开源协议

Maka 使用 Apache License 2.0 开源，归属信息见 NOTICE。第三方组件仍分别适用其自身的许可证与声明。

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

[！注意]
Apache Maka (Incubating) 是一个正在 Apache 软件基金会（ASF）孵化的项目，由 Apache Incubator PMC 主办。所有新接受的项目都必须经过孵化，直到进一步审查表明其基础设施、沟通方式和决策流程已经稳定到与其他成功的 ASF 项目一致的程度。孵化状态未必反映代码的完成度或稳定性，但它确实表明该项目尚未得到 ASF 的完全认可。项目当前已知的问题记录在 DISCLAIMER-WIP（以英文原文为准）。

[！重要]
Maka 仍在活跃开发中。数据格式、CLI 和实验能力仍可能变化。