feat(reference-curator): add --wayback-fallback flag + CAPTCHA/IP block detection

- Add _is_captcha_response() to detect Google sorry page, 429, and
  "unusual traffic" markers in crawler responses
- Add --wayback-fallback CLI flag: auto-switches remaining URLs to
  web.archive.org/web/2024/ after 3 consecutive CAPTCHA blocks
- Add --delay CLI flag for polite crawling with configurable interval
- Add retry logic with exponential backoff on 429/5xx responses
- Document GOTCHA section in crawler CLAUDE.md with detection signals,
  Wayback detour solution, and prevention tips
- Add GOTCHA callout in pipeline orchestrator Stage 2 docs
- Record source: wayback in frontmatter for traceability

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-13 01:55:11 +09:00
parent b1c2dca080
commit 382b55e9c8
3 changed files with 180 additions and 13 deletions

View File

@@ -100,12 +100,22 @@ If mode == 'topic':
### Stage 2: Web Crawler
```
→ Claude uses Firecrawl MCP tools
→ Claude uses Firecrawl MCP tools or seo_crawler_adapter.py
→ crawl_mgr.py store-result
→ If --save-raw or --no-distill: write raw .raw.md files to output
→ pipeline.py advance --stage storing
```
**⚠️ GOTCHA — IP Block / CAPTCHA Detour:**
If the crawl stage encounters persistent 429 or CAPTCHA responses (e.g., Google's `google.com/sorry/` redirect), the pipeline should **NOT** retry indefinitely. Instead:
1. Detect: 3+ consecutive 429/CAPTCHA responses = IP blocked
2. Detour: Re-invoke `seo_crawler_adapter.py` with `--wayback-fallback` flag
3. The crawler auto-switches remaining URLs to `web.archive.org/web/2024/{url}`
4. Frontmatter records `source: wayback` for traceability
5. Resume normal pipeline from Stage 3
**Common triggers:** Large-volume crawls (>50 pages) on `support.google.com`, `developer.mozilla.org`, or any site with aggressive bot detection. **Prevention:** Always use `--delay 2.0` or higher for these domains.
### Stage 3: Content Repository
```
→ repo.py store (for each crawled doc)