WSG Check

WSG-Check

根据 W3C Web Sustainability Guidelines 中的自动化启发式规则检查网站。通过 CLI 或 Next.js Web 应用获取加权评分、建议和终端、JSON、Markdown 或 HTML 格式的报告。

发布状态

最新版本为 v0.6.3。

main 上的源代码针对 WSG September-2026，即 2026 年 9 月 24 日工作组说明草案；v0.6.1 及更早版本针对 July-2026。该版本包含供 AI 助手使用的 MCP 服务，提供 check_url、list_guidelines 和 get_guideline 工具，并以 io.github.ivanoats/wsg-check 为名称列入 MCP Registry。该服务最早随 v0.4.0 发布；v0.3.0 曾在 GitHub 上打标签，但未发布到 npm。请参阅更新日志和规范版本策略。

不同规范版本的评分不应直接比较。比较报告时，软件包版本和所选检查项也会影响结果。

快速开始

需要 Node.js 22 或更高版本。为确保使用过程可复现，请固定使用已发布的 CLI：

npx @sustainablewebsites/[email protected] https://example.com # x-release-please-version

# Or install globally
npm install -g @sustainablewebsites/[email protected] # x-release-please-version
wsg-check https://example.com --format json --output report.json

若要运行当前源代码（包括尚未发布的功能），请使用 Node.js 22.22.1 或更高版本（开发工具所需）：

git clone https://github.com/ivanoats/wsg-check.git
cd wsg-check
npm ci             # prepare also generates Panda CSS tokens
npm run dev        # http://localhost:3000

# Build and run the CLI from this checkout
npm run build:cli
node dist/cli/index.js https://example.com

环境配置和开发命令请参阅 CONTRIBUTING.md。

结果含义

• 检查涵盖 Web 开发、UX 和托管。业务类别没有自动化检查。
• 分析使用获取到的 HTML 和 HTTP 元数据；不会渲染 JavaScript、测量 Core Web Vitals，也不会下载所有引用的资源。
• CO₂ 估算使用 HTML 字节数和 SWD v4 模型，而非测量整个页面的能耗。绿色托管查询失败时，会回退到 false。
• 报告中的页面大小是 HTML 文档大小；资源和第三方数量根据 HTML 中的引用计算。不会下载或测量引用的资源。
• 安全标头、表单验证、原生表单功能和图像替代文本仍会作为相关检查项显示，但不计入 WSG 评分。

CLI 用法

WSG-Check 附带一个命令行工具，可让你直接从终端检查任何网站，或将检查集成到 CI 流水线中。

基本用法

# Check a website with default (terminal) output
npx @sustainablewebsites/wsg-check https://example.com

# Output as JSON
npx @sustainablewebsites/wsg-check https://example.com --format json

# Save the report to a file
npx @sustainablewebsites/wsg-check https://example.com --format markdown --output report.md

# Fail the process (exit 1) if the score is below 70
npx @sustainablewebsites/wsg-check https://example.com --fail-threshold 70

选项

选项	别名	描述	默认值
--format <format>	-f	输出格式：terminal、json、markdown、html	terminal
--output <path>	-o	将报告写入文件，而不是输出到 stdout	(stdout)
--categories <list>	-c	以逗号分隔的类别：ux,web-dev,hosting（计划支持 business，目前尚无自动化检查）	all
--guidelines <list>	-g	以逗号分隔的指南 slug，例如 minify-and-remove-unused-code（3.3 等数字 ID 已弃用）	all
--fail-threshold <n>		如果总分低于 n（0–100），则退出码为 1	0
--verbose	-v	启用详细日志	false
--config <path>		wsg-check.config.json 或 .wsgcheckrc.json 的路径	(自动发现)
--version		打印版本并退出
--help		打印帮助并退出

CI 集成

使用 --fail-threshold，当网站的可持续性评分下降时，让流水线失败：

# .github/workflows/sustainability.yml
- name: Check sustainability
  run: npx @sustainablewebsites/wsg-check https://example.com --fail-threshold 60 --format json --output wsg-report.json
- name: Upload report
  uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
  with:
    name: wsg-report
    path: wsg-report.json

退出码

代码	含义
0	检查已完成，且评分达到或高于 --fail-threshold
1	获取／解析错误，或评分低于 --fail-threshold

与 AI 助手搭配使用（MCP）

