aiseo-audit

aiseo-audit

一款确定性、类似 Lighthouse 的 AI 搜索就绪度审计工具。 测试生成式引擎能否轻松抓取、提取、理解并复用网页内容。

AI SEO 衡量的是内容就绪度，而非传统搜索排名。评分是一种基于研究的启发式审计结果，并不代表被引用的概率，也不保证引擎会引用该网页。

网站与指南 · 快速开始 · CI/CD · 与 AI 助手搭配使用 · 库 API · 评分方法

快速开始

需要 Node.js 20.19 或更高版本。

npx aiseo-audit https://yoursite.com

无需安装或 API 密钥。分析在本地运行，不会调用 AI API，也不会收集遥测数据。网络访问仅限于网页、站点地图以及 robots.txt 和 llms.txt 等域名信号文件。

典型输出以总分、流水线阶段和影响最大的修复建议开头：

Overall Score: 68/100  Grade: D+

Pipeline Stages:
  Technical Eligibility    PASS 96%
  Retrieval Alignment           58%
  Citation Fitness              63%
  Provenance                    42%

Top fixes:
  1. Topic Consistency  (Entity Clarity)
  2. Citation Patterns  (Grounding Signals)
  3. Lead Summary       (Answerability)

要在项目本地安装 CLI：

npm install --save-dev aiseo-audit

使用编程 API 时，将其作为常规依赖安装；也可以通过 npm install -g aiseo-audit 全局安装。

为什么选择 aiseo-audit？

• 分析内容，而非检测标签。 像引擎一样读取网页：网页是否始终如一地说明主题、直接回答问题、为观点提供来源，并避免模板内容干扰？包含 50 多项因素。
• 按证据等级评分。 每项因素都标注为有支持、条件性、启发式、诊断性或实验性，并对应到经过审查的文献。
• 按流水线阶段报告。 查看主要限制来自技术资格、检索匹配度、引用适用性还是来源溯源。
• 确定且可检查。 相同的评分版本、配置、抓取输入和评估日期会产生相同的分数。权重和阈值均有文档说明，不会隐藏在外部服务之后。
• 多种运行方式。 可使用 CLI、GitHub Action、MCP 服务或类型化的 TypeScript API；并可生成终端、JSON、Markdown 或独立 HTML 报告。

常见工作流

针对目标查询进行审计

查询感知审计会衡量三方面：标题和标题等结构字段中的查询词、正文中的查询词，以及网页中是否有针对查询各方面的内容章节。建议提供约五条查询以获得稳定的测量结果；最多可提供十条。

npx aiseo-audit https://example.com/guide \
  --query "how to set up sso" \
  --query "saml vs oidc" \
  --query "sso troubleshooting checklist"

使用 --domain product 可进行针对产品的价格、规格和对比检查。--engine gemini|gpt|perplexity 会应用实验性预设，重新调整现有类别的权重以适配各引擎；不会增加新的检查项。

创建可分享的报告

格式会根据输出文件扩展名推断：

npx aiseo-audit https://example.com --out report.html
npx aiseo-audit https://example.com --out report.md
npx aiseo-audit https://example.com --out report.json

使用 --tldr 仅输出分数和排名前三的修复建议。

随时间跟踪变化

# First run establishes a baseline; later runs show the delta.
npx aiseo-audit https://example.com --diff

# Compare with a specific result without updating tracked history.
npx aiseo-audit https://example.com --baseline ./previous-audit.json

# Show the timeline for every tracked URL.
npx aiseo-audit --diff --all

默认情况下，--diff 会将 JSON 结果记录到 ./audits，并更新发现的配置文件。在仓库中启用此选项前，请参阅 CLI 指南。

审计站点地图

npx aiseo-audit --sitemap https://example.com/sitemap.xml --out site-report.html

报告包含平均分、全站类别平均分、主机级溯源概况和各 URL 的结果。支持站点地图索引。默认情况下，URL 会依次处理；使用 --max-urls 和 --concurrency 限制工作量。

更多示例和所有标志的说明请参阅 CLI 指南。如需教程和实用的实施指导，请访问 aiseo-audit.com。

审计报告内容

每份报告都会将结果汇总为四个阶段：

阶段	含义
技术资格	页面能否被抓取、提取出可用文本，并且至少对一种已知 AI 爬虫保持可访问？
检索匹配度	结构字段、实体、主题覆盖范围和结构化数据是否有助于检索？
引用适用性	上下文中的内容是否直接、有依据、足够新，并且可供重用？
溯源	页面是否清晰说明作者身份、组织身份和归属信息？

技术资格是一道门槛。抓取失败、文本不可用或屏蔽所有已知爬虫，都会将总分限制在 25 分，并抑制后续阶段的百分比。对于明显过时的时效性内容、目标查询不匹配以及缺少产品价格，引用适用性也设有基于证据的负向门槛。

各项因素分为十个类别；只有提供目标查询时才会显示查询匹配度，只有产品页面才会显示产品适配度。完整的因素、权重、阈值和阶段对应关系请参阅审计明细。

未计分的诊断不会影响分数。当研究尚不足以支持评分时，这些诊断会保留相关观察结果。

