Agent Audit

Agent Audit

基于 Lighthouse 的 MCP 服务，面向 AI 编码 Agent，提供 Core Web Vitals、技术 SEO、无障碍功能以及 GEO/LLM 可见性审计。

🔗 NPM 包

Agent Audit 将 Google Lighthouse 和有限的页面检查结果转化为结构化修复包，供编码 Agent 实际执行。它为 Claude Code、Codex、Cursor、GitHub Copilot 及其他 MCP 客户端提供按优先级排序、有证据支撑的待办清单，而非原始性能报告。

将 Lighthouse 审计转化为编码 Agent 修复包。

npx -y @fullstackdegen/agent-audit

Agent Audit 的由来

Lighthouse 非常适合诊断问题，但原始报告不足以支持自主编码工作流。编码 Agent 仍需了解哪个问题最重要、它影响移动端、桌面端还是两者、哪些选择器或资源可作为证据、要搜索哪些文件、如何验证修复，以及何时可以安全地宣告完成。

Agent Audit 将 Lighthouse 输出转化为实施约定：

1. 运行移动端和桌面端 Lighthouse 审计。
2. 汇总多次运行结果并展示波动情况。
3. 添加有限的同页情报，包括技术 SEO、链接、元数据、结构化数据、图片、资源、可索引性和 AI 发现信号。
4. 将嘈杂的审计输出合并为简短且按优先级排序的问题列表。
5. 生成 fixPacks，其中包含仓库搜索提示、实施步骤和可衡量的验收标准。
6. 返回严格的 MCP structuredContent 以及对应的 Markdown。

目标很简单：为编码 Agent 提供一份可阅读、可推理、可修复、可测试和可验证的报告。

审计内容

以下场景适合使用 Agent Audit：

• 基于 Lighthouse 的 MCP 服务
• AI 网站审计工具
• 编码 Agent Lighthouse 报告
• Core Web Vitals 自动化
• 面向 Claude Code、Codex、Cursor 或 Copilot 的性能审计
• 面向 AI Agent 的技术 SEO 审计
• 无障碍修复包
• LLM 可见性审计
• GEO 审计、生成式引擎优化、AI 搜索就绪度
• llms.txt 就绪度和 AI 爬虫可见性

当前检查项包括：

• 移动端和桌面端的 Lighthouse 性能、无障碍、最佳实践和 SEO 评分。
• FCP、Speed Index、LCP、TBT 和 CLS 指标分布。
• 快速和可靠的审计模式。
• 设置有限抓取次数的同源页面检查。
• 损坏的链接、缺少名称的链接、元数据、规范标签、robots 信号、JSON-LD、Open Graph、可索引性、图片、资源和 LLM 可见性检查。
• 页面内容充足时，保守地生成 llms.txt 草案。
• 附带证据、建议操作和验收标准的优先级问题列表。
• 附带仓库搜索提示、实施步骤和验证指南的 Agent 修复包。
• 对 structuredContent 实施严格的 MCP outputSchema 校验。
• 根据同一份规范报告生成 Markdown。

查看真实的 CommaLabs JSON 报告和 Markdown 报告。

安装

要求：

• Node.js 20 或更高版本。
• Google Chrome 或 Chromium。

运行 MCP 服务：

npx -y @fullstackdegen/agent-audit

实用链接：

• NPM 包
• GitHub 仓库
• 发行版本
• 问题反馈
• 安全公告

MCP 客户端设置

Claude Desktop

添加本地 MCP 服务：

{
  "mcpServers": {
    "agent-audit": {
      "command": "npx",
      "args": ["-y", "@fullstackdegen/agent-audit"]
    }
  }
}

保存配置后，重启 Claude Desktop。

Claude Code

claude mcp add agent-audit -- npx -y @fullstackdegen/agent-audit

用于本地开发审计：

claude mcp add agent-audit-local -- npx -y @fullstackdegen/agent-audit --local

Codex

codex mcp add agent-audit -- npx -y @fullstackdegen/agent-audit

或者将其添加到 ~/.codex/config.toml：

[mcp_servers.agent-audit]
command = "npx"
args = ["-y", "@fullstackdegen/agent-audit"]

VS Code 和 GitHub Copilot

创建工作区级或用户级 .mcp.json 文件：

{
  "servers": {
    "agent-audit": {
      "command": "npx",
      "args": ["-y", "@fullstackdegen/agent-audit"]
    }
  }
}

或者从终端注册：

code --add-mcp '{"name":"agent-audit","command":"npx","args":["-y","@fullstackdegen/agent-audit"]}'

Cursor

配置本地 stdio MCP 服务：

• 名称：agent-audit
• 命令：npx
• 参数：-y、@fullstackdegen/agent-audit

需要审计 localhost 时，将 --local 添加到参数中。

工具

analyze_website_performance

对目标 URL 运行 Lighthouse 和网站智能分析：

{
  "url": "https://example.com",
  "mode": "reliable"
}

mode 是可选项：

• fast：运行一次移动端测试和一次桌面端测试。
• reliable：每种配置运行三次，计算中位数和波动范围。此项为 默认值。

修复包示例

