@nomadamas/k-skill 0.1.0

package/skills/jobkorea-talent-search/scripts/jobkorea_talent_parse.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import html
+import re
+import urllib.parse
+
+from jobkorea_talent_models import BASE_URL, Candidate
+
+ACTION_CONTROL_RE = re.compile(
+    r"^(?:스크랩\s*\d*|저장하기|닫기|포지션\s*제안|메모하기|프로필\s*확인|이력서\s*확인|펼쳐보기|접기|이전|다음)$"
+)
+ACTION_CONTROL_INLINE_RE = re.compile(
+    r"(?:스크랩\s*\d+|저장하기|닫기|포지션\s*제안|메모하기|프로필\s*확인|이력서\s*확인|펼쳐보기|접기|이전|다음)"
+)
+RESUME_LINK_RE = re.compile(r'href="(?P<href>/corp/person/find/resume/view\?rNo=(?P<rno>\d+))"')
+
+
+def clean_text(value: str) -> str:
+    value = html.unescape(value)
+    value = re.sub(r"<script[\s\S]*?</script>", " ", value, flags=re.I)
+    value = re.sub(r"<style[\s\S]*?</style>", " ", value, flags=re.I)
+    value = re.sub(r"<[^>]+>", " ", value)
+    value = re.sub(r"[ \t\r\f\v]+", " ", value)
+    value = re.sub(r"\n\s*\n+", "\n", value)
+    return value.strip()
+
+
+def is_action_control_label(value: str) -> bool:
+    label = re.sub(r"\s+", " ", html.unescape(value)).strip()
+    return bool(label and ACTION_CONTROL_RE.match(label))
+
+
+def filter_action_control_text(value: str) -> str:
+    lines = []
+    for line in value.splitlines():
+        label = line.strip()
+        if not label or is_action_control_label(label):
+            continue
+        label = ACTION_CONTROL_INLINE_RE.sub(" ", label)
+        label = re.sub(r"\s+", " ", label).strip()
+        if label:
+            lines.append(label)
+    return "\n".join(lines).strip()
+
+
+def row_contains_other_resume(candidate_markup: str, rno: str) -> bool:
+    refs: list[str] = []
+    for href_rno, data_rno in re.findall(r"rNo=(\d+)|data-rno=[\"'](\d+)[\"']", candidate_markup):
+        refs.append(href_rno or data_rno)
+    return any(ref != rno for ref in refs)
+
+
+def extract_regex_candidate_markup(markup: str, match: re.Match[str], rno: str) -> str:
+    row_start = markup.rfind("<tr", 0, match.start())
+    if row_start >= 0:
+        row_open_end = markup.find(">", row_start, match.start())
+        row_end = markup.find("</tr>", match.end())
+        row_open = markup[row_start : row_open_end + 1] if row_open_end >= 0 else ""
+        if row_end >= 0 and f'data-rno="{rno}"' in row_open:
+            return markup[row_start : row_end + len("</tr>")]
+
+    booth_start = markup.rfind('<div class="booth"', 0, match.start())
+    if booth_start >= 0:
+        next_booth = markup.find('<div class="booth"', match.end())
+        section_end = markup.find("</section>", match.end())
+        end_candidates = [pos for pos in (next_booth, section_end) if pos >= 0]
+        booth_end = min(end_candidates) if end_candidates else min(len(markup), match.end() + 2500)
+        booth = markup[booth_start:booth_end]
+        if not row_contains_other_resume(booth, rno):
+            return booth
+
+    start = max(0, match.start() - 300)
+    end = min(len(markup), match.end() + 1200)
+    return markup[start:end]
+
+
+def parse_with_bs4(markup: str, limit: int) -> list[Candidate] | None:
+    try:
+        from bs4 import BeautifulSoup
+    except ImportError:
+        return None
+
+    soup = BeautifulSoup(markup, "html.parser")
+    candidates: list[Candidate] = []
+    seen: set[str] = set()
+
+    for link in soup.select('a[href*="/corp/person/find/resume/view?rNo="]'):
+        raw_href = link.get("href", "")
+        href = raw_href if isinstance(raw_href, str) else ""
+        matched_rno = re.search(r"rNo=(\d+)", href)
+        if not matched_rno:
+            continue
+        rno = matched_rno.group(1)
+        if rno in seen:
+            continue
+        seen.add(rno)
+
+        container = (
+            link.find_parent("tr", attrs={"data-rno": rno})
+            or link.find_parent(class_=re.compile(r"(^|\s)booth(\s|$)", re.I))
+            or link.parent
+        )
+        if container and row_contains_other_resume(str(container), rno):
+            container = link.parent
+
+        raw = clean_text(str(container)) if container else clean_text(str(link))
+        texts = []
+        for node in container.find_all(["dt", "dd", "p", "span", "li"]) if container else []:
+            label = node.get_text(" ", strip=True)
+            if label and not is_action_control_label(label):
+                texts.append(label)
+        for btn in container.select(".keywordSkill button, .keywordBox button") if container else []:
+            label = btn.get_text(" ", strip=True)
+            if label and not is_action_control_label(label):
+                texts.append(label)
+        text_join = " | ".join(dict.fromkeys(texts))
+
+        name_scope = container.select_one(".nameAge") if container else None
+        dt = (name_scope or container).find("dt") if container else None
+        name = dt.get_text(" ", strip=True) if dt else ""
+        dd = dt.find_next("dd") if dt else None
+        meta = dd.get_text(" ", strip=True) if dd else ""
+        if not name:
+            m_name = re.search(r"([가-힣A-Za-z]OO)\s*\(([^)]*)\)", raw)
+            if m_name:
+                name = m_name.group(1)
+                meta = "(" + m_name.group(2) + ")"
+
+        skills = []
+        for btn in container.select(".keywordSkill button, .keywordBox button") if container else []:
+            label = btn.get_text(" ", strip=True)
+            if label and not is_action_control_label(label):
+                skills.append(label)
+
+        career_node = container.select_one(".career") if container else None
+        candidates.append(
+            Candidate(
+                rno=rno,
+                url=urllib.parse.urljoin(BASE_URL, href),
+                name=name,
+                meta=meta,
+                career=career_node.get_text(" ", strip=True) if career_node else "",
+                skills=", ".join(skills[:25]),
+                raw_summary=filter_action_control_text(text_join[:1000] or raw[:1000]),
+            )
+        )
+        if len(candidates) >= limit:
+            break
+    return candidates
+
+
+def parse_with_regex(markup: str, limit: int) -> list[Candidate]:
+    candidates: list[Candidate] = []
+    seen: set[str] = set()
+    for match in RESUME_LINK_RE.finditer(markup):
+        rno = match.group("rno")
+        if rno in seen:
+            continue
+        seen.add(rno)
+        raw_markup = extract_regex_candidate_markup(markup, match, rno)
+        raw = clean_text(raw_markup)
+        name = ""
+        meta = ""
+        name_match = re.search(r"([가-힣A-Za-z]OO)\s*\(([^)]*)\)", raw)
+        if name_match:
+            name = name_match.group(1)
+            meta = "(" + name_match.group(2) + ")"
+        candidates.append(
+            Candidate(
+                rno=rno,
+                url=urllib.parse.urljoin(BASE_URL, match.group("href")),
+                name=name,
+                meta=meta,
+                raw_summary=filter_action_control_text(raw[:1000]),
+            )
+        )
+        if len(candidates) >= limit:
+            break
+    return candidates
+
+
+def parse_candidates(markup: str, limit: int) -> list[Candidate]:
+    parsed = parse_with_bs4(markup, limit)
+    if parsed is not None:
+        return parsed
+    return parse_with_regex(markup, limit)

