@nomadamas/k-skill 0.1.0

package/skills/subway-lost-property/scripts/subway_lost_property.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import json
+import shlex
+import subprocess
+from dataclasses import asdict, dataclass
+from datetime import date, timedelta
+from typing import Callable
+
+LOST112_LIST_URL = "https://www.lost112.go.kr/find/findList.do"
+LOST112_REFERER_URL = "https://www.lost112.go.kr/"
+LOST112_OUTPUT_FILE = "lost112-search-result.html"
+LOST112_CURL_MAX_TIME = 60
+SEOUL_METRO_LOST_CENTER_URL = "https://www.seoulmetro.co.kr/kr/page.do?menuIdx=541"
+CURL_USER_AGENT = "Mozilla/5.0"
+
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+
+
+@dataclass(frozen=True)
+class SearchQuery:
+    station: str
+    item: str | None = None
+    line: str | None = None
+    start_date: date | None = None
+    end_date: date | None = None
+
+
+@dataclass(frozen=True)
+class SearchPlan:
+    query: SearchQuery
+    payload: dict[str, str]
+    suggested_keywords: list[str]
+    official_sources: list[dict[str, str]]
+    guidance: list[str]
+    cautions: list[str]
+    curl_example: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "query": {
+                **asdict(self.query),
+                "start_date": self.query.start_date.isoformat() if self.query.start_date else None,
+                "end_date": self.query.end_date.isoformat() if self.query.end_date else None,
+            },
+            "payload": self.payload,
+            "suggested_keywords": self.suggested_keywords,
+            "official_sources": self.official_sources,
+            "guidance": self.guidance,
+            "cautions": self.cautions,
+            "curl_example": self.curl_example,
+        }
+
+
+def normalize_station(station: str) -> str:
+    normalized = " ".join(station.split())
+    if not normalized:
+        raise ValueError("station is required")
+    return normalized
+
+
+def expand_station_keywords(station: str) -> list[str]:
+    normalized = normalize_station(station)
+    keywords = [normalized]
+    if normalized.endswith("역") and len(normalized) > 1:
+        keywords.append(normalized[:-1])
+    return list(dict.fromkeys(keyword for keyword in keywords if keyword))
+
+
+def build_search_payload(query: SearchQuery) -> dict[str, str]:
+    station = normalize_station(query.station)
+    if not query.start_date or not query.end_date:
+        raise ValueError("start_date and end_date are required")
+
+    payload = {
+        "pageIndex": "1",
+        "START_YMD": query.start_date.strftime("%Y%m%d"),
+        "END_YMD": query.end_date.strftime("%Y%m%d"),
+        "PRDT_NM": (query.item or "").strip(),
+        "DEP_PLACE": station,
+        "SITE": "V",
+        "PLACE_SE_CD": "",
+        "FD_LCT_CD": "",
+        "FD_SIGUNGU": "",
+        "IN_NM": "",
+        "ATC_ID": "",
+        "F_ATC_ID": "",
+        "PRDT_CL_CD01": "",
+        "PRDT_CL_CD02": "",
+        "PRDT_CL_NM": "",
+        "MENU_NO": "",
+    }
+    return payload
+
+
+def _base_curl_command(url: str | None, max_time: int, *, follow_redirects: bool = True) -> list[str]:
+    command = [
+        "curl",
+        "-fsS",
+        "--http1.1",
+        "--tls-max",
+        "1.2",
+        "--retry",
+        "1",
+        "--max-time",
+        str(max_time),
+        "-A",
+        CURL_USER_AGENT,
+    ]
+    if follow_redirects:
+        command.insert(2, "-L")
+    if url:
+        command.append(url)
+    return command
+
+
+def build_curl_command(payload: dict[str, str]) -> str:
+    command = _base_curl_command("", LOST112_CURL_MAX_TIME, follow_redirects=False)
+    command.extend(["--referer", LOST112_REFERER_URL])
+    for key, value in payload.items():
+        if value:
+            command.extend(["--data-urlencode", f"{key}={value}"])
+    command.extend(["--output", LOST112_OUTPUT_FILE])
+    command.append(LOST112_LIST_URL)
+    return " ".join(shlex.quote(part) for part in command)
+
+
+def probe_source(name: str, url: str, runner: Runner = subprocess.run) -> dict[str, str]:
+    command = _base_curl_command(url, 15)
+    try:
+        completed = runner(command, capture_output=True, text=True, check=True)
+        return {
+            "name": name,
+            "url": url,
+            "status": "reachable",
+            "detail": f"fetched {len(completed.stdout)} bytes",
+        }
+    except subprocess.CalledProcessError as error:
+        detail = (error.stderr or error.stdout or str(error)).strip() or "unknown error"
+        status = "timeout" if error.returncode == 28 or "timed out" in detail.lower() else "error"
+        return {"name": name, "url": url, "status": status, "detail": detail}
+
+
+def build_search_plan(
+    station: str,
+    item: str | None = None,
+    line: str | None = None,
+    days: int = 30,
+    today: date | None = None,
+    verify_live: bool = False,
+    probe: Callable[[str, str], dict[str, str]] | None = None,
+) -> SearchPlan:
+    normalized_station = normalize_station(station)
+    if days <= 0:
+        raise ValueError("days must be positive")
+
+    today = today or date.today()
+    end_date = today
+    start_date = today - timedelta(days=days)
+    query = SearchQuery(
+        station=normalized_station,
+        item=(item or "").strip() or None,
+        line=(line or "").strip() or None,
+        start_date=start_date,
+        end_date=end_date,
+    )
+    payload = build_search_payload(query)
+    suggested_keywords = expand_station_keywords(normalized_station)
+    if query.line:
+        suggested_keywords.append(query.line)
+    suggested_keywords = list(dict.fromkeys(suggested_keywords))
+
+    default_sources = [
+        {
+            "name": "LOST112 습득물 목록",
+            "url": LOST112_LIST_URL,
+            "purpose": "경찰 이외 기관(지하철·공항 등) 습득물 검색",
+            "status": "not_checked",
+        },
+        {
+            "name": "서울교통공사 유실물센터",
+            "url": SEOUL_METRO_LOST_CENTER_URL,
+            "purpose": "서울 지하철 공식 유실물 진입점/추가 안내",
+            "status": "not_checked",
+        },
+    ]
+    if verify_live:
+        probe = probe or probe_source
+        default_sources = [
+            {**probe(source["name"], source["url"]), "purpose": source["purpose"]}
+            for source in default_sources
+        ]
+
+    item_hint = query.item or "분실물"
+    guidance = [
+        f"먼저 LOST112에서 보관장소를 '{normalized_station}' 로, 물품명은 '{item_hint}' 로 검색합니다.",
+        "검색 폼에서는 SITE=V(경찰이외의기관) 기준으로 지하철/공항 등 기관 습득물을 우선 좁힙니다.",
+        "결과가 없으면 역명에서 '역'을 뺀 키워드나 호선명을 추가로 검색합니다.",
+        "서울교통공사 안내 페이지를 함께 열어 운영사 유실물센터/후속 절차를 확인합니다.",
+    ]
+    cautions = [
+        "v1은 공식 웹 조회 경로를 구조화하는 안내형/하이브리드 스킬이다.",
+        "공개 API가 확인되지 않아 자동 결과 수집은 보장하지 않는다.",
+        "공식 사이트 응답 속도가 느리면 manual open으로 전환한다.",
+    ]
+
+    return SearchPlan(
+        query=query,
+        payload=payload,
+        suggested_keywords=suggested_keywords,
+        official_sources=default_sources,
+        guidance=guidance,
+        cautions=cautions,
+        curl_example=build_curl_command(payload),
+    )
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Generate official subway lost-property search guidance.")
+    parser.add_argument("--station", required=True, help="역명 또는 보관장소 키워드")
+    parser.add_argument("--item", help="예: 지갑, 이어폰")
+    parser.add_argument("--line", help="예: 2호선")
+    parser.add_argument("--days", type=int, default=30, help="검색 기간(일), 기본값 30")
+    parser.add_argument("--verify-live", action="store_true", help="공식 페이지 reachability를 curl로 확인")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = parse_args(argv)
+    plan = build_search_plan(
+        station=args.station,
+        item=args.item,
+        line=args.line,
+        days=args.days,
+        verify_live=args.verify_live,
+    )
+    print(json.dumps(plan.to_dict(), ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/skills/subway-lost-property/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "subway-lost-property",
+  "description": "Use when the user asks how to look up 지하철 분실물 or 유실물 by 역명/물품명. v1 is an 안내형/하이브리드 skill that structures the official LOST112 + 서울교통공사 flow conservatively. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:communication"
+  ],
+  "frontmatter": "name: subway-lost-property\ndescription: Use when the user asks how to look up 지하철 분실물 or 유실물 by 역명/물품명. v1 is an 안내형/하이브리드 skill that structures the official LOST112 + 서울교통공사 flow conservatively. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: transit\n  locale: ko-KR\n  phase: v1"
+}

