Files
maka/README.zh-CN.md
T
agent-radar 7be535059e
Dependency audit / audit (push) Canceled after 0s
CI / plan (push) Canceled after 0s
Gitoxide helper admission / macos-latest (push) Canceled after 0s
Gitoxide helper admission / ubuntu-latest (push) Canceled after 0s
Gitoxide helper admission / windows-latest (push) Canceled after 0s
Runtime Host peer admission / quality (push) Canceled after 0s
Windows recovery / windows_recovery (push) Canceled after 0s
CI / heavy (push) Canceled after 0s
CI / test (push) Canceled after 0s
源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)
2026-09-01 19:05:14 +08:00

288 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<h1 align="center">
<img src="apps/desktop/assets/app-icons/sky.png" alt="Maka" width="72" valign="middle" /> Apache Maka (Incubating)
</h1>
<p align="center"><sub>正在 Apache 软件基金会孵化</sub></p>
<p align="center">
<a href="https://github.com/apache/maka/stargazers"><img src="https://img.shields.io/github/stars/apache/maka?style=flat&label=%E2%98%85&color=4C8DFF" alt="GitHub stars" /></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-4C8DFF?style=flat" alt="License: Apache 2.0" /></a>
<img src="https://img.shields.io/badge/macOS-arm64-4C8DFF?style=flat&logo=apple&logoColor=white" alt="macOS Apple Silicon" />
<img src="https://img.shields.io/badge/Windows-preview-9BB8F0?style=flat&logo=windows&logoColor=white" alt="Windows 未签名预览" />
<img src="https://img.shields.io/badge/Linux-soon-D0D4DA?style=flat&logo=linux&logoColor=6B7280" alt="Linux 尚未支持" />
<a href="https://deepwiki.com/apache/maka"><img src="https://img.shields.io/badge/DeepWiki-%E7%AC%AC%E4%B8%89%E6%96%B9%20AI%20%E6%96%87%E6%A1%A3-9BB8F0?style=flat" alt="DeepWiki:第三方 AI 生成文档" /></a>
<a href="./README.md"><img src="https://img.shields.io/badge/English-4C8DFF?style=flat" alt="English" /></a>
</p>
<p align="center">
<strong>一个为真实工作而生的本地优先 Agent 工作台。</strong><br/>
Maka 在沙箱边界下阅读项目、执行工具,并把模型消息和工具调用保存为可恢复的运行事实——数据在本机,执行走同一个 Runtime Host。
</p>
<p align="center">
<a href="https://github.com/apache/maka/releases"><img src="https://img.shields.io/badge/%E4%B8%8B%E8%BD%BD%20Desktop%20Nightly-1F6FEB?style=for-the-badge" alt="下载 Desktop Nightly" /></a><br/>
每天从 <code>main</code> 构建,面向开发者和测试者。不是 ASF release,也不适合生产使用。
</p>
![Maka——你的工作,你的 Agent。](./.github/assets/maka-hero.zh-CN.png)
> [!NOTE]
> Apache Maka (Incubating) 是一个正在 Apache 软件基金会(ASF)孵化的项目,由 Apache Incubator PMC 提供 sponsor。所有新接受的项目都必须经过孵化,直到进一步审查表明其基础设施、沟通方式和决策流程已经稳定到与其他成功的 ASF 项目一致的程度。孵化状态并不必然反映代码的完成度或稳定性,但它确实表明该项目尚未得到 ASF 的完全认可。项目当前已知的问题记录在 [DISCLAIMER-WIP](./DISCLAIMER-WIP)(以英文原文为准)。
> [!IMPORTANT]
> Maka 仍在活跃开发中。数据格式、CLI 和实验能力仍可能变化。
## 为什么是 Maka
- **数据在你的机器上。** 会话、设置和运行记录默认保存在本机。模型由你接:云 API、本地模型或兼容网关。
- **做过的事会留下来。** 模型消息、工具调用、工具结果、这一轮怎么结束,都会记下来。界面和下一次模型请求只是这份记录的视图,不是唯一副本。
- **缩短上下文不等于删掉历史。** Maka 可以不把旧的工具输出送进下一轮提示,但不会扔掉已保存的证据。
- **Agent 只在一处跑。** 桌面、终端和 Maka 评测都走 Runtime Host。Eval 只负责实验和分数。
完整设计见 [Maka Backend Architecture](./ARCHITECTURE.zh-CN.md)。
## 运行形态
| 入口 | 适合什么 | 当前能力 |
|---|---|---|
| **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 接入](./docs/architecture/bot-onboarding-runtime.zh-CN.md)。
### 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`](./.github/ASF_SOURCE_RELEASE.md)。
[Desktop Nightly](https://github.com/apache/maka/releases) 面向开发者和测试者,每天从 `main` 构建。请选择最新的 **Maka Desktop Nightly** prerelease;安装后,应用会在 Nightly 渠道自动更新。它不是 ASF release,不适合生产使用。Desktop 目前面向 Apple Silicon Mac(`arm64`)。暂不支持 Intel Mac 和 Linux。[Windows](docs/windows-support.md) 是未签名预览,不是正式支持的发布层级。
### 环境要求
- Node.js 22.19 或更高(CI 使用 Node.js 24);
- npm(仓库 lockfile 和 scripts 以 npm 为准,`packageManager` 当前为 npm 11);
- Git;
- `ripgrep`,供 Runtime 的 `Grep` 工具使用。
### 启动 Desktop
```sh
git clone https://github.com/apache/maka.git
cd maka
npm ci
npm run dev
```
`npm run dev` 启动带 HMR 的 Desktop 开发环境。需要先完整构建再启动 Electron 时使用:
```sh
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:
```sh
npm run dev:peer # HMR
npm run dev:full:peer # 完整构建
```
如果安装时设置过 `ELECTRON_SKIP_BINARY_DOWNLOAD=1`,启动前需要补装 Electron 平台二进制:
```sh
node node_modules/electron/install.js
```
### 第一次运行
Maka 不内置共享模型账号。第一次打开时:
1. 进入 `设置 → 模型`;
2. 添加一个 API、本地模型或已经接通的账号连接;
3. 测试连接并选择默认模型;
4. 返回工作台开始任务。
应用会根据真实连接状态区分“已配置”“可发送”和“实验入口”,不会把没有接入 Runtime 的账号展示成可用模型。
## 使用终端入口
公共 npm 包的安装和使用方式请查看 [CLI 中文指南](./packages/cli/README.zh-CN.md)。下面的命令
用于从源码 checkout 运行开发版 CLI。
先构建 workspace:
```sh
npm run build
```
然后可以启动 TUI 或执行单次 Turn:
```sh
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`](./packages/eval)。
## 架构
Maka 后端可以用一条主线概括:
```text
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](./ARCHITECTURE.zh-CN.md) 开始阅读。它提供总体架构图、代码边界、按问题组织的阅读路径,以及六篇中英双语深度文章。
## 仓库结构
```text
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
docs/ 架构、产品、安全、隐私和测试契约
scripts/ Build hygiene、视觉检查、smoke 和 release helpers
```
## 本地数据与恢复
Workspace 数据默认放在 Electron `userData` 下:
```text
<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](./SECURITY.md)、[隐私](./docs/workspace-privacy-context.md)、[续跑](./docs/architecture/runtime-resume-architecture.zh-CN.md)。
## 开发与验证
提交改动前请先阅读 [CONTRIBUTING.zh-CN.md](./CONTRIBUTING.zh-CN.md)。
常用仓库级命令:
```sh
npm run build
npm run typecheck
npm test
npm run check:release
```
针对单个 workspace:
```sh
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`,不要手动修改生成文件。
```sh
npm run refresh:model-metadata
npm --workspace @maka/core run test:dist
```
Desktop 的真实窗口与视觉验证:
```sh
npm --workspace @maka/desktop run e2e
npm --workspace @maka/desktop run smoke:real-window
```
提交代码前至少运行与改动范围相称的 typecheck、build 和 focused tests,并执行 `git diff --check`。
## 文档入口
- [文档索引与权威来源说明](./docs/README.md)
- [后端架构总览](./ARCHITECTURE.zh-CN.md)
- [产品设计](./DESIGN.md)
- [贡献指南](./CONTRIBUTING.zh-CN.md)
- [安全政策](./SECURITY.md)
## 开源协议
Maka 使用 [Apache License 2.0](./LICENSE) 开源,归属信息见
[NOTICE](./NOTICE)。第三方组件仍分别适用其自身的许可证与声明。
Apache Maka、Maka、Apache、Apache 羽毛标志和 Apache Maka 项目标志是 Apache 软件基金会的注册商标或商标。