@nomadamas/k-skill 0.1.0

package/skills/daangn-used-goods-search/scripts/daangn_used_goods.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+import argparse, json, re, sys, urllib.parse, urllib.request
+from html import unescape
+
+HEADERS = {"User-Agent":"Mozilla/5.0", "Accept":"application/json,text/html;q=0.9,*/*;q=0.8"}
+
+def fetch_json(url):
+    req = urllib.request.Request(url, headers=HEADERS)
+    with urllib.request.urlopen(req, timeout=25) as r:
+        return json.load(r)
+
+def fetch_text(url):
+    req = urllib.request.Request(url, headers={"User-Agent":"Mozilla/5.0", "Accept":"text/html"})
+    with urllib.request.urlopen(req, timeout=25) as r:
+        return r.read().decode('utf-8', 'ignore')
+
+def won(v):
+    if v in (None, ''): return '-'
+    try: return f"{int(float(v)):,}원"
+    except Exception: return str(v)
+
+def resolve_region(region):
+    if not region: return None
+    url = 'https://www.daangn.com/kr/api/v1/regions/keyword?keyword=' + urllib.parse.quote(region)
+    data = fetch_json(url)
+    locs = data.get('locations') or []
+    if not locs: raise SystemExit(f'지역 후보 없음: {region}')
+    # Exact dong/name match first, then Seoul depth-3, then first candidate.
+    exact = [x for x in locs if region in (x.get('name'), x.get('name1'), x.get('name2'), x.get('name3'))]
+    seoul = [x for x in locs if x.get('name1') == '서울특별시' and x.get('depth') == 3]
+    sel = (exact or seoul or locs)[0]
+    return sel
+
+def region_param(sel):
+    return urllib.parse.quote(f"{sel['name']}-{sel['id']}")
+
+def absolute(href):
+    if not href: return ''
+    if href.startswith('http'): return href
+    return 'https://www.daangn.com' + href
+
+def print_json(obj):
+    print(json.dumps(obj, ensure_ascii=False, indent=2))
+
+
+def cmd_search(args):
+    params = []
+    effective = None
+    path = '/kr/buy-sell/'
+    if args.region:
+        effective = resolve_region(args.region)
+        path = '/kr/buy-sell/all/'
+        params.append(('in', f"{effective['name']}-{effective['id']}"))
+    params.append(('search', args.keyword))
+    if args.only_on_sale: params.append(('only_on_sale','true'))
+    params.append(('_data','routes/kr.buy-sell._index'))
+    url = 'https://www.daangn.com' + path + '?' + urllib.parse.urlencode(params)
+    data = fetch_json(url)
+    arr = (((data.get('allPage') or {}).get('fleamarketArticles')) or [])[:args.limit]
+    print_json({
+        'source': url,
+        'effective_region': effective or data.get('region'),
+        'count': len(arr),
+        'items': [{
+            'title': a.get('title'), 'price': a.get('price'), 'price_text': won(a.get('price')),
+            'region': (a.get('region') or {}).get('name'), 'status': a.get('status'),
+            'url': absolute(a.get('href') or a.get('webUrl')),
+        } for a in arr]
+    })
+
+def cmd_detail(args):
+    u = args.url.rstrip('/') + '/?_data=routes%2Fkr.buy-sell.%24buy_sell_id'
+    data = fetch_json(u); p = data.get('product') or data.get('article') or data
+    print_json({'source': u, 'product': p})
+
+p=argparse.ArgumentParser(description='Daangn used-goods read-only search/detail')
+sub=p.add_subparsers(dest='cmd', required=True)
+s=sub.add_parser('search'); s.add_argument('keyword'); s.add_argument('--region'); s.add_argument('--limit',type=int,default=10); s.add_argument('--only-on-sale',action='store_true',default=True); s.set_defaults(func=cmd_search)
+d=sub.add_parser('detail'); d.add_argument('url'); d.set_defaults(func=cmd_detail)
+args=p.parse_args(); args.func(args)

