如何利用浏览器使用数据以及Claude API来构建一个本地SEO审计工具

hitl.py通过两个函数来解决这些问题：一个函数用于判断是否需要暂停操作，另一个函数则负责执行暂停操作本身。

from state import add_to_needs_human

LOGIN_KEYWORDS = {"login", "sign in", "sign-in", "access denied", "log in", "unauthorized"}
REDIRECT_CODES = {301, 302, 307, 308}

def should_pause(snapshot: dict) -> bool:
    code = snapshot.get("status_code")

    # 如果导航完全失败
    if code is None:
        return True

    # 如果状态码不是200，且不属于重定向代码
    if code != 200 and code not in REDIRECT_CODES:
        return True

    # 检查标题或H1标签中是否包含登录相关关键词
    title = (snapshot.get("title") or "").lower()
    h1s = [h.lower() for h in (snapshot.get("h1s") or [])]

    if any(kw in title for kw in LOGIN_KEYWORDS):
        return True
    if any(kw in h1 for kw in LOGIN_keywords for h1 in h1s):
        return True

    return False


def pause_reason(snapshot: dict) -> str:
    code = snapshot.get("status_code")
    if code is None:
        return "导航失败（状态码未知）"
    if code != 200 and code not in REDIRECT_CODES:
        return f"出现异常状态码：{code}"
    return "可能遇到了登录障碍"
should_pause()函数可以检测四种情况：导航失败、出现非预期的HTTP状态码、标题中包含登录相关关键词，以及H1标签中包含这些关键词。其中，对标题的检查能够有效识别那些虽然返回200状态码但实际上无法访问的页面。
在--auto模式下（用于定时执行任务），主循环会直接跳过pause_and_prompt()函数的调用，而是将相关信息记录到needs_human[]数组中，然后继续执行后续操作。
模块6：报告生成工具
reporter.py会逐个记录处理结果。这一点非常重要：因为结果是在每次审核完一个URL后立即被记录下来的，而不是在所有操作完成后才一次性生成。这样一来，如果任务中途被中断，之前完成的工作也不会丢失。
import json
import os
from datetime import datetime, timezone

REPORT_JSON = os.path.join(os.path.dirname(__file__), "report.json")
REPORTTXT = os.path.join(os.path.dirname(__file__), "report-summary.txt")

def _load_report() -> list:
    if not os.path.exists(REPORT_json):
        return []
    with open(REPORT_JSON, encoding="utf-8") as f:
        return json.load(f)

def write_result(result: dict) -> None:
    """在 report.json 文件中添加或更新相关数据。"""
    entries = _load_report()
    url = result.get("url", "")

    # 如果该 URL 已经存在于文件中，则更新相应的记录（支持重试机制）
    for i, entry in enumerate(entries):
        if entry.get("url") == url:
            entries[i] = result
            break
    else:
        entries.append(result)

    with open(REPORT_JSON, "w", encoding="utf-8") as f:
        json.dumpentries, f, indent=2, ensure_ascii=False)


def _is_overall_pass(result: dict) -> bool:
    fields = ["title", "description", "h1", "canonical"]
    for field in fields:
        if result.get(field, {}).get("status") not in ("PASS",):
            return False
    if result.get("broken_links", "").get("status") == "FAIL":
        return False
    return True


def write_summary() -> None:
    entries = _load_report()
    passed = sum(1 for e in entries if _is_overall_pass(e))

    lines = []
    for entry in entries:
        overall = "PASS" if _is_overall_pass(entry) else "FAIL"
        failed_fields = [
            f for f in ["title", "description", "h1", "canonical", "broken_links"]
            if entry.get(f, "").get("status") == "FAIL"
        ]
        suffix = f" [{', '.join(failed_fields)}]" if failed_fields else ""
        lines.append(f"{entry.get('url', 'unknown'):<60} | {overall}{suffix}")

    lines.append("")
    lines.append(f"{passed}/{len(entries)} 个 URL 通过了检测")

    with open(REPORTTXT, "w", encoding="utf-8") as f:
        f.write("\n".join(lines))

write_result()中的去重机制能够妥善处理重试操作。如果在人工审核并完成身份验证后再次尝试访问某个URL，系统会用新的审核结果替换原有的记录，而不会创建重复的条目。

模块7：主循环

index.py负责将所有组件连接在一起。它读取URL列表，加载状态信息，跳过已经完成审核的URL，然后启动审核流程。

import csv
import os
import sys
import time
import argparse

from state import load_state, is_audited, mark_audited, add_to_needs_human
from browser import fetch_page
from extractor import extract
from linkchecker import check_links
from hitl import should_pause, pause_reason, pause_and_prompt
from reporter import write_result, write_summary

INPUT_csv = os.path.join(os.path.dirname(__file__), "input.csv")

def read_urls(path: str) -> list[str]:
    with open(path, newline="", encoding="utf-8") as f:
        return 
