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#

bash

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

Explicit mode#

bash

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)#

bash

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

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 里甜品店”
• “规划一个商场内、清爽口味优先的甜品点”