地图选址与出行规划（trae-map-planner）

用高德开放平台 REST 接口做真实的 POI 检索与路线计算，回答「去哪家店最方便」「哪两家店可以顺路一起逛」。

何时使用

不适用：需要实时公交到站、室内导航、订座、外卖下单等场景。

前置条件

1. Node.js ≥ 18（脚本用内置 fetch 与 ESM）。优先使用 PATH 中的 node，不要假设安装在某个固定路径。
   - 验证：node --version
2. 自备高德 Key（每个使用者都要自己申请，不能共用他人的）
   - 入口：<https://lbs.amap.com/> → 控制台 → 应用管理 → 创建应用 → 添加 Key
   - 服务平台必须选「Web服务」（不是「Web端(JS API)」，也不是「Android/iOS」）
   - 拿到形如 32 位十六进制的 Key 后，写入环境变量 AMAP_KEY：
   • Windows PowerShell（当前会话）：$env:AMAP_KEY="你的Key"
   • Windows 永久（新终端生效）：setx AMAP_KEY "你的Key"
   • macOS / Linux：export AMAP_KEY="你的Key"（可写入 ~/.zshrc 或 ~/.bashrc）
   • 未设置时脚本会直接报错退出，并提示 provider=amap 需要密钥：请先设置环境变量 AMAP_KEY。

> 安全：Key 只从环境变量读取，不会写入包内任何文件，也不会出现在输出里（报错信息会脱敏为 ***KEY***）。

硬性规则（不可违反）

1. 出发地必须每次由用户显式提供，--origin 无任何默认值；缺失时脚本直接报错退出（退出码 1）。禁止擅自替用户填一个「常用出发地」，也不要拿上一次的缓存值当出发地。
2. 默认出行方式为地铁/公交（transit）。不得擅自改成骑行或驾车；只有用户明确要求时才用 --mode walking|riding|driving。
3. 直线距离 ≤ 1 公里一律优先步行（--walk-first-m，默认 1000）。该段只算步行，不与骑行/公交/地铁比较，也不会因为骑行耗时显示更短而改选骑行。
4. 候选排序一律用真实路线耗时，不得用直线距离代替耗时排序。直线距离只用于「粗筛/决定先算谁」，最终名次必须由接口返回的 duration 决定。未计算耗时的候选必须单独标注，禁止与已计算候选混排。

城市范围：默认就近本市，跨城要显式开启

默认行为（不加 --cross-city）：就近在本市搜索。

• 先解析出发地/起点地址，取接口返回的 city 字段识别所在城市（全国通用，不绑定任何城市）。
• POI 检索 city=<该城市> 且 citylimit=true，所有候选门店都在出发地城市内；公交规划 city、cityd 一律用出发地城市。
• 若 --city 指定的城市与出发地城市不同，工具直接报错并提示加 --cross-city，不会静默跨城。
• 输出会打印 识别城市: 上海市（按出发地自动识别） | 起点城市: 上海市 | 跨城: 关闭（就近本市），方便核对。

跨城（显式开启 --cross-city）：

• 起点、终点城市各自识别，transit 的 city（起点城市）与 cityd（终点城市）分别传，上海 → 苏州这类场景可以正常算。
• 典型用法：从上海出发、但想检索苏州的门店 → --city "苏州市" --cross-city。
• find-place 的 single / multi 模式本身是「就近找店」，跨城只在 --city 指向异地城市时才有意义；开了但城市相同会提示"按同城就近处理"。

其他约定：

• 想强制指定城市传 --city "杭州市"（城市名或 adcode），显式值优先于自动识别。
• 识别失败或地址模糊时不会静默猜一个，会列出候选城市并提示用 --city 指定。
• 百度通道（--provider baidu）的地理编码不返回城市字段，只能按地址文本推断，跨城建议显式传 --city。

用法

以下命令在 skill 目录下执行（scripts/ 与 SKILL.md 同级）。

模式一：单品牌选店

node scripts/find-place.mjs --mode single \
  --origin "上海市徐汇区云锦路277号" \
  --brand "成都你六姐"

输出：该品牌全量门店中直线最近的 N 家，逐一评估方案，再按真实总耗时升序给出 Top 3。1 公里内的门店会标注「（1公里内步行优先）」。

换个城市只需换 --origin，城市会自动识别（同城就近检索；跨城需加 --cross-city）：

node scripts/find-place.mjs --mode single \
  --origin "浙江省杭州市西湖区文三路100号" --city "杭州市" \
  --brand "成都你六姐" --top-n 2

需要跨城（例如从上海出发但检索苏州的门店）时，显式开启并指定城市：

node scripts/find-place.mjs --mode single \
  --origin "上海市徐汇区云锦路277号" --city "苏州市" --cross-city \
  --brand "成都你六姐" --top-n 2

模式二：多品牌同址

node scripts/find-place.mjs --mode multi \
  --origin "上海市徐汇区云锦路277号" \
  --brands "小满手工粉,成都你六姐"

输出：跨品牌门店间距 ≤ --pair-max-m（默认 300 米）的组合，先按 --scan-km（默认 15 公里）做宽松初筛，再逐组计算真实耗时，按耗时升序输出；超出 --candidates 预算未算的组合会明确标注「未计算」，不与已算组合混排。

品牌组合闭环行程（起点 → A → B → 起点）

node scripts/route-planner.mjs --origin "上海市徐汇区云锦路277号" \
  --brand-a "小满手工粉" --brand-b "成都你六姐" \
  --max-walk-min 20 --top-n 5

先 --dry-run 估算本次要发多少请求，再正式跑。

常用参数

find-place.mjs：

route-planner.mjs：

配额与缓存

• 所有请求严格串行，最小间隔 1 秒，单次运行有上限（--max-requests）；超限会停止并明确提示，不会静默失败。
• 响应缓存在 scripts/cache.json（首次运行自动创建，纯响应体、不含 Key）。重复查询同一出发地/目的地/方式时直接命中缓存，0 请求。
• 建议日常工作值：--candidates 10 --max-requests 45；想一次拿全量结论用 --candidates all --max-requests 120。

常见问题