ClawHub

Local Poi Planner

Other

Recommend nearby dining, dessert, cafe, mall, or date spots based on user location, access, preferences, and constraints with fallback to area-level guidance.

Install

openclaw skills install local-poi-planner

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