seoul-density

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Seoul Density

What this skill does

该技能功能

서울 실시간 도시데이터 API(data.seoul.go.kr)를 호출해 121개 핫스팟의 현재 혼잡도 단계(여유 / 보통 / 약간 붐빔 / 붐빔)와 추정 인구 범위를 반환한다.

데이터는 KT·SKT 통신 신호 기반 추계치이며, 5분 주기로 갱신되나 호출 시점 기준 약 15분 전 값이다.

调用首尔实时城市数据API(data.seoul.go.kr)，返回121个热点场所的当前拥挤度等级（宽松/一般/稍拥挤/拥挤）和预估人口范围。

数据基于KT·SKT通信信号的估算值，每5分钟更新一次，但调用时返回的是约15分钟前的数据。

When to use

使用场景

"지금 강남역 얼마나 붐벼?"
"홍대 지금 인파 어때?"
"명동 지금 사람 많아?"
"여의도한강공원 지금 여유로워?"

"现在江南站有多挤？"
"弘大现在人流量怎么样？"
"明洞现在人多吗？"
"汝矣岛汉江公园现在宽松吗？"

Prerequisites

前置条件

별도 API 키 발급 없이 그대로 쓸 수 있다. 모든 호출은 k-skill-proxy 경유다.

기본 프록시 URL:
```
https://k-skill-proxy.nomadamas.org
```
— 프록시 서버가
```
SEOUL_OPEN_API_KEY
```
를 보유하고 있어 사용자는 키 없이 호출만 하면 된다.
```
KSKILL_PROXY_BASE_URL
```
환경변수로 프록시 주소를 바꿀 수 있다(예: 로컬 개발용
```
http://127.0.0.1:4020
```
).

无需单独申请API密钥即可直接使用。所有调用均通过k-skill-proxy中转。

默认代理URL:
```
https://k-skill-proxy.nomadamas.org
```
— 代理服务器持有
```
SEOUL_OPEN_API_KEY
```
，用户无需密钥即可直接调用。
可通过
```
KSKILL_PROXY_BASE_URL
```
环境变量修改代理地址（例如：本地开发使用
```
http://127.0.0.1:4020
```
）。

Single entrypoint

单一入口点

이 스킬의 모든 동작은 단일 진입점을 통한다. OS·CWD에 관계없이 동일하게 동작하도록 절대 경로 + Python launcher fallback을 사용한다:

bash

undefined

该技能的所有操作均通过单一入口点执行。使用绝对路径 + Python启动器回退机制，确保不受操作系统/当前工作目录影响：

bash

undefined

macOS / Linux / Git-bash

python3 "$SKILL_DIR/scripts/seoul_density.py" <subcommand> [args]

Windows (PowerShell): py 런처 또는 python

Windows (PowerShell): py 启动器或 python

py -3 "$env:SKILL_DIR\scripts\seoul_density.py" <subcommand> [args]


`$SKILL_DIR`은 이 SKILL.md가 위치한 디렉토리다(`~/.claude/skills/seoul-density` 또는 레포의 `seoul-density/`). 호출 예시는 아래 Workflow 참조.

첫 사용 시 `Bash(python3 *seoul_density.py:*)` (또는 PowerShell 환경에서 `PowerShell(py -3 *seoul_density.py*)`) 패턴 한 번만 승인하면 이후 호출은 모두 자동 허용된다. 외부 dependency는 없고 Python 표준 라이브러리만 사용한다.

py -3 "$env:SKILL_DIR\scripts\seoul_density.py" <subcommand> [args]


`$SKILL_DIR`为当前SKILL.md所在目录（`~/.claude/skills/seoul-density`或仓库的`seoul-density/`）。调用示例可参考下方Workflow部分。

首次使用时，只需批准一次`Bash(python3 *seoul_density.py:*)`（或PowerShell环境下的`PowerShell(py -3 *seoul_density.py*)`）模式，后续调用将自动获得许可。该技能无外部依赖，仅使用Python标准库。

Subcommands

子命令

명령	설명
`list [--json]`	지원 121개 장소 목록 (카테고리별)
`match <키워드> [--limit N] [--json]`	사용자 입력 → 지원 장소명 매칭
`query <장소명> [--json]`	실시간 혼잡도/인구 조회 (사람이 읽는 요약 또는 JSON)

命令	说明
`list [--json]`	列出支持的121个场所（按类别分类）
`match <关键词> [--limit N] [--json]`	将用户输入匹配到支持的场所名称
`query <场所名> [--json]`	查询实时拥挤度/人口数据（返回可读摘要或JSON格式）

Workflow

工作流程

