@nomadamas/k-skill 0.1.0

package/skills/express-bus-booking/references/kobus-http-flow.md

@@ -0,0 +1,159 @@
+# KOBUS HTTP/API Probe Notes
+
+Session-proven on 2026-05-08. Goal: avoid browser automation where possible.
+
+## Base
+
+```text
+https://www.kobus.co.kr
+```
+
+Use a desktop User-Agent, HTTP/1.1 if needed, a cookie jar, and referers.
+
+## Tested Flow
+
+### Route / Terminal Candidates
+
+```text
+POST /mrs/readRotLinInf.ajax
+```
+
+Observed JSON keys:
+
+```text
+tfrLen
+tfrInfList
+len
+codeYn
+rotInfList
+```
+
+One probe returned about 1,208 route records in `rotInfList`.
+
+### Timetable
+
+```text
+POST /mrs/alcnSrch.do
+```
+
+Example tested route/date:
+
+```text
+서울경부(010) -> 부산(700), 2026-05-09
+```
+
+Observed result:
+
+```text
+42 schedule links/cards
+25 selectable seat snippets
+first selectable: 00:30 / 천일고속 / 심야우등 / 10 seats
+```
+
+Typical POST fields:
+
+```text
+deprCd=010
+arvlCd=700
+pathDvs=sngl
+pathStep=1
+deprDtm=YYYYMMDD
+busClsCd=0
+rtrpChc=1
+timeLinkMin=00
+timeLinkMax=23
+```
+
+Parse `fnSatsChc(...)` onclick values for the next step. Example:
+
+```text
+fnSatsChc('20260509','003000','003000','010','700','3','07','0','Y','N','010','700','N','N','N','N')
+```
+
+### Seat / Fare Stage
+
+```text
+POST /mrs/satschc.do
+```
+
+Send the original `alcnSrchFrm` hidden fields plus selected values from `fnSatsChc(...)`, including values such as:
+
+```text
+deprTime=003000
+alcnDeprTime=003000
+alcnDeprTrmlNo=010
+alcnArvlTrmlNo=700
+indVBusClsCd=3
+cacmCd=07
+dcDvsCd=0
+prvtBbizEmpAcmtRt=N
+chldSftySatsYn=N
+dsprSatsYn=N
+```
+
+Observed response contained `form#satsChcFrm` and hidden values:
+
+```json
+{
+  "deprTime": "003000",
+  "alcnDeprTrmlNo": "010",
+  "alcnArvlTrmlNo": "700",
+  "adltFee": "47600",
+  "rmnSatsNum": "10",
+  "totSatsNum": "28"
+}
+```
+
+### Temporary Hold
+
+```text
+POST /mrs/setPcpy.ajax
+```
+
+Observed successful response markers:
+
+```text
+MSG_CD=S0000
+pcpyNoAll
+satsNoAll
+ESTM_AMT
+DC_AMT
+TISSU_AMT
+```
+
+### Hold Cancellation
+
+```text
+POST /mrs/cancPcpy.ajax
+```
+
+Observed success marker:
+
+```text
+MSG_CD=S0000
+```
+
+2026-05-13 서울→광주 re-verification: `센트럴시티(서울)(021) -> 광주(유·스퀘어)(500)`, 2026-05-20 00:45 중앙고속 심야우등, seat 1. `/mrs/setPcpy.ajax` returned `MSG_CD=S0000`, `pcpyNoAll`, `satsNoAll=01`, `TISSU_AMT=36900`; `/mrs/stplcfmpym.do?keep=/mrs/pay` rendered the official payment-information page; `/mrs/cancPcpy.ajax` returned `MSG_CD=S0000`.
+
+### Checkout Entry
+
+```text
+POST /mrs/stplcfmpym.do
+```
+
+The POST body must include the selected schedule/seat form values plus temporary hold identifiers and fare amounts. A helper page can auto-submit this form to the official KOBUS endpoint.
+
+For mobile browsers, use:
+
+```text
+POST /mrs/stplcfmpym.do?keep=/mrs/pay
+```
+
+This preserves the POST body while placing `/mrs/pay` in `location.href`, which avoids a KOBUS client-side mobile redirect condition observed in the common JavaScript.
+
+## Interpretation
+
+- Login was not required for route lookup, timetable lookup, seat-selection-page entry, temporary hold, or checkout-entry page display in the tested flow.
+- Page HTML can include login or `grecaptchaToken` forms, but these did not block the tested lookup/seat-stage path.
+- Final payment should remain a manual, explicitly confirmed stage.
+- KOBUS mobile behavior is less stable than desktop because common JavaScript can redirect narrow screens to the mobile main page.

