将 seo-audit-skill 接入 CI:脚本退出码与结构化 JSON 输出实践指南

原创2026-10-28 20:54:521,382 阅读

将 seo-audit-skill 接入 CI:脚本退出码与结构化 JSON 输出实践指南

seo-audit-skill 是一个单页面 SEO 审计 Agent skill:给它一个 URL,即可得到一份结构化的 HTML SEO 审计报告。它的 4 个 Python 检查脚本不只服务人类阅读——每个脚本都把检查结果作为结构化 JSON 输出到 stdout,并遵循极简的退出码协议(0 = 全部 pass/warn,1 = 任一 fail/error)。这套设计让整条 SEO 检查链路天然可接入 CI 流水线,实现自动化 SEO 体检。

Script + LLM 双层架构:JSON 输出为什么被设计成"契约"

先看 README.md 中的架构图:seo-audit 采用 Script + LLM 双层架构——

层级 执行者 职责
Layer 1 Python 脚本 确定性检查(HTTP 状态、XML 解析、字符串匹配)→ 输出结构化 JSON
Layer 2 LLM Agent 仅对脚本标记的字段做语义判断(关键词意图、文案质量、页面类型推断)

两层之间靠 JSON 传递数据,其中有一个关键标记:llm_review_required。脚本只报告"可机械验证的事实",遇到需要语言理解的判断(例如 H1 与关键词只是部分字符串匹配时),就把该字段标记为 llm_review_required: true,交给 LLM 裁决。

这正是 CI 友好的核心设计:机器门禁(gate)只依赖确定性的脚本层——同样的 URL,任何时候重跑,退出码和 JSON 都一致;LLM 不参与门禁路径,杜绝了"AI 这次说通过、下次说失败"的不稳定。

seo-audit-skill 审计报告摘要:展示 Critical、Warnings、Passing 三栏检查结果统计

退出码协议:0 与 1 两条规则

SKILL.md 对协议的定义只有一句话:

Each script exits with code 0 (all pass/warn) or 1 (any fail/error).

各脚本的落地实现高度一致,例如 check-site.py 的收尾逻辑:

# Exit with code 1 if any check is fail or error — useful for CI integration
has_failure = any(r["status"] in ("fail", "error") for r in [robots_result, sitemap_result])
sys.exit(1 if has_failure else 0)
脚本 检查内容 触发 exit 1 的条件
check-site.py robots.txt + sitemap.xml 任一检查 fail 或 error
check-page.py H1 / title / meta / canonical / slug 任一检查 fail
check-schema.py JSON-LD 结构化数据 整体 status == "fail"
fetch-page.py 原始 HTML 抓取(含 SSRF 防护) 抓取出错

三个值得新手注意的设计意图:

1. warn 不拉挂流水线。 状态共四档:pass / warn / fail / error,但只有 fail(及错误场景)才返回 1。比如 title 长度 48 字符只是轻微偏短(warn),脚本不会让它打断 CI;而 robots.txt 缺失(fail)则必须阻断。这样门禁只针对"真缺陷",避免流水线被建议性警告刷屏。

2. 出错时也绝不静默。 无论是网络超时、页面返回非 200 还是缺少依赖,脚本都会先向 stdout 打印带 error 字段的 JSON,再 sys.exit(1)。CI 永远拿得到"裁决(退出码)+ 细节(JSON)"两份信息,不会出现"脚本挂了但啥也没输出"的排查困境。

3. 依赖缺失也有明确出口。 未安装 requests 时,错误信息写入 stderr 并以退出码 1 结束——在 CI 里这就是一条清晰的构建失败原因,而不是莫名崩溃。

结构化 JSON 输出:机器可读的"证据链"

每个脚本的 stdout 都是缩进良好的 JSON,字段命名规整、语义稳定。以 check-page.py 的输出为例(摘自脚本头部注释的示例):