1. 모호한 입력은 match로 후보 확인 (선택)

1. 模糊输入用match确认候选（可选）

사용자가 "홍대 인파"처럼 모호하게 말하면 먼저 후보를 확인한다.

bash

python3 "$SKILL_DIR/scripts/seoul_density.py" match "홍대" --json

当用户输入如“弘大人流量”这类模糊内容时，先确认候选场所。

bash

python3 "$SKILL_DIR/scripts/seoul_density.py" match "弘大" --json

→ ["홍대 관광특구", "홍대입구역(2호선)"]

→ ["弘大观光特区", "弘大入口站(2号线)"]


후보가 1개면 바로 `query`로 넘어가도 되고(스크립트가 자동 매칭), 여러 개면 어느 쪽인지 사용자에게 확인한다.


若候选只有1个，可直接进入`query`操作（脚本会自动匹配）；若有多个候选，则需向用户确认具体场所。

2. 혼잡도 조회

2. 查询拥挤度

키워드 1개만 매칭되면 자동으로 보정한다.

bash

undefined

若仅匹配到1个关键词，脚本会自动修正。

bash

undefined

macOS / Linux / Git-bash

python3 "$SKILL_DIR/scripts/seoul_density.py" query "강남역"

python3 "$SKILL_DIR/scripts/seoul_density.py" query "江南站"

Windows PowerShell

py -3 "$env:SKILL_DIR\scripts\seoul_density.py" query "강남역"


출력 예시:

장소: 강남역 혼잡도: 약간 붐빔 인구 추정: 24000~26000명 기준 시각: 2026-05-14 09:30 상황: 사람이 몰려있을 수 있어요


기계적 후처리가 필요하면 `--json` 플래그를 쓴다:

```bash
python3 "$SKILL_DIR/scripts/seoul_density.py" query "강남역" --json

자동 매칭을 끄고 싶으면

--no-auto

를 쓴다.

py -3 "$env:SKILL_DIR\scripts\seoul_density.py" query "江南站"


输出示例：

场所: 江南站拥挤度: 稍拥挤预估人口: 24000~26000人基准时间: 2026-05-14 09:30 提示: 可能会有较多人群聚集哦


若需要机械后处理，可使用`--json`参数：

```bash
python3 "$SKILL_DIR/scripts/seoul_density.py" query "江南站" --json

若要关闭自动匹配，可使用

--no-auto

参数。

Done when

完成条件

장소명, 혼잡도 단계, 추정 인구 범위(최소~최대), 기준 시각, 혼잡도 메시지를 사용자에게 전달했다.

已向用户传达场所名称、拥挤度等级、预估人口范围（最小~最大）、基准时间、拥挤度提示信息。

Failure modes

异常场景

상황	동작
프록시 정상 응답	별도 키 불필요, 즉시 결과 반환
지원하지 않는 장소명 ( `exit 1` )	`match` 결과로 후보 제안
프록시 HTTP/네트워크 오류 ( `exit 1` )	stderr에 사유 출력, `KSKILL_PROXY_BASE_URL` 점검 또는 5분 후 재시도 안내
새벽 01~05시 빈 응답	실시간 데이터 미제공 시간대임을 안내
일일 할당량 초과	다음 날 재시도 안내

场景	操作
代理正常响应	无需额外密钥，立即返回结果
不支持的场所名称 ( `exit 1` )	提供 `match` 结果作为候选建议
代理HTTP/网络错误 ( `exit 1` )	在stderr输出原因，提示检查 `KSKILL_PROXY_BASE_URL` 或5分钟后重试
凌晨01~05时返回空响应	告知用户当前为实时数据未提供时段
每日配额超限	告知用户次日重试

Notes

注意事项

인구 수치는 실제값이 아닌 추계치 (KT·SKT 통신 신호 데이터 기반).
데이터는 호출 시점 기준 약 15분 전 값.
단일 진입점 외에
```
curl
```
,
```
python3 -c
```
,
```
source
```
같은 inline 명령을 직접 실행하지 말 것. 그렇게 하면 사용자가 매번 별도 승인을 받아야 한다.
새 카테고리/장소가 추가되면
```
seoul-density/scripts/seoul_density.py
```
의
```
AREAS
```
딕셔너리만 갱신한다.

人口数值为估算值（基于KT·SKT通信信号数据），非实际值。
数据为调用时刻约15分钟前的数值。
除单一入口点外，请勿直接执行
```
curl
```
、
```
python3 -c
```
、
```
source
```
等内联命令，否则用户每次都需单独批准。
若新增类别/场所，只需更新
```
seoul-density/scripts/seoul_density.py
```
中的
```
AREAS
```
字典即可。