k-skill 首尔实时拥挤度查询seoul-density完整指南121 个热门地点的实时人流数据接入实战【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill首尔实时拥挤度查询是 k-skill 项目面向韩国场景提供的一个实用 Skill通过seoul-density你可以随时获取首尔主要 121 个热点区域的实时拥挤等级여유 宽松 / 보통 普通 / 약간 붐빔 略拥挤 / 붐빔 拥挤、基于 KT·SKT 通信信令估算的人口范围以及基准时刻等关键信息而且无需自行申请任何 OpenAPI Key。读完本文你将掌握该 Skill 的基本原理、代理调用链路、CLI 子命令用法、错误处理与故障模式并能直接通过 curl 或 k-skill CLI 在实际项目中对现在江南站有多挤弘大现在人流量如何这类问题给出可落地的回答。功能概述一次调用拿到四个维度的实时信息seoul-density的核心数据来自首尔开放数据广场data.seoul.go.kr的citydata_ppltn实时城市数据接口。每个查询返回的核心字段包括响应字段含义示例值AREA_NM地点名称강남역江南站AREA_CONGEST_LVL拥挤等级여유 / 보통 / 약간 붐빔 / 붐빔약간 붐빔略拥挤AREA_PPLTN_MIN估算人口下限KT·SKT 通信信令估算24000AREA_PPLTN_MAX估算人口上限26000PPLTN_TIME数据基准时刻2026-05-14 09:30AREA_CONGEST_MSG拥挤说明消息사람이 몰려있을 수 있어요可能人很多作为对比Skill 的元信息在 skill.json 中声明为category: utility、locale: ko-KR、phase: v1归属于proxy与lookup两个 profile说明它是一个面向查询、经由代理的纯工具型 Skill。该 Skill 不依赖任何第三方 Python 包只用 Python 标准库实现方便在任何环境中直接运行。核心架构用户免密钥的代理调用链路seoul-density最重要的设计决策是用户侧完全不需要拥有首尔开放数据广场的 OpenAPI Key所有上游密钥只在代理服务器上管理。其调用链如下client / skill - k-skill-proxy - 首尔开放数据广场 citydata_ppltn具体流程分三步客户端Skill 脚本向默认 hosted 路径https://k-skill-proxy.nomadamas.org/v1/seoul-density/citydata发起请求若设置了KSKILL_PROXY_BASE_URL环境变量则改用该变量值对应的地址。代理服务器以服务器端持有的SEOUL_OPEN_API_KEY调用首尔开放数据广场的citydata_ppltn/1/1/{area}接口。代理将上游响应原样返回并附加proxy.cache.hit缓存命中元数据。代理端的关键实现位于 packages/k-skill-proxy/src/server.jsnormalizeSeoulCityDataQuery负责参数校验只接受area、areaNm、area_nm三个别名缺失时返回400 bad_request随后构建上游 URLSEOUL_CITYDATA_BASE_URL/{apiKey}/json/citydata_ppltn/1/1/{encodedArea}进行转发当服务器未配置SEOUL_OPEN_API_KEY时返回503与upstream_not_configured错误体。该代理的缓存策略基于area计算 cache key命中时响应中proxy.cache.hit为true未命中时为false。对应行为在 packages/k-skill-proxy/test/server.test.js 中有完整测试覆盖连续两次相同请求只会触发一次上游 fetch、缺失参数返回 400、未配置密钥返回 503。代理的全部接口清单与运维说明可参考 k-skill 代理服务器指南。适用前提默认 hosted 代理https://k-skill-proxy.nomadamas.org面向公共免费 API 提供无人值守的公开端点只读、allowlist 路由并配合缓存与限流因此直接使用无需任何凭证但代理服务器必须已经配置SEOUL_OPEN_API_KEY才能正常转发。环境准备需要什么、不需要什么开始使用前你只需要确认公共环境即可不需要申请任何 Key。相关说明参见公共设置指南用户侧不需要申请首尔开放数据广场 Key也不需要在本地配置SEOUL_OPEN_API_KEY。SEOUL_OPEN_API_KEY只在代理服务器端hosted 或 self-host管理docs/setup.md中功能별로 필요한 값表格明确标注서울 실시간 혼잡도 조회사용자 시크릿 불필요기본 hosted proxy 사용, 운영자만 SEOUL_OPEN_API_KEY。若使用 self-host 代理只需在服务器端填入SEOUL_OPEN_API_KEY客户端依旧无需任何 Key。可选环境变量KSKILL_PROXY_BASE_URL用于切换代理地址留空则使用默认 hosted 地址在通用运行时中它可写入~/.config/k-skill/secrets.env建议权限0600。输入参数与支持的地点列表接口只需一个输入参数参数必填说明示例area是支持的地点名称必须与官方名称一致강남역、홍대 관광특구、여의도한강공원全部 121 个地点在 seoul_density.py 的AREAS字典中按类别组织包括고궁·문화유산宫阙·文化遗产5 处、관광특구观光特区7 处、공원公园33 处、발달상권发达商圈28 处、인구밀집지역人口密集区域46 处等。可以通过以下两种方式查看完整列表# 方式一直接阅读 SKILL.md 或源码中的 AREAS 分类 # 方式二运行 list 子命令 npx -y nomadamas/k-skill0 exec seoul-density scripts/seoul_density.py -- list值得注意的是代理端normalizeSeoulCityDataQuery并不校验地点名称因此传入不支持的名称时上游会返回空数据——这正是 Skill 提供match子命令做模糊匹配的原因。使用方法一直接调用代理端点curl最直接的调用方式是向代理端点发 GET 请求area参数通过 URL 编码传递BASE${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org} curl -fsS --get ${BASE}/v1/seoul-density/citydata \ --data-urlencode area강남역预期响应摘要{ SeoulRtd.citydata_ppltn: [ { AREA_NM: 강남역, AREA_CONGEST_LVL: 약간 붐빔, AREA_PPLTN_MIN: 24000, AREA_PPLTN_MAX: 26000, PPLTN_TIME: 2026-05-14 09:30, AREA_CONGEST_MSG: 사람이 몰려있을 수 있어요 } ], RESULT: { RESULT.CODE: INFO-000 } }RESULT.RESULT.CODE为INFO-000表示成功proxy.cache.hit字段会附加在响应中用于判断是否命中了代理缓存。使用方法二Skill 单入口 CLIseoul-density采用单入口点设计所有操作统一通过scripts/seoul_density.py 子命令路由见 seoul_density.py 顶部 docstring用户首次使用时只需批准一次 Bash 调用模式如Bash(python3 *seoul_density.py:*)后续调用即可自动放行。子命令说明示例list [--json]按类别输出 121 个支持地点... -- listmatch 키워드 [--limit N] [--json]将用户关键词模糊匹配到支持地点... -- match 홍대 --jsonquery 장소명 [--json]查询实时拥挤度/人口人读摘要或 JSON... -- query 강남역Linux / macOS / Git-bash 下查询示例npx -y nomadamas/k-skill0 exec seoul-density scripts/seoul_density.py -- query 강남역输出示例장소: 강남역 혼잡도: 약간 붐빔 인구 추정: 24000~26000명 기준 시각: 2026-05-14 09:30 상황: 사람이 몰려있을 수 있어요Windows PowerShell 下则使用py启动器$SKILL_DIR指向 SKILL.md 所在目录py -3 $env:SKILL_DIR\scripts\seoul_density.py query 강남역需要机器可读输出时加--json标志npx -y nomadamas/k-skill0 exec seoul-density scripts/seoul_density.py -- query 강남역 --jsonquery支持--no-auto参数来关闭单候选自动匹配默认autoTrue。禁止绕过单入口点直接执行curl、python3 -c、source等内联命令否则会导致每次调用都需要单独审批。模糊匹配与推荐工作流seoul-density提供了从模糊输入到最终结果的标准工作流。其fuzzy_match实现位于 seoul_density.py匹配优先级为包含关系keyword in name→ 反向包含name in keyword→ 归一化后的宽松匹配_normalize会去除空白并剥离관광특구/한강공원/공원/시장/역/거리/광장等后缀→difflib.get_close_matches相似度匹配cutoff 0.3。推荐工作流1. 模糊输入先用 match 确认候选可选当用户说홍대 인파这类模糊表达时先确认候选npx -y nomadamas/k-skill0 exec seoul-density scripts/seoul_density.py -- match 홍대 --json # → [홍대 관광특구, 홍대입구역(2호선)]若候选只有 1 个可直接进入query脚本会自动匹配若多个则向用户确认。2. 查询拥挤度npx -y nomadamas/k-skill0 exec seoul-density scripts/seoul_density.py -- query 강남역query内部会先检查area是否在all_areas()中不在时调用fuzzy_match取前 3 个候选若仅 1 个候选则自动纠正除非--no-auto否则提示候选并返回 exit 1。summarize会检查RESULT.RESULT.CODE非INFO-000时抛出API 오류无SeoulRtd.citydata_ppltn行时抛出인구 데이터가 없습니다错误提示先用match确认地点。完成标准Done when将地点名称、拥挤等级、估算人口范围最小~最大、基准时刻、拥挤说明消息完整传达给用户即为一次成功的查询。失败模式与排查seoul-density定义了一套完整的故障处理矩阵场景行为代理正常响应无需额外 Key立即返回结果不支持的地点名exit 1用match结果提供候选建议代理 HTTP/网络错误exit 1stderr 输出原因提示检查KSKILL_PROXY_BASE_URL或 5 分钟后重试凌晨 01~05 时空响应提示为实时数据不提供时段日配额超限提示次日重试源码中的错误处理覆盖以下分支HTTP 503 且错误体为upstream_not_configured时提示k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다运营方未配置密钥其他 HTTP 错误输出状态码与原因URLError时提示代理无响应설정된 k-skill-proxy 서버가 응답하지 않습니다RuntimeError/JSONDecodeError时直接输出错误信息。所有这些分支都以非零退出码结束便于 Agent 捕获并继续向用户说明。注意事项与数据边界使用seoul-density时必须清楚数据的固有特性人口是估算值AREA_PPLTN_MIN ~ AREA_PPLTN_MAX基于 KT·SKT 通信信令数据推算不是精确统计。数据延迟约 15 分钟响应反映的是调用时刻约 15 分钟前的数据每 5 分钟周期更新一次。凌晨 01~05 时可能无实时数据该时段接口可能不提供实时值表现为空响应。日调用配额超过每日配额后需次日重试。地点名称必须精确传入不支持的地点会得到空响应请先用match子命令确认候选。扩展阅读在 SKILL.md 中可查看完整 Skill 说明、单入口点命令与失败模式表通过npx -y nomadamas/k-skill0 instruct seoul-density可获取针对当前运行时的指令。代理端完整接口清单与 self-host 部署方式见 k-skill 代理服务器指南其测试用例位于 packages/k-skill-proxy/test/server.test.js。环境变量与凭据管理整体策略见公共设置指南。原始数据源为首尔开放数据广场data.seoul.go.kr的城市数据 API正式使用前建议以该官方数据集说明为准核对字段定义。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考