autosearch:tikhub-fallback

TikHub Fallback Decision Tree — Advisory

Cost anchor: TikHub averages $0.0036 per request (per docs/mcp-channels-playbook.md measurement). A research session with 1000 TikHub calls costs about $3.60/month. Cheap per call, but accumulates fast if every query defaults to paid.

Boss rule: Free paths first; TikHub is the paid cushion, not the default.

Covered Platforms (5)

| Platform | Free native skill | TikHub endpoint | Free path reliability | |---|---|---|---| | Xiaohongshu | search-xiaohongshu (requires cookie) | xiaohongshu/web/search_notes | Low — reliably gated; TikHub is usually required | | Weibo | search-weibo (free API) | web/fetch_search | Medium — free works but TikHub upstream is flaky | | Douyin | search-douyin (free native) | TikHub + mcporter-routed free MCP | Medium — free works, TikHub more complete | | Zhihu | search-zhihu (free native) | TikHub endpoint | Low — Zhihu blocks aggressive scraping | | Twitter / X | search-twitter-exa | search-twitter-xreach (XReach) | Medium — Exa covers public, XReach covers deeper signal |

Other hard Chinese platforms not covered by TikHub (do not escalate, degrade gracefully):

• WeChat Mini Programs
• Private Xiaohongshu accounts
• Facebook / Instagram private pages
• Any account-gated content

Decision Tree

Apply per query, not per session:

1. Try the free native channel skill first.
   ├─ Returns usable results? → DONE (do not escalate).
   └─ Blocked / empty / flaky? → step 2.

2. If `TIKHUB_API_KEY` is not set in env:
   ├─ Try the mcporter free MCP if applicable (Weibo, Douyin).
   └─ Otherwise report to user: "no free path, no TikHub key — gracefully degraded."

3. If `TIKHUB_API_KEY` is set AND the platform is one of the 5 covered:
   ├─ If query is research-critical (user explicitly asked or Best-tier step) → escalate to TikHub.
   ├─ If query is exploratory / fan-out → skip TikHub, try a different channel instead.
   └─ After 3 failed TikHub requests on the same session / same query shape → stop, do not retry a 4th time (rate-limit or upstream regression signal).

4. Bundle call patterns to reduce cost:
   ├─ Dedupe queries across channels before calling TikHub.
   └─ Prefer single calls that return rich payloads over multiple narrow calls.

Per-Platform Notes

• Xiaohongshu: Free scraping needs cookie that expires; TikHub is usually the primary practical path.
• Weibo: Free path works for recent hot topics; TikHub upstream has returned ok=1 but cards empty occasionally — ~20% flake. Pair with search-wechat for long-form verification.
• Douyin: Free mcporter MCP usable if user has cookie configured; TikHub as paid fallback when MCP 403s.
• Zhihu: Free path rate-limits after ~30 queries/session. Escalate to TikHub on rate-limit.
• Twitter/X: Prefer search-twitter-exa (free, Exa semantic site: query); only reach search-twitter-xreach (XReach paid) when a fresh timeline read is mandatory.

What This Skill Is Not

• Not a wrapper around the TikHub client (that's autosearch/lib/tikhub_client.py).
• Not a replacement for the channel skill's own fallback_chain. The channel skills carry fallback_chain: [via_tikhub, api_search, api_video_detail] in frontmatter — that is the per-channel sequence. This skill is the meta policy deciding whether the runtime AI should even reach into the fallback chain for the TikHub hop.

Boss Rules

• Do not default to TikHub. Free paths first, always.
• Do not flip global policy from a single failure. If a free channel failed once, retry with a different query shape before escalating. Only a repeated pattern (3+ failures on same query shape) or a known upstream block (Xiaohongshu) justifies escalating immediately.
• Budget-aware runtime AI should warn the user when TikHub spend crosses a session threshold (~$1 equivalent = ~280 requests).

Related Skills

• autosearch:router — picks the channel group first.
• autosearch:model-routing — picks model tier (orthogonal to cost).
• mcporter — the free-MCP fallback path (Weibo / Douyin alternatives without TikHub).
• Individual channel SKILL.md frontmatters already list via_tikhub in their fallback_chain.

Quality Bar

• Evidence items have non-empty title and url.
• No crash on empty or malformed API response.
• Source channel field matches the channel name.