ns-trains

NS Trains Skill 是一款专为荷兰铁路出行设计的智能查询工具，基于荷兰国家铁路公司（Nederlandse Spoorwegen）官方 API 构建，为用户提供实时、准确的火车时刻表查询和行程规划服务。

核心用法方面，该技能提供多种查询模式：通过 commute.mjs 脚本配合环境变量配置的上下班站点，可一键查询日常通勤路线；使用 journey.mjs 可规划任意两站之间的行程；departures.mjs 和 arrivals.mjs 分别用于查询指定车站的出发和到达信息；disruptions.mjs 则实时展示线路中断情况。所有功能均支持自然语言交互，用户可直接询问"下一班去阿姆斯特丹的火车"或"今天有列车延误吗"等问题。输出信息包含详细的出发/到达时间、实时延误、行程时长、换乘次数、站台号、中断警告以及拥挤度预测（以颜色标识）。

显著优点体现在多个维度：首先，数据直接源自 NS 官方 API，确保信息的权威性和实时性；其次，项目采用零依赖设计，仅使用 Node.js 内置 API，彻底规避了供应链攻击风险；安全架构上，代码实现了严格的 HTTPS 白名单机制，仅允许访问 gateway.apiportal.ns.nl 域名，拒绝所有非授权网络请求，且对 API 密钥实施严格的 Header 传输保护，绝不记录或输出敏感信息。此外，工具提供贴心的通勤快捷功能和拥挤度预测，显著提升日常出行效率。

潜在缺点与局限性主要包括：服务范围严格限定于荷兰境内铁路系统，无法查询国际列车或其他国家铁路信息；功能依赖用户自行申请 NS API 订阅密钥（免费额度 5000 次/天），增加了初次使用门槛；作为 T3 来源的社区项目，虽代码质量达到 A 级，但缺乏大型企业或基金会的长期维护背书。

适合的目标群体主要是在荷兰生活、工作或旅行的用户，特别是依赖火车通勤的上班族、需要频繁查询时刻表和延误信息的旅客，以及对出行时间敏感、希望提前了解车厢拥挤度的规划者。

使用风险方面，常规风险包括：对外部 NS API 服务可用性的依赖，若官方服务故障或变更接口可能影响功能；API 调用受限于每日 5000 次的免费额度，高频使用可能触发限制；网络环境要求稳定的互联网连接，离线状态下无法使用。安全层面虽经 A 级认证，但用户仍需妥善保管个人 API 密钥，避免通过不安全渠道泄露。

核心用法

ns-trains 是一款面向荷兰铁路（Nederlandse Spoorwegen, NS）乘客的 CLI 工具，封装了 NS 官方 Reisinformatie API 的完整功能集。用户通过环境变量 NS_SUBSCRIPTION_KEY 完成一次性鉴权后，即可调用六大脚本模块：

• commute.mjs – 配置 NS_HOME_STATION 与 NS_WORK_STATION 后，一键查询上下班行程；
• journey.mjs – 任意两站间的实时路线规划，输出含换乘次数、站台号、拥挤度预测（🟢/🟡/🔴）的完整方案；
• departures.mjs / arrivals.mjs – 查询指定站点的出发或到达时刻；
• stations.mjs – 模糊搜索站点名称，解决荷兰语拼写差异；
• disruptions.mjs – 查看全网或特定区间的运行中断与维护公告。

所有脚本均支持自然语言交互，典型指令如 "When is the next train to Amsterdam?" 可被自动解析。

显著优点

1. 官方数据源：直接对接 NS 官方 API，时刻表、延误、站台变更等信息实时同步，准确性与官方 App 同级。
2. 零第三方依赖：纯 Node.js 原生实现，无 npm 包依赖，极大降低供应链攻击面，依赖审计得分 100/100。
3. 安全架构：强制 HTTPS + TLS 1.2+、域名白名单校验、输入参数 encodeURIComponent 编码、密钥仅通过环境变量注入，静态与动态分析均获高分（98/96）。
4. 隐私合规：遵循 GDPR 数据最小化原则，不采集用户身份、不存储行程历史，仅读取公开交通数据。
5. 轻量高效：500 行代码、7 个文件，启动延迟低，适合集成至自动化工作流（如定时推送通勤提醒）。

潜在缺点或局限性

• 地理局限：仅覆盖荷兰境内 NS 运营线路，国际列车（如 Eurostar、Thalys）及邻国铁路（DB、SNCF）不支持。
• API 配额：免费订阅 5,000 次/天，高频用户（如每 5 分钟轮询）可能触及上限，需付费升级。
• 环境变量门槛：需手动注册 NS API Portal 并配置密钥，对非技术用户存在上手成本；密钥泄露风险由用户侧承担。
• 功能单一：无购票、座位预订、票价计算功能，仅提供信息查询。
• CLI 局限：无图形界面，移动端体验依赖终端 App 或自建封装。

适合人群

• 荷兰日常通勤者：需快速查询固定路线的延误与站台变更；
• 开发者/极客：希望将列车数据集成至个人自动化脚本、通知机器人或数据面板；
• 隐私敏感用户：不愿安装官方 App 或授予其过多权限，偏好最小权限的 CLI 工具；
• 技术运维团队：需监控特定线路运行状态，对接内部告警系统。

常规风险

• 密钥泄露：若用户误将 NS_SUBSCRIPTION_KEY 提交至代码仓库或日志，可能导致 API 配额被滥用；建议配合 .env 文件与 CI/CD Secret 管理。
• API 服务中断：NS 官方 API 维护或变更可能导致功能暂时不可用，需关注 status.ns.nl。
• 输入注入边界：虽然已对参数做 URL 编码，但极端长字符串或特殊 Unicode 字符仍可能触发非预期行为（概率极低）。
• 数据时效性：拥挤度预测与实时延误依赖 NS 数据推送，极端天气或突发事件下可能存在分钟级延迟。