高德 AI 路书

GitHub 仓库预览效果： zuo-wentao/Amap-Roadbook-Skill

根据用户的自然语言旅行计划，生成一份可执行的地图路书。路书应结合高德 API、路线规划、天气信息、每日时间线和可用于地图渲染的结构化数据。

亮点：

• 在线预览：生成可分享的网站页面，用户打开链接即可查看完整地图路书。
• 实时编辑：修改行程后复用同一个 publishId 覆盖更新，让预览链接保持不变。
• Excel 计划表：主动生成并返回 .xlsx 下载地址，方便同行人查看、打印或二次编辑。
• 交互地图：基于高德 JS API 展示停靠点、路线和每日时间线。
• 路线兜底：优先使用真实线路，查不到路线时自动使用直线兜底。

核心规则

在生成路书前，必须确认最低规划信息是否齐全。如果关键信息缺失，先提出简洁的澄清问题并停止，不要编造日期、出发地、目的地或必去地点。

最低必需信息：

• 出发城市或出发地点。
• 目的城市或旅行区域。
• 出行日期、开始日期或旅行天数。
• 至少一个必去地点、目的地列表或兴趣偏好。

强烈建议确认的信息：

• 住宿地址、酒店名称或偏好的住宿区域。
• 城际交通偏好：高铁、飞机、自驾或都可以。
• 市内交通偏好：公共交通、打车、步行、自驾或都可以。
• 每日节奏：轻松、均衡或紧凑。
• 旅行限制：老人、小孩、行李、无障碍需求、预算限制等。

每次最多问 3-5 个问题。优先询问能让第一版路书成立的最少问题。

完整反问策略见 references/clarification-policy.md。

Key 配置

用户需要配置自己的高德 Key。不要把作者的 Key 写死进 skill、脚本或示例输出。

• AMAP_WEB_SERVICE_KEY：高德 Web Service API Key，用于地理编码、POI 搜索、路径规划、天气等服务。
• AMAP_JS_API_KEY：高德 JavaScript API Key，用于交互式地图渲染。
• AMAP_JS_SECURITY_CODE：高德 JavaScript API 安全密钥，用于前端地图渲染。

配置方式（按优先级）

脚本 scripts/plan-roadbook.mjs 中的 resolveKey() 按以下优先级读取 Key：

1. Shell 环境变量（最高优先级）
2. ~/.openclaw/openclaw.json 中的 skills.entries.amap-roadbook.env.\x3CKEY_NAME>

⚠️ 注意：脚本读取的是 ~/.openclaw/openclaw.json，不是 gateway.json。如果你在 gateway 配置配了 Key，需要同步写到 openclaw.json 的对应位置，否则脚本拿不到。

方式 1：在 openclaw.json 中配置（推荐）

{
  skills: {
    entries: {
      "amap-roadbook": {
        enabled: true,
        env: {
          AMAP_WEB_SERVICE_KEY: "YOU_AMAP_WEB_SERVICE_KEY",
          AMAP_JS_API_KEY: "YOUR_AMAP_JS_API_KEY",
          AMAP_JS_SECURITY_CODE: "YOUR_AMAP_JS_SECURITY_CODE"
        }
      }
    }
  }
}

不建议只配置 apiKey 便捷字段；本 skill 需要同时读取三个环境变量。

如果你是本地开发、并且需要让 OpenClaw 扫描额外目录，再单独加：

{
  skills: {
    load: {
      extraDirs: [
        "/path/to/amap-roadbook/parent-dir"
      ]
    }
  }
}

方式 2：Shell 环境变量（本地测试用）

export AMAP_WEB_SERVICE_KEY="你的高德 Web Service Key"
export AMAP_JS_API_KEY="你的高德 JS API Key"
export AMAP_JS_SECURITY_CODE="你的高德 JS 安全密钥"

验证 Key 配置

运行脚本时，第一行日志会打印 Key 状态：

🔑  Key 状态：WEB=✅  JS=✅  SECCODE=✅

如果某个 Key 为 ❌，对应字段会有详细提示（配置文件路径、缺失字段名、解析错误等）。也可以直接运行路书生成验证：

cd /path/to/amap-roadbook
node scripts/plan-roadbook.mjs --input input/sample.json --output-dir /tmp/check

高德 Key 申请地址

• 高德开放平台：https://lbs.amap.com/
• 控制台 → 应用管理 → 我的应用 → 创建新应用
• Web Service Key：平台选「Web 服务」
• JS API Key：平台选「Web 端(JSAPI)」，启用安全密钥并设置域名白名单

工作流程

1. 将用户输入解析为旅行需求草稿。
2. 检查最低必需信息是否齐全。
3. 如果信息缺失，提出澄清问题并停止。
4. 如果信息齐全，构造结构化路书请求。
5. 先用高德 API 解析地点，再规划路线。
6. 按天生成有序停靠点和交通路段。
7. 返回简洁说明和可用于地图渲染的 JSON。
8. 信息齐全并需要生成产物时，默认使用 scripts/plan-roadbook.mjs --publish --excel 发布到公网静态目录。
9. 如果用户明确说“不发布”“仅本地生成”或类似要求，才输出到本地 output/。
10. 如果用户在同一会话要求修改已发布路书，复用上一次 publishId 覆盖同一发布目录，让链接保持不变。

公网发布

默认发布配置：

• 本地暂存目录：output/\x3CpublishId>/
• 上传接口：http://120.46.7.129:30002/publish
• 服务器保存目录：/opt/openclaw-publish/\x3CpublishId>/
• 公网地址：http://120.46.7.129:30001
• HTML 页面：http://120.46.7.129:30001/\x3CpublishId>/
• Excel 下载：http://120.46.7.129:30001/\x3CpublishId>/roadbook.xlsx

