fagun

# 🦊 Fagun **给任何AI一个浏览器，让它像真实用户一样使用您的产品，运行完整的用户验收测试，查找真实的错误，并告诉您产品是否准备好发布。** Fagun是一款单一的工具，可以与 **Claude, Cursor, Codex, Antigravity, Windsurf, Cline, 或 VS Code** 等工具集成。一旦设置完成，您只需输入 **`fagun`** （或 `/fagun`），您的AI就可以打开一个真实的浏览器： - **像真实用户一样使用网站** — 移动设备、慢速互联网、低端设备、仅限键盘操作、屏幕阅读器、国际化、首次访问者 — 带有真实设备和网络仿真。 - **了解业务** — 映射目标的CTA、表单、导航、身份验证状态和可能的收入/转化流程，然后再进行评估。 - **运行用户验收测试** — 完成整个旅程（注册、登录、搜索、结账、密码重置...）一步一步确认真实用户可以完成它们。 - **模糊每个输入字段** — 有效、无效、负数、空值、空格、特殊字符、Unicode、边界和注入观察用例。 - **查找真实的、可复制的错误** — 损坏的链接、控制台/JS错误、失败的请求、表单验证漏洞、辅助功能违规、缓慢的页面、安全配置错误。 - **提供产品准备就绪的裁决** — 16类别的记分卡（UX、UI、业务逻辑、辅助功能、性能、安全...）和发布决定，带有优先修复的建议。 您只需设置 **一次**。它适用于 **所有** AI工具。Chrome会 **自行安装**。 🌐 **网站：** https://mejbaurbahar.github.io/fagun/ · 📦 **PyPI：** https://pypi.org/project/fagun/ --- ## ⚡ 一条命令设置所有内容 **推荐，无需Python：** ```bash uvx fagun init ``` **已经安装但仍看到旧输出？强制最新版本：** ```bash uvx --upgrade --reinstall fagun init ``` **如果您更喜欢pip/Python：** ```bash pip install --upgrade fagun fagun init ``` 这就是整个安装过程。`fagun init`安装浏览器引擎 **和** 自动检测您机器上的所有AI工具（Claude Code、Claude Desktop、Cursor、Codex、Windsurf）并注册fagun浏览器工具、 **Chrome DevTools MCP** 、 **和** 每个工具中的 `/fagun` 技能。它还打开 `chrome://inspect/#remote-debugging` 以便Chrome显示官方的 **允许远程调试？** 弹出窗口，当Fagun连接到您的已登录的默认Chrome会话时。 设置输出是一个现代的CLI仪表板：任务、进度表、配置文件、最终摘要和下一个命令。路径会缩短为 `~` 以便用户可以看到究竟发生了什么变化，而无需阅读嘈杂的日志。 如果您的终端仍然显示 `Fagun init — setting up everything…` ，则表示您正在运行一个旧的缓存包。请使用 `uvx --upgrade --reinstall fagun init` 或 `pip install --upgrade fagun && fagun init` 刷新它。 然后重启您的AI工具并输入 **`fagun`** — 后面跟着您想要测试的内容。 在设置完成后，在您的AI工具中使用Fagun： ```text fagun deep test https://example.com fagun security scan https://example.com fagun check links on https://example.com fagun test the signup form on https://example.com ``` <details> <summary>其他安装方式</summary> **粘贴提示** （让AI为您完成）： > 安装并设置 **fagun** 为我：安装 `uv` （如果缺失），然后运行 `uvx fagun init`。 > 按照 https://github.com/mejbaurbahar/fagun/blob/main/install.md 进行操作，如果出现任何问题。 **Claude Code插件：** ``` /plugin marketplace add mejbaurbahar/fagun /plugin install fagun@fagun ``` **目标工具：** ```bash uvx fagun install claude-code # 或：cursor | claude | vscode ``` </details> <details> <summary>没有<code>uv</code>？ （一行命令，无需Python）</summary> **macOS / Linux:** `curl -LsSf https://astral.sh/uv/install.sh | sh` **Windows:** `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"` 然后重启您的终端。 </details> --- ## 🚀 手动安装（任何操作系统 - 无需Python或pip） **步骤1 — 安装 `uv`** （它自带Python，因此不需要其他依赖）： **macOS / Linux：** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` **Windows (PowerShell)：** ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` > ⚠️ **重启您的终端** 以使 `uv` 生效。 > （macOS/Linux：或在当前shell中运行 `source $HOME/.local/bin/env` 。） **步骤2 — 设置Fagun：** ```bash uvx fagun init # 安装浏览器 + 连接AI工具 + Chrome DevTools MCP + /fagun技能 ``` 就这样。重启您的AI工具，输入 **`fagun`** ，然后开始。 > **已经有 `pip`/Python？** 运行 `pip install --upgrade fagun && fagun init`。 > 💡 不想考虑配置？只需告诉您的AI： > *"安装并设置fagun为我 - 按照 https://github.com/mejbaurbahar/fagun/blob/main/install.md"* > 然后它为您完成所有上述操作。 --- ## 🔌 连接到您的AI工具 每个工具都获得两个MCP服务器： - **fagun** — 用户验收测试、错误查找、安全、辅助功能、表单、报告。 - **chrome-devtools** — 官方Chrome DevTools MCP，用于实时DevTools调试、控制台/网络检查、DOM/CSS检查和性能跟踪。 `uvx fagun init` 自动编写这两个。手动配置： | 工具 | 操作 | |------|-----| | **Claude Code** | `claude mcp add fagun -- uvx fagun` 和 `claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --auto-connect --no-usage-statistics` | | **Claude Desktop** | 将下面的JSON添加到 `claude_desktop_config.json` | | **Cursor** | `uvx fagun install cursor` （写入 `~/.cursor/mcp.json` ） | | **VS Code (Copilot)** | `uvx fagun install vscode` （写入 `.vscode/mcp.json` ） | | **Windsurf / Cline / Antigravity** | 将下面的JSON粘贴到它们的MCP设置中 | | **Codex CLI** | 将下面的TOML添加到 `~/.codex/config.toml` | ```jsonc // Claude Desktop / Cursor / Windsurf / Cline / Antigravity { "mcpServers": { "fagun": { "command": "uvx", "args": ["fagun"] }, "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest", "--auto-connect", "--no-usage-statistics"], "env": { "CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS": "1", "CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS": "1" } } } } ``` ```toml # Codex — ~/.codex/config.toml [mcp_servers.fagun] command = "uvx" args = ["fagun"] [mcp_servers.chrome-devtools] command = "npx" args = ["-y", "chrome-devtools-mcp@latest", "--auto-connect", "--no-usage-statistics"] env = { CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS = "1", CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS = "1" } startup_timeout_ms = 20_000 ``` `-y` 标志防止 `npx` 询问用户是否确认软件包下载。 `--auto-connect` 使Chrome DevTools MCP连接到用户正在运行的Chrome。 在首次设置时，Fagun打开 `chrome://inspect/#remote-debugging` ；打开远程调试，然后点击 **允许** ，当Chrome显示权限弹出窗口时。 用户无需先运行 `fagun connect to my Chrome` ； `fagun deep test <url>` 应该在AI客户端公开时自动使用Chrome DevTools MCP。 如果目标仍未登录，Fagun报告 `login-required` 并要求手动登录或提供授权的测试凭证进行 `login_with_credentials` 。 密码在输出中被掩盖，结果会话可以保存以便未来的身份验证测试。 Fagun退出Chrome DevTools MCP的使用统计和更新检查噪音，在生成的配置文件中。 **重启工具后添加它。** 然后输入 `fagun`。 --- ## 🎬 看看它在行动 ▶️ **实时动画演示（macOS / Windows / Linux）：** https://mejbaurbahar.github.io/fagun/#see-it-in-action 每个操作系统上的设置 + 首次错误： **macOS / Linux** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh # 获取uv（一次） uvx fagun init # 浏览器 + 所有AI工具 + 技能 # 然后，在您的AI工具中输入： # fagun deep test https://example.com ``` **Windows（PowerShell）** ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # 获取uv（一次） uvx fagun init # 浏览器 + 所有AI工具 + 技能 # 然后，在您的AI工具中输入： # fagun audit https://example.com ``` 就是这个流程： **安装uv → `uvx fagun init` → 在任何AI工具中输入 `fagun <task>`** 。 ## 💬 如何使用它 只需用纯英语与您的AI对话： - `fagun` → 显示菜单并启动 - `go to example.com and take a screenshot` - `run QA on https://example.com` - `deep test https://example.com and save the report to ./report.md` - `check for broken links on https://example.com` - `test the forms on the signup page` - `are there any console errors?` · `any failed network requests?` - `log in with test@x.com / password123, then check the dashboard` ### 🕵️ `/fagun` 错误查找器 Fagun配备了一项技能，将您的AI变成一个有条理的QA测试人员。它扫描整个产品准备度表面，只报告它可以实际重现的错误（无猜测）： | # | 检查 | |---|-----------| | 1 | **功能性** — 损坏的旅程、按钮/链接撒谎 | | 2 | **JavaScript错误** — 崩溃、加载和点击时的控制台错误 | | 3 | **网络 / API** — 4xx/5xx、失败的调用、混合内容 | | 4 | **表单** — 缺失验证、不安全的提交、无标签 | | 5 | **身份验证 / 会话** — 登录错误、泄漏、访问控制 | | 6 | **辅助功能** — 缺失的替代文本、标签、键盘陷阱 | | 7 | **性能** — 加载缓慢、资源繁重 | | 8 | **视觉 / 响应式** — 布局破坏、溢出、文本截断 | | 9 | **安全** — 缺失CSP/HSTS、暴露的版本、代码中的秘密 | | 10 | **SEO / 可发现性** — 标题、H1、元数据、可爬行性 | | 11 | **UX / 产品清晰度** — 混淆的流程、阻碍、弱的空状态 | | 12 | **业务逻辑** — 错误的结果、错误的总数、损坏的引导/结账路径 | | 13 | **移动 / 桌面兼容性** — 断点和设备特定的故障 | | 14 | **键盘 / 屏幕阅读器使用** — 焦点顺序、陷阱、标签、对比度 | | 15 | **头部 / CORS / CSP** — 浏览器安全姿势和错误配置 | | 16 | **边缘情况** — 重载、后退按钮、巨大的输入、Unicode、类似离线状态 | | 17 | **AI/安全编排** — 针对更深层次的授权测试的可选安全工具规划 | 每个发现都带有 **重现步骤、观察结果和影响**。 --- ## 🪙 节省令牌（默认开启） 浏览器工具通常会用巨大的JSON大块和完整的网络/控制台转储填充您的AI上下文 — 快速烧掉令牌。Fagun构建为 **节省令牌**： - **默认简洁输出** — 紧凑的每项发现一行文本而不是漂亮的JSON（~70%更少的令牌）。设置 `FAGUN_TERSE=0` 为完整JSON，或在任何工具中传递 `verbose=true` 进行一次调用。 - **一次调用，而不是十次** — `deep_test` 爬取 + 检查控制台、网络、表单、头部、辅助功能、性能跨整个站点在 **单个** 工具调用中，而不是许多手动 `navigate` + `get_console` + `get_network` 往返。 - **上限和去重** — 长链接/控制台/网络列表被截断为 `+N more` 标记；重复的发现被折叠。 - **报告磁盘，不在上下文中** — 传递 `report_path` 并写入原始详细信息；最终聊天答案显示完整的用户端结果：裁决、所有发现、证据、修复、覆盖率和报告链接。 > 💡 最便宜的工作流： `deep test <url> and save the report to ./report.md` > → 一次调用，完整的Fagun答案在聊天中，原始证据/报告在磁盘上。 ## ⚙️ 选项（可选） 如果需要，请将这些设置为环境变量： | 变量 | 默认值 | 它做什么 | |----------|---------|--------------| | `FAGUN_HEADLESS` | `1` | 设为 `0` 以 **观看** 浏览器工作 | | `FAGUN_BROWSER` | `chromium` | 使用 `firefox` 或 `webkit` 而不是 | | `FAGUN_CDP_URL` | — | 附加到 **您自己的** 打开的Chrome，例如 `http://127.0.0.1:9222` | | `FAGUN_TERSE` | `1` | 紧凑的节省令牌的输出。设为 `0` 为完整JSON，或 `mini` 为极简的摘要。 | | `FAGUN_FINDING_CAP` | `40` | 聊天输出中每页显示的最大发现数。完整的报告仍然会保存到磁盘。 | | `FAGUN_PAGE_CAP` | `12` | 多页面聊天摘要中显示的最大页面数。 | | `FAGUN_DETAIL_CHARS` | `100` | 简洁输出中每个发现的详细信息的最大字符数。 | | `FAGUN_URL_CHARS` | `60` | 简洁输出中每个URL的最大字符数。 | 使用最低令牌工作流： ```bash FAGUN_TERSE=mini ``` 然后询问：`deep test <url> and save the report to ./fagun-report.html`。聊天 获得一个微小的摘要；完整的证据保存在报告文件中。 ## 🎨 Fagun 样式（所有模型相同输出） Fagun 配备了一个可重用的响应契约，以便Claude、Codex、Cursor、Gemini、Qwen、 DeepSeek或其他自定义包装器可以用相同的样式显示结果： - `fagun_style_prompt` — 复制到系统/自定义指令中以获取Markdown输出。 - `fagun_style_prompt(mode="json")` — 告诉模型返回结构化的JSON。 - `fagun_style_schema` — 带有卡片/面板的前端渲染器的JSON模式。 - `fagun_render_response` — 将JSON或纯文本转换为Fagun样式的Markdown。 默认部分：执行摘要、问题、分析、解决方案、实施、 测试用例、边缘情况、风险、生产影响、API验证、性能、 Jira Ticket和最终建议。 ## 🧠 高级安全 + 工具目录 用于更深入的授权漏洞猎人工作流，Fagun现在包括AI安全工程师提示和外部工具目录。它 **不** 盲目运行利用工具； 它计划适配器，解释每个工具的适用性，并保持执行范围受控： - `fagun_security_prompt` — 用于授权安全测试的改进企业提示。 - `list_external_security_tools` — 漏洞扫描器、Loxs、Skill Security Scanner、 Shannon、Lonkero、recon-skills、payload corpora、RFC822 Email Validator、 LostFuzzer、img-payloads、customBsqli、BeeXSS、TimeVault和NextSploit的目录。 - `recommend_security_tools` — 从目标配置文件和目标中选择最小的相关工具计划，然后告诉AI如何验证和报告证据。 用于攻击图规划、工具选择、重复数据删除、验证、 补救和回归测试。主动探针仍然需要授权。 `recon-skills` 被视为只读方法包：Fagun可以使用它 选择相关的侦察、红队、部门、链条、SAML、Docker、WordPress、CORS、 XMLRPC、JS-secret、metrics和API流程检查清单，然后将其翻译成 授权的Fagun安全测试计划。 --- ## 🔐 授权目标的安全扫描（仅限） `security scan <url>` 运行漏洞猎人得到的漏洞类别 — **非破坏性**， GET/HEAD 仅限，不攻击第三方： - 暴露的文件（`/.git`，`/.env`，`/.aws/credentials`，备份，执行器） - HTML/JS中泄露的秘密（AWS，Stripe，Google，GitHub，JWT，私钥） - CORS 配置错误 · 反射XSS候选 · 开放重定向 · SQLi错误信号 - Cookie 标志 · 安全头部（CSP/HSTS/X-Frame） > ⚠️ 仅扫描您拥有或被授权测试的网站。 ## 🔌 使用您自己的已登录Chrome（自我修复 + 会话） - Chrome DevTools MCP 在正常深度测试期间使用 `--auto-connect` ，因此它可以 重用您已经登录的默认Chrome浏览器，并在您允许远程调试后。 适用于在登录后进行测试，无需向AI提供凭证。 - 如果Chrome未登录，Fagun报告 `login-required` 并要求手动 登录或授权测试凭证。 `login_with_credentials` 记录登录操作跟踪 但仅将密码打印为 `[hidden]`。 - `connect to my Chrome` 仅是一个故障排除备用方案，启动一个 专用可调试Chrome配置文件并连接到它。 - `browser_exec` → 当内置工具不合适时，AI编写Python对抗实时 页面（完整的Playwright）。 `save_helper` 持久化有效的内容，因此Fagun变得更智能 每次运行。 ## 🧰 它可以做的所有事情（MCP工具） `fagun_start` · `product_map` · `auth_status` · `login_with_credentials` · `open_browser` · `navigate` · `click` · `fill` · `press_key` · `screenshot` · `evaluate_js` · `get_console` · `get_network` · `crawl` · `run_qa` · `check_links` · `test_forms` · `fuzz_forms` · `list_test_data` · `perf_audit` · `a11y_audit` · `security_headers` · `security_scan` · `advanced_security` · `deep_test` · `full_qa_sweep` · `write_report` · `browser_exec` · `save_helper` · `list_helpers` · `load_helper` · `connect_chrome` · `fagun_security` · `list_external_security_tools` · `recommend_security_tools` · `close_browser` **最新版本有什么变化 v0.7.0 — 更深入、更智能、证据为基础：** - **`fuzz_forms`** — 积极填充每个表单字段带有标签的测试数据目录（有效/无效/负数/空值/空格/特殊字符/ Unicode/边界/超出范围/注入）并读取浏览器的**实际**约束验证判决。报告包括失败用例的字段-by-字段场景矩阵和截图。 验证间隙仅在浏览器本身接受它应该拒绝的值时报告。 - **`perf_audit`** — 真实的Web重要性能指标（LCP、CLS、TBT、FCP、TTFB）来自浏览器的性能API +类似Lighthouse的可比0-100分数。没有估计值。 - **`a11y_audit`** — 深入的WCAG 2.1检查，包括实际计算的色对比度。 - **`advanced_security`** / 更大的`security_scan` — CSP质量、点击劫持、危险的HTTP方法、混合内容、缺少SRI、敏感页面缓存、主机 头注入、CR/LF、路径遍历/LFI、SSTI、命令注入、GraphQL 内省、错误/堆栈跟踪披露、敏感数据在URL中。 - **Jira错误报告** — 每个确认的发现都生成一个Markdown/HTML报告中的Jira-ready工单：摘要、优先级、严重性、步骤、观察结果、预期结果、 影响、证据、截图路径和建议的修复。 - 每个发现都带有 **证据** — 没有制造任何内容；无法重现 = 不报告。 --- ## 🛠️ 开发者 ```bash git clone https://github.com/mejbaurbahar/fagun && cd fagun pip install -e . python -m playwright install chromium python -m fagun # 在stdio上运行MCP服务器 ``` **发布（维护者）：** 发布是通过GitHub Actions和 [PyPI Trusted Publishing](https://pypi.org/manage/account/publishing/) 自动进行的。递增版本号在 `pyproject.toml` 和 `src/fagun/__init__.py` 中，然后： ```bash git tag v0.3.0 && git push origin v0.3.0 ``` --- MIT © [Mejbaur Bahar Fagun](https://github.com/mejbaurbahar)