package/skills/express-bus-booking/scripts/kobus_express_booking.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""KOBUS timetable lookup and temporary hold helper.
+
+Default mode searches timetables. With --hold-first-seat or --hold-seat it creates
+a temporary seat hold through /mrs/setPcpy.ajax and saves a local auto-submit
+HTML helper for the official KOBUS payment-information page. It never submits
+card fields or final payment.
+"""
+from __future__ import annotations
+
+import argparse
+import html
+import http.cookiejar
+import json
+import re
+import ssl
+import sys
+import tempfile
+import urllib.parse
+import urllib.request
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterable
+
+BASE_URL = "https://www.kobus.co.kr"
+UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/125 Safari/537.36"
+FN_SATS_RE = re.compile(r"fnSatsChc\((.*?)\)", re.DOTALL)
+ARG_RE = re.compile(r"'([^']*)'")
+FORM_RE = re.compile(r"<form\b([^>]*)>(.*?)</form>", re.DOTALL | re.IGNORECASE)
+INPUT_RE = re.compile(r"<input\b([^>]+)>", re.DOTALL | re.IGNORECASE)
+ATTR_RE = re.compile(r"([\w:-]+)=[\"']([^\"']*)[\"']")
+SEAT_RE = re.compile(r'<input\b([^>]*name=["\']seatBoxDtl["\'][^>]*)>', re.DOTALL | re.IGNORECASE)
+TAG_RE = re.compile(r"<[^>]+>")
+
+
+@dataclass
+class Schedule:
+    index: int
+    departure_time: str | None
+    company: str | None
+    bus_class: str | None
+    remaining_text: str | None
+    raw_args: list[str]
+
+
+@dataclass
+class Hold:
+    success: bool
+    pcpy_no_all: str | None
+    sats_no_all: str | None
+    seat: str | None
+    estm_amt: str | None
+    dc_amt: str | None
+    tissu_amt: str | None
+    checkout_helper_path: str | None
+    checkout_response_path: str | None
+    cancel_fields_path: str | None
+    raw_response: dict[str, object]
+
+
+def opener() -> urllib.request.OpenerDirector:
+    jar = http.cookiejar.CookieJar()
+    ctx = ssl._create_unverified_context()
+    try:
+        ctx.set_ciphers("DEFAULT@SECLEVEL=1")
+    except ssl.SSLError:
+        pass
+    return urllib.request.build_opener(
+        urllib.request.HTTPCookieProcessor(jar),
+        urllib.request.HTTPSHandler(context=ctx),
+    )
+
+
+def request(url: str, data: dict[str, str] | list[tuple[str, str]] | None = None, referer: str | None = None) -> urllib.request.Request:
+    headers = {"User-Agent": UA}
+    if referer:
+        headers["Referer"] = referer
+    if data is None:
+        return urllib.request.Request(url, headers=headers, method="GET")
+    headers["Content-Type"] = "application/x-www-form-urlencoded"
+    return urllib.request.Request(url, data=urllib.parse.urlencode(data).encode(), headers=headers, method="POST")
+
+
+def open_text(op: urllib.request.OpenerDirector, req: urllib.request.Request, timeout: int) -> str:
+    with op.open(req, timeout=timeout) as resp:
+        return resp.read().decode(resp.headers.get_content_charset() or "utf-8", errors="replace")
+
+
+def attrs(fragment: str) -> dict[str, str]:
+    return {k.lower(): html.unescape(v) for k, v in ATTR_RE.findall(fragment)}
+
+
+def strip_tags(s: str) -> str:
+    return re.sub(r"\s+", " ", html.unescape(TAG_RE.sub(" ", s))).strip()
+
+
+def parse_form(body: str, form_id: str) -> list[tuple[str, str]]:
+    for attr_text, form_body in FORM_RE.findall(body):
+        a = attrs(attr_text)
+        if a.get("id") == form_id or a.get("name") == form_id:
+            fields = []
+            for input_text in INPUT_RE.findall(form_body):
+                ia = attrs(input_text)
+                if ia.get("name"):
+                    fields.append((ia["name"], ia.get("value", "")))
+            return fields
+    return []
+
+
+def search(op: urllib.request.OpenerDirector, depart: str, arrive: str, date: str, timeout: int) -> tuple[str, list[Schedule]]:
+    open_text(op, request(f"{BASE_URL}/main.do"), timeout)
+    body = open_text(
+        op,
+        request(
+            f"{BASE_URL}/mrs/alcnSrch.do",
+            {
+                "deprCd": depart,
+                "arvlCd": arrive,
+                "pathDvs": "sngl",
+                "pathStep": "1",
+                "deprDtm": date,
+                "busClsCd": "0",
+                "rtrpChc": "1",
+                "timeLinkMin": "00",
+                "timeLinkMax": "23",
+            },
+            f"{BASE_URL}/main.do",
+        ),
+        timeout,
+    )
+    schedules: list[Schedule] = []
+    for idx, m in enumerate(FN_SATS_RE.finditer(body), 1):
+        args = ARG_RE.findall(m.group(1))
+        context = strip_tags(body[max(0, m.start() - 900) : m.start() + 900])
+        departure = args[1][:2] + ":" + args[1][2:4] if len(args) > 1 and len(args[1]) >= 4 else None
+        schedules.append(
+            Schedule(
+                index=idx,
+                departure_time=departure,
+                company=(re.search(r"\((?:주|유)\)[^\s]+|[가-힣]+고속", context) or [None])[0],
+                bus_class=(re.search(r"심야우등|우등|프리미엄|고속", context) or [None])[0],
+                remaining_text=(re.search(r"잔여\s*\d+석|\d+\s*/\s*\d+", context) or [None])[0],
+                raw_args=args,
+            )
+        )
+    return body, schedules
+
+
+def seat_stage_fields(search_form: list[tuple[str, str]], schedule: Schedule) -> list[tuple[str, str]]:
+    a = schedule.raw_args
+    values = dict(search_form)
+    updates = {
+        "deprTime": a[1],
+        "alcnDeprTime": a[2],
+        "alcnDeprTrmlNo": a[3],
+        "alcnArvlTrmlNo": a[4],
+        "indVBusClsCd": a[5],
+        "cacmCd": a[6],
+        "dcDvsCd": a[7],
+        "prvtBbizEmpAcmtRt": a[8],
+        "chldSftySatsYn": a[12],
+        "dsprSatsYn": a[13],
+    }
+    return [(k, updates.get(k, v)) for k, v in search_form]
+
+
+def hold(op: urllib.request.OpenerDirector, alcn_body: str, schedule: Schedule, seat: str | None, out: Path, timeout: int) -> Hold:
+    search_form = parse_form(alcn_body, "alcnSrchFrm")
+    seat_body = open_text(op, request(f"{BASE_URL}/mrs/satschc.do", seat_stage_fields(search_form, schedule), f"{BASE_URL}/mrs/alcnSrch.do"), timeout)
+    fields = parse_form(seat_body, "satsChcFrm")
+    field_map = dict(fields)
+    seats = []
+    for input_text in SEAT_RE.findall(seat_body):
+        a = attrs(input_text)
+        if "disabled" not in input_text and a.get("value"):
+            seats.append(a["value"])
+    selected = seat or (seats[0] if seats else None)
+    if not selected:
+        raise RuntimeError("No selectable KOBUS seat found")
+
+    def set_field(items: list[tuple[str, str]], key: str, val: str) -> list[tuple[str, str]]:
+        return [(k, val if k == key else v) for k, v in items]
+
+    for key, val in {
+        "selSeatNum": selected,
+        "selSeatCnt": "1",
+        "selAdltCnt": "1",
+        "selAdltDcCnt": "0",
+        "prmmDcDvsCd": field_map.get("prmmDcDvsCd") or "0",
+    }.items():
+        fields = set_field(fields, key, val)
+    raw = json.loads(open_text(op, request(f"{BASE_URL}/mrs/setPcpy.ajax", fields, f"{BASE_URL}/mrs/satschc.do"), timeout))
+    success = raw.get("MSG_CD") == "S0000"
+    if not success:
+        return Hold(False, None, None, selected, None, None, None, None, None, None, raw)
+
+    for key, val in {
+        "satsNoAll": str(raw.get("satsNoAll", "")),
+        "pcpyNoAll": str(raw.get("pcpyNoAll", "")),
+        "estmAmt": str(raw.get("ESTM_AMT", "")),
+        "dcAmt": str(raw.get("DC_AMT", "")),
+        "tissuAmt": str(raw.get("TISSU_AMT", "")),
+        "nonMbrsYn": "Y",
+    }.items():
+        fields = set_field(fields, key, val)
+
+    out.mkdir(parents=True, exist_ok=True)
+    checkout = open_text(op, request(f"{BASE_URL}/mrs/stplcfmpym.do?keep=/mrs/pay", fields, f"{BASE_URL}/mrs/satschc.do"), timeout)
+    checkout_path = out / "kobus-checkout-response.html"
+    checkout_path.write_text(checkout)
+    helper_path = out / "kobus-payment-autosubmit.html"
+    inputs = "\n".join(f'<input type="hidden" name="{html.escape(k)}" value="{html.escape(v, quote=True)}">' for k, v in fields)
+    helper_path.write_text(f'<!doctype html><meta charset="utf-8"><p>공식 KOBUS 결제정보 입력 페이지로 이동합니다. 결제는 직접 진행하세요.</p><form id="f" method="post" action="{BASE_URL}/mrs/stplcfmpym.do?keep=/mrs/pay">{inputs}</form><script>document.getElementById("f").submit();</script>')
+    cancel_path = out / "kobus-cancel-fields.txt"
+    cancel_path.write_text("\n".join(f"{k}={v}" for k, v in fields))
+    return Hold(True, str(raw.get("pcpyNoAll")), str(raw.get("satsNoAll")), selected, str(raw.get("ESTM_AMT")), str(raw.get("DC_AMT")), str(raw.get("TISSU_AMT")), str(helper_path), str(checkout_path), str(cancel_path), raw)
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--depart-code", required=True)
+    p.add_argument("--arrive-code", required=True)
+    p.add_argument("--date", required=True)
+    p.add_argument("--select-index", type=int, default=1)
+    p.add_argument("--hold-first-seat", action="store_true")
+    p.add_argument("--hold-seat")
+    p.add_argument("--output-dir")
+    p.add_argument("--limit", type=int, default=20)
+    p.add_argument("--timeout", type=int, default=20)
+    args = p.parse_args(argv)
+    op = opener()
+    body, schedules = search(op, args.depart_code, args.arrive_code, args.date, args.timeout)
+    result: dict[str, object] = {"route": {"depart_code": args.depart_code, "arrive_code": args.arrive_code, "date": args.date}, "count": len(schedules), "items": [asdict(s) for s in schedules[: args.limit]]}
+    if (args.hold_first_seat or args.hold_seat) and schedules:
+        out = Path(args.output_dir) if args.output_dir else Path(tempfile.mkdtemp(prefix="kobus-hold-"))
+        result["hold"] = asdict(hold(op, body, schedules[args.select_index - 1], args.hold_seat, out, args.timeout))
+        result["payment_note"] = "Opened/saved the official KOBUS payment-information page; final card entry/payment remains manual."
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/express-bus-booking/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "express-bus-booking",
+  "description": "Search and assist Korean 고속버스/KOBUS bookings using official HTTP/API-first flows; use for 고속버스 예매, 시간표, 좌석 조회, 임시 선점, and official checkout-entry handoff. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:booking"
+  ],
+  "frontmatter": "name: express-bus-booking\ndescription: Search and assist Korean 고속버스/KOBUS bookings using official HTTP/API-first flows; use for 고속버스 예매, 시간표, 좌석 조회, 임시 선점, and official checkout-entry handoff. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: travel\n  locale: ko-KR\n  phase: v1"
+}

package/skills/fine-dust-location/instruction.md

@@ -0,0 +1,89 @@
+# Fine Dust By Location
+
+## What this skill does
+
+기본적으로 `https://k-skill-proxy.nomadamas.org/v1/fine-dust/report` 로 요청해서 PM10 / PM2.5 / 통합대기등급을 요약한다.
+
+## When to use
+
+- "지금 내 위치 미세먼지 어때?"
+- "강남 쪽 초미세먼지 수치 알려줘"
+- "여기 공기질 괜찮아?"
+
+## Inputs
+
+- 일반 입력: 지역명/행정구역 힌트
+- 재조회 입력: 정확한 측정소명
+
+## Region naming convention
+
+지역명은 아래처럼 **측정소명에 가까운 한국어 행정구역 이름**을 우선 사용한다.
+
+- 좋음: `강남구`, `서울 강남구`, `종로구`, `수원시`
+- 애매함: `강남`, `서울 남쪽`, `코엑스 근처`
+
+여러 토큰이 들어오면 helper / proxy 는 보통 **가장 구체적인 토큰**을 우선 본다. 예: `서울 강남구` → `강남구`.
+
+## Default path
+
+추가 client API 레이어는 불필요하다. 그냥 프록시 서버에 HTTP 요청만 넣으면 된다.
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/fine-dust/report' \
+  --data-urlencode 'regionHint=서울 강남구'
+```
+
+스크립트 helper 도 같은 report endpoint 를 기본 경로로 사용한다.
+
+```bash
+python3 scripts/fine_dust.py report --region-hint '서울 강남구' --json
+```
+
+## Ambiguous locations
+
+입력한 지역명이 단일 측정소로 바로 확정되지 않으면 proxy 는 `ambiguous_location` 과 함께 후보 측정소 목록을 돌려준다.
+
+예:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/fine-dust/report' \
+  --data-urlencode 'regionHint=광주 광산구'
+```
+
+이때 응답의 `candidate_stations` 중 하나를 골라 다시 `stationName` 으로 조회한다.
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/fine-dust/report' \
+  --data-urlencode 'stationName=우산동(광주)'
+```
+
+## Detailed API paths
+
+원본 AirKorea와 비슷한 passthrough 경로(`/B552584/...`)나 direct fallback 상세는 아래 문서만 참고한다.
+
+- `docs/features/fine-dust-location.md`
+- `docs/features/k-skill-proxy.md`
+
+## Keep the answer compact
+
+응답에는 아래만 먼저 정리한다.
+
+- 측정소
+- 조회 시각
+- PM10 값과 등급
+- PM2.5 값과 등급
+- 통합대기등급
+- 조회 방식(`fallback`)
+
+## Failure modes
+
+- regionHint 가 너무 넓거나 단일 측정소를 확정할 수 없는 경우
+- 프록시 서버가 내려가 있거나 upstream key가 비어 있는 경우
+- 측정소명과 지역명이 달라 직접 fallback 이 필요한 경우
+
+## Notes
+
+- 기본 경로는 항상 `k-skill-proxy.nomadamas.org` 의 report endpoint 다.
+- 지역명 조회는 먼저 후보를 얻고, 필요하면 정확한 측정소명으로 재조회한다.
+- passthrough / direct AirKorea 구현 세부는 스킬 본문에 길게 반복하지 않는다.
+- free API 프록시는 공개 endpoint 를 기본으로 둔다.

package/skills/fine-dust-location/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "fine-dust-location",
+  "description": "에어코리아 기반 미세먼지/초미세먼지를 지역명 또는 위치 힌트로 조회한다. 기본 경로는 k-skill-proxy의 report endpoint다.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: fine-dust-location\ndescription: 에어코리아 기반 미세먼지/초미세먼지를 지역명 또는 위치 힌트로 조회한다. 기본 경로는 k-skill-proxy의 report endpoint다.\nlicense: MIT\nmetadata:\n  category: utility\n  locale: ko-KR\n  phase: v1"
+}