Communitygithub.com

Heraut SEO

深度只读式SEO调查,回答“Google为何不索引网站或不带来流量,以及具体如何解决”。并行运行四个调查方向,输出咨询式综合报告。

Heraut SEO 是什么?

Heraut SEO 是一项 AI Agent 技能,专门用于对网站及其服务器进行深度、只读的 SEO 调查。当网站完全没有自然搜索流量、博客文章未被 Google 索引、SEO 项目或内容流水线产出为零、或计划在内容上投入更多资金之前,可以使用此技能。它也能以完全相同的方式对一批网站进行统一审计。该技能并行运行四个调查方向(Google Search Console 与 GA4 的 URL 分层抽样检查、服务器日志与 DNS 验证的 Googlebot 访问、代码与内容的实际渲染解析、以及通过 DataForSEO 和 Perplexity 获取的外部排名与权威数据),然后生成一份咨询式的综合报告,包含现状、问题、根本原因树、分阶段行动计划、30/60/90 天的关键绩效指标,以及供业主决策的建议。所有脚本都采用只读模式,不修改网站、不写入数据库、不向 Google 提交任何内容。每个结论都附带可验证的证据(命令、数字、文件)。该技能支持通过 `gsc.py`, `logs.py`, `pages.py`, `dataforseo.py`, `perplexity.py` 等 Python 脚本在本地运行,并严格遵守预算限制和访问权限。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/koffih/claude-skill-heraut-seo/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Heraut SEO 是做什么的?

heraut(传令官)是让一个域名被世界知晓的角色。当无人听闻时,此技能会调查原因,为每个论断提供证据,并返回一份业主可以按步骤执行的计划。

它源于一个真实案例:一个拥有 58 000 个 URL 和 1 000 篇生成文章、内容负责人每天花钱但博客零展示的网站。答案并非内容负责人所关注的(重写页面),而是在于网站整体的质量、权威性和需求。以下方法旨在找到此类答案,而不是证实最初的假设。

规则

  1. 只读,无所不读。 不修改生产环境,不写入数据库,不重启,不向 Google 提交任何内容(不请求索引,不添加或删除站点地图)。调查只做描述;计划会在后续执行,一次只实施一个已决定的变更。
  2. 每个论断都有证据。 命令、数字、日期、文件。标明哪些是测量所得,哪些是推测所得。样本不等于计数:必须给出 n。
  3. 对网站保持礼貌。 一次只发一个请求,至少间隔 1.5 秒(politesse.delai_s)。小型服务器经不起审计的冲击。
  4. 付费 API 设预算上限。 脚本会在每次调用前强制执行 budgets.dataforseo_usd 和 budgets.perplexity_usd;每次成本都会记录。报告总花费。
  5. 任何输出不得包含密钥。 说明密钥所在位置,但不输出其值。脚本从环境变量或配置指定的 env 文件中读取密钥。

文件位置

脚本位于 scripts/(通常为 ~/.claude/skills/heraut-seo/scripts),仅使用 Python 标准库,openssl 用于生成 Google 令牌。每个脚本接受 --config <site.json> --dossier <investigation folder> 参数,并将 CSV 和 JSON 数据写入该文件夹,同时生成一个首要读取的 resume.json 文件。

脚本方向功能
sitemap.py代码完整的站点地图树,每个 URL 的类型和语言、最后修改时间真实性、重复项
gsc.py performanceGoogle按月份和页面类型查看过去 16 个月的数据、最近 28 天与前一周期对比、查询词、国家、板块
gsc.py sitemapsGoogle已提交的站点地图、错误、待处理、Google 上次读取时间
gsc.py echantillon / inspecter / analyserGoogle分层 URL 检查(每天 2 000 次配额,可续传)、按类型的覆盖范围、与上次运行相比的变化
ga4.pyGoogle过去一年各渠道数据,Google 自然流量(前后对比),AI 助手流量,类似机器人的分享比例
pages.py代码样本页面的页面内读取:语言、规范标签、hreflang、机器人元数据、文字量、JSON-LD、指向博客的链接、Googlebot 与浏览器所见差异
logs.py服务器真实的 Googlebot(经 DNS 验证)按天、按类型的访问,浪费的抓取,响应时间,首次访问的被跟踪 URL
ttfb.py服务器按类型、热缓存、冷缓存和源服务器计算的首次字节时间
dataforseo.py外部真实 SERP、排名关键词、网站及竞争对手的反向链接、搜索量、bilan
perplexity.py外部带日期和来源的深度研究(Agent API,effort 参数)

