Poi Clean

Plan nearby places for dining, desserts, cafes, malls, and date spots using one local POI planning workflow. Best for queries like “附近有什么适合坐着聊天的咖啡店”, “帮我找地铁可...

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