首尔共享单车따릉이实时查询实战k-skill seoul-bike 技能的 CLI 命令与 k-skill-proxy 架构解析【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本指南围绕 k-skill 仓库中的seoul-bike技能展开讲解如何通过 k-skill CLI 单入口脚本经由k-skill-proxy代理服务器查询首尔共享单车따릉이的实时可借车辆数与空闲车桩数。读完本文你将掌握nearby、search、realtime三个子命令的完整用法、proxy 三个 HTTP 端点的调用方式以及从客户端脚本到代理服务器再到首尔开放数据平台的上游调用链与错误处理机制。技能定位做什么、何时用seoul-bike是 k-skill 技能集中的一个「查询类」技能功能定义见 skill.jsonprofiles为proxylookup。它通过首尔开放数据广场서울 열린데이터 광장的 따릉이 实时租赁信息接口汇总查询坐标周边或指定名称的租赁站当前「可借车辆数」和「空车桩数」。适合以下典型对话场景「现在这里能借到 따릉이 吗」「光化门附近有空车桩吗」「江南站 따릉이 租赁站还剩几辆车」注意该技能是纯查询用途不包含任何预约或租车自动化能力详见 instruction.md 的 Notes 章节。前置条件与环境变量运行环境只需 Python 3 标准库。查看入口脚本 seoul_bike.py 的导入列表仅使用了argparse、json、os、sys、urllib.error、urllib.parse、urllib.request、typing无任何第三方依赖可在任意 Python 3 环境直接运行。可选的KSKILL_PROXY_BASE_URL仅在使用自托管self-host或其他独立代理时设置留空则使用默认的 hosted 代理https://k-skill-proxy.nomadamas.org。源码中get_proxy_base_url()seoul_bike.py对取值做了归一化读取环境变量后先strip()若为空字符串或占位符replace-me则回退到默认值最终结果再去掉尾部/。测试用例test_proxy_base_url_defaults_to_hosted_proxytest_seoul_bike.py验证了在无环境变量时返回默认 hosted 代理地址。环境变量要求客户端零密钥本技能没有必填的环境变量。用户无需自行申请首尔开放数据广场的 OpenAPI key。/v1/seoul-bike/*三个路由默认由 hosted proxy 调用上游 keySEOUL_OPEN_API_KEY只保存在代理服务器端客户端全程接触不到明文密钥——这正是「key 不出客户端、只存代理」的架构设计具体策略参见 k-skill-proxy.md。单一入口命令技能统一通过 k-skill CLI 的exec子命令调用入口脚本npx -y nomadamas/k-skill0 exec seoul-bike scripts/seoul_bike.py -- subcommand [args]首次使用时Agent 只需批准一次Bash(python3 *seoul_bike.py:*)模式的执行权限此后对该脚本的调用都会自动放行。--之后的位置即传给seoul_bike.py的参数。main()入口通过argparse的add_subparsers(destcommand, requiredTrue)强制要求指定子命令seoul_bike.py缺省会直接报错退出。子命令一览命令说明nearby --lat LAT --lon LON [--radius-m 500] [--limit 10] [--json]查询指定坐标周边的实时租赁站search 关键词 [--limit 10] [--json]在实时数据中按租赁站名称包含的关键词检索realtime [--start-index 1 --end-index 1000]输出实时租赁信息原始 JSON 分页各子命令的完整参数含默认值如下表均来自 build_parser()子命令参数类型默认值说明nearby--latfloat必填基准纬度--lonfloat必填基准经度--radius-mint500搜索半径米--limitint10最多返回的站点数--jsonflag关以 JSON 输出原始 payloadsearchkeywordstr必填站点名称关键词--start-indexint1实时数据起始索引--end-indexint1000首页结束索引搜索会继续翻完全部分页--limitint10最多返回的匹配站点数--jsonflag关以 JSON 输出匹配结果realtime--start-indexint1起始索引--end-indexint1000结束索引实战工作流1. 查询当前位置周边租赁站npx -y nomadamas/k-skill0 exec seoul-bike scripts/seoul_bike.py -- nearby --lat 37.5717 --lon 126.9763 --radius-m 500输出为逐行摘要每个站点包含租赁站名称대여소명可借车辆数parkingBikeTotCnt空车桩数rackTotCnt - parkingBikeTotCnt距离米仅 nearby 返回查询时刻proxy.requested_at对应的格式化逻辑见format_nearby()与format_station()seoul_bike.py首行输出站点总数与基准坐标/半径随后逐站输出末尾附带查询时刻。若车辆数或车桩数为空则显示「알 수 없음」而不是报错。测试test_summarize_nearby_includes_bikes_docks_distance_and_timestamptest_seoul_bike.py验证了输出必须同时包含站点名、대여 가능 4대、빈 거치대 11개、距离0m与조회 시각时间戳。加--json时直接输出代理返回的完整 JSON含query、count、items、proxy元信息便于程序化消费npx -y nomadamas/k-skill0 exec seoul-bike scripts/seoul_bike.py -- nearby --lat 37.5717 --lon 126.9763 --radius-m 500 --limit 2 --json2. 按租赁站名称搜索npx -y nomadamas/k-skill0 exec seoul-bike scripts/seoul_bike.py -- search 광화문 --limit 5search的实现策略是先全量拉取、再本地过滤cmd_search()调用fetch_realtime_payload()从--start-index起按--end-index作为页大小循环翻页直到覆盖rentBikeStatus.list_total_count总数或拿到空页为止seoul_bike.py随后filter_realtime_rows()将关键词strip().lower()后对每个站点的名称做不区分大小写的包含匹配达到--limit即停止seoul_bike.py。测试test_search_fetches_all_realtime_pages_before_filteringtest_seoul_bike.py通过 mockfetch_json模拟两页数据验证了fetch_realtime_pages(1, 1)会把两页的行都收集回来且恰好调用两次接口。无匹配时向 stderr 输出「关键词와 일치하는 따릉이 대여소가 없습니다.」并返回退出码 1有匹配时按与 nearby 相同的格式输出并附带查询时刻。3. 直接查看实时原文 JSONnpx -y nomadamas/k-skill0 exec seoul-bike scripts/seoul_bike.py -- realtime --start-index 1 --end-index 1000该命令等价于直接请求代理的/v1/seoul-bike/realtime端点把上游bikeList的原始 JSON含rentBikeStatus.row明细原样打印适合排查数据问题或做自定义分析。底层调用链客户端 → k-skill-proxy → 首尔开放数据广场Proxy 三个端点端点上游数据集说明GET /v1/seoul-bike/realtime?startIndex1endIndex1000서울bikeList实时租赁信息原文GET /v1/seoul-bike/stations?startIndex1endIndex1000서울tbCycleStationInfo租赁站主数据masterGET /v1/seoul-bike/nearby?lat37.5717lon126.9763radius_m500limit10—代理侧坐标周边过滤内部先取全量实时数据三个端点都已在 k-skill-proxy 中实现并注册路由定义见 server.js端点清单与上游 key 说明见 k-skill-proxy.md。客户端脚本通过fetch_json()统一发起请求urllib.parse.urlencode编码查询参数后拼接到{proxy_base_url}{path}?{query}带User-Agent: k-skill/seoul-bike请求头超时 15 秒TIMEOUT_SEC 15seoul_bike.py。代理端的关键实现上游请求构造在proxySeoulBikeDatasetRequest()中server.js${SEOUL_CITYDATA_BASE_URL}/${apiKey}/json/${dataset}/${startIndex}/${endIndex}/realtime端点对应dataset bikeListstations端点对应dataset tbCycleStationInfo见proxySeoulBikeRealtimeRequest/proxySeoulBikeStationsRequestserver.js。若服务器未配置SEOUL_OPEN_API_KEY代理直接返回 503错误体为{error: upstream_not_configured, ...}不会请求上游。成功响应会注入proxy.requested_at new Date().toISOString()即查询时刻统一由代理服务器生成requested_at字段来源。响应带内存缓存makeCacheKey依据路由与归一化参数生成 key命中时返回proxy.cache.hit true与ttl_ms未命中且上游返回 2xx 时才写缓存server.js。上游返回的 JSON 若命中语义错误getSeoulOpenApiSemanticError代理统一回 502 并携带语义错误信息。nearby端点在代理侧完成「拉全量 → 逐行归一化 → 过滤无坐标/超半径 → 按距离升序排序 → 截取 limit 条」的完整流程server.js客户端无需自行做地理计算。字段归一化两种命名都能消化客户端normalize_realtime_row()seoul_bike.py对每个字段都兼容「上游 camelCase」与「代理 snake_case」两种键名并做健壮的类型转换输出字段camelCase上游snake_case代理计算station_idstationIdstation_id—station_namestationNamestation_name—rack_total_countrackTotCntrack_total_count字符串转 intavailable_bikesparkingBikeTotCntavailable_bikes字符串转 intempty_docks——max(0, rack_total - available)shared_percentsharedshared_percent字符串转 intlatitude/longitudestationLatitude/stationLongitudelatitude/longitude—_to_int()会先把值转 float 再取整并容忍空值empty_docks用max(0, ...)保证不为负。测试test_search_realtime_filters_station_names_and_reports_empty_dockstest_seoul_bike.py验证了 camelCase 输入能被正确换算为available_bikes 4、empty_docks 11。错误处理与失败模式入口脚本的main()对三类异常做了统一兜底seoul_bike.pyHTTPError 503 upstream_not_configured输出「k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요.」——对应代理端未配置SEOUL_OPEN_API_KEY。其他 HTTPError优先输出代理返回的message字段否则输出API HTTP 오류: {code} {reason}。URLError代理不可达输出「설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요.」并附原因。JSONDecodeError输出「API 응답 JSON 파싱 실패」并附解析异常信息。instruction.md 列出的失败模式与之对应代理上游 key 未设置缺少SEOUL_OPEN_API_KEY→ 客户端收到 503 提示首尔开放数据广场 quota 超限 → 上游语义错误代理回 502实时 API 返回空行或临时错误 → 输出为空或解析失败需要重试坐标缺失或半径内无租赁站 → nearby 返回count: 0search 返回空并给出「无匹配」提示。完成标准一次成功的查询应答应满足已汇总可借车辆数与空车桩数明确标注基于 live data 的查询时刻proxy.requested_at全程未向客户端暴露 upstream key。使用注意事项实时数据持续变化回答时必须附带查询时刻避免给用户造成「当前状态」的错觉。本技能是查询专用不会执行预约/租车等写操作。关于 proxy 的运维与更多环境变量配置请参考 docs/features/k-skill-proxy.md客户端与代理的环境变量约定KSKILL_PROXY_BASE_URL留空即用 hosted 代理也在该文档中有系统说明。想直接验证代理端可用性可先请求GET /health确认seoulBikeConfigured类健康指标再调用业务端点详见代理部署文档中的自检实践。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考