简体中文 | English
Mingyi 是一个基于 Electron 的本地 AI Agent 桌面应用:将现代化本地 AI Agent 的 AgentController、统一模型路由、多工作模式、扩展中心与插件、安全工具、MCP 及会话状态流封装成本地通用 Runtime,并通过类型完备的 IPC 协议暴露给桌面端。支持多任务与项目空间的分组管理、多厂商模型服务无缝切换、多步工具流水线执行、内置集成终端以及面向授权安全评估的渗透测试(Pentest)可视化工作流。
Warning
开发阶段说明 (Notice for Early Development Phase)
本项目当前处于高频迭代的活跃开发早期阶段(Alpha / Experimental)。系统的底层架构(AgentController/Runtime)、数据持久化机制、IPC 交互契约以及桌面端 UI 随时可能发生较大幅度的重构与 Breaking Changes。
欢迎社区开发者测试体验并提供宝贵反馈与建议!如果在生产环境或关键场景中使用,请务必注意重要数据的本地备份与版本锁定。
| 实时渗透测试执行链路与思考 | 完整工作区、黑板事实与漏洞发现 |
|
|
|
| 多安全等级实证验证与漏洞发现面板 | |
|
| |
| 主界面与步骤执行 | 任务快捷操作 |
|
|
|
| 侧栏任务与空间管理 | 内置终端面板 (⌘J) |
|
|
|
| 统一模型服务配置 | Pentest 渗透测试工作流 |
|
|
|
| 开源致谢与社区贡献 | 扩展中心与专家角色 |
|
|
|
.
├── apps/desktop # Electron 桌面应用(主进程 / preload / renderer)
├── packages/runtime # 通用本地 Agent Runtime(开源核心)
├── docs # 架构设计、ADR 与发布指南
└── patches # 依赖补丁
packages/runtime/:通用的本地 AI Agent 核心 Runtime,提供 AgentController、Session、统一模型路由、模式(Mode)、Subagent、工具执行、MCP 协议支持、技能与自动化引擎,并内建面向授权安全评估的 Pentest 域能力;Desktop 与 TUI 等应用层只通过 Runtime 的稳定公开接口调用。apps/desktop/:Electron 应用,主进程代码在src/main/,preload API 在src/preload/,浏览器 UI 在src/renderer/。
支持主流闭源大模型与开源本地推理端点,统一由 Runtime 模型路由进行安全调度:
- 公有云 API:OpenAI、Anthropic、Google Gemini、DeepSeek、SiliconFlow 等;
- 本地/私有化端点:Ollama、vLLM、LocalAI 等兼容 OpenAI 协议的自建服务;
- 统一设置:在桌面端左下角点击
设置 -> 模型服务,即可可视化增删改查 Provider API Key 与 Base URL,或通过环境变量快捷注入。
为防止自动化渗透测试对宿主机造成意外破坏或端口冲突,系统原生提供 Docker 纯执行沙箱适配层(详细指南见 container/README.md):
- 构建本地沙箱镜像: docker build -t mingyi-sandbox:latest ./container (镜像内置完整 Kali 安全工具链、离线 PoC 库及 HackTricks/PayloadsAllTheThings 知识库)
- 启动常驻沙箱容器(亦可通过
pnpm run container:run跨平台一键启动): # macOS / Linux (工作区默认映射至 \~/.atlas/sandbox_workspace) docker run -d \ --name mingyi-sandbox \ --network host \ --cap-add=NET_RAW --cap-add=NET_ADMIN \ -v \~/.atlas/sandbox_workspace:/home/kali/workspace \ mingyi-sandbox:latest # Windows (工作区默认映射至 %USERPROFILE%.atlas\sandbox_workspace) docker run -d ^ --name mingyi-sandbox ^ --network host ^ --cap-add=NET_RAW --cap-add=NET_ADMIN ^ -v "%USERPROFILE%.atlas\sandbox_workspace:/home/kali/workspace" ^ mingyi-sandbox:latest - 自动化探测与握手:
Agent 在执行前会自动调用内置的detect_sandbox_environment工具探测当前环境。只有在触发kali_*系列工具时才向沙箱下发执行指令,未启用时零资源开销; - 配置与环境变量:
MINGYI_SANDBOX_CONTAINER:指定容器名称(默认mingyi-sandbox);MINGYI_SANDBOX_IMAGE:指定镜像名称(默认mingyi-sandbox:latest);MINGYI_SANDBOX_WORKSPACE_DIR:指定宿主机工作区挂载目录(默认~/.atlas/sandbox_workspace,Windows 为%USERPROFILE%\.atlas\sandbox_workspace);MINGYI_SANDBOX_DISABLED=1:一键关闭沙箱桥接,直接在宿主环境受限执行。
系统遵循“引擎状态机 + 向量记忆 + 项目私有隔离”的三层存储体系:
- 全局 Runtime 存储:会话状态、Message 树以及向量检索记忆集中持久化在数据库中(支持通过
MASTRA_APP_DATA_DIR统一指定如~/.atlas/),包含任务 SQLite 库与向量索引库(vectors.db); - 工作区项目本地存储:每个目标代码工程下的渗透测试任务黑板、靶标资产、漏洞发现与证据链统一保存在工程根目录的
.mingyi/pentest/中,天然支持与 Git 协同和审计归档; - 项目专家角色:支持在项目
<workspace>/.mastracode/agents/*.md中放置专属的专家人设,随工程自动加载为 Mode。
Atlas 具备高度开放的双轨扩展能力,支持安全研究员和开发者自由扩充:
- 原生安全工具扩展 (Native Security Tools):
1. 在packages/runtime/src/tools/security-tools/新增工具实现(需实现RuntimePentestTool接口规范);
2. 声明工具的参数 schema(Zod 校验)、只读性(readOnly)及执行回调;
3. 在index.ts导出并经DEFAULT_PENTEST_TOOLS自动注册进 Agent 调度图,受packages/runtime/test/tool-layout.test.ts架构守护。 - 标准 MCP 协议服务接入 (Model Context Protocol):
- 原生内建 MCP 客户端管理器,支持接入任意遵循 MCP 规范的外部工具服务器(如外部数据库、代码语义索引、自定义扫描器);
- 可通过配置动态挂载为 Agent 工具,无需修改前端即可实现全流程交互与参数悬停审批。
- 项目技能 (Skills) 自动化:
- 支持在项目
.agents/skills/<skill_name>/SKILL.md中以结构化 Markdown 形式封装专家操作经验; - 智能体可自动匹配语义并在对话中直接调度对应技能流水线。
欢迎社区安全研究员、模型工程研究者与全栈开发者共同完善 Atlas!
- 贡献者荣誉墙:项目桌面客户端内建了【开源致谢与社区贡献】专属面板(
设置 -> 关于我们 -> 致谢与贡献,见上方功能截图)。所有提交有效 PR、完善安全工具规则、扩展 MCP 或优化核心 Runtime 的贡献者,其 GitHub 个人资料与主页链接将被永久铭刻在应用致谢面板中; - 构建与发版规范:详细的本地开发规范、Conventional Commits 提交约定以及跨平台自动化 CI/CD 打包流水线(macOS DMG/ZIP、Linux AppImage/deb、Windows NSIS/ZIP)请参阅:
👉 Atlas 版本发布与贡献指南 (Release Guide)
先在仓库根目录安装依赖(本仓库使用 pnpm 工作区,要求 Node.js >= 22.19):
pnpm install
常用命令:
# 启动 Electron 应用(开发模式)
pnpm dev
# 构建与类型检查
pnpm build
pnpm typecheck
# 测试
pnpm test # Desktop Playwright E2E(无头)
pnpm --filter @mingyi/runtime test # Runtime Vitest 单测
# Lint 与格式化
pnpm lint
import { createLocalRuntime } from '@mingyi/runtime'
const runtime = await createLocalRuntime({
workspacePath: '/path/to/project',
})
// Desktop 通过 IPC 暴露 runtime.sessions 的可序列化接口;
// TUI 等简单场景可直接使用 runtime.session
await runtime.sessions.create({ title: '新任务' })
await runtime.sessions.sendMessage({ sessionId, content: '你好' })
await runtime.shutdown()
Atlas (Mingyi) 的诞生离不开现代开源 AI 与前端交互生态的卓越贡献。我们向以下优秀的开源项目、设计哲学及其研发团队致以诚挚的感谢:
- Mastra (
@mastra/core&@mastra/code-sdk):为 Atlas 提供了工业级、稳健的本地 AgentController 引擎底座、工作模式(Modes)、工具编排体系与会话状态持久化能力; - assistant-ui (
@assistant-ui/react):为桌面端呈现极致流畅、可组合且具备丰富交互细节的现代化生成式 AI 对话与工具流体验; - Vercel AI SDK (
ai):为系统提供了优雅、统一的流式消息协议、工具执行生命周期以及跨模型交互的标准数据契约; - Electron & React:构建高性能、原生集成终端与跨平台安全演练桌面工作台的坚实基础。
本项目开源核心部分遵循 GNU Affero General Public License v3.0 (AGPLv3) 许可证。
- 个人学习、研究与内部自用:完全免费,可在遵守 AGPLv3 的前提下自由运行、修改和分发。
- 免除开源约束 / 商业化使用:
若您或您的机构存在以下需求,无法或不愿遵守 AGPLv3 的强开源传染条款(包括但不限于向网络用户开放全部衍生系统源码): - 将本项目闭源集成进企业自研的商业产品中;
- 规避 AGPLv3 的网络分发(Section 13)传染限制;
- 寻求定制开发、企业级 SLA 支持或官方商业版 SaaS 插件扩展。
请联系我们获取 商业许可证(Commercial License):
- 团队: Mingyi (@MingyiSecLab)
- 邮箱:
starrepository@gmail.com
The core open-source codebase of this project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).
- Non-commercial / Community Use: Free for personal learning, research, and internal deployment under the terms of the AGPLv3.
- Commercial Licensing: If your organization requires closed-source distribution, integration into proprietary products, or wants to operate without the copyleft obligations of AGPLv3 (such as the Section 13 network-interaction requirement), you must obtain a Commercial License.
For commercial licensing and enterprise inquiries, please visit @MingyiSecLab or contact: starrepository@gmail.com