默认生成并发布：

node scripts/plan-roadbook.mjs --input input/roadbook-input.json --publish --excel

会话内修改已有发布结果时，使用上一次的 publishId：

node scripts/plan-roadbook.mjs --input input/roadbook-input.json --publish --publish-id \x3CpreviousPublishId> --excel

发布模式会生成：

output/\x3CpublishId>/
  index.html
  roadbook.json
  roadbook.xlsx

然后通过 Node 上传服务写入服务器：

POST http://120.46.7.129:30002/publish

Nginx 只负责静态访问；上传服务只接收 index.html、roadbook.json、roadbook.xlsx 并保存到 /opt/openclaw-publish/\x3CpublishId>/。

发布客户端需要配置：

• ROADBOOK_PUBLISH_TOKEN：必填，上传服务鉴权 token。
• ROADBOOK_PUBLISH_ENDPOINT：可选，默认 http://120.46.7.129:30002/publish。

服务端运行 scripts/publish-server.mjs，需要配置：

• ROADBOOK_PUBLISH_TOKEN：可选，必须和客户端一致（默认无需 token）。
• ROADBOOK_PUBLISH_PORT：默认 30002。
• ROADBOOK_PUBLISH_ROOT：默认 .（当前目录）。
• ROADBOOK_PUBLIC_BASE_URL：默认 http://120.46.7.129:30001。

发布后必须主动在回答中返回可打开/可下载的产物地址，不要只说“已生成”：

• publishId
• 网站页面访问链接（HTML）
• Excel 下载链接（XLSX）
• 远程服务器目录路径
• JSON/HTML/XLSX 文件路径

如果脚本生成了 roadbook.html、index.html 或 roadbook.xlsx，回答里必须明确列出对应地址或文件路径；如果某个产物生成失败，必须直接说明失败原因或缺失项。

必须提醒用户：发布链接公网可访问，可能包含出行日期、住宿区域、同行人和预算等信息，只分享给可信对象。用户明确要求不发布时，使用本地模式。

Excel 路书

运行脚本时加 --excel 可额外生成格式化的 .xlsx 表格：

node scripts/plan-roadbook.mjs --input input/roadbook-input.json --publish --excel

生成的 roadbook.xlsx 包含 5 个 Sheet：

也可以单独运行导出脚本：

node scripts/export-excel.mjs --input output/roadbook.json --output output/roadbook.xlsx

本地模式

只有当用户明确要求“不发布”或“仅本地生成”时，使用本地模式：

node scripts/plan-roadbook.mjs --input input/roadbook-input.json --output-dir output --excel

本地模式会生成 roadbook.html、roadbook.json 和可选的 roadbook.xlsx，不会返回公网链接。回答中仍然必须主动返回本地 HTML 和 XLSX 文件路径，方便用户直接打开或下载。

高德 API 使用原则

以下事实应优先来自高德 API：

• 地理编码：解析城市、酒店、车站、机场、景点和地址。
• 输入提示和关键字搜索：消解模糊地点名。
• 路径规划：估算路段耗时，并选择市内交通方式。
• 天气查询：添加每日天气提醒和风险提示。
• 行政区划查询：规范城市、区县和 adcode。
• 静态地图或 JavaScript 地图：后续用于生成可分享的地图路书。

不要编造高德 API 不覆盖的实时事实。酒店价格、景区门票、机票价格、火车票价格、班次和营业时间，除非有可靠来源，否则必须标注为"需另行确认""用户提供"或"估算"。

API 选择细节见 references/amap-api-map.md。

输出协议

输出应包含：

• 对已理解行程的简短确认。
• 明确列出假设。
• 每日时间线：时间、地点、推荐活动和备注。
• 路线路段：起点、终点、交通方式、耗时、距离和换乘说明。
• 天气提醒和时间风险。
• 遵循 references/roadbook-schema.md 的地图可渲染 JSON。
• 如果生成了公网产物，必须主动附上网站页面链接、Excel 下载链接、publishId 和服务器路径。
• 如果生成了本地产物，必须主动附上本地 HTML、JSON 和 XLSX 文件路径。
• 不要省略网站和 xlsx 地址；只要文件存在，就必须在最终回答中列出来。

输出风格

回答要像一个实用的旅行执行助理，不要像营销文案。好的结果应该说明：

• 哪些信息已经确认。
• 哪些信息是默认假设。
• 每天的简明安排。
• 哪些地方存在时间过紧、换乘过多、天气风险或信息缺失。

本地产物

当前 skill 默认生成公网可访问的 JSON/HTML/Excel 产物。只有用户明确要求不发布时，才生成本地 JSON/HTML/Excel 产物用于演示。除非用户明确要求做页面渲染，否则不要把精力放在网页细节实现上。

反问示例

用户："我明天去北京，想去圆明园、大兴机场和迪士尼，玩三天。"

应反问：

"我可以把它做成高德路书。生成前先确认 4 个信息：1. 你从哪里出发？2. 北京住宿已经确定了吗，还是需要我推荐住宿区域？3. 城际交通偏好是高铁、飞机，还是都可以？4. 每天希望轻松一点还是尽量多打卡？"

信息充分示例

用户："使用 $amap-roadbook。我 6 月 15 日从合肥出发去北京玩 4 天，偏好高铁，住海淀附近，想轻松安排圆明园、北京环球度假区、大兴机场和半天咖啡/书店。"

此时可以继续构造路书请求，并生成结构化路书结果或本地产物。