企业官网建设流程全解析

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实时城市数据接口。每个查询返回的核心字段包括：

作为对比，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

具体流程分三步：

1. 客户端（Skill 脚本）向默认 hosted 路径https://k-skill-proxy.nomadamas.org/v1/seoul-density/citydata发起请求；若设置了KSKILL_PROXY_BASE_URL环境变量，则改用该变量值对应的地址。
2. 代理服务器以服务器端持有的SEOUL_OPEN_API_KEY调用首尔开放数据广场的citydata_ppltn/1/1/{area}接口。
3. 代理将上游响应原样返回，并附加proxy.cache.hit缓存命中元数据。

代理端的关键实现位于 packages/k-skill-proxy/src/server.js：normalizeSeoulCityDataQuery负责参数校验（只接受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）。

输入参数与支持的地点列表

接口只需一个输入参数：

全部 121 个地点在 seoul_density.py 的AREAS字典中按类别组织，包括：고궁·문화유산（宫阙·文化遗产，5 处）、관광특구（观光特区，7 处）、공원（公园，33 处）、발달상권（发达商圈，28 处）、인구밀집지역（人口密集区域，46 处）等。可以通过以下两种方式查看完整列表：

# 方式一：直接阅读 SKILL.md 或源码中的 AREAS 分类 # 方式二：运行 list 子命令 npx -y @nomadamas/k-skill@0 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 单入口 CLI

seoul-density采用单入口点设计，所有操作统一通过scripts/seoul_density.py <子命令>路由（见 seoul_density.py 顶部 docstring），用户首次使用时只需批准一次 Bash 调用模式（如Bash(python3 *seoul_density.py:*)），后续调用即可自动放行。

Linux / macOS / Git-bash 下查询示例：

npx -y @nomadamas/k-skill@0 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-skill@0 exec seoul-density scripts/seoul_density.py -- query "강남역" --json

query支持--no-auto参数来关闭单候选自动匹配（默认auto=True）。禁止绕过单入口点直接执行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-skill@0 exec seoul-density scripts/seoul_density.py -- match "홍대" --json # → ["홍대 관광특구", "홍대입구역(2호선)"]

若候选只有 1 个可直接进入query（脚本会自动匹配）；若多个则向用户确认。

2. 查询拥挤度

npx -y @nomadamas/k-skill@0 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定义了一套完整的故障处理矩阵：

源码中的错误处理覆盖以下分支：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-skill@0 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