解读分数

字母等级采用常见的学术评分区间。它们不是总体百分位数、经过校准的引用可能性估算，也不能证明某个网站“高于平均水平”。请在工具版本和配置保持稳定的情况下，使用分数比较同一页面或页面集合，然后优先处理权重最高的问题并重新测量。

如果使用 --fail-under，应根据自己的 v2 基线设定阈值，而不要把任何通用分数视为保证及格的标准。

CI/CD

官方 GitHub Action 可以为工作流设置门槛，并维护固定的 PR 评论：

name: AI SEO Audit
on:
  pull_request:

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: agencyenterprise/aiseo-audit@v2
        with:
          url: https://yoursite.com
          fail-under: 70
          comment-on-pr: true

在将检查设为阻断性之前，请根据自己的页面校准 fail-under。也可以使用单行 CI 调用：

npx aiseo-audit https://yoursite.com --fail-under 70

与 AI 助手配合使用（MCP）

随附的 MCP 服务向 Cursor、Claude Desktop、Windsurf 和其他 MCP 客户端提供 audit_url 工具：

{
  "mcpServers": {
    "aiseo-audit": {
      "command": "npx",
      "args": ["-y", "aiseo-audit-mcp"]
    }
  }
}

该工具接受可选的 queries 和 domain 参数。无需单独安装服务。

配置

CLI 会从当前目录开始向上查找 aiseo.config.json、.aiseo.config.json 或 aiseo-audit.config.json。

{
  "queries": ["how to audit ai seo", "ai seo checklist"],
  "domain": "auto",
  "format": "html",
  "weights": {
    "answerability": 2,
    "groundingSignals": 2,
    "queryAlignment": 2
  }
}

缺失的权重键默认为 1；将类别设为 0 可将其排除。所有字段、默认值和示例请参阅 CLI 配置。

离线审计、重放和回归门槛

2.0.2 之后的下一个版本将增加提供 HTML、可复现快照、稳定的问题发现、按页面检查爬虫，以及明确的 CI 失败策略。迁移详情请参阅 可靠性与集成指南。

npx aiseo-audit --file ./dist/index.html --url https://example.com --out report.html
npx aiseo-audit https://example.com --snapshot-out inputs.json --out baseline.json
npx aiseo-audit --replay inputs.json --json
npx aiseo-audit https://example.com --baseline baseline.json --fail-on-regression

程序化 API

import { analyzeUrl, loadConfig, renderReport } from "aiseo-audit";

const config = await loadConfig();
const result = await analyzeUrl({ url: "https://example.com" }, config);
const html = renderReport(result, { format: "html" });

console.log(result.overallScore, result.grade);

该软件包支持 ESM 和 CommonJS，并导出分析器、站点地图、报告、差异、配置和评分类型。请参阅 API 指南。

局限性

• 抓取的是 HTML，而不是浏览器渲染后的 DOM。 审计不会执行客户端 JavaScript。服务端渲染和预渲染的内容可见；仅在页面加载后添加的内容可能会被遗漏。
• 不评估视觉效果或多模态内容。 布局质量、侵入式广告、视觉层级以及仅通过图像传达的信息不在审计范围内。可以检查图像的 alt 文本，但无法检查像素内容。
• 假设可通过 HTTP 公开访问。 身份验证、同意流程、个性化设置、机器人防护和地理位置都可能改变审计获取的内容。
• 网络响应可能有所不同。 确定性仅适用于对相同抓取输入的评分；重定向、动态 HTML、实验和服务器故障都可能改变这些输入。
• 站点地图处理有明确限制。 默认按顺序执行；对于较大的网站，请使用 --max-urls 和 --concurrency。除非明确允许部分覆盖，否则页面抓取失败会导致 CLI 失败。
• 引擎行为仍具有非确定性。 准备度评分无法预测已部署的引擎是否会针对某个具体答案检索或引用某个页面。

研究与方法论

评分模型参考了有关生成式引擎优化（GEO）和生成式信息检索的同行评审研究，包括固定上下文实验、检索研究以及对已部署引擎的观察。证据强度和实验范围都很重要：权重和阈值仍是由专家设定的启发式规则，而非拟合得出的概率。

• 审计细目：所有类别、因素、区间、阶段和门槛
• 证据：因素与证据之间的可追溯关系及证据层级
• 新兴研究：跨论文综合分析与维护政策
• 论文评述：当前模型所依据的原始来源评述

从 1.x 迁移

版本 2.0 重新评估了因素集，因此同一页面通常会获得不同的评分。在将 GitHub Action 从 @v1 改为 @v2 之前，请重新建立关键页面的基线，并重新校准 CI 阈值。现有的 1.x 配置和基线数据仍可读取，但 --tldr 输出的 JSON 结构已改变。

请参阅完整的 2.0 迁移指南。

文档

• 网站和指南
• CLI 和配置
• 编程 API
• 评分方法论
• 证据图谱
• 研究综合分析
• 未来工作
• 变更日志

贡献

有关开发环境设置、项目结构和拉取请求指南，请参阅 CONTRIBUTING.md。安全问题请遵循 SECURITY.md。

许可证

MIT