上海公交实时信息
实时到站与发车时刻来自上海市公共数据开放平台"公交实时信息"官方接口；地名转坐标、线路方向和全程站点来自高德 Web 服务。汇报结果时明确区分数据来源。
选择脚本
scripts/query_nearby.mjs：按坐标或地名查询附近公交、实时到站和发车信息。scripts/query_line.mjs：按线路名查方向与全程站点，或按站名查途经线路。- 用户同时问"某线路到哪了"和"还有几站"时，用
query_nearby.mjs --with-route合并实时与线路信息。
已有经纬度且只查实时数据时，仅需 SH_DATA_TOKEN。使用 --place、--with-route 或 query_line.mjs 时，还需 AMAP_KEY。
配置凭据
SH_DATA_TOKEN
官方获取路径：
- 打开上海市公共数据开放平台，登录或注册账号。
- 自然人完成实名认证；机构用户完成相应认证。
- 进入「个人中心 → 基本信息 → 个人资料」，复制页面中的用户 token。
- token 过期时，在同一页面点击「更新 token」后重新配置。
export SH_DATA_TOKEN='你的上海市公共数据开放平台 token'
AMAP_KEY
官方获取路径：
- 登录高德开放平台控制台，按平台要求完成开发者认证。
- 进入「应用管理」，点击「创建新应用」。
- 打开应用，点击「添加 Key」。
- 服务平台选择「Web 服务」，创建后复制 Key。
export AMAP_KEY='你的高德 Web 服务 Key'
真实凭据只在本机配置，不写入技能文件、仓库或输出结果。
常用命令
# 坐标附近的实时公交；默认把坐标按 WGS-84 发送
node scripts/query_nearby.mjs --lon 121.455708 --lat 31.249574
# 高德、腾讯、微信定位通常是 GCJ-02，必须显式声明
node scripts/query_nearby.mjs --lon 121.4620 --lat 31.2540 --coord-type 2
# 按地名查询，需要 AMAP_KEY
node scripts/query_nearby.mjs --place 静安寺
# 限定线路并补充走向、全程站点和本站站序，需要两个凭据
node scripts/query_nearby.mjs --place 静安寺 --line 49路 --with-route
# 查询线路方向与全程站点，或查询某站的途经线路
node scripts/query_line.mjs --line 13路
node scripts/query_line.mjs --stop 静安寺
# 结构化输出
node scripts/query_nearby.mjs --place 静安寺 --format json
常用参数：
query_nearby.mjs：--radius、--coord-type、--line、--stop、--no-arrivals、--with-route、--expand-stop、--format json、--timeout。query_line.mjs：--line、--stop、--direction、--city、--refresh、--clear-cache、--format json。
运行约束
--place与--lon/--lat互斥。--place的高德坐标会自动按 GCJ-02 查询，不再传--coord-type。- 原始 GPS 或后端 WGS-84 坐标使用默认
--coord-type 1；高德、腾讯或微信坐标使用--coord-type 2。坐标系错误会返回错误地点附近的正常结果。 - 官方接口单次最多返回 50 条且无可用分页。要补齐某个同名站台的记录，可显式使用
--expand-stop <站名>；它会增加官方请求次数。 - 官方与高德接口都有频率和日配额限制。脚本已重试和缓存，但批量查询仍须串行，避免并发扫描。
--place会自动合并重合候选，并在近距离候选或唯一精确同名时自动选择；真正的异地歧义以退出码2返回候选，需用户确认后用--place-index重查。- 高德线路数据可能不收录定制线、通勤专线、墓园专线或新开线路。查不到静态线路不能据此断定官方实时线路不存在。
- 官方接口字段虽定义公交、地铁、轮渡，当前能力只承诺公交实时信息；不要承诺地铁或轮渡实时到站。
解读结果
- 向用户汇报时始终带线路方向或终点站，避免上下行混淆。
current是最近一辆，next是下一辆；arriveMinutes和stopCount使用官方返回值，不自行重算，也不替换成高德预测。arrivals为空不等于报错。结合schedule.message、schedule.codeText和快照时间，区分不在运营、等待发车、暂无实时数据。barrierFree可用于标注无障碍车辆；comfort=0表示未知，不展示为拥挤度结论。- 跨零点夜宵线可能出现首班时间晚于末班到站时间，按跨日运营解释。
--with-route中实时数据来自上海官方，地名、方向、站序和全程站点来自高德。
接口字段、错误码、缓存、站名匹配与方向对齐细节见 references/api.md，仅在核对字段或排查异常时读取。