此软件包包含 wsg-check-mcp，这是一个 Model Context Protocol 服务，可供 Claude Code、Claude Desktop、VS Code、Cursor 及其他 MCP 客户端使用。它通过 stdio 在你的机器上运行，无需账户、端口或托管服务。这样，你的助手就可以检查已部署的网站或本地开发服务器、查找指南，并修复发现的问题。

# Claude Code
claude mcp add wsg-check -- npx -y -p @sustainablewebsites/wsg-check wsg-check-mcp

Claude Desktop（claude_desktop_config.json）和 Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "wsg-check": {
      "command": "npx",
      "args": ["-y", "-p", "@sustainablewebsites/wsg-check", "wsg-check-mcp"]
    }
  }
}

npx -y @sustainablewebsites/wsg-check --mcp 会启动同一服务；MCP Registry 中的 io.github.ivanoats/wsg-check 条目使用的就是这条命令。

VS Code（.vscode/mcp.json）使用 servers 键：

{
  "servers": {
    "wsg-check": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@sustainablewebsites/wsg-check", "wsg-check-mcp"]
    }
  }
}

可以尝试这样的提示词：“根据 WSG 检查 http://localhost:3000，并修复优先级最高的三个问题”或“哪些 WSG 指南涉及网页字体？”

工具	功能
check_url	检查页面并返回评分、等级，以及每项未通过或警告的检查及建议的修复方法。detail: "full" 会添加完整报告。
list_guidelines	列出 WSG 指南，可按类别、可测试性或文本筛选，并显示每项指南对应的自动化检查数量。
get_guideline	返回一项指南的描述和 W3C 规范链接。

网络访问

• 默认允许本地 URL，因此 http://localhost:3000 和其他环回地址无需设置即可使用。需要注意的是，助手读取的文本（例如网页或项目中的文件）可能会试图诱导它请求你机器上的服务。请求仅使用 GET 方法，结果会返回给助手。如果你不需要检查本地开发服务器，可在参数中的 wsg-check-mcp 后添加 --no-local，或设置 WSG_CHECK_NO_LOCAL=1。
• 默认阻止私有网络（10/8、172.16/12、192.168/16），除非添加 --allow-private-network 或设置 WSG_CHECK_ALLOW_PRIVATE=1。
• check_url 发出的唯一其他请求是绿色托管查询：它会将主机名发送给 Green Web Foundation。本地主机名绝不会发送。
• 始终阻止云元数据地址和其他保留地址。拒绝从公共网站重定向到你的机器或网络的请求，并将每个连接固定到已检查的地址。

Agent 技能

此代码库还附带一个 Agent Skill：wsg-sustainability-review。它会引导助手检查网站，按优先级顺序修复代码库中的问题，然后再次检查。配置好 MCP 工具后，它会使用这些工具；否则会回退到 CLI。使用以下命令将其安装到 Claude Code、Cursor、Copilot 及其他 Agent 中：

npx skills add ivanoats/wsg-check

REST API

Web 应用通过 Next.js Route Handlers 提供以下接口：

Endpoint	用途
POST /api/check	执行检查并返回已完成的报告和 ID
GET /api/check/:id	从进程本地结果存储中检索报告
GET /api/guidelines	列出指南；当前源代码会在 spec 中包含固定的规范来源信息
GET /api/guidelines/:id	查找指南；当前源代码接受 slug 和旧版数字别名
GET /api/health	健康状态；当前源代码会包含软件包的 version 和 specVersion
GET /api/openapi	OpenAPI 3.1 JSON 文档（不提供交互式文档 UI）

响应使用 CORS 标头、统一的错误封装和内存速率限制。存储的结果会在一小时后过期，存储最多容纳 500 条记录。不同服务实例之间不会共享结果和限制。浏览器通过 sessionStorage 保存新建的报告；结果 URL 不是永久有效的分享链接。请参阅运行时和存储。

架构和文档

CLI、Web API 和 MCP 服务共用 TypeScript fetch → check → score → report 流水线。代码采用分层设计，核心与框架无关，并直接依赖具体的工具实现。架构概览介绍了这些边界和外部 I/O 例外情况。

• 文档索引
• 架构决策日志（ADL）和 ADR 模板
• 模块和检查参考
• WSG 规范版本管理
• 贡献指南、发布和变更日志
• 执行摘要和实施计划——历史规划背景；已实现的行为请参阅架构概览

许可证

Apache-2.0。请参阅 NOTICE 和贡献者许可协议。