Back to Details

seoul-subway-arrival

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Seoul Subway Arrival

首尔地铁到站查询

What this skill does

该技能的功能

서울 열린데이터 광장의 실시간 지하철 도착정보 Open API로 역 기준 도착 예정 열차 정보를 요약한다.
通过首尔开放数据广场的实时地铁到站信息Open API，汇总以站点为基准的预计到站列车信息。

When to use

使用场景

  • "강남역 지금 몇 분 뒤 도착해?"
  • "서울역 1호선 도착 정보 보여줘"
  • "잠실역 곧 들어오는 열차 정리해줘"
  • "江南站现在列车还有几分钟到站？"
  • "给我看下首尔站1号线的到站信息"
  • "整理下蚕室站马上要进站的列车"

Prerequisites

前置条件

  • 서울 열린데이터 광장 API key
  • sops
    and 
    age
    installed
  • common setup reviewed in 
    ../k-skill-setup/SKILL.md
  • secret policy reviewed in 
    ../docs/security-and-secrets.md
  • optional: 
    jq
  • 首尔开放数据广场API key
  • sops
    和 
    age
    已安装
  • 已查看 
    ../k-skill-setup/SKILL.md
    中的通用设置说明
  • 已查看 
    ../docs/security-and-secrets.md
    中的密钥策略
  • 可选：
    jq

Required secrets

所需密钥

  • SEOUL_OPEN_API_KEY
  • SEOUL_OPEN_API_KEY

Inputs

输入参数

  • 역명
  • 선택 사항: 가져올 건수
  • 站名
  • 可选：获取的信息条数

Workflow

工作流程

1. Stop for secure registration when the API key is missing

1. 缺少API密钥时终止流程，引导用户完成安全配置

평문 key를 붙여 넣지 않는다.
SEOUL_OPEN_API_KEY
, 
~/.config/k-skill/secrets.env
, 
~/.config/k-skill/age/keys.txt
중 하나라도 없으면 다음 식으로 안내하고 멈춘다.
text
이 작업에는 SEOUL_OPEN_API_KEY 가 필요합니다.
값을 채팅창에 붙여 넣지 말고 ~/.config/k-skill/secrets.env.plain 에 직접 채운 뒤
sops 로 ~/.config/k-skill/secrets.env 로 암호화해 주세요.
암호화가 끝나면 plaintext 파일은 지우고 bash scripts/check-setup.sh 로 다시 확인해 주세요.
시크릿이 없다는 이유로 비공식 미러 API나 다른 출처로 자동 우회하지 않는다.
bash
SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" 'test -n "$SEOUL_OPEN_API_KEY"'
不要粘贴明文key。
如果 
SEOUL_OPEN_API_KEY
、
~/.config/k-skill/secrets.env
、
~/.config/k-skill/age/keys.txt
中任意一项缺失，就按照如下提示告知用户并终止流程：
text
该操作需要SEOUL_OPEN_API_KEY。
请不要将值粘贴到聊天窗口，而是直接填写到 ~/.config/k-skill/secrets.env.plain 中，
然后使用sops加密为 ~/.config/k-skill/secrets.env。
加密完成后请删除明文文件，并运行 bash scripts/check-setup.sh 重新检查配置。
不得因为缺少密钥自动跳转到非官方镜像API或其他数据源。
bash
SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" 'test -n "$SEOUL_OPEN_API_KEY"'

2. Query the official station arrival endpoint

2. 调用官方站点到站接口查询

서울 실시간 지하철 API는 역명 기준 실시간 도착 정보를 JSON/XML로 제공한다. 기본 질의 예시는 다음 패턴을 쓴다.
bash
SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" \
  'curl -s "http://swopenAPI.seoul.go.kr/api/subway/${SEOUL_OPEN_API_KEY}/json/realtimeStationArrival/0/8/강남"'
首尔地铁实时API以站名为基准提供JSON/XML格式的实时到站信息。基础查询示例遵循如下模式：
bash
SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" \
  'curl -s "http://swopenAPI.seoul.go.kr/api/subway/${SEOUL_OPEN_API_KEY}/json/realtimeStationArrival/0/8/강남"'

3. Summarize the response

3. 汇总返回结果

가능하면 아래 항목만 먼저 요약한다.
  • 호선
  • 상/하행 또는 외/내선
  • 첫 번째 도착 메시지
  • 두 번째 도착 메시지
  • 도착 예정 시간(있으면 초 단위)
尽可能优先只汇总以下字段：
  • 线路号
  • 上/下行或外/内线
  • 第一趟列车到站提示
  • 第二趟列车到站提示
  • 预计到站时间（如有则以秒为单位）

4. Be conservative about live data

4. 谨慎处理实时数据

실시간 데이터는 몇 초 단위로 바뀔 수 있으므로, 답변에는 조회 시점을 같이 적는다.
实时数据可能每几秒就会更新，因此回答中需要同时标注查询时间点。

Done when

完成条件

  • 요청 역의 도착 예정 열차가 정리되어 있다
  • live data 기준 시점이 명시되어 있다
  • key가 노출되지 않았다
  • 已整理好所查询站点的预计到站列车信息
  • 已明确标注实时数据的查询时间点
  • 未泄露密钥

Failure modes

失败场景

  • API key 미설정
  • quota 초과
  • 역명 표기 불일치
  • 未配置API key
  • 调用配额超出上限
  • 站名拼写不匹配

Notes

注意事项

  • 서울 열린데이터 광장 가이드는 실시간 지하철 Open API에 일일 호출 제한이 있을 수 있다고 안내한다
  • endpoint path는 API 버전 변경 가능성이 있으므로 실패 시 dataset console의 최신 샘플 URL을 다시 확인한다
  • 首尔开放数据广场指南说明实时地铁Open API可能存在每日调用次数限制
  • 接口路径可能随API版本更新发生变化，调用失败时请重新查看数据集控制台的最新示例URL