Local POI Planner

Use this skill when the user wants a specific nearby place recommendation with constraints like:

• start point / origin
• metro access
• seating / environment quality
• mall preference
• budget / category / vibe
• avoid rules (night market, takeaway-only, no seating)

This skill is a single top-level skill. Internally it may call the existing unified-search skill script as a supporting evidence source.

What this skill does

1. Parse the request into:
   - origin (see Location Resolution below)
   - category (see Category Resolution below)
   - preferences
   - constraints
   - avoid rules
2. Recall nearby candidates from a structured POI source (currently Amap-first with OSM fallback)
3. Expand the origin into nearby anchors (mall / road / station / area)
4. Generate multiple local search queries
5. Run unified-search over those queries and top POI candidates
6. Score evidence via auto-derived category hints (from CATEGORY_ALIASES)
7. Quality gate: assess bundle quality (poor/weak/acceptable); if evidence is weak, trigger specialty fallback
8. Specialty fallback: for cinema queries, supplement with Maoyan API city-level hall search (IMAX/4DX/CINITY/Dolby/LUXE/CGS)
9. Return:
   - top pick
   - backups
   - not recommended / weak-evidence notes
   - fallback area-level guidance if store-level evidence is weak

Category Resolution

• --category explicitly set by caller → used directly (for known categories like cafe, dessert)
• infer_category(query) matches a known category via regex rules → used
• Neither → _extract_fallback_keywords(query) strips noise words (我/附近/的/找/...) → raw keywords passed directly to Amap as pure keyword search (no typecode, no category normalization)
• No Grok/LLM involved — the agent should NOT translate queries to categories (e.g. don't convert "修理书包" to "皮具护理"). Just pass --query and let the fallback pipeline handle keyword extraction. Amap supports free-text keyword search without a category/typecode.

Location Resolution

• --origin explicitly set: used directly
• --corelocation flag: forces CoreLocationCLI (WiFi-based, ~500m accuracy) to get current coordinates
• No flag + query contains nearby hints (附近/周边/方圆): auto-tries CoreLocationCLI → IP geolocation fallback
• None of the above: "未指定起点"

Quick Start

Natural language mode

python3 scripts/planner.py \
  --query "福州大学旗山校区北门附近，地铁可达，适合坐着吃甜品，偏酸奶/gelato" \
  --format markdown

Explicit mode

python3 scripts/planner.py \
  --origin "福州大学旗山校区北门" \
  --category dessert \
  --preferences "yogurt,gelato,smoothie" \
  --constraints "metro,seating,environment,mall" \
  --avoid "night_market,takeaway_only,no_seating" \
  --format markdown

CoreLocation mode (auto-detect current position)

python3 scripts/planner.py \
  --query "附近有什么电影院支持4DX" \
  --corelocation \
  --format markdown

Output contract

The planner returns either:
- store-level recommendation when evidence is sufficient, or
- area-level fallback when exact shop hits are weak.

Confidence levels:
- high: repeated store-level hits with supporting evidence
- medium: usable candidates but some ambiguity
- low: fallback area recommendation only

Internal dependency

This skill uses the unified-search entrypoint here:

bash <unified-search>/scripts/unified-search.sh "<query>" --num 5 --topic general

Important — which path actually runs (verified 2026-05-31):
- The entrypoint is the new unified-search.sh, not unified-search-legacy.sh.
- For an ordinary query with no --legacy/--mode flag, the script routes to
run_search_layer_auto → deep search-layer with --source exa,tavily,grok,tinyfish.
So Grok + TinyFish are part of the real path; the legacy Tavily+Exa+Google merge is not used here.
- --num 5 --topic general are legacy-only flags. On the deep search-layer path they are
effectively ignored (not forwarded to search-layer), so they do not change behavior.
- When debugging latency/hangs, profile run-search-layer.sh → search.py (deep search-layer),
not unified-search-legacy.sh. The legacy script is a different code path.

Lessons / Pitfalls

See references/lessons-2026-05-31.md for hard-won debugging notes:
- Profiling the wrong unified-search path (legacy vs deep) wastes hours — always confirm the actual entry script first.
- Only Grok is usable for local Chinese queries; Tavily/TinyFish pollute ~87% of results; Exa often 402s.
- Grok needs proxies={http:None,https:None} (Surge proxy hangs enable_search) and a 1800s timeout for Chinese multi-agent queries.
- Transit detail rendering rules: same-segment buslines are alternatives (not sequential transfers); via_stops carries stop names; walking has full turn-by-turn; no max_parts truncation.
- Accessibility scoring/thresholds and the "shops are just geographically far from metro" reality.

Rules

• Planner execution time: The planner is silent during execution (3-10 minutes is normal).
  All output is buffered until completion — there is zero intermediate output even on
  stdout. MANDATORY: when running planner.py via exec, you MUST set timeout=1800
  (30 minutes). Do NOT use shorter timeouts (120s, 600s) — they will kill the process
  before unified-search completes. The planner runs these stages sequentially: POI search
  → web enrichment (up to 5 POIs, 30-90s each) → anchor expansion → unified-search
  queries (up to 3, 30-90s each) → decision → transit details. 5 POIs × 90s ≈ 7.5 min
  for web enrichment alone; the full pipeline can exceed 10 minutes. Do NOT kill the
  process because you see "no output yet." If the planner actually hangs, it's more
  likely in the unified-search network calls than in local Python code.

• Prefer one final recommendation workflow, not fragmented sub-skills

• If exact local store evidence is weak, do not hallucinate shop names
• Fallback to area / mall / anchor recommendation with explicit uncertainty
• Use concise decision output:
• 首选
• 备选
• 不推荐 / 风险点
• 下一步
• Web search: ALL external web enrichment MUST go through unified-search.sh.
  Do NOT DIY via DuckDuckGo Lite, curl to Baidu/Sogou/360, requests scraping, or ad-hoc
  HTTP calls. These are unreliable (empty results, anti-bot blocking, wrong encoding) and
  waste time. Only unified-search.sh (especially with Grok) works for Chinese local queries.
  The Tavily research script is a secondary option for deep-dive topics, but for POI
  enrichment always prefer unified-search.

• For cinema/venue features that POI APIs don't expose (e.g. 4D/IMAX/Dolby screen types),
  the skill may supplement with structured venue APIs like Maoyan (m.maoyan.com city-level
  cinema list). See references/lessons-2026-06-01.md for Maoyan API notes.

• Quality gate: After unified-search completes, _assess_bundle_quality evaluates
  each candidate bundle (max_score ≤2 → poor, avg_score <10 → weak, else acceptable).
  If need_fallback=True, the pipeline automatically triggers _specialty_fallback_run
  (currently only cinema → Maoyan API) and inserts the fallback bundle at the front of
  the run list.

• CATEGORY_EVIDENCE_HINTS auto-derivation: _get_evidence_hints(category) first checks
  the curated CATEGORY_EVIDENCE_HINTS dict (dessert/cafe/tea/bakery/restaurant/电影院);
  if not found, it auto-generates hints from CATEGORY_ALIASES by collecting all aliases
  that map to the same canonical category. This means adding a new category only requires
  updating CATEGORY_ALIASES — no separate hints dict needed.

• CoreLocation: On macOS, the skill can auto-resolve current position via
  CoreLocationCLI (WiFi-based, ~500m accuracy). Requires brew install corelocationcli.
  Use --corelocation flag to force this, or rely on auto-detection when origin is
  unspecified and query contains nearby hints (附近/周边/方圆). CoreLocationCLI may
  trigger a macOS location permission popup on first use.
  See scripts/macos_location.py for the implementation.

Suggested trigger examples

• “帮我找附近适合约会的甜品店”
• “从 XX 出发，找地铁可达、能坐着聊天的咖啡馆”
• “附近有没有适合带女朋友去的 mall 里甜品店”
• “规划一个商场内、清爽口味优先的甜品点”