将 seo-audit-skill 接入 CI:脚本退出码与结构化 JSON 输出实践指南
将 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 这次说通过、下次说失败"的不稳定。
退出码协议:0 与 1 两条规则
SKILL.md 对协议的定义只有一句话:
Each script exits with code
0(all pass/warn) or1(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 证据渲染后的效果:
为什么这套设计天然适合 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 的原因。


