ROS智能排线(体验版)
上传订单/车辆 Excel，一键出路线结果 Excel + 可视化地图。本 skill 是「体验版」：用小批量真实数据试跑看效果，不承载日常业务量；不提供地址解析，坐标需由 Excel 自带。
使用限制
| 项目 | 上限 |
|---|---|
| 订单 | 30 单/次 |
| 车辆 | 3 台/次（按「车辆数量」展开后计） |
| 调用次数 | 10 次/天/公网 IP（次日恢复；本地校验失败不消耗次数） |
超限会被平台直接拒绝且不做自动分批，需自行拆分 Excel 分批调用（各批独立出结果）。
3 分钟上手
第 1 步：本 skill 不预置 Excel 模板文件（SkillHub 平台禁止 skill 包内包含 .xlsx）。需要模板时直接说"给我模板"，我会运行 skill 自带的 scripts/make_template.py 在本地生成一份标准模板 订单车辆模板(示例).xlsx（含「订单」「车辆」「填写说明」三 sheet，全中文表头、带示例行与填写说明），生成后直接发给你。也可直接按下方列名在自己的 Excel 里填写（订单 / 车辆 可同文件两 sheet，也可分开）。
第 2 步：订单 sheet 填一行（坐标必须自带，标清来源）：
| 订单编号 | 任务编号 | 任务类型 | 客户名称 | 地址 | 纬度 | 经度 | 服务时长 | 时间窗开始 | 时间窗结束 | 数量1 | 数量2 | 坐标来源 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| WO2026102300001 | WO2026102300001 | D | 上海虹桥南丰城店 | 上海市长宁区遵义路150号 | 31.208732 | 121.407049 | 00:15:00 | 08:00:00 | 12:00:00 | 1000 | 1 | 高德 |
第 3 步：车辆 sheet 填一行：
| 车辆编号 | 车辆名称 | 起点纬度 | 起点经度 | 容量1 | 容量2 | 开始时间 | 结束时间 | 速度系数 | 车辆数量 |
|---|---|---|---|---|---|---|---|---|---|
| 沪A12345 | 4.2米厢车 | 31.230416 | 121.473701 | 2000 | 2 | 06:00:00 | 20:00:00 | 0.7 | 1 |
> 车辆不必填「坐标来源」——默认沿用订单的来源。多台同车型想一次投入 N 台，把「车辆数量」填 N。
> 速度系数按路况填：白天 0.6~0.7、凌晨/夜间路况好 0.9~1、雨雪天气 0.5。
第 4 步：直接把文件丢给 WorkBuddy，说一句「用这个文件跑排线」。
第 5 步：约 10~30 秒拿到两样东西——
- ROS优化结果_时间戳.xlsx：概览 + 路线明细 + 未分配
- ROS路线地图_*.html（有高德 key）或 ROS路线示意图_*.html（无 key）
想一次多看几单：订单加到 ≤30 行、车型总台数 ≤3 台即可（体验版每日 10 次/公网 IP）。
> 数据安全说明：订单里的「客户名称」「地址」仅用于本地结果展示（地图标注、结果 Excel），不会发送给算法。提交给上游的报文中这两项一律为空；算法求解只需坐标、数量、时间窗与标签。因此可放心填写真实客户名称与地址以便核对，无需担心数据外泄。
没有标准模板 / 列名对不上？
skill 已内置大量中英文列名同义词（如 门店编码→订单编号、车牌→车辆编号、收货地址→地址、件数→数量1、车型→车型、台数→车辆数量…），所以很多业务系统导出的 Excel 直接就能跑，无需任何改动。
若仍认不出必填列，pipeline 不会逐行报错，而是输出一段 MAPPING_NEEDED 结构化信息（含检测到的全部表头 + 缺失字段含义），由 WorkBuddy 引导你做一次性列映射：
- 我会把缺失字段（如「订单编号」「纬度」「经度」）列出，并给出你文件里实际存在的列名供你选择对应；
- 映射结果写成
vrp_colmap.json（与 Excel 同目录即可，或--colmap指定）； - 重跑同一条命令，自动套用映射出结果。
映射文件示例（只写你文件里真实存在的列名）：
{
"orders": { "id": "门店编码", "latitude": "纬度", "longitude": "经度",
"serviceDuration": "停留时长", "startTime1": "最早送达", "endTime1": "最晚送达",
"quantity1": "件数" },
"vehicles": { "vehicleId": "车牌", "startLatitude": "仓纬度", "startLongitude": "仓经度",
"capacity1": "载量", "startTime": "出车", "endTime": "收车",
"speed": "速度系数", "numberOfVehicles": "台数" },
"orders_defaults": { "coordinateSource": "高德" }
}
> 字段含义对照见 references/dev_guide.md；orders_defaults / vehicles_defaults 用于"你文件里压根没有这一列"时的兜底（如没有坐标来源，默认按高德处理）。
> 进阶（一站式）：vrp_colmap.json 还能写 orders_sheet / vehicles_sheet 直接指定非标准 sheet 名（与 Excel 同目录时全自动生效，连 --orders-sheet 都不用传）；vehicleName（车辆名称）为可选字段，缺省自动用车牌号兜底——所以「只有车牌、没有车辆名称」的车辆表也能直接跑。
三个最常见的填错
| 现象 | 原因 | 修正 |
|---|---|---|
| 点位全偏到海里/邻省 | 百度坐标标成了「高德」 | 坐标来源必须与实际一致；百度坐标会自动换算 |
| 报「订单缺坐标」 | 只填了地址没填经纬度 | 本 skill 不做地址解析，必须自带坐标 |
| 报「订单编号重复」 | 复制行没改编号 | 编号必须唯一 |
运行与输出（agent 执行手册）
算法地址与密钥已内置（config.json），无需向用户索要任何 key、API 地址或账号：
python "scripts/ros_vrp_pipeline.py" --file "<Excel绝对路径>" --output "<结果目录>"
- 订单/车辆可同文件两 sheet（
--file，推荐），也可分开（--orders/--vehicles）。 - 常用参数：
--dry-run（只校验+生成报文，不调算法）、--no-map（不出地图）、--amap-key（用户自备高德 key 出真实地图）。完整参数见references/dev_guide.md。 - 非标准格式：缺必填列时脚本退出码 3 并输出
MAPPING_NEEDED；用--colmap <json>（或与 Excel 同目录的vrp_colmap.json）把内部字段映射到你的真实列名后重跑；sheet 不叫「订单/车辆」时，可在 colmap 里写orders_sheet/vehicles_sheet一站式指定（或分别用--orders-sheet/--vehicles-sheet）。详见上文「没有标准模板 / 列名对不上？」。 - 脚本先校验 Excel，一次列出全部问题再退出；校验失败不消耗调用次数。完整字段表与校验规则见
references/dev_guide.md。 - 输出：
RESULT_JSON: {...}（看status/routes/assigned/unassigned）+ 结果 Excel（概览/路线明细/未分配）+ 地图 HTML；同目录另存vrp_request_*.json/vrp_response_*.json供排查。 - 地图：有高德 key 出真实底图，无 key 自动降级为示意图（零外部依赖）；地图版必须本地双击打开（file://），从 preview 面板打开会因域名白名单白屏；示意图版无此限制。
- 汇报：present_files 先结果 Excel、再地图 HTML；口头报 status/路线数/已分配/未分配；未分配列订单号及可能原因。
- 环境要求：Python 3.9+、
pip install openpyxl requests；Windows 下python无输出等环境坑见references/dev_guide.md。
常见问题
| 现象 | 处理 |
|---|---|
| 返回「错误的apikey」/ 鉴权失败 | 内置访问密钥可能已停用（版本迭代/迁移），请更新到 skill 最新版本 |
| 订单缺坐标 | 本 skill 不做地址解析，请在「纬度」/「经度」列补齐 |
| 「坐标来源」为空或非法 | 每行填 高德 或 百度（坐标从哪家地图取的就填哪家） |
LIMIT_EXCEEDED: 单次 stop 数量超限 |
超 30 单/3 车上限，拆分 Excel 分批调用 |
PROXY_ALGO_ERROR: 算法服务器 HTTP 400 |
报文结构不对；本 skill 已内置正确格式，报文细节见 references/api_protocol.md |
更多文档
scripts/make_template.py— 标准模板生成脚本。运行python scripts/make_template.py [输出路径.xlsx]会在本地生成「订单车辆模板(示例).xlsx」（订单 / 车辆 / 填写说明 三 sheet，全中文表头）。因 SkillHub 禁止包内带 .xlsx，模板改为本地生成而非预置文件。references/dev_guide.md— 完整字段表、校验规则、报文格式、运行参数、环境细节、自测验收references/api_protocol.md— 算法报文逐字段说明（唯一格式）scripts/selftest.py— 自测脚本（离线回归 12 例 + 可选真实联调）
