Maka 编辑器

项目概述

Apache Maka（孵化中）是一个本地优先的智能体（Agent）工作台。它能检视本地工程、在沙箱边界内执行工具，并把模型消息与工具调用以"可恢复的执行事实"形式记录在用户本机上。模型来源由用户自选，可以是云端 API、本地模型或兼容的网关。

设计动机

• 数据归属用户：会话、设置与运行记录默认全部存于本地，模型由用户自备；
• 记录即真相：模型消息、工具调用、工具结果与回合结束方式均被持久化，界面与下一次模型调用都只是该记录的视图；
• 上下文裁剪 ≠ 历史删除：可在不丢弃已存证据的前提下，将旧的工具输出从下一轮提示中省略；
• 统一的运行时入口：桌面端、终端与评测都通过同一个 Runtime Host 执行，评测仅负责实验编排与评分。

接入方式

入口	适用场景	当前能力
Desktop	日常交互、文件与产物工作流、模型与权限设置	基于 Electron + React，支持流式会话、工具时间线、分支、搜索与恢复
TUI / CLI	在当前项目目录使用 Maka，或执行单次非交互回合	maka、maka run；与桌面端共享工作区与模型连接
Eval	可复现的基准评测	maka eval run <spec> --out <directory>

核心能力

智能体运行时

• 多模型连接、流式输出、推理过程与用量统计，错误提示更清晰；
• 内置工具：Read、Write、Edit、Bash、Glob、Grep；Computer Use 与目录化技能为可选；
• 越界工具需用户审批，运行可中止，失败被分类记录；
• 提供持久化的执行记录、崩溃恢复与可选的回合续跑。

桌面工作区

• 支持会话的创建、归档、搜索、重命名、重试、重新生成与分支；
• 提供产物列表与预览、工作区指令、模型设置、沙箱设置；
• 已配置时支持本地记忆与网页搜索。

评测模块

• 声明式多臂实验，可展开为 任务 × 重复 × 主体 的单元格；
• 单元格级不可变 attempt，支持定向基础设施替换与最早有效选择；
• 结果内核覆盖分数、归一化用量、可归属成本、耗时、状态、失败原因与产物。

快速开始

环境要求：Node.js ≥ 22.19（CI 使用 24）、npm 11、Git、ripgrep。当前桌面构建仅面向 Apple Silicon Mac。

git clone https://github.com/apache/maka.git
cd maka
npm ci
npm run dev    # 启动 Desktop 开发环境，含 HMR

首次启动需进入 Settings → Models 添加模型连接并选择默认模型。

非交互回合与评测示例：

npm run build
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"
maka eval run <spec> --out <directory>

TUI 支持 /graph on、/graph off、/graph <task>。--graph 模式需在干净的 Git worktree 中运行。

架构骨架

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

Experiment → Cells → Attempts → Results

仓库目录：

apps/desktop/      Electron 主进程 / preload / React 渲染层
packages/core/     Session、Event、Permission、Connection 纯契约
packages/storage/  SQLite 运营态、配置与载荷存储
packages/runtime/  AgentRun、模型适配器、工具、上下文与恢复
packages/eval/     实验单元格、attempt、结果与执行器/主体适配器
packages/cli/      TUI 与非交互 CLI
packages/ui/       会话、Markdown、产物与 UI 基础组件
docs/              架构、产品、安全、隐私与测试契约

本地数据与恢复

工作区数据默认位于 Electron userData 下的 workspaces/default/，包括 runtime.sqlite、connection-catalog.json、credential-vault.json、settings.json 与 artifacts/。

• 凭据以本地明文文件保存，仅当前操作系统账户可读，渲染进程无法访问；
• 写文件或执行 Shell 的工具必须通过沙箱边界审批；
• 升级后旧版 JSONL 会话与旧凭据文件不会被导入，对应线程会显示为空，凭据需重新录入；
• 回合续跑默认关闭，可通过设置 MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 启用 Desktop Safe resume、CLI /resume 与启动自动续跑——这些调用会消耗模型 token。

开发与校验

常用命令：

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

模型元数据刷新：npm run refresh:model-metadata 会拉取最新目录并重新生成 TypeScript 文件；当上游字段被移除时刷新会失败，需用 --accept-upstream-removals 显式确认；sync:model-metadata 仅做离线生成。

桌面端真实窗口与视觉校验：

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

许可

Apache Maka 基于 Apache License 2.0 发布，第三方组件仍遵循各自许可。Apache、Maka 与羽毛标识为 Apache 软件基金会的注册商标或商标。