package/skills/daangn-used-goods-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "daangn-used-goods-search",
+  "description": "당근 중고거래 공개 웹 데이터로 매물을 검색하고, 돌쇠에서는 공식 계정 표면에서 찜·채팅·거래 준비까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "action:commerce"
+  ],
+  "frontmatter": "name: daangn-used-goods-search\ndescription: 당근 중고거래 공개 웹 데이터로 매물을 검색하고, 돌쇠에서는 공식 계정 표면에서 찜·채팅·거래 준비까지 진행한다.\nlicense: MIT\nmetadata:\n  category: marketplace\n  locale: ko-KR\n  phase: v1"
+}

package/skills/daishin-report-search/instruction.md

@@ -0,0 +1,138 @@
+# Daishin Report Search
+
+## What this skill does
+
+대신증권 리포트 HTML 미러(`jay-jo-0/github_pages_repo`)에서 최신 리포트 목록을 찾고, 특정 리포트의 원문 텍스트·제목·헤딩·Rating/Target 표·원문 링크를 에이전트가 재사용하기 쉬운 JSON으로 반환한다.
+
+이 스킬은 투자 조언, 매매 자동화, 추천을 하지 않는다. 공개 HTML 리포트를 읽어 요약 가능한 자료로 정리하는 조회 전용 스킬이다.
+
+## When to use
+
+- "대신증권 최신 리포트 보여줘"
+- "대신증권 반도체 리포트 찾아줘"
+- "20260511082352 리포트 원문과 설명 페이지를 읽어줘"
+- "대신증권 리포트 목록을 에이전트가 쓰기 좋은 JSON으로 줘"
+
+## Prerequisites
+
+- 인터넷 연결
+- Node.js 18+
+- 이 저장소의 `daishin-report-search` npm package 또는 동일 로직
+
+## Public access path discovered
+
+### Primary source: GitHub recursive tree API
+
+- list endpoint: `https://api.github.com/repos/jay-jo-0/github_pages_repo/git/trees/main?recursive=1`
+- selected paths: repository-root files matching `YYYYMMDDHHMMSS.html`
+- optional companion paths: `YYYYMMDDHHMMSS_explain.html`
+- detail raw HTML: `https://raw.githubusercontent.com/Jay-jo-0/github_pages_repo/main/<path>`
+- browser detail URL: `https://jay-jo-0.github.io/github_pages_repo/<path>`
+- reason selected: the sample GitHub Pages URL maps directly to a public GitHub repository. The recursive tree API exposes all timestamped HTML filenames without relying on a brittle directory listing screen scrape. Raw GitHub URLs provide stable unauthenticated detail fetches.
+
+### Fallback source: GitHub contents API for an exact file
+
+- exact-file endpoint: `https://api.github.com/repos/jay-jo-0/github_pages_repo/contents/<path>?ref=main`
+- used automatically for a known timestamp when the raw detail URL is unavailable; it also provides GitHub content metadata for manual diagnostics.
+
+No `k-skill-proxy` route is used because the upstream is public and does not require an API key.
+
+## Workflow
+
+### 1. List latest reports
+
+```js
+const { listReports } = require("daishin-report-search")
+
+const result = await listReports({
+  limit: 10,
+  query: "반도체",   // optional; matches title/headings/detail text
+  maxInspect: 100,   // optional query crawl budget among newest pages
+  githubToken: process.env.GITHUB_TOKEN // optional; raises GitHub API limits when caller has one
+})
+
+console.log(result.items)
+```
+
+CLI:
+
+```bash
+node packages/daishin-report-search/src/cli.js --limit 10
+node packages/daishin-report-search/src/cli.js 반도체 --limit 5 --max-inspect 100
+```
+
+Return each item with:
+
+- `id` (`YYYYMMDDHHMMSS`)
+- `date`, `time`, `timestamp` (filename-derived KST timestamp)
+- `title`
+- `headings`
+- `excerpt`
+- `ratingTargets` when a Rating/Target table is present
+- `pageUrl`, `rawUrl`, `apiUrl`
+- `hasExplain`, `explainUrl` when a companion explanation page exists
+
+### 2. Fetch one report
+
+```js
+const { fetchReport } = require("daishin-report-search")
+
+const report = await fetchReport("20260511082352", {
+  includeExplain: true
+})
+
+console.log(report.title)
+console.log(report.text)
+console.log(report.explain?.text)
+```
+
+CLI:
+
+```bash
+node packages/daishin-report-search/src/cli.js --id 20260511082352 --include-explain
+```
+
+### 3. Summarize conservatively
+
+When answering a user, show:
+
+```text
+- 제목: ...
+  게시 추정 시각: 2026-05-11 08:23:52 KST (파일명 기준)
+  주요 헤딩: ...
+  Rating/Target: ... (있는 경우)
+  원문: https://jay-jo-0.github.io/github_pages_repo/...
+  설명 페이지: ... (있는 경우)
+```
+
+Always state that the timestamp is filename-derived and that report contents can change in the public mirror.
+
+## Fallback order
+
+1. GitHub recursive tree API → filter timestamped root HTML files → sort newest filename first → fetch raw detail HTML for selected/latest candidates.
+2. If a query is present, inspect newer candidates up to `maxInspect` until enough matches are found or the budget is exhausted; return a warning if the budget is exhausted.
+3. For a known id, fetch raw detail directly. If explanation is requested, fetch `<id>_explain.html`; if absent, return the original report plus a warning.
+4. If the tree endpoint is truncated, blocked, rate-limited, or changed, report that as a source warning/failure instead of guessing hidden pages.
+5. For a known id, if the raw detail URL fails, fall back to the GitHub contents API for that exact file path. Explanation pages use the same exact-file fallback but remain optional and return a warning if unavailable.
+6. If the caller has authenticated GitHub access, pass `githubToken` / `githubHeaders` in library calls or set `DAISHIN_GITHUB_TOKEN` / `GITHUB_TOKEN` for the CLI; these credentials are scoped to `api.github.com` requests and are not sent to raw detail URLs. Do not require or proxy a token by default.
+
+## Done when
+
+- Latest report rows or a specific report are returned with direct source URLs.
+- Query and limit were applied or explicitly left broad.
+- Explanation pages were included only when requested or when listing metadata shows they exist.
+- Empty results and upstream warnings are disclosed.
+
+## Failure modes
+
+- GitHub unauthenticated API rate limits can return 403/429; latest/search returns empty `items` plus `source.error.kind = "rate_limit"` and rate-limit reset metadata when GitHub exposes it. Retry later or use caller-supplied authenticated GitHub access if appropriate.
+- The repository path or branch can change; then tree/raw URLs will fail.
+- The tree response could become truncated; in that case the latest-list completeness is not guaranteed.
+- HTML structure can change; title/headings/table extraction may be partial, but URLs and raw text fallback should still be returned when available.
+- Some pages may not be authored by Daishin even though they are in the issue-scoped public mirror. Do not infer provenance beyond page title/content.
+
+## Notes
+
+- Read-only lookup only; no login, trading, order placement, recommendation, or investment advice.
+- Do not scrape private Daishin services or bypass CAPTCHA/login walls.
+- No secrets or API keys are required. Optional GitHub tokens are caller-owned, used only when explicitly supplied via options or environment, and scoped to GitHub API hosts.