调查步骤

0. 框架搭建(10 分钟,必要时与业主一起)

  • 用业主自己的话记录问题,并附上症状数字(展示量、点击量、已发表文章、已花费金额)。
  • 找出已知信息:之前的审计报告、笔记、内容流水线及其数据库。将其视为待检验的假设,而不是直接抄录的事实。
  • 根据 config.example.json 构建网站配置文件:域名、站点地图、语言、页面类型路径正则表达式(最重要部分:每个计数都按类型区分)、要关注的板块(博客)、Search Console 资源、GA4 ID、服务账号密钥路径、市场(DataForSEO 位置代码)、3 到 6 个竞争对手、15 到 30 个用户可能会输入的真实查询、预算。
  • 开始前检查访问权限:gsc.py sitemaps 有响应、GA4 有响应、日志可读(通常仅 root 和 adm 组可读:请询问业主,绝不绕过拒绝)。

1. 四个方向并行执行

在网站其他审计文件旁边创建文件夹 enquete-YYYY-MM-DD/,从 references/brief.md 写入 BRIEF.md,然后一次性启动四个调查员(子代理),每个调查员配备简报及其方向文件。每个调查员写入 volet-<track>.md,顶部包含 10 行摘要,旁边放置原始数据。

方向文件关键问题
Googlereferences/track-google.mdGoogle 是否知道这些页面,是否抓取并收录它们?情况是在变好还是变差?
服务器references/track-server.md真实的 Googlebot 是否会来?它读到了什么?是否有任何因素在减慢或阻止它?
代码与内容references/track-code-content.mdGoogle 读取网站时发现了什么:多少页面、多单薄、链接情况如何、内容是否诚实?
外部references/track-outside.md在真实的搜索中谁赢了?他们有什么权威?网站所写的内容是否有需求?

先运行 sitemap.py(其他脚本从中采样),再运行各方向。gsc.py inspecter 在一个完整样本上可能需要数小时:应后台运行。

2. 综合分析

阅读四份报告,然后使用 references/cause-tree.md 构建答案:该文件列出了实践中看到的常见原因、确认或排除每个原因的指标,以及陷阱(技术审计结果干净并不表示网站没问题)。

按照 references/report.md 撰写报告:先给出简短答案,然后是现状、复杂性、问题、带有每个分支证据的原因树、当前计划为何无效、分阶段行动计划(每个步骤带有“完成条件”)、30/60/90 天的关键绩效指标、业主需做的决策、调查的局限性、数据来源。在会话允许时将其发布为页面(默认私有),否则发布为 HTML 文件。

3. 交接

  • 向业主提供链接、五句话的核心诊断、调查成本、以及未能测量的内容。
  • 然后,一次一项地给出决策,每项决策附上背后的数据和推荐。在询问下一项决策之前,先执行已决定的步骤。
  • 将判定结果及其隐含的操作规则(例如“在核心页面被索引之前,不发布新内容”)保存在项目记录位置。

在其他服务器或网站上运行

将技能安装在拥有访问权限(Search Console 密钥、日志)的机器上,将 config.example.json 复制到网站文件夹,填写内容,然后执行第 0 步到第 3 步。为每次调查日期保留一个独立的文件夹,以便下次运行时可进行比较:gsc.py analyser --avant <old inspection.jsonl> 会逐 URL 显示哪些页面进入或离开了索引。

在计划开始后的 60 到 90 天重新运行调查。在两次运行之间,每天轮换检查 50 到 100 个 URL 是观察索引变化最经济的方式。

此技能不做什么

它不修改网站、不编写内容、不请求索引、也不购买链接。它不评判产品或商业模式,只判断搜索是否能为网站带来用户。来自 SEO 工具的评分(排名、垃圾评分、预估流量)是模型,不是真实测量结果:引用时要加以说明。

相关技能