QR Bridge

Entry point reconnaissance tool. Decode QR codes, trace redirect chains, inspect gated destinations, and explain what the link actually needs.

When to Use This Skill

Activate when the user asks to:

• - Decode / scan / read a QR code from an image
• Trace where a short URL redirects to
• Check if a link requires WeChat / WeCom / login / app
• Diagnose why a link "doesn't work"
• Generate a QR code from text or URL

Setup (First Run Only)

Before first use, compile the Swift decoder binary:

CODEBLOCK0

If setup was already run, the binary exists at ~/.claude/skills/qr-bridge/scripts/qr-decode. Skip setup if it exists.

Commands

1. DECODE - Extract QR code content from an image

Step 1: Check if binary exists
CODEBLOCK1

If NEED_SETUP, run:
CODEBLOCK2

Step 2: Run decoder (compiled binary - fast)
CODEBLOCK3

Step 3: If compiled binary fails, use interpreted mode (slower but always works)
CODEBLOCK4

Step 4: If CoreImage fails, try pyzbar fallback
CODEBLOCK5

Output format (JSON):
CODEBLOCK6

2. TRACE - Follow redirect chains

After decoding a URL from a QR code (or given a URL directly), trace the full redirect chain:

CODEBLOCK7

For the full chain with each hop, use:
CODEBLOCK8

Parse the Location: headers from the output to build the chain:
CODEBLOCK9

3. INSPECT - Detect gated destinations

After tracing, inspect the final URL for access gates. Check for these patterns:

WeChat/WeCom Gates (common in Chinese QR codes):

• - Domain contains: weixin.qq.com, work.weixin.qq.com, mp.weixin.qq.com, INLINECODE5
• Redirect to INLINECODE6
• Response contains: 请在微信客户端打开, INLINECODE8
• Response header logicret: -2 = article not found / deleted / unpublished
• User-Agent gating: returns different content for WeChat UA vs browser UA
• WeChat mini-program links: weixin://dl/business/?appid= — cannot be opened outside WeChat

App-Gated Links:

• - Taobao: tb.cn, m.tb.cn — returns 200 with JS redirect to Taobao app. Look for tbopen:// scheme or s_status: STATUS_NORMAL header
• Douyin: v.douyin.com — 302 redirect to www.douyin.com, then 404 for invalid links. Valid links redirect to INLINECODE17
• Xiaohongshu: xhslink.com — 307 → www.xiaohongshu.com. Look for snssdk:// or xhsdiscover:// deep-link schemes
• Alipay: ur.alipay.com — redirects to alipays:// scheme
• Response contains deep-link schemes: weixin://, alipays://, tbopen://, snssdk://, INLINECODE28
• Meta refresh or JavaScript redirect to app store

Login Walls:

• - HTTP 401 or 403 status
• Redirect to /login, /signin, INLINECODE31
• Response contains login form elements

Content Validity Check (run AFTER gate detection):

• - WeChat: header logicret value — -2 means content invalid/deleted
• Douyin: final destination is 404 = video removed or link expired
• Taobao: response body contains 对不起 or 宝贝不存在 = product delisted

Detection commands:
CODEBLOCK10

Header signals to check:

• - logicret: -2 → WeChat article invalid
• INLINECODE37 → Taobao link active
• INLINECODE38 containing app deep-link schemes → app-gated redirect

4. DIAGNOSE - Explain and suggest next steps

Based on decode + trace + inspect results, provide a structured diagnosis:

Output format:
CODEBLOCK11

Common diagnoses to provide:

Gate Type	Why It Fails	What It Needs
WeChat	Link requires WeChat's built-in browser	Open in WeChat app > scan QR
WeChat (invalid)

logicret: -2 — article deleted/unpublished | Request a valid article link |
| WeCom | Enterprise WeChat only | Must be a WeCom member of that org |
| Taobao | JS redirect to Taobao app | Open link in Taobao/淘宝 app |
| Douyin | 302→douyin.com, content requires app | Open in Douyin/抖音 app |
| Xiaohongshu | 307→xiaohongshu.com, app deep-link | Open in 小红书 app |
| Alipay | alipays:// scheme redirect | Open in Alipay/支付宝 app |
| Mini Program | weixin://dl/business/ scheme | Open in WeChat > scan QR to launch mini-program |
| Login Wall | Requires authentication | Sign in at [domain] first |
| App-Only | Deep link to native app | Install [app name] and scan in-app |
| Expired | Short link no longer resolves | Link has expired, request a new one |
| Geo-blocked | Returns different content by region | May need VPN to [region] |

5. GENERATE - Create QR codes from text/URLs

CODEBLOCK12

If qrcode is not installed:
CODEBLOCK13

Full Workflow

When the user provides a QR code image, run the full pipeline automatically:

1. 1. DECODE the image
2. If the decoded content is a URL:

a. TRACE the redirect chain b. INSPECT the final destination for gates c. DIAGNOSE with full report

1. 3. If the decoded content is NOT a URL (plain text, WiFi config, vCard, etc.):

a. Present the content with type identification b. Skip trace/inspect

Always present results in the structured diagnosis format above.

Error Handling

Image cannot be read:

• - Verify the file exists and path is correct
• Check format (PNG, JPEG, HEIC, TIFF supported)
• Suggest converting if format is unusual: INLINECODE42

No QR code detected:

• - Image may be too low resolution
• QR code may be partially obscured
• Suggest: crop to QR region, improve contrast, try a screenshot instead of photo
• Try pyzbar fallback (different algorithm may succeed)

Redirect fails (timeout/DNS):

• - Short link service may be down
• Link may have expired
• Try again with longer timeout: INLINECODE43

Cannot determine gate type:

• - Fetch page content and look for clues in HTML/JS
• Check response headers for X-Powered-By, Server, custom headers
• Report what IS known and suggest manual inspection

Notes

• - This skill is macOS-native. CoreImage is the primary decoder (zero external dependencies).
• The Swift binary is compiled once and reused for speed (~10ms vs ~2s interpreted).
• For batch processing, loop the binary over multiple files.
• All output is designed to be actionable: never just say "it failed" -- explain WHY and WHAT TO DO.