package/skills/ticket-availability/instruction.md

@@ -0,0 +1,175 @@
+# Ticket Availability
+
+## What this skill does
+
+YES24 (`ticket.yes24.com`) 와 인터파크 (`tickets.interpark.com`) 의 공개 BFF JSON / Ajax endpoint 를 단일 HTTP 요청으로 호출해 공연 일정과 등급별 잔여석 수를 정규화한다.
+
+- 공연 URL 또는 `platform:id` 표기로 입력을 받는다.
+- 일정 (날짜·시간·회차) 조회.
+- 등급별 잔여석 수 조회 (등급명, 잔여수, YES24의 경우 노출가).
+- 좌석맵 / 좌석 선택 / 예매 / 결제 / 로그인 세션 접근은 하지 않는다.
+- CloakBrowser, Playwright, fingerprint spoofing, CAPTCHA 우회를 사용하지 않는다 (`httpx` only).
+
+## When to use
+
+- "오늘 인터파크 ○○ 공연 잔여석 있어?"
+- "YES24 콘서트 ID 58026 일정 알려줘"
+- "이 공연 R석 몇 자리 남았어?"
+- "공연 URL 줄게, 회차별 잔여석 확인해줘"
+
+## When not to use
+
+- 예매·결제·취소·환불 처리 — **공연법 §4조의2 (2023.9 시행) 매크로 입장권 부정구매·판매 금지** 대상이며 이 스킬은 의도적으로 예매를 지원하지 않는다.
+- 좌석 선택, 좌석맵 시각화, 특정 좌석 번호 확인 — 잔여 *수* 만 노출한다.
+- 회원 등급별 우선 예매, 쿠폰가, 카드사 할인가 — 공개 endpoint 만 사용한다.
+- 차단 우회, CAPTCHA 우회, headless 감지 우회 — `httpx` 한 호출로 안 되면 실패 모드로 처리하고 종료한다.
+
+## Required inputs
+
+공연 URL 또는 `platform:id` 표기가 없으면 먼저 물어본다.
+
+권장 질문:
+
+> 확인하실 공연의 YES24 또는 인터파크 URL을 알려주세요.
+> 예: `https://tickets.interpark.com/goods/26000541`
+>     `https://ticket.yes24.com/Perf/58026`
+
+## Prerequisites
+
+- Python 3.9+
+- `httpx` (표준 패키지)
+
+설치:
+
+```bash
+pip install httpx
+```
+
+## Workflow
+
+### 1. URL 파싱
+
+| 입력 | 매칭 |
+|---|---|
+| `https://tickets.interpark.com/goods/<goods_code>` | platform=interpark |
+| `https://ticket.yes24.com/Perf/<perf_id>` | platform=yes24 |
+| `https://ticket.yes24.com/New/Perf/Detail/View/<perf_id>` | platform=yes24 |
+| `yes24:<id>` / `interpark:<id>` | shorthand |
+
+### 2. 일정 조회 (`schedule`)
+
+```bash
+python3 scripts/ticket_availability.py schedule "https://tickets.interpark.com/goods/26000541"
+```
+
+응답 — Interpark:
+```json
+{
+  "platform": "interpark",
+  "id": "26000541",
+  "schedule": [
+    {"date": "2026-05-13", "time": "14:30", "play_seq": "055"},
+    {"date": "2026-05-14", "time": "19:30", "play_seq": "057"}
+  ]
+}
+```
+
+응답 — YES24:
+```json
+{
+  "platform": "yes24",
+  "id": "58026",
+  "schedule": [
+    {"date": "2026-05-16", "time_label": "1회", "id_time": "1432397"}
+  ]
+}
+```
+
+YES24 는 기본 3주 윈도우. 6개월 전체는 `--all-dates` 추가.
+
+### 3. 잔여석 조회 (`seats`)
+
+```bash
+python3 scripts/ticket_availability.py seats "interpark:26000541"
+```
+
+응답:
+```json
+{
+  "platform": "interpark",
+  "id": "26000541",
+  "seats": {
+    "2026-05-13|14:30|055": {
+      "date": "2026-05-13", "time": "14:30", "play_seq": "055",
+      "seats": [
+        {"grade": "VIP석", "remain": 150},
+        {"grade": "R석",  "remain": 36},
+        {"grade": "S석",  "remain": 82},
+        {"grade": "A석",  "remain": 71}
+      ]
+    }
+  }
+}
+```
+
+YES24 응답은 등급별 `price` (노출가) 도 포함:
+```json
+{"grade": "전석", "price": "110,000원", "remain": 2}
+```
+
+### 4. 헬스체크 (`health`)
+
+```bash
+python3 scripts/ticket_availability.py health
+```
+
+응답:
+```json
+{"yes24": {"status": 200, "ok": true}, "interpark": {"status": 200, "ok": true}}
+```
+
+## Output format
+
+기본 출력은 들여쓰기 JSON. 파이프/스크립트용은 `--compact` 추가 (한 줄 JSON).
+
+## Endpoints used
+
+이 스킬이 호출하는 공개 endpoint 만:
+
+| Platform | Method | URL |
+|---|---|---|
+| YES24 | POST | `https://ticket.yes24.com/New/Perf/Sale/Ajax/axPerfDay.aspx` |
+| YES24 | POST | `https://ticket.yes24.com/NEw/Perf/Detail/Ajax/axPerfPlayTime.aspx` |
+| YES24 | POST | `https://ticket.yes24.com/New/Perf/Detail/Ajax/axPerfRemainSeat.aspx` |
+| Interpark | GET | `https://api-ticketfront.interpark.com/v1/goods/<id>/playSeq` |
+| Interpark | GET | `https://api-ticketfront.interpark.com/v1/goods/<id>/playSeq/PlaySeq/<seq>/REMAINSEAT` |
+
+전부 비로그인 / 무인증. 헤더는 `User-Agent` + `Referer` + JSON `Accept` 만.
+
+## Failure modes
+
+- **YES24 `schedule` 결과 빈 배열**: 공연 ID 가 유효하지만 향후 3주(또는 6개월) 내 일정이 없음. ID 자체가 잘못된 경우와 구분되지 않으므로, 사용자에게 `--all-dates` 또는 다른 ID 확인을 안내한다.
+- **Interpark `data: []`**: goods_code 가 지나갔거나 아직 오픈 전 / 비공개. 다른 ID 확인을 안내한다.
+- **HTTP 4xx/5xx**: 차단/일시 장애. 우회 시도하지 않고 `http error` 출력 후 종료.
+- **JSON 스키마 변경**: YES24 axPerfRemainSeat 는 HTML 응답을 정규식으로 파싱 — 사이트 갱신 시 영향 가능. `remain` 0 으로 잘못 보고될 수 있어 사용자에게 "조회 시각 기준" 이라고 표기.
+- **공연 매진**: API 는 `remain: 0` 반환. 매진 표시.
+
+## Response style
+
+- 잔여석은 "조회 시각 기준" 으로 표현한다 (실시간 변동).
+- "매크로", "선점", "오픈런", "자동 예매" 표현 금지 — 이 스킬은 조회 전용.
+- 잔여석 수치 + 등급명 만 인용. 좌석 번호 / 좌석 위치는 노출하지 않는다.
+- "지금 사라" 같은 행위 유도 금지 — 사용자가 직접 페이지에서 결제.
+
+## Notes
+
+- 본 스킬은 의도적으로 **예매 / 결제 / 좌석선택 / 로그인 자동화** 를 포함하지 않는다. 매크로를 통한 입장권 부정구매·판매는 공연법 §4조의2 (2023.9.22 시행) 에 의해 형사처벌 대상.
+- 시크릿 / 키 / 로그인 세션 일체 사용하지 않는다.
+- Rate limit: `seats` 명령은 회차별 순차 호출 — Interpark 0.3s, YES24 0.4s 간격. 100회차 짜리 공연이면 약 30s ~ 40s 소요. 짧은 모니터링 루프에 넣지 말 것.
+
+## Done when
+
+- 공연 URL 또는 `platform:id` 가 확인되었다.
+- 일정 또는 잔여석 결과 JSON 을 반환하거나, 빈 결과 사유를 설명했다.
+- 예매 / 결제 / 좌석 선택 기능을 자동화하지 않았다.
+- 조회 시각 기준임을 안내했다.