package/skills/daishin-report-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "daishin-report-search",
+  "description": "대신증권 리포트 GitHub Pages 미러에서 최신 HTML 리포트 목록과 원문/설명 페이지를 조회한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: daishin-report-search\ndescription: 대신증권 리포트 GitHub Pages 미러에서 최신 HTML 리포트 목록과 원문/설명 페이지를 조회한다.\nlicense: MIT\nmetadata:\n  category: finance\n  locale: ko-KR\n  phase: v1"
+}

package/skills/daiso-product-search/instruction.md

@@ -0,0 +1,172 @@
+# Daiso Product Search
+
+## What this skill does
+
+다이소몰 공식 검색/매장/재고 표면을 사용해 **특정 다이소 매장의 상품 재고**를 확인한다.
+
+- 공식 매장 검색으로 매장 코드를 찾는다.
+- 공식 상품 검색으로 상품 후보를 찾는다.
+- 공식 매장 픽업 재고 표면으로 해당 매장의 재고를 확인한다.
+- **공식 표면이 매장 내 진열 위치를 주지 않으면 재고 중심으로만 답한다.**
+
+## When to use
+
+- "강남역2호점에 리들샷 있어?"
+- "다이소 특정 매장 재고 확인해줘"
+- "이 상품 어느 매장에 있는지 확인해줘"
+- "다이소 매장명 주면 그 매장 재고 봐줘"
+
+## When not to use
+
+- 매장명도 상품명도 전혀 없는 상태에서 바로 재고를 단정해야 하는 경우
+- 결제/주문/픽업 예약까지 자동화해야 하는 경우
+- 비공식 크롤링 결과를 우선해야 하는 경우
+
+## Prerequisites
+
+- 인터넷 연결
+- `node` 18+
+- 이 저장소의 `daiso-product-search` package 또는 동일 로직
+
+## Required inputs
+
+### 1. Ask the store name first if it is missing
+
+매장명이 없으면 바로 조회하지 말고 먼저 물어본다.
+
+- 권장 질문: `어느 다이소 매장을 확인할까요? 매장명(예: 강남역2호점)을 알려주세요.`
+- 비슷한 매장이 여러 개면: `후보 매장이 여러 개예요. 정확한 매장명을 하나만 골라주세요.`
+
+### 2. Ask the product name or keyword if it is missing
+
+상품명/검색어도 반드시 필요하다.
+
+- 권장 질문: `찾을 상품명이나 검색어도 알려주세요. 예: VT 리들샷 100`
+- 너무 넓으면: `검색어가 너무 넓어요. 브랜드나 용량까지 같이 알려주세요.`
+
+## Official Daiso Mall surfaces
+
+- store keyword catalog: `https://www.daisomall.co.kr/api/ms/msg/selStrSrchKeyword`
+- store search: `https://www.daisomall.co.kr/api/ms/msg/selStr`
+- store detail: `https://www.daisomall.co.kr/api/dl/dla-api/selStrInfo`
+- product search summary: `https://www.daisomall.co.kr/ssn/search/Search`
+- product search list: `https://www.daisomall.co.kr/ssn/search/SearchGoods`
+- product summary list: `https://www.daisomall.co.kr/ssn/search/GoodsMummResult`
+- auth (비로그인 JWT 발급): `https://www.daisomall.co.kr/api/auth/request`
+- store pickup stock: `https://www.daisomall.co.kr/api/pd/pdh/selStrPkupStck`  ← **인증 필요**
+- pickup eligibility fallback: `https://www.daisomall.co.kr/api/ms/msg/selPkupStr`
+- optional online stock cross-check: `https://www.daisomall.co.kr/api/pdo/selOnlStck`
+
+## Workflow
+
+### 1. Resolve the store
+
+공식 매장 검색 API로 매장명을 먼저 해결한다.
+
+```js
+const { searchStores } = require("daiso-product-search")
+
+const storeResult = await searchStores("강남역2호점", {
+  limit: 5
+})
+
+console.log(storeResult.items)
+```
+
+매장 후보가 여러 개면 상위 2~3개만 보여주고 다시 확인받는다.
+
+### 2. Resolve the product
+
+공식 `SearchGoods` 표면으로 상품 후보를 찾는다.
+
+```js
+const { searchProducts } = require("daiso-product-search")
+
+const productResult = await searchProducts("VT 리들샷 100", {
+  limit: 10
+})
+
+console.log(productResult.items)
+```
+
+상품 후보가 여러 개면 아래 우선순위로 짧게 정리한다.
+
+- 정확히 일치하는 이름
+- 브랜드 + 용량/호수까지 포함된 이름
+- 리뷰 수/검색 점수가 높은 후보
+- 온라인 재고 교차 확인이 필요하면 후보의 `onldPdNo` 를 함께 보존한다
+
+### 3. Check the store pickup stock
+
+`selStrPkupStck`는 `Authorization` 헤더 없이 호출하면 **403**을 반환한다.
+로그인 없이 `/api/auth/request`로 비로그인 JWT를 발급받아 AES-CBC로 암호화한 뒤 Bearer 헤더로 전달한다.
+
+**Bearer 토큰 생성 방법:**
+
+1. `GET /api/auth/request` → 응답 바디: JWT 평문, 응답 헤더 `x-dm-uid` 보존 (유효 30초)
+2. 랜덤 16바이트 IV 생성 후 JWT를 AES-128-CBC / PKCS7 / 키 `"PRE_AUTH_ENC_KEY"`로 암호화
+3. `bearer = base64(IV) + base64(암호문)` 으로 조합 후 `Authorization: Bearer <bearer>`, `X-DM-UID: <uid>` 헤더로 전달
+
+바디는 `{pdNo, strCd}` 쌍 배열로 여러 매장을 한 번에 조회할 수 있다.
+응답의 `stck` 필드가 `"0"` 또는 빈 값이면 재고 없음.
+
+```js
+const { getStorePickupStock } = require("daiso-product-search")
+
+const stock = await getStorePickupStock({
+  pdNo: "1049275",
+  strCd: "10224"
+})
+
+console.log(stock)
+```
+
+### 4. Use the end-to-end helper when both names are already known
+
+```js
+const { lookupStoreProductAvailability } = require("daiso-product-search")
+
+const result = await lookupStoreProductAvailability({
+  storeQuery: "강남역2호점",
+  productQuery: "VT 리들샷 100"
+})
+
+console.log(result.selectedStore)
+console.log(result.selectedProduct)
+console.log(result.pickupStock)
+```
+
+### 5. Respond conservatively
+
+응답은 짧고 명확하게 정리한다.
+
+- 매장명
+- 상품명
+- 매장 재고 수량 또는 재고 없음
+- 필요하면 온라인 재고 참고값
+- **공식 표면이 매장 내 진열 위치를 주지 않으면 `공식 표면에서는 매장 재고까지만 확인된다`고 분명히 말한다.**
+
+## Done when
+
+- 매장명과 상품명이 모두 확인되었다.
+- 공식 표면으로 매장 후보와 상품 후보를 찾았다.
+- 공식 매장 재고 결과를 최소 1회 반환했다.
+- 위치 정보가 없으면 없다고 분명히 고지했다.
+
+## Failure modes
+
+- 매장명이 너무 넓으면 같은 상권의 여러 지점이 동시에 잡힐 수 있다.
+- 상품명이 너무 넓으면 다른 용량/호수 후보가 많이 섞일 수 있다.
+- 공식 재고는 시점 차이로 실제 방문 시 수량이 달라질 수 있다.
+- 현재 확인된 공식 표면은 **매장 내 aisle/진열 위치**를 직접 주지 않을 수 있다.
+- `selStrPkupStck` 403 → `/api/auth/request` 재호출 후 Bearer를 새로 빌드해 재시도한다.
+- Bearer 재시도 후에도 401/403이면 재고 수량은 `retrievalStatus: "blocked"` 로 표시하고, `selPkupStr` 기반 `pickupEligibility`(픽업 가능 여부)만 보조 정보로 제공한다.
+
+## Notes
+
+- 조회형 스킬이다.
+- 공식 표면 우선 원칙을 유지한다.
+- 공식 표면이 위치를 주지 않으면 억지 추정을 하지 않는다.
+- 인증 키(`PRE_AUTH_ENC_KEY`)는 JS 번들에 하드코딩되어 있으며 변경될 수 있다.
+- `selStrPkupStck` 호출 시: `/api/auth/request` 호출 후 Bearer를 만들어 시도한다.
+- fallback order: Bearer 재고 조회 → 401/403 시 토큰 재발급 후 1회 재시도 → 구조화된 blocked 재고 → 선택적 `selPkupStr` 픽업 가능 여부.

