深入 web-quality-skills 源码analyze.sh 只读 HTML 质量扫描脚本的设计与实现解析【免费下载链接】web-quality-skillsAgent Skills for optimizing web quality based on Lighthouse and Core Web Vitals.项目地址: https://gitcode.com/gh_mirrors/we/web-quality-skills在 web-quality-skills 开源项目中analyze.sh 是一个只读的 HTML 质量扫描脚本它逐行检查 HTML 文件中的 doctype、viewport、title、lang属性、图片 alt 等 7 类常见问题并以结构化 JSON 输出结果。整个扫描过程零写入、零副作用是 AI Agent 执行网页质量审计时最可靠的眼睛。本文将带你完整解析这个不到 120 行的 Bash 脚本是如何做到既安全、又机器友好的 web-quality-skills 是什么web-quality-skills 是一套面向 AI 编码助手的Agent Skills 技能包把 150 次 Lighthouse 审计经验沉淀为 6 个技能模块技能作用web-quality-audit全维度质量总审计performance加载速度与运行时性能core-web-vitalsLCP / INP / CLS 专项优化accessibilityWCAG 2.2 无障碍合规seo搜索引擎优化best-practices安全与现代最佳实践而analyze.sh就藏在全站审计技能 web-quality-audit 的scripts/目录中负责其中的静态 HTML 快速体检部分。一键上手如何运行 HTML 质量扫描脚本零运行时依赖仅需jq支持单个文件或整个目录bash skills/web-quality-audit/scripts/analyze.sh index.html bash skills/web-quality-audit/scripts/analyze.sh ./public/成功时stdout 输出如下结构化 JSON{ success: true, issues: [index.html:0: Missing title tag], warnings: [index.html:12: Non-HTTPS URL], issueCount: 1, warningCount: 1, truncated: false }失败时同样输出 JSON而非报错文本例如缺少jq依赖时{success: false, error: {type: missing_dependency, message: jq is required..., retryable: false, suggestion: Install: brew install jq}} 关键点无论成功失败输出永远是合法 JSONAI Agent 可以直接解析无需猜测错误含义。核心设计只读扫描脚本的三根支柱支柱一只读承诺——不写入、无副作用脚本第 2 行的注释就写明了身份契约Read-only HTML quality analyzer (v2). No filesystem mutations.实现上全程只使用grep、find等读取类命令不创建临时文件、不修改任何内容。这意味着可以放心在任意目录下运行不会污染工作区适合放进 CI 流水线做前置检查与 AGENTS.md 中脚本应自包含、依赖清晰的规范完全一致支柱二双通道输出——stderr 给人看stdout 给机器读脚本严格遵守项目 AGENTS.md 的脚本规范人类日志走 stderrAnalyzing: xxx.html、Scanned. 3 issues, 5 warnings.机器结果走 stdout唯一的 JSON 对象这样调用方可以只捕获 stdout 就拿到完整数据日志不会污染 JSON 流。支柱三快速失败 结构化错误开头一行set -euo pipefail保证任何未预期错误立即终止所有可预见错误统一交给fail()函数处理错误对象包含 4 个字段字段含义type机器可分类的错误码如invalid_inputmessage发生了什么retryable重试是否可能成功suggestion给修复方向的建议retryable字段尤其巧妙——它告诉自动化系统别白费力气重试了。7 类 HTML 质量检查项详解analyze_html()函数用轻量grep模式完成全部静态检查兼顾性能与覆盖面检查项严重程度判定标准HTML5 doctype❗ issue缺少!doctype htmlcharset 声明⚠️ warning缺少或非 UTF-8viewport meta❗ issue缺少nameviewport移动端必备htmllang 属性❗ issue缺少语言声明无障碍 SEOtitle标签❗ issue缺少标题SEO 硬伤img缺少 alt⚠️ warning逐个标签复查见下文非 HTTPS 资源⚠️ warning带行号定位混合内容issue 与 warning 的分级思路与技能文档 SKILL.md 的严重度模型Critical → Low一脉相承。其中img无 alt 的检查值得一提v1 版本依赖 PCRE 前瞻断言在 macOS 默认的 BSD grep 上会失效v2 改为两遍扫描——先grep -noE找出所有img标签及行号再逐个复查是否含alt。不依赖正则高级特性任何平台行为一致 ✅结果上限设计防止发现项爆炸扫描大型项目时一个页面上可能有上百个无 alt 的图片。如果全部输出JSON 会膨胀到 Agent 上下文都装不下。脚本用两级上限优雅解决这个问题单文件单类别上限MAX_PER_CATEGORY_PER_FILE20超过后追加一条findings truncated提示并停止计数——保证某一种问题不能挤占其他问题的展示名额全局上限MAX_FINDINGS100且 JSON 中显式携带truncated: true/false字段 这是机器可读输出的黄金法则宁可少而完整不要多而失控并让截断本身也成为数据的一部分。两个值得学习的工程细节进程替换修掉 v1 的子 shell 坑v1 版本中find ... | while read管道会让循环在子 shell 中执行循环里累加的ISSUES数组在循环结束后凭空消失。v2 改用进程替换done (find $TARGET \( -name *.html -o -name *.htm \) -print0)数组留在主 shell 中累加同时-print0保证含空格的文件名也能正确处理。jq 兜底与安全转义组装发现项时用jq -Rs把数组安全转为 JSON 数组杜绝引号、换行导致的 JSON 破坏极端情况下即使jq缺失fail()也会降级用printf拼出一个合法的简化 JSON 后退出——连错误输出都保证机器可解析在 AI Agent 工作流中如何发挥作用analyze.sh体现了 CLAUDE.md 中优先用脚本做自动化脚本输出不占用上下文的理念。典型流程用户对 Agent 说审计这个站点的质量Agent 触发web-quality-audit技能运行analyze.sh拿到 JSONAgent 按issues/warnings逐条给出修复建议含 Lighthouse 深度检查对于使用 Codex 的朋友插件安装方式详见 docs/codex-setup.md。延伸阅读全量审计规则与阈值参考skills/web-quality-audit/SKILL.mdCore Web Vitals 指标详解skills/core-web-vitals/SKILL.md脚本编写规范stderr/stdout 分离要求AGENTS.md扫描脚本本体全文仅 113 行值得逐行阅读skills/web-quality-audit/scripts/analyze.sh一句话总结analyze.sh 用最小的代码量展示了生产级 Agent 脚本的完整设计范式——只读无副作用、双通道输出、结构化错误、结果截断保护。把它放进你的 AI 编程工作流网页质量体检只需一条命令 【免费下载链接】web-quality-skillsAgent Skills for optimizing web quality based on Lighthouse and Core Web Vitals.项目地址: https://gitcode.com/gh_mirrors/we/web-quality-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考