close
Skip to content

README.zh-CN.md

Latest commit

 

History

History
273 lines (196 loc) · 12.5 KB

README.zh-CN.md

File metadata and controls

273 lines (196 loc) · 12.5 KB
Raw

Maka Apache Maka (Incubating)

正在 Apache 软件基金会孵化

GitHub stars GitHub downloads License: Apache 2.0 macOS Apple Silicon Windows 未签名预览 Linux 尚未支持

English

一个为真实工作而生的本地优先 Agent 工作台。
Maka 在沙箱边界下阅读项目、执行工具，并把模型消息和工具调用保存为可恢复的运行事实——数据在本机，执行走同一个 Runtime Host。

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

Note

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

Important

Maka 仍在活跃开发中。macOS Apple Silicon 桌面版是首个早期公开版本，数据格式、CLI 和实验能力仍可能变化。

为什么是 Maka

  • 数据在你的机器上。 会话、设置和运行记录默认保存在本机。模型由你接：云 API、本地模型或兼容网关。
  • 做过的事会留下来。 模型消息、工具调用、工具结果、这一轮怎么结束，都会记下来。界面和下一次模型请求只是这份记录的视图，不是唯一副本。
  • 缩短上下文不等于删掉历史。 Maka 可以不把旧的工具输出送进下一轮提示，但不会扔掉已保存的证据。
  • Agent 只在一处跑。 桌面、终端和 Maka 评测都走 Runtime Host。Eval 只负责实验和分数。

完整设计见 Maka Backend Architecture。

运行形态

入口 适合什么 当前能力
Desktop 日常交互、文件与 Artifact 工作流、模型和权限配置 Electron + React，支持流式会话、工具时间线、分支、搜索和恢复
TUI / CLI 在当前工程目录中使用 Maka，或执行单次非交互 Turn maka、maka run，复用 Desktop 的 workspace 和模型连接
Eval Maka 与外部 subject 的可复现实验 maka eval run <spec> --out <directory>

当前能力

Agent Runtime

  • 多模型连接、流式输出、thinking、用量统计，以及更清楚的 provider 错误；
  • 内置工具：Read、Write、Edit、Bash、Glob、Grep。Computer Use 和目录里的 skill 是可选的，默认不开；
  • 越出沙箱的工具需要批准；运行可以中止；失败会被分类；
  • 有一份可恢复的执行记录，进程崩溃后可以收敛状态，中断的回合可以按需续跑。

Desktop Workspace

  • 会话创建、归档、搜索、重命名、重试、重新生成和从 Turn 分支；
  • Artifact 列表与预览、工作区说明、模型和沙箱设置；
  • 配置后可使用本地记忆和联网搜索；
  • 聊天应用（IM bot）仍是实验能力，见 IM 接入。

Evaluation

  • 声明式多臂 Experiment 展开为 task × repetition × subject cell；
  • 每个 cell 使用 immutable attempt，基础设施失败只替换该 cell，并选择最早有效 attempt；
  • 通用结果只包含 score、normalized usage、可归因 cost、duration、status/failure reason 与 artifacts；
  • Maka subject 只通过 Runtime Host 执行，外部 subject 使用 generic external subject adapter。

快速开始

Release 与下载

Apache Maka 目前还没有发布过 Apache release。当前从本仓库或包管理器分发的一切内容，都是在进入孵化器之前或孵化期间产生的，不是 Apache 软件基金会的 release，也没有经过 Incubator PMC 审查和投票。

在 Apache release 出现之后，官方 release 指的是由 ASF 发布、并经 podling PPMC 和 Incubator PMC 批准的源码 release。由该源码构建并通过其他渠道分发的包，例如包管理器中的包或 Desktop 安装程序，属于 convenience artifact，本身不是 release，并且只有在由获批源码 release 构建时才有效。候选契约、签名路径和验包步骤见 .github/ASF_SOURCE_RELEASE.md。

在获批源码 release 出现之前，本 README 不推荐任何预构建下载，请按下文从源码构建并运行 Maka。Desktop 目前面向 Apple Silicon Mac（arm64）。暂不支持 Intel Mac 和 Linux。Windows 是未签名预览，不是正式支持的发布层级。

环境要求

  • Node.js 22.19 或更高（CI 使用 Node.js 24）；
  • npm（仓库 lockfile 和 scripts 以 npm 为准，packageManager 当前为 npm 11）；
  • Git；
  • ripgrep，供 Runtime 的 Grep 工具使用。

启动 Desktop

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

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

node node_modules/electron/install.js

第一次运行

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

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

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

使用终端入口

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

先构建 workspace：

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 开始阅读。它提供总体架构图、代码边界、按问题组织的阅读路径，以及六篇中英双语深度文章。

仓库结构

apps/desktop/       Electron main / preload / React renderer

packages/core/      Session、Event、Permission、Connection 等纯 contracts
packages/storage/   SQLite 运行状态、配置与 payload stores
packages/runtime/   AgentRun、模型适配、工具、上下文和恢复
packages/eval/      Experiment cell、attempt、result 与 executor/subject adapter
packages/cli/       TUI 和非交互 CLI
packages/ui/        共享对话、Markdown、Artifact 与 UI primitives

docs/               架构、产品、安全、隐私和测试契约
scripts/            Build hygiene、视觉检查、smoke 和 release helpers

本地数据与恢复

Workspace 数据默认放在 Electron userData 下：

<Electron userData>/workspaces/default/
  runtime.sqlite
  connection-catalog.json
  credential-vault.json
  settings.json
  artifacts/
  • API key 一类的秘密是本地明文文件（credential-vault.json），只有你的系统账号能读。界面进程拿不到明文。
  • 写文件、跑 Shell 的工具必须先过沙箱边界。
  • runtime.sqlite 是当前活记录。更早的 JSONL transcript 和 Electron safeStorage 凭据不会导入；升级后会话可能是空的，那些凭据需要重新填写。
  • 中断回合的续跑默认关闭。只有设置 MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 才会打开 Desktop 安全恢复、CLI /resume 和启动时自动续跑——这些路径会打模型、消耗 token。

细节见 SECURITY.md、隐私、续跑。

开发与验证

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

常用仓库级命令：

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

针对单个 workspace：

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

用 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 test

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

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

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

文档入口

开源协议

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

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