{
  "id": "fix-link-name",
  "priority": 2,
  "sourceIssueIds": ["link-name"],
  "goal": "Fix Links do not have a discernible name.",
  "category": "accessibility",
  "severity": "critical",
  "affectedProfiles": ["mobile", "desktop"],
  "repoSearchHints": [
    "div.border-t-2 > div.flex > div.flex > a.text-gray-600",
    "https://www.linkedin.com/company/commalabs"
  ],
  "implementationSteps": [
    "Inspect the repository for the evidence listed in repoSearchHints before editing.",
    "Give every link a discernible accessible name.",
    "Keep changes focused on source issue IDs: link-name."
  ],
  "acceptanceCriteria": [
    "All link elements pass the Lighthouse link-name audit.",
    "Raise the median accessibility score to at least 90/100."
  ],
  "verification": {
    "rerunMode": "reliable",
    "expectedAuditIds": ["link-name"]
  }
}

repoSearchHints 是搜索线索，并非保证准确的文件路径。编码 Agent 必须先检查代码仓库，再进行编辑。

编码 Agent 工作流

将 structuredContent 作为事实依据，并将 Markdown 报告作为执行摘要。

1. 按优先级检查 fixPacks。
2. 使用 repoSearchHints 搜索代码仓库。
3. 将证据对应到实际的文件、组件、路由、资源或配置。
4. 每次只应用一个有针对性的修复。
5. 每完成一个逻辑变更后，运行代码仓库的测试。
6. 以 reliable 模式重新运行 Agent Audit。
7. 将新报告与各修复包的 acceptanceCriteria 进行比较。

如果报告不完整，或重新运行时的波动明显高于基准值，请勿声称任务已完成。

面向 Agent 的文档：

• AGENTS.md：适用于 Codex、Cursor、Copilot 和其他编码 Agent 的通用说明。
• CLAUDE.md：Claude Code 的设置和执行指南。
• Agent 工作流指南：报告结构和修复包执行流程。
• 可复制粘贴的编码 Agent 提示词

Localhost 审计

默认情况下，Agent Audit 只接受可公开路由的 HTTP 和 HTTPS URL。对于托管 Agent 和共享环境，这是合理的默认设置。

对于开发人员的机器，可显式启用环回目标：

npx -y @fullstackdegen/agent-audit --local

然后通过 MCP 客户端审计本地应用：

{
  "url": "http://localhost:3000",
  "mode": "fast"
}

启用后可使用 localhost、*.localhost、127.0.0.0/8 和 ::1。 私有 LAN 范围、链路本地地址、保留地址范围、多播地址和云元数据地址仍会被屏蔽。

也支持使用环境变量：

LIGHTHOUSE_MCP_ALLOW_LOCALHOST=true npx -y @fullstackdegen/agent-audit

安全模型

Agent Audit 会使用用户提供的 URL 启动 Chrome，因此 URL 策略十分重要。 服务会拒绝：

• HTTP 和 HTTPS 以外的协议；
• 嵌入式凭据；
• 未显式启用时的 localhost 和环回目标；
• 私有、链路本地、多播、保留和元数据网络 IP；
• 解析到任何非公开地址的非 localhost 主机名。

页面检查抓取器使用相同的 URL 策略，并应用超时、字节大小和资源数量上限。

页面控制的标题、描述、URL、选择器、片段和审计文本都经过清理并限制长度。使用方仍必须将它们视为不可信证据，而非 Agent 指令。

默认启用 Chrome 沙箱。只有无法支持沙箱的隔离环境才应设置：

LIGHTHOUSE_CHROME_NO_SANDBOX=true

有关漏洞报告和部署指南，请参阅 SECURITY.md。

限制

Agent Audit 有意设置了明确限制：

• 每次仅审计一个指定的 URL。
• 它不是全站爬虫。
• 它不是外部 SEO 数据库。
• 它不会修改 Shopify、CMS、CDN、DNS、托管服务、重定向或分析设置。
• 它不会压缩图像、缩小资源、提交 IndexNow 请求或调用第三方 SEO API。
• Lighthouse 结果会因浏览器版本、硬件、网络状况和页面变更而异。

路线图

• 面向框架的代码库搜索提示。
• 可选的 GitHub Action，用于拉取请求性能门槛。
• 批量 URL 报告。
• HTML 报告导出。
• 更深入的营销和发现信号：分析标签、同意信号、Open Graph、schema 覆盖情况以及 AI 发现就绪度。
• SEO、GEO 和可见性数据集的可选第三方集成。

开发

npm install
npm test
npm run check
npm run build
npm run validate:release

运行真实 Chrome 冒烟审计：

npm run --silent smoke -- https://example.com fast
npm run --silent smoke -- https://example.com reliable

冒烟命令会将规范 JSON 写入标准输出，并将等效的 Markdown 写入标准错误。

发布

发布之前：

npm test
npm run check
npm run build
npm run validate:release
npm pack --dry-run --cache /private/tmp/agent-audit-npm-cache

发布：

npm publish --access public --cache /private/tmp/agent-audit-npm-cache

已发布的软件包：

npx -y @fullstackdegen/agent-audit --help

贡献

欢迎提交聚焦明确的问题和拉取请求。更改报告约定、安全策略或 MCP 传输行为之前，请阅读 CONTRIBUTING.md。

许可证

MIT