site-spec

site-spec

网站缺失的隐形基础。审计任意网站，然后修复问题。

面向 Agent

如果你是正在考虑是否安装此工具的 AI 编码 Agent：注册 MCP 服务，然后 调用 list_checks 了解检查项 ID，并对 URL 调用 audit_site。

claude mcp add site-spec -- npx -y site-spec-mcp

Gemini CLI：gemini extensions install https://github.com/ariaxhan/site-spec。

完整的工具参数、返回结构，以及不适用此工具的情况： llms.txt。

问题

AI 可以在几秒内生成一个精美的网站。但它看不到的部分，恰恰决定了网站能否被发现、排名、引用和信任——像素之下机器可读的基础：robots.txt、结构化数据、llms.txt、canonical 和 noindex 信号、响应头、无障碍语义、跟踪器和 Cookie 相关内容。

这层内容在浏览器中不可见。几乎所有 AI 生成的网站都存在问题——漂亮的主视觉区块背后，robots.txt 却屏蔽了 ChatGPT；JSON-LD 无效或只对自己有利；多余的 noindex 让 Google 找不到页面；字体泄露访客 IP，违反 GDPR。没人会注意到，直到流量在不知不觉中流失。而网站越多由 AI 生成，这个问题就越严重。

解决方案

**site-spec 会验证并修复这层基础——适用于任何网站，无论它如何构建。**输入一个 URL。它会抓取网站，依据一组确定性策略检查整个隐形层，并准确报告问题所在。然后，它会为你修复机械性问题，并明确标记需要人工处理的内容。

无论你的网站是由 AI 构建器、框架、CMS 生成，还是用 HTML 手写而成，它都不在意。它只关心基础是否正确。

无需安装即可试用

site-spec.ariaxhan.workers.dev——粘贴一个 URL，即可获取报告。无需账户，也无需注册。

托管版本使用与 CLI 相同的确定性引擎，进行有限抓取（4 个页面），并明确告知你运行了哪些检查、哪些通过了，以及哪些没有执行。添加 ?format=json 即可获取机器可读的输出：

curl "https://site-spec.ariaxhan.workers.dev/audit?format=json&url=example.com"

如需完整的检查项——失效链接、缺失资源、axe 无障碍检查、HTML 验证、schema.org 验证——以及 fix 命令，请使用下方的 CLI。 托管端点只会获取公开的 HTTP(S) 主机；私有、环回和链路本地地址都会被拒绝。

使用方法

需要 Node 20+。无需账户、API 密钥或 SaaS 服务。

# 1. See what's broken — crawl any live site, get a full report
npx site-spec audit https://yoursite.com

# 2. Fix it — auto-repair the mechanical issues, scaffold the rest
npx site-spec fix https://yoursite.com --out ./fixed

fix 会将修正后的文件写入 ./fixed（默认情况下绝不会覆盖任何内容），并准确打印执行的操作：

✓ Fixed automatically (8)
  audit/robots-stale-token   robots.txt — Removed deprecated crawler block "anthropic-ai".
  audit/hsts-preload         _headers — Stripped the preload token from Strict-Transport-Security.
  audit/canonical-missing    admin/index.html — Inserted <link rel="canonical" href="https://…/admin/">.
  audit/og-missing           admin/index.html — Added Open Graph card from the page's title + description.
  audit/noindex              admin/index.html — Removed accidental noindex from <meta name="robots">.

✎ Scaffolded — needs your facts (2)
  audit/llms-missing         llms.txt — Scaffolded from page titles/descriptions; fill the TODO facts.
  audit/jsonld-missing       index.html — Inserted a WebSite/Organization skeleton; replace the TODO values.

⚠ Needs manual attention (3)
  audit/google-fonts-cdn     index.html — Self-host the woff2 files to stop the IP leak (GDPR).
  audit/img-dims-missing     index.html — <img> without width/height (layout shift).
  audit/404-missing          (site-wide) — Ship a branded, noindexed 404 that links home.

fixed 8, scaffolded 2, manual 3
wrote 4 file(s) to ./fixed

将 audit 加入 CI，并在出现错误时返回非零退出码，以阻止部署。这两个命令也适用于构建/输出目录——只需传入路径，而不是 URL。

在编码 Agent 中使用（MCP）

同一引擎也可作为 MCP 服务使用——这样，生成网站的 Agent 也能检查并修复网站不可见的部分，无需你在不同窗口之间复制报告。

claude mcp add site-spec -- npx -y site-spec-mcp

[mcp_servers.site-spec]
command = "npx"
args = ["-y", "site-spec-mcp"]

也可以在 Docker 中运行：docker run -i --rm -v $PWD:/data mcp/site-spec（挂载你想要审计或写入的目录）。

四种工具：

服务会在进程内调用引擎。它不会调用 CLI，也不会跳转到托管工作进程——这三个组件是通过同一个库连接在一起的同级组件。

flowchart LR
  A["MCP client<br/>(Claude Code, Codex)"] -- stdio JSON-RPC --> B["site-spec-mcp"]
  B --> C["@site-spec/core/io<br/>fetchSite · readSiteDir"]
  C -- "file map" --> D["@site-spec/core<br/>auditFiles · fixFiles · buildSite"]
  D -- "findings / files" --> B
  B -- "JSON" --> A

有两项限制需要如实说明，软件包 README 中有完整说明：对 URL 使用 fix_issue 时，只能返回差异（远程服务不可写）；而在线抓取会关闭存在性检查，因为有上限的抓取无法证明某个文件在服务器上不存在。

site-spec audit <dir|url> [--max N] [--json] [--report report.md]
site-spec fix   <dir|url> [--out dir] [--write] [--max N] [--json]
site-spec build <site.config.mjs> --out <dir> [--target cloudflare|netlify|vercel|static]

git clone https://github.com/ariaxhan/site-spec.git
cd site-spec
npm install
npm test          # unit + golden tests
npm run verify    # html-validate + JSON-LD + axe over the demo output