中文 | English
Mingyi Atlas 是一个面向软件工程和授权安全评估的终端 AI Agent。它提供交互式 TUI、无头自动化、持久化项目上下文、内置技能、浏览器/容器辅助能力，以及专用的渗透测试模式。
本项目发布为 @mingyilab/mingyi-atlas，并提供 mingyi-atlas 命令。
npm install -g @mingyilab/mingyi-atlas
mingyi-atlas也可以不全局安装，直接运行：
npx @mingyilab/mingyi-atlas运行要求：
- Node.js
>=22.19.0 fd或fdfind可选，但建议安装，用于更快的@file自动补全- Docker 可选，但使用容器支持的渗透测试浏览器/工具运行器时需要 Docker
支持的运行环境包括 macOS、Linux，以及现代 x64 或 arm64 Node.js 构建上的 Windows。原生可选依赖会由包管理器按当前平台解析。
启动交互式 TUI：
mingyi-atlas运行一次无头任务：
mingyi-atlas --prompt "Review the auth module and summarize risks"在无头自动化中使用渗透测试模式：
mingyi-atlas --mode pentest --prompt "Start an authorized assessment of https://example.test"
- 交互式终端 UI，支持持久线程和项目级状态。
- 支持 build、plan、fast 和 pentest 模式。
- 通过模型包配置支持多模型提供商。
- 支持 OAuth 和 API Key 认证。
- 项目与全局配置分别存放在
.mingyi-atlas/和~/.mingyi-atlas/。 - 内置技能加载机制，支持显式搜索和读取技能。
- Goal 模式用于较长周期的持续目标。
- 通过
/browser配置浏览器自动化。 - 为渗透测试工作流提供结构化安全上下文、发现、报告和工具产物。
- Mastra Workflow 接入：为侦察、验证、报告生成、清理等确定性安全评估流程引入可复用工作流编排。
- Workflow Tool 接入：将关键工作流封装为语义清晰的模型工具，使 pentest mode 和专用子 Agent 能在合适上下文中自主选择调用。
- 逆向分析 Agent 模式：面向二进制、固件、移动应用和协议样本的辅助分析工作流。
- APK 渗透 Agent 模式：面向授权 Android APK 安全评估，覆盖静态分析、组件暴露面梳理、敏感配置审查和报告生成。
可以使用 /login 登录支持 OAuth 的提供商，也可以在启动 CLI 前通过环境变量设置提供商 API Key。
常用 API Key 环境变量：
export ANTHROPIC_API_KEY=...
export OPENAI_API_KEY=...
export GOOGLE_GENERATIVE_AI_API_KEY=...凭据会保存在本机的 ~/.mingyi-atlas/auth.json。
渗透测试模式仅用于授权测试。它会为 Agent 提供面向安全任务的提示词、专用子 Agent、持久化目标上下文和受范围约束的工具。
渗透测试模式使用技能作为工作流指导。对于 benchmark、CTF 和夺旗类任务，它会优先使用 benchmark 工作流。对于 Atlas 风格的红队评估，它可以搜索并激活内置 Atlas 工作流技能，用于协调评估接收、OPPLAN 风格目标、专家委派、验证和报告。普通范围内评估会根据当前阶段选择最匹配的工作流或方法论技能。
系统提供监督、侦察、漏洞分析、验证、报告和修复等专用子 Agent。侦察和漏洞分析子 Agent 可以使用离线/API/认证辅助工具进行发现和证据审查。验证子 Agent 可以使用有边界、非破坏性的探测工具进行范围内检查。报告和修复子 Agent 默认不会获得主动探测工具。
安全工具包：
| 类别 | 工具 | 用途 | 安全边界 |
|---|---|---|---|
| HTTP 验证 | http_request |
范围内 HTTP 请求验证 | 仅面向授权目标和任务范围 |
| 离线分析 | crypto_analyze、hash_analyze |
编码/解码、摘要计算、哈希格式识别 | 不破解哈希，不恢复密钥 |
| API 与认证 | graphql_validate、websocket_validate、jwt_analyze、oauth_validate |
API、协议和认证配置验证 | 以配置审查和低风险验证为主 |
| 漏洞信号检查 | sqli_probe、ssti_probe、ssrf_probe、xxe_probe |
SQL 注入、模板注入、SSRF、XXE 信号检查 | 有边界、非破坏性探测 |
| 请求走私评估 | request_smuggling_assess |
被动/低风险请求走私信号评估 | 不发送畸形 TE/CL payload |
| 认证边界识别 | detect_auth_scheme |
识别登录、认证和访问控制边界 | 仅做检测和归类 |
| CAPTCHA 检测 | detect_captcha |
检测 CAPTCHA 和机器人挑战，提取人工输入相关选择器 | 不自动求解或绕过 CAPTCHA |
| 前端发现 | extract_js_endpoints |
从前端资源提取路由和 API 端点 | 用于发现和审查，不执行攻击 |
| CVE 查询 | cve_search |
带缓存的本地/远程 CVE 查询 | 只读查询 |
| 浏览器自动化 | run_browser_cli |
任务范围内的浏览器自动化 | 遵循授权目标和工具审批 |
| 容器工具 | run_container_tool |
容器化工具执行并捕获产物 | 隔离运行，保留执行产物 |
| 发现管理 | 结构化发现工具 | 报告、更新和复测发现 | 面向证据整理和复核 |
运行时渗透测试数据会按目标分桶保存：
.mingyi-atlas/pentest/targets/<target-slug>/
context.json
findings.json
http-responses/
browser-runs/
tool-runs/
reports/
CAPTCHA 处理仅限检测和人工交接。工具可以识别提供商、图片 CAPTCHA 字段、输入选择器、表单和提交控件，但不会自动求解或绕过 CAPTCHA。
常用命令：
| 命令 | 用途 |
|---|---|
/setup |
重新运行初始化引导 |
/login / /logout |
管理提供商认证 |
/models |
配置模型包 |
/mode |
切换模式 |
/subagents |
配置子 Agent 默认模型 |
/browser |
启用或配置浏览器自动化 |
/skills |
列出技能 |
/skill/<name> |
显式激活某个技能 |
/goal |
启动或管理持久目标 |
/threads |
列出并切换线程 |
/mcp |
查看或重新加载 MCP 服务连接 |
/hooks |
查看或重新加载 hooks |
/permissions |
管理工具审批 |
/settings |
管理通用设置 |
/diff |
查看本地 git diff |
/help |
查看命令帮助 |
全局数据：
~/.mingyi-atlas/
auth.json
analytics.json
settings.json
mingyi-atlas.db
mingyi-atlas-vectors.db
locks/
signals/
analytics.json 保存匿名、持久化的本机 telemetry distinct ID，不再使用主机名派生标识。
项目数据：
<project>/.mingyi-atlas/
hooks.json
mcp.json
commands/
skills/
pentest/
可以通过代码覆盖配置目录：
import { createMingyiAtlas } from '@mingyilab/mingyi-atlas';
const app = await createMingyiAtlas({
configDir: '.acme-agent',
});常用环境变量：
| 变量 | 用途 |
|---|---|
ANTHROPIC_API_KEY |
Anthropic API Key 兜底配置 |
OPENAI_API_KEY |
OpenAI API Key |
GOOGLE_GENERATIVE_AI_API_KEY |
Google 模型 API Key |
MASTRA_TELEMETRY_DISABLED=1 |
禁用产品 telemetry |
MINGYI_ATLAS_DISABLE_CAFFEINATE=1 |
禁用 macOS 防休眠 |
MINGYI_ATLAS_ANALYTICS_DEBUG=1 |
打印 analytics 调试事件 |
MINGYI_ATLAS_CVE_CACHE_PATH |
覆盖 CVE 缓存路径 |
MASTRA_PLANS_DIR |
覆盖已保存计划目录 |
安装依赖：
pnpm install从源码运行：
pnpm cli检查、测试和构建：
pnpm check
pnpm test:run
pnpm build运行发布前检查：
pnpm prepublishOnly
pnpm pack:check贡献者和维护者文档：
- CONTRIBUTING.md：PR 期望和贡献规则。
- DEVELOPMENT.md：本地设置、项目布局和实现模式。
- SECURITY.md：漏洞报告和安全工具边界。
- docs/architecture.md：高层实现架构概览。
- docs/pentest-capabilities.md：渗透测试能力全景参考，包括工具矩阵、子 Agent 职责、技能覆盖和安全边界。
- docs/pentest-tools.md：渗透测试工具设计细节和 Scope 规则。
- docs/security-domain.md：安全域数据层：数据模型、持久化、去重和报告。
- docs/skills.md：技能结构、发现规则和编写说明。
- docs/workflows.md：工作流分层、运行时工作流现状与使用边界。
包发布为 @mingyilab/mingyi-atlas，并提供一个二进制命令：
mingyi-atlas -> dist/cli.js
发布：
npm login
npm publish --access public@mingyilab npm scope 必须存在，并且你的 npm 账号需要具备发布权限。
Mingyi Atlas 社区版代码基于 Apache License 2.0 开源。
Mingyi Atlas 名称、Logo 和相关品牌资产属于 MingyiLab，不随 Apache-2.0 授权。