.strip() for row in csv.DictReader(f) if row.get("url", "").strip()]
def run(auto: bool = False):
    if not os.environ.get("ANTHROPIC_API_KEY"):
        print("错误：未设置ANTHROPIC_API KEY环境变量。")
        sys.exit(1)

    urls = read_urls(INPUT_csv)
    pending = [u for u in urls if not is_audited(u)]

    print(f"开始审核：还有{len(pending)}个URL待审核，已有{len(urls) - len(pending)}个URL完成审核。\n")

    total = lenurls)

    try:
        for i, url in enumerate(pending, start=1):
            position = urls.index(url) + 1
            print(f"[{position}/{total}] {url}", end=" -> ", flush=True)

            # 打开浏览器访问该URL
            snapshot = fetch_page(url)

            # 进行人工审核
            if should_pause(snapshot):
                reason = pause_reason(snapshot)

                if auto:
                    print(f"自动跳过({reason})")
                    add_to_needs_human(url)
                    mark_audited(url)
                    continue

                action = pause_and_prompt(url, reason)
                if action == "quit":
                    print("退出审核流程。")
                    break
                elif action == "skip":
                    add_to_needs_human(url)
                    mark_audited(url)
                    continue
                # 如果选择“retry”，则重新尝试访问该URL
                snapshot = fetch_page(url)

            # 使用Claude工具提取信息
            result = extract(snapshot)

            # 检查是否存在失效的链接
            links = check_links(snapshot.get("raw_links", []), snapshot.get("final_url", url))
            result["broken_links"] = links

            # 立即写入审核结果
            write_result(result)
            mark_audited(url)

            overall = "PASS" if all(
                result.get(f, "").get("status") == "PASS"
                for f in ["title", "description", "h1", "canonical"]
            ) and links["status"] == "PASS" else "FAIL"

            print(overall)

    except KeyboardInterrupt:
        print("\n审核过程被中断。已保存进度，重新运行即可继续。")
        return

    write_summary()
    passed = sum(
        1 for e in [r for r in []]
        if all(e.get(f, "").get("status") == "PASS" for f in ["title", "description", "h1", "canonical"])
    )
    print(f"\n审核完成。报告已保存至report.json和report-summary.txt文件中。")


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--auto", action="store_true", help="自动跳过需要人工审核的URL")
    args = parser.parse_args()
    run(auto=args.auto)

KeyboardInterrupt处理程序就是用于恢复程序运行的机制。当你按下Ctrl+C时，该处理程序会输出一条消息并干净地退出程序。由于对于每个URL来说，在write_result()方法执行之后都会调用mark_audited()方法，因此下次运行程序时会跳过已经处理过的所有内容。

运行代理程序

交互模式（在遇到特殊情况时会暂停程序运行）：

python index.py

自动模式（会跳过特殊情况，并将未处理的URL添加到needs_human[]列表中）：

python index.py --auto

当程序运行时，你会看到每个URL对应的浏览器窗口会被打开，同时终端也会显示进度信息：

开始审计：还有7个URL未处理，0个已经完成。
[1/7] https://example.com -> 通过
[2/7] https://example.com/about -> 失败
[3/7] https://example.com/contact -> 被自动跳过（返回的状态码为404）
…
审计已完成。报告文件已保存为report.json和report-summary.txt

如果程序运行过程中被中断，可以重新运行它：

python index.py --auto
# 开始审计：还有4个URL未处理，3个已经完成。

为机构使用安排调度任务

对于需要每周定期执行的审计任务，可以创建一个批处理文件，然后通过Windows任务计划程序来安排执行。

创建run-audit.bat文件：

@echo off
set ANTHROPIC_API_KEY=你的API密钥
cd /d C:\Users\你的用户名\Desktop\seo-agent
python index.py --auto

在Windows任务计划程序中，按照以下步骤操作：

1. 创建一个新的基本任务。

2. 将触发条件设置为“每周一上午7点”。

3. 将动作设置为“启动一个程序”。

4. 选择run-audit.bat文件作为要执行的程序。

周一早上查看report-summary.txt文件。其中那些被标记为needs_human[]的URL需要人工审核——比如那些需要输入用户名或密码才能访问的页面，或者返回了异常状态码的页面。

对于macOS/Linux系统，可以使用cron来安排任务：

# 每周一上午7点运行
0 7 * * 1 cd /path/to/seo-agent && ANTHROPIC_API_KEY=你的API密钥 python index.py --auto

审计结果是什么样的

我使用这个代理程序对我的在Hashnode、freeCodeCamp和DEV.to上发布的7个页面进行了检测，结果所有这些页面都失败了。

https://hashnode.com/@dannwaneri                    | 失败 [标题]
https://freecodecamp.org/news/claude-code-skill     | 失败 [描述]
https://freecodecamp.org/news/stop-letting-ai-guess | 失败 [描述]
https://freecodecamp.org/news/rag-system-handbook   | 失败 [标题, 描述]
https://freecodecamp.org/news/author/dannwaneri     | 失败 [描述]
https://dev.to/dannwaneri/gatekeeping-panic         | 失败 [标题]
https://dev.to/dannwaneri/production-rag-system     | 失败 [标题]

0/7个URL通过审核

freeCodeCamp在描述文章时存在的问题，部分是由于平台本身的限制所致——freeCodeCamp使用的模板有时会截断或省略文章列表页面的元描述信息。而DEV.to在标题处理方面存在的问题则出在我自己身上，那些被用作标题的文章，其