{
  "url": "https://example.com/",
  "h1": { "status": "pass", "count": 1, "values": ["Best Running Shoes 2025"] },
  "title": {
    "status": "warn",
    "value": "Best Running Shoes 2025 | Free Shipping",
    "length": 42,
    "keyword_match": "partial",
    "llm_review_required": true
  }
}

这套字段设计对应三类 CI 消费场景:

  • 门禁:直接读每个对象的 status 字段做 pass / warn / fail 判定;
  • 报表:detail 字符串是人可读的证据描述(如 "sitemap.xml found with 42 URLs"),可原样贴进 PR 评论或日报;
  • 指标采集:length、url_count、keyword_match、http_status 等数值字段可入库,追踪站点 SEO 健康度随时间的变化。

脚本输出的每一行 status + detail,最终都会映射进 HTML 报告的检查表。下面是同一份 JSON 证据渲染后的效果:

SEO 审计报告站点级检查明细:robots.txt、sitemap.xml、canonical 标签的 FAIL/PASS 状态与修复建议

SEO 审计报告页面级检查明细:Title Tag、Meta Description、H1 Tag 与 JSON-LD Schema 的检查状态

为什么这套设计天然适合 CI

💡 把上面两点组合起来,就得到四个工程收益:

① 确定性与可复现。 门禁路径上没有 LLM。CI 每次运行拿到的是同一份 JSON 和同一个退出码,"昨天红了今天又绿了"这种事不会发生在脚本层。

② 细粒度门禁能力。 退出码是"粗闸"(有 fail 就红),JSON 是"细闸"——你可以在 CI 脚本里解析 stdout,只门禁自己关心的字段。例如:title.status == "fail" 才失败,而 meta_description 的 warn 只在 PR 评论里提示,不阻断合并。

③ 对外部 URL 的安全运行。 CI 里脚本会请求任意域名,fetch-page.py 与各 check 脚本内置了 SSRF 防护(拦截解析到内网/环回/保留地址的域名)、超时控制和重定向链跟踪,避免在构建环境里产生危险请求。

④ 可组合的管道。 fetch-page.py --json 输出不含正文的元数据(状态码、重定向链、内容长度),供其他脚本消费;check-schema.py --file page.html 支持直接复用已抓取的 HTML 文件,避免重复请求。整条链路可以像 Unix 管道一样自由拼装。

最小接入示例:三步跑通 CI

以 seo-audit/scripts/ 目录为例,一个最简的 CI 任务只需三步(依赖:pip install requests):

# 1. 抓取页面并做站点级检查
python seo-audit/scripts/check-site.py https://example.com > site.json

# 2. 页面级检查(建议带主关键词)
python seo-audit/scripts/check-page.py https://example.com --keyword "running shoes" > page.json

# 3. 退出码门禁:任一脚本 fail/error 则构建失败
echo "site: $(jq -c '.robots.status, .sitemap.status' site.json)"
echo "page: $(jq -r '.h1.status + " / " + .title.status' page.json)"

两个 Python 命令的退出码由 CI 平台自动捕获——0 放行,1 红灯;而两份 JSON 可以直接作为构建产物(artifact)归档,或交给 Agent 按 SKILL.md 定义的工作流继续生成完整报告。字段边界情况可查阅 references/REFERENCE.md。

小结

设计点 意图
退出码只有 0 / 1 CI 平台零配置即可消费;warn 不拉挂,fail 才阻断
失败也输出 JSON 裁决(退出码)与证据(stdout)分离,永不静默
llm_review_required 标记 确定性检查与语义判断解耦,门禁路径可复现
SSRF 防护 + 超时 允许 CI 安全地请求任意外部域名

一句话总结:seo-audit-skill 把"AI 审计"中最需要稳定性的部分(事实核查)做成了纯脚本 + JSON + 退出码的经典 CLI 契约,把最需要理解力的部分(语义判断)留给 LLM。这种分工既是它与 Agent 框架协作的基础,也是它能无缝嵌入 CI 的原因。

登录后查看全文
seo-audit-skill