Heraut SEO 是做什么的?
heraut(传令官)是让一个域名被世界知晓的角色。当无人听闻时,此技能会调查原因,为每个论断提供证据,并返回一份业主可以按步骤执行的计划。
它源于一个真实案例:一个拥有 58 000 个 URL 和 1 000 篇生成文章、内容负责人每天花钱但博客零展示的网站。答案并非内容负责人所关注的(重写页面),而是在于网站整体的质量、权威性和需求。以下方法旨在找到此类答案,而不是证实最初的假设。
规则
- 只读,无所不读。 不修改生产环境,不写入数据库,不重启,不向 Google 提交任何内容(不请求索引,不添加或删除站点地图)。调查只做描述;计划会在后续执行,一次只实施一个已决定的变更。
- 每个论断都有证据。 命令、数字、日期、文件。标明哪些是测量所得,哪些是推测所得。样本不等于计数:必须给出 n。
- 对网站保持礼貌。 一次只发一个请求,至少间隔 1.5 秒(
politesse.delai_s)。小型服务器经不起审计的冲击。 - 付费 API 设预算上限。 脚本会在每次调用前强制执行
budgets.dataforseo_usd和budgets.perplexity_usd;每次成本都会记录。报告总花费。 - 任何输出不得包含密钥。 说明密钥所在位置,但不输出其值。脚本从环境变量或配置指定的 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 performance | 按月份和页面类型查看过去 16 个月的数据、最近 28 天与前一周期对比、查询词、国家、板块 | |
gsc.py sitemaps | 已提交的站点地图、错误、待处理、Google 上次读取时间 | |
gsc.py echantillon / inspecter / analyser | 分层 URL 检查(每天 2 000 次配额,可续传)、按类型的覆盖范围、与上次运行相比的变化 | |
ga4.py | 过去一年各渠道数据,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 行摘要,旁边放置原始数据。
| 方向 | 文件 | 关键问题 |
|---|---|---|
| references/track-google.md | Google 是否知道这些页面,是否抓取并收录它们?情况是在变好还是变差? | |
| 服务器 | references/track-server.md | 真实的 Googlebot 是否会来?它读到了什么?是否有任何因素在减慢或阻止它? |
| 代码与内容 | references/track-code-content.md | Google 读取网站时发现了什么:多少页面、多单薄、链接情况如何、内容是否诚实? |
| 外部 | 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 工具的评分(排名、垃圾评分、预估流量)是模型,不是真实测量结果:引用时要加以说明。