MkThingsHQ/mkagent

MkThingsHQ/mkagent has 207 GitHub stars and 50 forks. Star changes are not measured yet. Last checked 2026-11-14 00:55 UTC. Last push 2026-10-26.

这些数字如何统计

207 星标 50 复刻

可以做什么

Local-first workspaces — keep sessions, files, settings, and workspace history on your machine.
Flexible model connections — use ChatGPT Plus, Claude Pro/Max, provider API keys, OpenAI-compatible or Anthropic-compatible endpoints, and local Ollama models.
Desktop, WebUI, and CLI — work through the Electron app, a browser-based renderer, or an RPC command-line client backed by the same runtime.
Agent workflows — create and branch sessions, build plans, use Skills, resume work, manage follow-ups, and run multiple windows.

实测星标增长

24小时: 正在收集历史
7天: 正在收集历史
15天: 正在收集历史
1个月: 正在收集历史

各周期内的星标净变化，周期相互重叠，并非每日新增。缺失的测量保持空白。星标代表关注度，不代表软件质量。

关于

A local-first, Pi-powered AI agent workspace for Desktop, WebUI, and CLI

开发工具

README.zh.md

原文

MkAgent

面向桌面端、WebUI 和 CLI 的本地优先、由 Pi 驱动的 AI Agent 工作区。

官网 · 中文文档 · English README · 快速开始 · 社区 ·

MkAgent 是一个开源、本地优先的 AI Agent 工作区，适合希望更好掌控 AI 工作方式的用户。你可以通过桌面应用、WebUI 或 CLI 下载使用，也可以基于其开源基础构建自己的桌面 Agent 产品。它由 Pi Agent 运行时驱动，把可持久化的本地工作区、灵活的模型连接、浏览器工具和文档工具整合在一个应用中。应用状态保存在本地数据目录，凭据通过操作系统凭据管理器存储。

功能特性

本地优先工作区 — 会话、文件、设置和工作区历史都保留在你的设备上。
灵活的模型连接 — 支持 ChatGPT Plus、Claude Pro/Max、Provider API key、OpenAI 兼容或 Anthropic 兼容端点，以及本地 Ollama 模型。
桌面应用、WebUI 和 CLI — 通过 Electron 应用、基于浏览器的渲染界面，或由同一运行时支撑的 RPC 命令行客户端工作。
Agent 工作流 — 创建和分支会话、制定计划、使用 Skills、恢复工作、管理后续任务，并运行多个窗口。
内置工具 — 浏览网页、处理附件、渲染 Markdown 和代码，以及检查或转换常见文档格式。
明确的控制权 — 选择 Explore、Ask 或 Execute 权限模式，配置网络代理，并在英文与简体中文之间切换。

技术栈

Bun — 工作区运行时、包管理器、脚本和测试工具。
Electron — 跨平台桌面应用外壳。
React 和 TypeScript — 共享用户界面与类型化应用代码。
Vite 和 Tailwind CSS — 渲染界面构建工具和样式方案。
Pi — Agent 运行时、模型 Provider、会话和工具执行。

使用界面

界面	适用场景	命令
Desktop	完整的本地体验和 Browser 面板	`bun run electron:dev`
WebUI	在浏览器中访问 headless server	`bun run server:prod`
CLI	脚本化、远程控制和终端工作流	`bun run apps/cli/src/index.ts --help`

快速开始

前置要求

Bun 1.3.14 或更高版本
Node.js 18 或更高版本
Git
Python 3.12 和 uv，用于完整的文档工具测试套件

运行桌面应用

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

MkAgent 会在 ~/.mkagent/workspaces/default 创建默认工作区。开发或测试时，可通过 CONFIG_DIR=/path/to/directory 隔离配置根目录。

常用命令

命令	说明
`bun run electron:dev`	启动 Electron 开发环境
`bun run electron:start`	构建并单次启动 Electron
`bun run server:prod`	构建并启动带 WebUI 的 headless server
`bun run cli:build`	构建 CLI bundle
`bun run test`	运行单元测试和隔离测试
`bun run validate:ci`	运行完整的类型、测试、文档工具和本地化检查

更多命令和环境变量请参阅开发指南。

架构

MkAgent 是一个 Bun workspace，三个使用界面共用同一套运行时和渲染层：

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

有关运行时边界、进程职责和数据流，请阅读架构指南。

文档

完整文档提供英文版和简体中文版。

范畴	指南
从这里开始	开发、架构、测试
模型	连接、Ollama
工作方式	工作区、会话、Skills
工具	Browser、附件、文档工具
运行时	CLI、权限、网络代理
项目	功能、发布、上游同步

参与贡献

欢迎贡献。请先 Fork 仓库，创建聚焦的分支；行为变更请同时提交测试和文档，并在创建 pull request 前运行相关检查。完整的本地检查命令为：

bun run validate:ci
git diff --check

请通过 GitHub Issues 提交 bug 和功能建议。

链接

官网 — 了解更多 MkAgent 信息。
英文文档 — 查看安装、架构、模型、工具和开发指南。
中文文档 — 阅读简体中文指南。
Discord — 加入社区并获取帮助。
GitHub Issues — 报告 bug 或提出功能需求。

项目沿革

MkAgent 起步于 Craft Agents OSS，当前选择性同步基线为 v0.12.1（d7592c481216），并保持独立的 Git 历史与产品边界。MkAgent 与上游项目不存在关联，也未获其认可。归属说明请参阅 NOTICE，当前差异请参阅对比指南。

作者

OpenFox 是一位独立开发者，专注于构建产品和开发者工具。其产品包括：

MkAgent — 面向 Desktop、WebUI 和 CLI 的本地优先、由 Pi 驱动的 AI Agent 工作区。
TanStarter — 基于 TanStack 快速交付，借助 Cloudflare 降低成本。
MkSaaS — 在一个周末做出你的 AI SaaS 产品。
MkImage — 让任何图像成为可能。
Mkdirs — 30 分钟上线 AI 驱动的目录站。
MkDollar — 帮助你赚到第一桶金的一体化平台。

许可证

本项目采用 Apache License 2.0 许可。你可以在遵守许可条款和 NOTICE 中归属声明的前提下使用、修改和分发代码，包括用于商业用途。