package/skills/jobkorea-talent-search/scripts/jobkorea_talent_search.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Search public JobKorea talent summaries.
+
+This helper uses JobKorea's browser-visible corporate talent search page and its
+same AJAX endpoint. It only reads public/obfuscated list summaries. Full resume
+view, contact details, scraping at scale, scrap/bookmark, and position proposal
+flows are intentionally out of scope because they require an employer account,
+paid entitlements, or user confirmation.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.error
+from dataclasses import asdict
+
+from jobkorea_talent_models import Candidate
+from jobkorea_talent_parse import clean_text, parse_candidates
+from jobkorea_talent_search_condition import build_search_condition, post_search
+
+__all__ = ["parse_candidates"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Search public JobKorea talent summaries")
+    parser.add_argument("--keyword", "-k", action="append", default=[], help="통합검색 키워드. 여러 번 지정 가능")
+    parser.add_argument("--and-keyword", action="append", default=[], help="AND 키워드")
+    parser.add_argument("--or-keyword", action="append", default=[], help="OR 키워드")
+    parser.add_argument("--exclude-keyword", action="append", default=[], help="제외 키워드")
+    parser.add_argument("--job-category", action="append", default=[], help="직무 대분류명 예: AI·개발·데이터")
+    parser.add_argument("--work-area", action="append", default=[], help="희망 근무지역 예: 서울, 강남구, 경기")
+    parser.add_argument("--residential-area", action="append", default=[], help="거주지역 예: 서울, 성남시 분당구")
+    parser.add_argument("--career-min", type=int, help="최소 경력 연수")
+    parser.add_argument("--career-max", type=int, help="최대 경력 연수")
+    parser.add_argument("--page", type=int, default=1)
+    parser.add_argument("--limit", type=int, default=20, choices=[10, 20, 30, 50, 100])
+    parser.add_argument("--sort", default="0", help="잡코리아 sf 정렬 코드. 기본 0")
+    parser.add_argument("--json", action="store_true", help="JSON으로 출력")
+    return parser
+
+
+def print_markdown(candidates: list[Candidate], matched: dict[str, list[str]], args: argparse.Namespace) -> None:
+    print("# 잡코리아 인재검색 결과\n")
+    print(f"- 검색어: {', '.join(args.keyword + args.and_keyword + args.or_keyword) or '(없음)'}")
+    print(f"- 제외어: {', '.join(args.exclude_keyword) or '(없음)'}")
+    if any(matched.values()):
+        print(f"- 매칭된 필터: {json.dumps(matched, ensure_ascii=False)}")
+    print(f"- 결과 수: {len(candidates)}")
+    print("- 주의: 이름/회사명은 잡코리아 공개 화면 기준으로 마스킹되어 있으며, 상세 이력서 확인·포지션 제안은 기업회원 로그인/권한/사용자 확인이 필요합니다.\n")
+    for idx, candidate in enumerate(candidates, 1):
+        c = candidate
+        bits = [c.name, c.meta, c.career]
+        title = " ".join(x for x in bits if x).strip() or f"rNo={c.rno}"
+        print(f"## {idx}. {title}")
+        print(f"- URL: {c.url}")
+        if c.skills:
+            print(f"- 키워드/스킬: {c.skills}")
+        summary = c.raw_summary.replace("\n", " ")
+        if summary:
+            print(f"- 요약: {summary[:500]}")
+        print()
+
+
+def run(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not (args.keyword or args.and_keyword or args.or_keyword or args.job_category or args.work_area or args.residential_area):
+        parser.error("최소 하나 이상의 --keyword, --job-category, --work-area 등을 지정하세요")
+
+    sc, matched = build_search_condition(args)
+    markup = post_search(sc)
+    cleaned = clean_text(markup)
+    if "로그인" in cleaned[:500] and "인재" not in cleaned[:2000]:
+        raise RuntimeError("잡코리아가 로그인/차단 화면을 반환했습니다")
+    candidates = parse_candidates(markup, args.limit)
+
+    if args.json:
+        print(json.dumps({"matched_filters": matched, "candidates": [asdict(c) for c in candidates]}, ensure_ascii=False, indent=2))
+    else:
+        print_markdown(candidates, matched, args)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(run())
+    except urllib.error.HTTPError as exc:
+        print(f"HTTP error: {exc.code} {exc.reason}", file=sys.stderr)
+        raise SystemExit(2)
+    except (RuntimeError, urllib.error.URLError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        raise SystemExit(1)

package/skills/jobkorea-talent-search/scripts/jobkorea_talent_search_condition.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import argparse
+import json
+import urllib.parse
+import urllib.request
+from collections.abc import Iterator
+from typing import Any
+
+from jobkorea_talent_models import AJAX_PATH, BASE_URL, DEFAULT_UA, FIND_PATH
+
+
+def fetch(url: str, *, data: bytes | None = None, headers: dict[str, str] | None = None) -> str:
+    req_headers = {"User-Agent": DEFAULT_UA, "Referer": BASE_URL + FIND_PATH}
+    if headers:
+        req_headers.update(headers)
+    req = urllib.request.Request(url, data=data, headers=req_headers, method="POST" if data else "GET")
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return resp.read().decode("utf-8", "ignore")
+
+
+def extract_json_object(source: str, marker: str) -> dict[str, Any]:
+    idx = source.find(marker)
+    if idx < 0:
+        raise RuntimeError(f"cannot find marker: {marker}")
+    start = source.find("{", idx)
+    if start < 0:
+        raise RuntimeError("cannot find JSON object start")
+    depth = 0
+    in_string = False
+    escape = False
+    for pos in range(start, len(source)):
+        ch = source[pos]
+        if in_string:
+            if escape:
+                escape = False
+            elif ch == "\\":
+                escape = True
+            elif ch == '"':
+                in_string = False
+            continue
+        if ch == '"':
+            in_string = True
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                loaded = json.loads(source[start : pos + 1])
+                if not isinstance(loaded, dict):
+                    raise RuntimeError("search condition was not a JSON object")
+                return loaded
+    raise RuntimeError("unterminated JSON object")
+
+
+def iter_nodes(node: Any) -> Iterator[dict[str, Any]]:
+    if isinstance(node, dict):
+        yield node
+        for value in node.values():
+            yield from iter_nodes(value)
+    elif isinstance(node, list):
+        for item in node:
+            yield from iter_nodes(item)
+
+
+def mark_matching_nodes(sc: dict[str, Any], top_key: str, labels: list[str]) -> list[str]:
+    if not labels:
+        return []
+    section = sc.get(top_key)
+    if section is None:
+        return []
+    wanted = [x.strip().lower() for x in labels if x.strip()]
+    matched: list[str] = []
+    for node in iter_nodes(section):
+        title = str(node.get("t", ""))
+        code = str(node.get("v", ""))
+        title_l = title.lower()
+        code_l = code.lower()
+        if any(w == title_l or w == code_l or w in title_l for w in wanted):
+            for key in ("s", "c", "use"):
+                if key in node:
+                    node[key] = 1
+            matched.append(title or code)
+    return matched
+
+
+def build_search_condition(args: argparse.Namespace) -> tuple[dict[str, Any], dict[str, list[str]]]:
+    first = fetch(BASE_URL + FIND_PATH)
+    sc = extract_json_object(first, "var searchcondition =")
+
+    sc["p"] = args.page
+    sc["ps"] = args.limit
+    sc["saveno"] = 0
+    sc["ff"] = 0
+    sc["sf"] = args.sort
+
+    terms: list[dict[str, Any]] = []
+    for kw in args.keyword:
+        terms.append({"s": 1, "c": 1, "t": kw, "v": kw, "kwdtypecode": 1, "logictypecode": 0})
+    for kw in args.and_keyword:
+        terms.append({"s": 1, "c": 1, "t": kw, "v": kw, "kwdtypecode": 1, "logictypecode": 1})
+    for kw in args.or_keyword:
+        terms.append({"s": 1, "c": 1, "t": kw, "v": kw, "kwdtypecode": 1, "logictypecode": 3})
+    for kw in args.exclude_keyword:
+        terms.append({"s": 1, "c": 1, "t": kw, "v": kw, "kwdtypecode": 1, "logictypecode": 2})
+    sc["totalkeywordlist"] = terms
+
+    if terms:
+        first_kw = terms[0]["t"]
+        sc.setdefault("pfr", {}).setdefault("ck", {})["Keyword"] = first_kw
+        sc["pfr"]["ck"]["KeywordType"] = 1
+        sc["pfr"]["n"] = 1
+
+    if args.career_min is not None:
+        sc.setdefault("career", {})["s"] = str(args.career_min)
+    if args.career_max is not None:
+        sc.setdefault("career", {})["e"] = str(args.career_max)
+
+    matched = {
+        "job_category": mark_matching_nodes(sc, "jobtype", args.job_category),
+        "work_area": mark_matching_nodes(sc, "workarea", args.work_area),
+        "residential_area": mark_matching_nodes(sc, "residentialarea", args.residential_area),
+    }
+    return sc, matched
+
+
+def post_search(sc: dict[str, Any]) -> str:
+    body = urllib.parse.urlencode({"searchCondition": json.dumps(sc, ensure_ascii=False)}).encode()
+    return fetch(
+        BASE_URL + AJAX_PATH,
+        data=body,
+        headers={
+            "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+            "X-Requested-With": "XMLHttpRequest",
+        },
+    )

package/skills/jobkorea-talent-search/scripts/test_jobkorea_talent_search.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Fixture tests for JobKorea public fallback parsing."""
+from __future__ import annotations
+
+import importlib.util
+import sys
+import unittest
+from pathlib import Path
+
+SCRIPT = Path(__file__).with_name("jobkorea_talent_search.py")
+sys.path.insert(0, str(SCRIPT.parent))
+spec = importlib.util.spec_from_file_location("jobkorea_talent_search", SCRIPT)
+assert spec is not None
+helper = importlib.util.module_from_spec(spec)
+sys.modules["jobkorea_talent_search"] = helper
+assert spec.loader is not None
+spec.loader.exec_module(helper)
+
+
+FALLBACK_FIXTURE = """
+<section class="searchList">
+  <table class="tblSearchList">
+    <tbody>
+      <tr class="dvResumeTr" data-rno="111">
+        <td class="tdProfile">
+          <dl class="nameAge"><dt><a class="dvResumeLink" href="/corp/person/find/resume/view?rNo=111" data-rno="111">김OO</a></dt><dd>(여, 만 29세)</dd></dl>
+          <ul class="bullList"><li>25분전 공고 스크랩</li></ul>
+        </td>
+        <td class="tdSummary">
+          <div class="userInfoBox">
+            <span class="career">경력 4년</span>
+            <p class="title"><a class="dvResumeLink" href="/corp/person/find/resume/view?rNo=111" data-rno="111">퍼포먼스 마케터</a></p>
+            <div class="keywordSkill keywordBox">
+              <button type="button" class="js-kwrdSearch">Google Analytics</button>
+              <button type="button" class="js-kwrdSearch">GA4</button>
+            </div>
+          </div>
+        </td>
+        <td class="tdAction">
+          <button>스크랩 1</button><button>이력서 확인</button><button>포지션 제안</button><button>메모하기</button><button>저장하기</button><button>닫기</button>
+        </td>
+      </tr>
+      <tr class="dvResumeTr" data-rno="222">
+        <td class="tdProfile">
+          <dl class="nameAge"><dt><a class="dvResumeLink" href="/corp/person/find/resume/view?rNo=222" data-rno="222">박OO</a></dt><dd>(남, 만 31세)</dd></dl>
+        </td>
+        <td class="tdSummary">
+          <span class="career">경력 6년</span>
+          <p class="title"><a class="dvResumeLink" href="/corp/person/find/resume/view?rNo=222" data-rno="222">브랜드 마케터</a></p>
+          <div class="keywordSkill keywordBox"><button type="button" class="js-kwrdSearch">브랜딩</button></div>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</section>
+"""
+
+
+class JobKoreaFallbackParserTest(unittest.TestCase):
+    def test_parser_keeps_each_candidate_inside_its_own_row(self) -> None:
+        candidates = helper.parse_candidates(FALLBACK_FIXTURE, 10)
+
+        self.assertEqual([c.rno for c in candidates], ["111", "222"])
+        self.assertEqual(candidates[0].name, "김OO")
+        self.assertIn("Google Analytics", candidates[0].raw_summary)
+        self.assertIn("GA4", candidates[0].raw_summary)
+        self.assertNotIn("박OO", candidates[0].raw_summary)
+        self.assertNotIn("브랜딩", candidates[0].raw_summary)
+        self.assertNotIn("저장하기", candidates[0].raw_summary)
+        self.assertNotIn("닫기", candidates[0].raw_summary)
+        self.assertNotIn("포지션 제안", candidates[0].raw_summary)
+        self.assertNotIn("이력서 확인", candidates[0].raw_summary)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/jobkorea-talent-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "jobkorea-talent-search",
+  "description": "잡코리아 기업회원 로그인 세션으로 유료 열람 전 마스킹된 인재 이력서를 검색·비교해 채용 검토용 shortlist를 만듭니다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "browser",
+    "action:communication"
+  ],
+  "frontmatter": "name: jobkorea-talent-search\ndescription: 잡코리아 기업회원 로그인 세션으로 유료 열람 전 마스킹된 인재 이력서를 검색·비교해 채용 검토용 shortlist를 만듭니다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: recruiting\n  locale: ko-KR\n  phase: v1"
+}

package/skills/joseon-sillok-search/instruction.md

@@ -0,0 +1,76 @@
+# 조선왕조실록 검색
+
+## What this skill does
+
+국사편찬위원회 조선왕조실록 사이트(`https://sillok.history.go.kr`)에서 **공식 검색 결과 HTML과 기사 상세 페이지를 직접 읽어** 조선왕조실록 기록을 찾는다.
+
+v1 범위는 단순 스크래핑이다.
+
+- 키워드 검색
+- 선택적 왕별 필터(`--king`)
+- 선택적 서기 연도 필터(`--year`)
+- 검색 결과 제목/요약/원문 링크 정리
+- 기사 상세 페이지에서 국역/원문 excerpt 추출
+
+## When to use
+
+- "조선왕조실록에서 훈민정음 찾아줘"
+- "세종 때 실록에서 측우기 관련 기사 검색해줘"
+- "1443년 조선왕조실록 기록 찾아줘"
+- "정조실록에서 수원 관련 기록 몇 개 보여줘"
+
+## Prerequisites
+
+- 인터넷 연결
+- `python3`
+- 별도 API 키 없음
+- 설치된 skill payload 안에 `scripts/sillok_search.py` helper가 함께 들어 있다.
+
+## Inputs
+
+- 필수: 검색어
+- 선택: 왕 이름 (`세종`, `정조`, `세종실록` 등)
+- 선택: 서기 연도 (`1443` 같이 Gregorian year)
+- 선택: 결과 수 (`--limit`)
+- 선택: 검색 타입 (`--type k|w`)
+  - `k`: 국역 검색
+  - `w`: 원문 검색
+
+## Workflow
+
+1. `python3 scripts/sillok_search.py --query "..."` 로 공식 검색 endpoint를 호출한다.
+2. 검색 결과 HTML에서 결과 수, 왕별 분류, 기사 링크, 요약을 파싱한다.
+3. 필요하면 `--king`, `--year` 로 결과를 추가로 좁힌다.
+4. 선택된 기사마다 `/id/<article_id>` 상세 페이지를 열어 국역/원문 excerpt를 가져온다.
+5. 구조화된 JSON으로 반환한다.
+
+## CLI examples
+
+```bash
+python3 scripts/sillok_search.py --query "훈민정음"
+python3 scripts/sillok_search.py --query "훈민정음" --king "세종" --year 1443 --limit 3
+python3 scripts/sillok_search.py --query "측우기" --king "세종실록" --limit 5
+python3 scripts/sillok_search.py --query "임진왜란" --type w --limit 5
+```
+
+## Response policy
+
+- 결과는 공식 실록 사이트에서 확인한 **기사 제목 + 링크 + 요약 + 상세 excerpt** 중심으로 답한다.
+- `--year` 는 서기 연도 기준으로 필터링한다.
+- 입력한 왕 이름은 `세종`, `세종실록`처럼 조금 달라도 canonical 왕명으로 정규화한다.
+- v1 에서는 semantic search, embedding, 대규모 색인 구축을 하지 않는다.
+- 결과가 없으면 억지로 추정하지 말고 빈 결과를 그대로 알려준다.
+
+## Done when
+
+- 공식 사이트에서 실제 검색 결과가 1건 이상 조회되었다.
+- 필요 시 왕/연도 필터가 적용되었다.
+- 적어도 하나 이상의 기사 detail excerpt가 포함되었다.
+- 링크가 `https://sillok.history.go.kr/id/...` 형태로 정리되었다.
+
+## Notes
+
+- 공식 메인: `https://sillok.history.go.kr`
+- 검색 endpoint: `https://sillok.history.go.kr/search/searchResultList.do`
+- 기사 상세: `https://sillok.history.go.kr/id/<article_id>`
+- 이 저장소 v1 은 공개 HTML 표면만 사용한다.