MkAgent:本地优先的开源 AI Agent 工作区,桌面、WebUI、CLI 三端同核

想在本地跑一个自己完全掌控的 AI agent?MkAgent 值得看看。它是一个开源、本地优先、Pi 驱动的 AI agent 工作区,同一套运行时撑起桌面端、WebUI 和 CLI 三种界面:会话、文件、设置和工作区历史都留在自己的机器上,凭证走操作系统的凭证管理器。项目由独立开发者 OpenFox 维护,Apache-2.0 协议(含 NOTICE 归属条款,可商用),也可以直接拿它的开源底座 fork 出自己的桌面 agent 产品。

项目简介

MkAgent 的底层是 Pi agent runtime,负责模型接入、会话和工具执行。它把"和 agent 干活"需要的东西装进了一个应用:持久化的本地工作区、灵活的模型连接、浏览器工具和文档工具。应用状态全部放在本地数据目录下,开发测试时还能用 CONFIG_DIR 把配置根目录整个隔离出来。

项目从 Craft Agents OSS v0.12.1 的部分架构和代码起家,现在是独立的 Git 历史和产品边界,与上游项目无隶属关系,归属信息见 NOTICE。

核心特性

本地优先工作区:会话、文件、设置、工作区历史都在本机,默认工作区在 ~/.mkagent/workspaces/default
灵活的模型连接:ChatGPT Plus、Claude Pro/Max 订阅(OAuth 接入)、各家 provider API 密钥、OpenAI 兼容或 Anthropic 兼容端点、本地 Ollama 模型,都能接
三端同核:Electron 桌面应用(带浏览器面板)、浏览器版 WebUI(连无头服务器)、RPC 命令行客户端,背后是同一个运行时,换个界面接着干
完整的 agent 工作流:创建和分支会话、做计划、用 Skills、恢复工作、管理跟进事项、多窗口并行
内置工具:浏览网页、处理附件、渲染 Markdown 和代码、检查和转换常见文档格式
显式控制:Explore、Ask、Execute 三种权限模式,支持配置网络代理,界面有英文和简体中文两种

技术栈

Bun 1.3.14 及以上:workspace 运行时、包管理、脚本和测试
Electron 39:跨平台桌面外壳
React + TypeScript:共享界面和类型化的应用代码
Vite + Tailwind CSS:渲染层工具链和样式
Pi:agent 运行时、模型 provider、会话与工具执行

安装指南

准备 Bun 1.3.14+、Node.js 18+、Git;想跑完整的文档工具测试套件还需要 Python 3.12 和 uv。桌面端三步跑起来:

bash

git clone https://github.com/MkThingsHQ/mkagent.git
cd mkagent
bun install --frozen-lockfile
bun run electron:dev

三种界面各有适用场景:

界面	适合	命令
Desktop	完整本地体验和浏览器面板	`bun run electron:dev`
WebUI	浏览器访问无头服务器	`bun run server:prod`
CLI	脚本、远程控制、终端工作流	`bun run apps/cli/src/index.ts --help`

快速开始

常用命令一览:

命令	用途
`bun run electron:dev`	启动 Electron 开发环境
`bun run electron:start`	构建并启动一次 Electron
`bun run server:prod`	构建并启动带 WebUI 的无头服务器
`bun run cli:build`	构建 CLI 包
`bun run test`	跑单元和隔离测试
`bun run validate:ci`	类型、测试、文档工具、本地化全量检查

架构一览

MkAgent 是一个 Bun workspace,三个界面共享运行时和渲染层:

text

apps/
  electron/              Electron 主进程、preload、渲染器与浏览器面板
  webui/                 共享渲染器的浏览器适配层
  cli/                   RPC 命令行客户端
packages/
  core/                  稳定的 DTO、事件与错误契约
  shared/                配置、凭证、提示词、Skills、主题与 i18n
  ui/                    共享 React UI 与内容渲染器
  server-core/           RPC 传输、会话与运行时编排
  server/                无头服务器
  pi-agent-server/       Pi agent 子进程
  session-tools-core/    计划、Skills、浏览器与会话工具

运行时边界、进程归属和数据流的细节,官方的 architecture guide 有完整说明。

产品边界

官网的 features 文档把"不做什么"也写得很清楚,这对评估一个开源 agent 产品挺重要:

Pi 是唯一的 agent 运行时,不内置 Claude Agent SDK 或 Copilot 等其他引擎
Skills 是一等公民,但不含通用的 API/MCP Sources 机制
桌面集成走 OpenConnector 的窄通道,只暴露五个固定的 Pi 工具
坚持本地优先:不做 Projects、看板、消息网关、公开分享、远程工作区、自动化调度和图像生成

边界小是刻意的。想扩展的话,代码就是起点,仓库带了完整的英文和简体中文文档。

项目链接

官网:https://mkagent.app
GitHub 仓库:https://github.com/MkThingsHQ/mkagent
中文文档:https://github.com/MkThingsHQ/mkagent/blob/main/docs/zh/README.md
底层运行时 Pi:https://github.com/badlogic/pi-mono
开发者 Discord 社区:https://mksaas.link/discord