package/skills/daiso-product-search/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "daiso-product-search",
+  "description": "Look up Daiso products by store name and product keyword using official Daiso Mall store/search/stock surfaces. Use when the user wants to know whether a product is available at a specific Daiso store. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:commerce"
+  ],
+  "frontmatter": "name: daiso-product-search\ndescription: Look up Daiso products by store name and product keyword using official Daiso Mall store/search/stock surfaces. Use when the user wants to know whether a product is available at a specific Daiso store. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: retail\n  locale: ko-KR\n  phase: v1"
+}

package/skills/danawa-price-search/instruction.md

@@ -0,0 +1,183 @@
+# Danawa Price Search
+
+## What this skill does
+
+다나와의 로그인 없는 공개 검색/가격비교 표면을 읽기 전용으로 호출해 한국 쇼핑몰 가격을 비교한다.
+
+- 상품명/검색어로 다나와 상품 후보와 `pcode`를 찾는다.
+- 선택한 상품의 쇼핑몰별 오퍼를 조회한다.
+- 상품가만이 아니라 배송비 포함 실구매가, 무료배송 여부, 카드 할인가, 무이자 할부 문구를 함께 정리한다.
+- 구매, 로그인, 장바구니, 찜, 주문 액션은 하지 않는다.
+
+## When to use
+
+- "다나와에서 에어팟 최저가 찾아줘"
+- "다나와 가격비교로 쇼핑몰별 가격 비교해줘"
+- "무료배송인지, 카드 할인까지 보면 어디가 제일 싸?"
+- "무이자 할부 붙은 최저가도 같이 봐줘"
+
+## When not to use
+
+- 실제 구매/주문/결제/로그인이 필요한 경우
+- 회원 전용 쿠폰, 개인화 포인트, 앱 전용 혜택을 확정해야 하는 경우
+- 대량 모니터링이나 고빈도 크롤링을 해야 하는 경우
+- CAPTCHA, 접근 차단, fingerprint 우회를 해야 하는 경우
+
+## Required inputs
+
+상품명 또는 검색어가 필요하다. 검색어가 넓으면 브랜드, 모델명, 용량, 색상, 자급제/통신사 여부 등을 추가로 물어본다.
+
+권장 질문:
+
+> 찾을 다나와 상품명이나 모델명을 알려주세요. 예: 갤럭시 S25 울트라 256GB 자급제, 에어팟 프로 2세대 USB-C
+
+## Public surfaces
+
+현재 구현은 인증 없는 공개 표면만 사용한다.
+
+- 검색 페이지: `https://search.danawa.com/dsearch.php?query=...`
+- 상품 상세 페이지: `https://prod.danawa.com/info/?pcode=...`
+- 가격비교 AJAX: `https://prod.danawa.com/info/ajax/getAllPriceCompareMallList.ajax.php`
+
+AJAX endpoint는 HTML fragment를 반환한다. helper는 `.diff_item`, 쇼핑몰 로고 `alt`, `em.prc_c`/`em.prc_t`, 배송 문구, 결제조건 배지(`.ico.cash`/`.ico.point`/`.ico.coupon`/`.ico.discount`/`.ico.card`/`.ico.membership` 등), 카드 할인 라인, 무이자 할부 레이어, 다나와 bridge link를 파싱한다.
+
+## Commands
+
+스킬 디렉터리에서 실행한다.
+
+```bash
+python scripts/danawa_search.py search "에어팟 프로 2세대" --limit 8
+python scripts/danawa_search.py offers 28208783 --limit 10
+python scripts/danawa_search.py compare "에어팟 프로 2세대" --limit 5 --offers 5
+```
+
+helper는 JSON만 출력한다. 결과를 확인한 뒤 사용자에게는 한국어 표와 짧은 결론으로 정리한다.
+
+## Output shape
+
+### `search`
+
+```json
+{
+  "query": "...",
+  "source_url": "...",
+  "count": 0,
+  "items": []
+}
+```
+
+각 `items[]` 주요 필드:
+
+- `pcode`
+- `title`
+- `price`, `price_text`
+- `mall_text`
+- `url`
+- `image_url`
+- `spec`
+
+### `offers`
+
+```json
+{
+  "pcode": "...",
+  "title": "...",
+  "source_url": "...",
+  "count": 0,
+  "normal_count": 0,
+  "conditional_count": 0,
+  "offers": [],
+  "meta": { "sort": "total_price" }
+}
+```
+
+`offers[]`는 **배송비 포함 실구매가(`total_price`) 오름차순**으로 정렬된다. `count` / `normal_count` / `conditional_count`는 `limit` 적용 후 실제 반환된 `offers[]` window 기준이다. 결제조건(현금/쿠폰/포인트/할인/특정카드/멤버십 한정)이 붙은 row도 같은 정렬에 그대로 참여한다 — 가장 싸면 1위로 올라온다. 결제조건은 분리 그룹이나 추가 필터링 없이 row 단위 `payment_badges` / `payment_condition_types` / `payment_condition_label` / `cash_only` / `point_only` / `coupon_only` / `card_only_badge` / `discount_badge` / `membership_badge` / `is_conditional_price` 필드로 노출한다. 호출자는 사용자의 결제 수단에 따라 직접 판단한다.
+
+각 `offers[]` 주요 필드:
+
+- `mall`
+- `price`, `price_text`
+- `shipping`
+- `is_free_shipping`
+- `shipping_fee`
+- `total_price`, `total_price_text`
+- `card_price`, `card_price_text`
+- `card_name`
+- `card_discount`, `card_discount_text`
+- `installment`
+- `installment_detail`
+- `payment_badges` — Danawa가 가격 옆에 노출한 결제조건 배지의 표시 라벨 목록. 배지 텍스트가 비어 있고 `.ico.cash`처럼 클래스만 있는 경우도 정규화 라벨을 합성한다 (예: `["현금"]`, `["포인트"]`, `["쿠폰"]`, `["카드"]`, `["할인"]`, `["멤버십"]`)
+- `payment_condition_types` — 화이트리스트 배지를 정규화한 조건 타입 목록 (`cash`/`point`/`coupon`/`card`/`discount`/`membership`)
+- `payment_condition_label` — 사용자 응답용 결제조건 라벨 (예: `현금`, `할인`, `멤버십`, 복수 조건이면 `현금, 할인`)
+- `cash_only` — 현금 결제 전용가
+- `point_only` — 포인트 차감 적용가
+- `coupon_only` — 쿠폰 적용가
+- `card_only_badge` — 특정 카드 한정 노출가
+- `discount_badge` — 할인 조건 배지 노출가
+- `membership_badge` — 멤버십 조건 배지 노출가
+- `is_conditional_price` — `payment_condition_types`가 하나 이상 있으면 True. **일반 결제가가 아니므로 카드 일반 결제 시 가격이 다르거나 불가능할 수 있음**
+- `url`
+
+항상 무료배송 여부, 배송비 포함 실구매가, 카드별 할인 가격, 무이자 할부 문구, **그리고 `payment_badges`/`payment_condition_label`/`is_conditional_price`를 함께 확인한다.** 조건부 가격을 일반가처럼 1위로 노출하면 비교 결과가 거짓이 된다.
+
+### `compare`
+
+`compare`는 검색 결과를 먼저 가져온 뒤 각 후보 상품에 대해 `offers[]`를 best-effort로 붙인다. 검색 결과가 애매하면 상위 후보의 제목과 `pcode`를 먼저 보여주고 선택을 요청한다.
+
+## Response style
+
+Discord/Telegram/chat 응답에서는 표 형식을 우선한다.
+
+```md
+| 순위 | 판매처 | 상품가 | 결제조건 | 배송 | 실구매가 | 카드할인가 | 무이자 | 링크 |
+|---:|---|---:|---|---|---:|---:|---|---|
+| 1 | 킴스클럽 | 979,000원 | **현금 전용** | 유/무료 | 979,000원 | - | - | 보기 |
+| 2 | 롯데ON | 1,073,890원 | 일반 | 무료배송 | 1,073,890원 | - | - | 보기 |
+| 3 | G마켓 | 1,089,590원 | 일반 | 무료배송 | 1,089,590원 | - | 최대 24개월 | 보기 |
+| 4 | 옥션 | 1,121,780원 | **쿠폰 적용가** | 무료배송 | 1,121,780원 | 우리카드 303,720원 | 최대 24개월 | 보기 |
+```
+
+정렬 기준:
+
+1. **`total_price` 오름차순 단일 기준.** 결제조건(현금/쿠폰/포인트/할인/특정카드/멤버십 한정)이 붙은 row도 같은 정렬에 그대로 참여한다 — 가장 싸면 1위로 올라온다. 결제조건은 분리 그룹화하지 않고 표의 "결제조건" 컬럼에 행별로 표시한다 (`payment_condition_label`이 있으면 그 값을 우선 표시, 없으면 "일반"; 세부 매핑은 `cash` → "현금 전용", `coupon` → "쿠폰 적용가", `point` → "포인트 적용가", `card` → 카드명/카드 조건, `discount` → "할인 조건", `membership` → "멤버십 조건"). 사용자는 자기 결제 수단에 따라 직접 판단한다.
+2. `card_price`가 있고 카드 적용 시 승자가 바뀌면 표 아래에 "카드 기준 최저가"를 별도로 적는다.
+3. 무이자 할부는 결제 조건이 달라질 수 있으므로 Danawa 노출 문구 기준이라고 밝힌다.
+4. 1위가 조건부 가격이면 요약 문장에 결제수단 단서를 짧게 덧붙인다. 예: "**최저 실구매가: 킴스클럽 979,000원 / 현금 결제 한정**, 카드 결제 기준 최저가는 롯데ON 1,073,890원". 카드 결제 가능한 최저가도 같이 알려 사용자가 결제수단별 결과를 한 번에 비교할 수 있게 한다.
+
+요약 예시:
+
+```md
+최저 실구매가: G마켓 217,950원 / 무료배송
+카드 기준 최저가: 옥션 우리카드 303,720원
+무이자: G마켓·옥션 최대 24개월 표기
+```
+
+카드 할인 markup이 없으면 "카드 할인가 표기 없음"이라고 쓰고, 체크아웃 할인 자체가 없다고 단정하지 않는다.
+
+## Workflow
+
+1. 검색어를 확인한다.
+2. `python scripts/danawa_search.py search "<검색어>" --limit 5`로 후보를 확인한다.
+3. 후보가 명확하면 해당 `pcode`로 `offers`를 실행한다.
+4. 후보가 애매하면 상위 3~5개 상품명/가격/`pcode`를 보여주고 선택을 요청한다.
+5. 오퍼는 **`total_price` 오름차순 단일 기준으로 정렬한다 (결제조건 분리 그룹화하지 않음).** 결제조건은 표의 "결제조건" 컬럼과 row 단위 플래그로만 표기하고, 1위가 현금/쿠폰가여도 그대로 1위로 노출한다.
+6. 카드 할인가가 있으면 카드 기준 최저가도 별도 요약한다. 1위가 조건부 가격이면 "카드 결제 기준 최저가"도 요약 문장에 함께 적어 결제수단별 최저가를 한 번에 알게 한다.
+7. 조회 시점 기준이며 가격/배송/카드 혜택은 변동될 수 있음을 짧게 덧붙인다.
+
+## Failure modes
+
+- 검색 결과가 0개면 검색어를 더 구체화한다.
+- Danawa HTML/AJAX 구조가 바뀌면 selector가 깨져 `offers`가 비거나 필드가 누락될 수 있다.
+- 다나와가 새로운 결제조건 배지 클래스나 문구를 도입하면 결제조건 배지 화이트리스트(`cash`/`point`/`coupon`/`discount`/`card`/`membership` 클래스, `현금`/`포인트`/`쿠폰`/`할인`/`카드`/`멤버십` 텍스트 키워드)와 `payment_condition_types`/`payment_condition_label` 매핑을 함께 갱신해야 한다.
+- 검색 결과 가격과 오퍼 AJAX 가격은 갱신 시점·카드가·제휴 링크 기준 차이로 다를 수 있다.
+- 카드 할인과 무이자 문구는 Danawa가 노출한 경우에만 확정적으로 보여준다.
+- 공개 표면 기반이므로 고빈도 요청에는 throttling/backoff를 추가해야 한다.
+- 접근 차단이나 CAPTCHA가 나오면 우회를 시도하지 말고 실패 모드로 보고한다.
+
+## Done when
+
+- 검색어 또는 모델명을 확인했다.
+- 상품 후보를 최소 1개 이상 반환하거나, 반환 실패 이유를 설명했다.
+- 쇼핑몰별 상품가, 배송비, 실구매가, 카드 할인가, 무이자 문구를 조회 시점 기준으로 정리했다.
+- 사용자 응답은 표 형식으로 제공했다.
+- 로그인/구매/차단 우회 범위를 벗어나지 않았다.