HTML 工具箱专业版

面向团队的全站HTML审计与WCAG合规治理专业工具，支持批量扫描、违规分级报告及组件库规范治理，提升合规与质量效率。

功能说明: 本技能涵盖 中文交互、提升工作效率、化工作流场景 等核心能力。

概述

专业版面向团队与企业，在免费版单页自检基础上，扩展全站批量 HTML 审计、WCAG 2.1 合规检查、组件库规范治理与结构化数据。审计清单与免费版兼容，已有检查项可直接纳入全站回归.

核心能力

能力	说明	专业版增强
全站审计	批量扫描所有页面 HTML	爬虫式回归
WCAG 合规	AA/AAA 级检查	违规分级报告
组件库治理	组件 HTML 规范与版本化	团队共享
结构化数据	Schema.org 标记验证	富结果优化
国际化	hreflang 与多语言标记	全站映射
技术实现要点：核心能力基于input_params参数与output_format配置实现,支持创建/查询/修改/删除等操作模式,通过config_options进行运行时配置.

核心功能执行

用input_params参数进行配置.

处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志.

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置.

处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志.

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置.

处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志.

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：面向团队的全站、合规与组件库治理、审计与、合规治理专业工具、全站批量、审计与回归、Use、when、需要安全检测、合规审计、质量检查、加密防护时使用、不适用于安全评估、未授权目标、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景一：全站 WCAG 审计

bash

# 批量审计（专业版）
npx @axe-core/cli http://localhost:8000 \
  --tags wcag2a,wcag2aa,wcag21aa \
  --save a11y-report.json

text

报告示例:
  严重: 3 处表单未关联 label
  中等: 5 处图片缺 alt
  提示: 2 处对比度不足
  覆盖页面: 28 / 28

场景二：组件库规范治理

json

{
  "component_rules": {
    "button": {"required": ["type"], "forbidden": ["onclick=inline"]},
    "img": {"required": ["alt", "width", "height"]},
    "a[target=_blank]": {"required_rel": ["noopener", "noreferrer"]}
  },
  "lint_on_build": true,
  "block_severe": true
}

场景三：结构化数据与国际化

html

<!-- 结构化数据 -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "示例产品",
  "offers": {"@type": "Offer", "price": "49", "priceCurrency": "CNY"}
}
</script>
# ...
<!-- 多语言 hreflang -->
<link rel="alternate" hreflang="zh-CN" href="https://example.com/zh">
<link rel="alternate" hreflang="en" href="https://example.com/en">
<link rel="alternate" hreflang="x-default" href="https://example.com/">

快速开始

1. 将免费版清单纳入全站审计规则.
2. 爬取站点批量执行 WCAG 检查.
3. 定义组件库 HTML 规范并接入构建.
4. 添加结构化数据与 hreflang 标记. 响应解析: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤.

示例

全站审计配置（html-audit.json）：

json

{
  "start_url": "https://example.com",
  "max_pages": 200,
  "wcag_level": "AA",
  "checks": ["img-alt", "label", "scope", "rel", "canonical", "hreflang"],
  "report": "html-audit-report.json",
  "regression_baseline": "main"
}

优选实践

• 合规先定级：先定 AA 还是 AAA，AA 是多数法规基线.
• 审计入 CI：构建后批量审计，严重违规阻断发布.
• 组件库强约束：组件规范接入 lint，违规即报错.
• 结构化数据验证：用 Schema.org 验证工具检查富结果资格.
• hreflang 双向闭环：每个语言页都要互相指向，加 x-default.

免费版兼容性

项目	免费版	专业版
检查清单	相同	相同（纳入规则）
范围	单页	全站批量
WCAG	基础项	AA/AAA 全量
组件库	不支持	支持

常见问题

Q1：全站审计要多久？ A：取决于页面数，200 页约 5-10 分钟，支持并发爬取. Q2：WCAG AA 与 AAA 区别？ A：AA 是法规基线，AAA 更严格，多数站点以 AA 为目标. Q3：组件库规范怎么落地？ A：定义规则 JSON，构建期 lint，严重违规阻断. Q4：结构化数据一定有效吗？ A：不保证富结果，但提升资格，需用验证工具检查. Q5：专业版有优先支持吗？ A：有。专业版享合规咨询与审计规则定制.

进阶用法

全站审计规则定制

json

{
  "checks": {
    "img-alt": {"severity": "block"},
    "label-association": {"severity": "block"},
    "heading-order": {"severity": "warn"},
    "button-type": {"severity": "warn"},
    "rel-noopener": {"severity": "block"},
    "canonical": {"severity": "warn"},
    "hreflang-bidirectional": {"severity": "block"}
  },
  "exclusions": [{"path": "legacy/**", "until": "2026-12"}]
}

结构化数据验证

bash

# 用 Schema.org 验证工具检查富结果资格
curl -X POST https://validator.schema.org/validate \
  -d "url=https://example.com/product"

text

常见结构化数据类型:
  Product    产品（价格、库存）
  Article    文章（标题、作者、日期）
  Breadcrumb 面包屑导航
  FAQ        常见问题
  Review     评价

hreflang 双向闭环

html

<!-- 每个语言页都要互相指向，加 x-default -->
<link rel="alternate" hreflang="ja" href="https://example.com/ja">

审计报告解读

text

违规分级:
  critical: 必须修复，阻断发布（如表单无 label）
  serious:  应修复，影响可访问性（如对比度不足）
  moderate: 建议修复（如缺 alt）
  minor:    锦上添花
# ...
回归判定:
  本次 critical 数 > 基线 → 阻断
  本次 serious 数 > 基线 ×1.2 → 告警

治理流程

• 基线定标准：选定 WCAG 级别作为基线，全站统一.
• CI 拦截严重：critical 违规阻断合并，serious 告警.
• 豁免限期：遗留违规走豁免流程，标注期限与原因.
• 定期全量扫：每周全站扫描，趋势监控.
• 组件源头治：违规多发的组件在组件库层修复，一处改全站受益.

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统: Windows / macOS / Linux
• Node.js: 18+（审计 CLI）

依赖详情

依赖项	类型	是否必需	获取方式
axe-core	审计工具	审计时必需	npm install -D @axe-core/cli
pa11y	审计替代	可选	npm install -g pa11y
LLM API	API	必需	由 Agent 内置 LLM 提供

API Key 配置

• 本工具为纯 Markdown 指令，无需额外 API Key
• 爬取需鉴权站点时配置访问凭证

可用性分类

• 分类: MD+EXEC（Markdown 指令 + 命令行审计）
• 说明: 通过自然语言指令驱动 Agent 完成全站审计与合规治理

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

已知限制

• 需LLM支持,无LLM环境不可用
• 复杂业务场景建议结合人工经验判断
• 执行效率受模型能力与网络环境影响

输出格式

json

{
  "success": true,
  "data": {
    "result": "HTML 工具箱专业版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "htmlkit pro"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}

安全注意事项

风险类型	防范措施
API密钥泄露	通过环境变量配置，禁止硬编码到代码或配置文件中
命令执行风险	仅执行白名单命令，避免拼接用户输入到命令行参数中
网络通信安全	使用HTTPS协议，验证SSL证书有效性
敏感数据暴露	输出结果中不包含密钥、令牌等敏感信息

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。