@clazic/urban 0.2.8 → 0.2.10

package/src/agent/skills/nanet.js

@@ -0,0 +1,485 @@
+/**
+ * 국회도서관 (NANET) 수집 플러그인
+ *
+ * prism-dl/src/nanet-api.js 를 ESM + Skill 클래스로 포팅
+ * - 쿠키 기반 ssotoken 세션 관리
+ * - HTML 검색 결과 파싱
+ * - rate limiting (요청 간 1초)
+ */
+import { Agent, fetch, request } from 'undici';
+import { Skill } from './base.js';
+import { normalizeNanetItem } from './_normalize.js';
+import { getSecureConfig } from '../../kb/db.js';
+
+const BASE_URL = 'https://www.nanet.go.kr';
+const DL_BASE_URL = 'https://dl.nanet.go.kr';
+const URLS = {
+  loginForm: `${BASE_URL}/loginForm.do`,
+  loginProc: `${BASE_URL}/newLoginProc.do`,
+  pdfInfoList: `${DL_BASE_URL}/search/getPDFInfoList.do`,
+  searchInnerList: `${DL_BASE_URL}/search/searchInnerList.do`,
+  fileDownload: `${DL_BASE_URL}/file/fileDownload.do`,
+};
+const HEADERS = {
+  'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+  Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+  'Accept-Language': 'ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7',
+};
+const JSON_HEADERS = {
+  ...HEADERS,
+  'Content-Type': 'application/json',
+  Accept: 'application/json, text/javascript, */*; q=0.01',
+  'X-Requested-With': 'XMLHttpRequest',
+};
+
+const SESSION_TTL_MS = 25 * 60 * 1_000; // 25분
+const REQUEST_DELAY_MS = 1_000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const PAGE_SIZE = 50;
+
+// ── 인증 정보 로드 ────────────────────────────────────────────────────
+
+function loadCredentials() {
+  // DB 우선 조회 (설정 UI에서 저장한 값)
+  try {
+    const dbUserId = getSecureConfig('source.nanet.userId');
+    const dbPassword = getSecureConfig('source.nanet.password');
+    if (dbUserId && dbPassword) return { userId: dbUserId, password: dbPassword };
+  } catch { /* DB 미초기화 시 무시 */ }
+
+  // 환경변수 폴백
+  const userId = process.env.NANET_USER_ID;
+  const password = process.env.NANET_USER_PW;
+  if (userId && password) return { userId, password };
+
+  throw new Error('NANET 인증정보가 없습니다. 설정 화면에서 아이디/비밀번호를 입력하거나 ~/.urban/.env 를 확인하세요.');
+}
+
+// ── 세션 클래스 ──────────────────────────────────────────────────────
+
+class NanetSession {
+  constructor() {
+    this._agent = new Agent({
+      connect: { rejectUnauthorized: false, connectTimeout: 15_000 },
+      connections: 5,
+      pipelining: 1,
+      keepAliveTimeout: 30_000,
+      keepAliveMaxTimeout: 60_000,
+    });
+    this._ssotoken = null;
+    this._loginTime = null;
+    this._lastRequestTime = 0;
+    this._dlSessionReady = false;
+    this._dlCookies = '';
+    this._credentials = null;
+  }
+
+  get isExpired() {
+    return !this._loginTime || Date.now() - this._loginTime > SESSION_TTL_MS;
+  }
+
+  async _throttle() {
+    const elapsed = Date.now() - this._lastRequestTime;
+    if (elapsed < REQUEST_DELAY_MS)
+      await new Promise(r => setTimeout(r, REQUEST_DELAY_MS - elapsed));
+    this._lastRequestTime = Date.now();
+  }
+
+  async login() {
+    if (this._ssotoken && !this.isExpired) return;
+    if (!this._credentials) this._credentials = loadCredentials();
+    const { userId, password } = this._credentials;
+
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+    try {
+      const { statusCode, headers, body: resBody } = await request(URLS.loginProc, {
+        method: 'POST',
+        headers: {
+          ...HEADERS,
+          'Content-Type': 'application/x-www-form-urlencoded',
+          Referer: URLS.loginForm,
+        },
+        body: new URLSearchParams({ userId, password }).toString(),
+        dispatcher: this._agent,
+        signal: ctrl.signal,
+        maxRedirections: 0,
+      });
+
+      await resBody.dump().catch(() => {});
+
+      const rawCookies = headers['set-cookie'];
+      const cookieList = Array.isArray(rawCookies) ? rawCookies : rawCookies ? [rawCookies] : [];
+      let ssotoken = null;
+      for (const c of cookieList) {
+        const m = c?.match(/ssotoken=([^;]+)/i);
+        if (m) { ssotoken = m[1]; break; }
+      }
+      if (!ssotoken)
+        throw new Error(`NANET 로그인 실패: ssotoken 없음 (HTTP ${statusCode}). 아이디/비밀번호 확인 필요.`);
+
+      this._ssotoken = ssotoken;
+      this._loginTime = Date.now();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  cookieHeader() { return `ssotoken=${this._ssotoken}`; }
+
+  invalidate() {
+    this._loginTime = null;
+    this._ssotoken = null;
+    this._dlSessionReady = false;
+    this._dlCookies = '';
+  }
+
+  async ensureDlSession() {
+    if (this._dlSessionReady) return;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+    let res;
+    try {
+      res = await fetch(`${DL_BASE_URL}/`, {
+        headers: { ...HEADERS, Cookie: this.cookieHeader() },
+        dispatcher: this._agent,
+        signal: ctrl.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const setCookies = res.headers.getSetCookie?.() ?? [];
+    const map = {};
+    for (const p of this._dlCookies.split(';')) {
+      const [k, v] = p.split('=').map(s => s.trim());
+      if (k && v) map[k] = v;
+    }
+    for (const sc of setCookies) {
+      const m = sc.match(/^([^=]+)=([^;]*)/);
+      if (m) map[m[1].trim()] = m[2].trim();
+    }
+    this._dlCookies = Object.entries(map).map(([k, v]) => `${k}=${v}`).join('; ');
+    await res.text();
+    this._dlSessionReady = true;
+  }
+
+  allCookies() {
+    return this._dlCookies ? `${this.cookieHeader()}; ${this._dlCookies}` : this.cookieHeader();
+  }
+
+  async close() { await this._agent.close(); }
+}
+
+let _session = null;
+function getSession() {
+  if (!_session) _session = new NanetSession();
+  return _session;
+}
+
+/** 인증정보 변경 시 기존 세션 무효화 (server.js에서 호출) */
+export function invalidateNanetSession() {
+  if (_session) _session.invalidate();
+}
+
+// ── HTML 파싱 ─────────────────────────────────────────────────────────
+
+function parseSearchHtml(html) {
+  const items = [];
+  const pattern = /searchInnerDetail\('([A-Z0-9]+)'[^)]*\)\s*"?\s*>\s*([\s\S]*?)<\/a>/gi;
+
+  for (const match of html.matchAll(pattern)) {
+    const controlNo = match[1];
+    const preceding = html.slice(Math.max(0, match.index - 800), match.index);
+    if (!preceding.includes('li_wrap')) continue;
+
+    const rawTitle = match[2].replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    const afterStart = match.index + match[0].length;
+    const nextDetail = html.indexOf("searchInnerDetail('", afterStart);
+    const rawChunk = html.slice(afterStart, nextDetail > 0 ? nextDetail : afterStart + 2000);
+    // 버튼/액션 영역 이전까지만 메타 추출 (원문보기·다운로드 버튼 텍스트 제외)
+    const btnCut = rawChunk.search(/<button|li_buttom_wrap|btn_bd_blue/);
+    const afterChunk = btnCut > 0 ? rawChunk.slice(0, btnCut) : rawChunk;
+    const metaParts = afterChunk.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim()
+      .split('|').map(s => s.trim()).filter(Boolean);
+
+    let publishYear = '';
+    for (const p of metaParts) {
+      if (/^\d{4}$/.test(p)) { publishYear = p; break; }
+    }
+    const yearIdx = metaParts.findIndex(p => p === publishYear);
+    let publisher = '';
+    if (yearIdx >= 2) publisher = metaParts[yearIdx - 1];
+    else if (metaParts.length >= 3) publisher = metaParts[2];
+
+    // publisher·year 외 나머지 메타(저자, 주제 등)를 description으로
+    const skipIdx = new Set([yearIdx, yearIdx - 1].filter(i => i >= 0));
+    const description = metaParts
+      .filter((p, i) => !skipIdx.has(i) && !/^\d+p$|^PDF$|^v\.\d/i.test(p))
+      .join(' · ');
+
+    // 다운로드 버튼 onclick에서 pdfCount 추출 (rawChunk 사용 — 버튼 태그 포함 전체 범위)
+    // 실제 JS: count==1 → itemNo 없이 바로 다운로드, count>1 → getPDFInfoList로 선택
+    // 다운로드 버튼 자체가 없으면 pdfCount=0 (서울관 실물소장 등 원문 미제공)
+    let pdfCount = 0;
+    const dlBtnMatch = rawChunk.match(new RegExp(`downloadDoc\\(this,\\s*'${controlNo}',\\s*'(\\d+)'`));
+    if (dlBtnMatch) pdfCount = parseInt(dlBtnMatch[1], 10);
+
+    // 다운로드 버튼 없는 항목(실물소장·열람전용) 제외
+    if (pdfCount === 0) continue;
+
+    items.push({ controlNo, title: rawTitle, publisher, publishYear, description, pdfCount });
+  }
+
+  const totalMatch = html.match(/전체\s*\(\s*([\d,]+)\s*\)/) || html.match(/총\s*([\d,]+)\s*건/);
+  const totalCount = totalMatch ? Number(totalMatch[1].replace(/,/g, '')) : items.length;
+  return { totalCount, items };
+}
+
+// ── API 함수 ──────────────────────────────────────────────────────────
+
+async function fetchPDFInfoList(controlNo) {
+  const session = getSession();
+  await session.login();
+  await session._throttle();
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+  try {
+    const res = await fetch(URLS.pdfInfoList, {
+      method: 'POST',
+      headers: {
+        ...JSON_HEADERS,
+        Cookie: session.cookieHeader(),
+        Referer: `${DL_BASE_URL}/search/searchInnerDetail.do`,
+      },
+      body: JSON.stringify({ controlNo }),
+      dispatcher: session._agent,
+      signal: ctrl.signal,
+    });
+    const text = await res.text();
+    if (!res.ok) return [];
+    // HTTP 200이어도 HTML 응답이면 세션 만료로 간주 (prism-dl nanetFetchJson 동일 로직)
+    if (text.startsWith('<!') || text.startsWith('<html') || text.includes('loginForm')) {
+      session.invalidate();
+      throw new Error('NANET 세션 만료: 서버가 HTML 페이지를 반환했습니다');
+    }
+    try {
+      const json = JSON.parse(text);
+      const list = json.pdfList || json.list || json.data || json;
+      if (!Array.isArray(list)) return [];
+      return list.map(item => ({
+        itemNo: String(item.itemNo || item.ITEM_NO || item.seq || '1'),
+        fileName: item.fileName || item.FILE_NM || item.orgFileNm || `${controlNo}.pdf`,
+        fileSize: Number(item.fileSize || item.FILE_SZ || item.fileSz || 0),
+      }));
+    } catch { return []; }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function searchPage(query, { pageNo = 1 } = {}) {
+  const session = getSession();
+  await session.login();
+  await session._throttle();
+  await session.ensureDlSession();
+
+  // 브라우저 실제 URL 파라미터 (searchMehtod=L, 전체 자료유형)
+  const params = new URLSearchParams({
+    searchType: 'INNER_SEARCH', resultType: 'INNER_SEARCH_LIST',
+    searchMehtod: 'F', searchClass: 'S',
+    controlNo: '',
+    queryText: `${query}:ALL_NI_TOC:AND`,
+    prevQueryText: `${query}:ALL_NI_TOC:AND`,
+    zone: 'ALL_NI_TOC',
+    fieldText: '', prevPubYearFieldText: '', languageCode: '',
+    synonymYn: '', refineSearchYn: '', ddcPopSearchYn: '',
+    pageNum: pageNo <= 1 ? '' : String(pageNo),
+    pageSize: String(PAGE_SIZE),
+    orderBy: 'WEIGHT',
+    topMainMenuCode: '', topSubMenuCode: '',
+    totalSize: '', totalSizeByMenu: '', seqNo: '',
+    hanjaYn: 'Y',
+    knowPub: '', isdb: '', isdbsvc: '', tt1: '', down: '',
+    frgnLangMtrlYn: '', targetLangCode: '',
+    checkedDbIdList: '', baseDbId: '', selectedDbIndexIdList: '',
+    caller: '', asideState: '',
+    dpBranch: 'ALL', journalKind: '', degreeDiv: '',
+    selZone: 'ALL_NI_TOC',
+    searchQuery: query,
+  });
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${URLS.searchInnerList}?${params}`, {
+      method: 'GET',
+      headers: { ...HEADERS, Cookie: session.allCookies(), Referer: URLS.searchInnerList.replace('/searchInnerList.do', '/') },
+      dispatcher: session._agent,
+      signal: ctrl.signal,
+    });
+    const html = await res.text();
+    if (!res.ok) throw new Error(`NANET 검색 HTTP ${res.status}`);
+    if (html.includes('오류가 발생했습니다') && html.length < 5000)
+      throw new Error('NANET 서버 오류 페이지');
+    return parseSearchHtml(html);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── Skill 클래스 ──────────────────────────────────────────────────────
+
+export class NanetSkill extends Skill {
+  static manifest = {
+    id: 'nanet',
+    name: '국회도서관 (NANET)',
+    version: '1.0.0',
+    defaultCron: '0 3 * * *',
+    defaultKeywords: [
+      '도시계획', '도시재생', '주거정책', '교통계획', '환경계획', '스마트시티',
+      '도시개발', '토지이용계획', '공간계획', '주택공급',
+    ],
+    rateLimit: { rps: 1, burst: 1 },
+    requiredEnv: [], // 인증정보는 설정창(secure_config) 또는 ~/.urban/.env 환경변수 폴백
+    capabilities: ['discover', 'download', 'normalize', 'search'],
+  };
+
+  get meta() {
+    return {
+      sessionTtlMs: SESSION_TTL_MS,
+      minRequestIntervalMs: REQUEST_DELAY_MS,
+      earlyStopConsecutiveEmpty: 5,
+      supportsRangeRequest: false,
+    };
+  }
+
+  async ensureSession() {
+    await getSession().login();
+  }
+
+  /** 세션 강제 무효화 — HTML 응답 감지 시 downloader가 호출 */
+  invalidateSession() {
+    getSession().invalidate();
+  }
+
+  async discover({ keywords = [], limit = 50 }) {
+    const results = [];
+    const seen = new Set();
+
+    for (const kw of keywords) {
+      if (results.length >= limit) break;
+      try {
+        const { items } = await searchPage(kw);
+        for (const searchItem of items) {
+          if (results.length >= limit) break;
+          // PDF 목록 조회
+          const pdfFiles = await fetchPDFInfoList(searchItem.controlNo);
+          const files = pdfFiles.length > 0 ? pdfFiles : [null];
+          for (const pdfFile of files) {
+            const item = normalizeNanetItem(searchItem, pdfFile, kw);
+            if (!seen.has(item.docid)) {
+              seen.add(item.docid);
+              results.push(item);
+            }
+          }
+        }
+      } catch (err) {
+        console.warn(`[nanet] discover 오류 (${kw}): ${err.message}`);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * 단일 쿼리로 NANET 검색 (UI 실시간 검색용)
+   * PDF 목록 조회 없이 빠르게 검색 결과만 반환
+   */
+  async search(query, { limit = 20 } = {}) {
+    const { items } = await searchPage(query);
+    const seenDocid = new Set();
+    const seenFile = new Set();
+    return items
+      .map(item => normalizeNanetItem(item, null, query))
+      .filter(item => {
+        const fileKey = `${item.fileName}|${item.fileSize}`;
+        if (seenDocid.has(item.docid) || seenFile.has(fileKey)) return false;
+        seenDocid.add(item.docid);
+        seenFile.add(fileKey);
+        return true;
+      })
+      .slice(0, limit);
+  }
+
+  async openDownloadResponse(item, { signal } = {}) {
+    const session = getSession();
+    await session.login();
+    await session._throttle();
+    await session.ensureDlSession();
+
+    const { controlNo, linkSystemId = 'NADL' } = item;
+    if (!controlNo) throw new Error(`NANET 다운로드: controlNo 없음 (docid=${item.docid})`);
+
+    // NANET JS 동작 재현:
+    //   count == 1 → downloadBySingleCount(controlNo) → itemNo 없이 직접 다운로드
+    //   count > 1  → getPDFInfoList → downloadItem(controlNo, itemNo) → itemNo 포함
+    const pdfCount = Number(item.pdfCount ?? 1);
+    let itemNo = item.itemNo || '';
+
+    if (pdfCount === 0) {
+      throw Object.assign(
+        new Error(`NANET 원문 미제공: 실물소장 또는 열람전용 자료입니다 (controlNo=${controlNo})`),
+        { nonRetryable: true, reason: 'link_missing' }
+      );
+    }
+
+    if (!itemNo) {
+      if (pdfCount > 1) {
+        // 다중 파일: getPDFInfoList로 첫 번째 itemNo 획득 (브라우저의 팝업 → 첫 항목 자동 선택)
+        const pdfFiles = await fetchPDFInfoList(controlNo);
+        if (pdfFiles.length > 0) {
+          itemNo = pdfFiles[0].itemNo;
+        } else {
+          throw Object.assign(
+            new Error(`NANET 원문 없음: PDF 목록 조회 실패 (controlNo=${controlNo})`),
+            { nonRetryable: true, reason: 'link_missing' }
+          );
+        }
+      }
+      // pdfCount == 1: itemNo 없이 바로 다운로드 (downloadBySingleCount 동작과 동일)
+    }
+
+    let url = `${URLS.fileDownload}?linkSystemId=${encodeURIComponent(linkSystemId)}&controlNo=${encodeURIComponent(controlNo)}`;
+    if (itemNo) url += `&itemNo=${encodeURIComponent(itemNo)}`;
+
+    const ctrl = signal ? null : new AbortController();
+    const timer = ctrl ? setTimeout(() => ctrl.abort(), 300_000) : null;
+    try {
+      const res = await fetch(url, {
+        method: 'GET',
+        headers: {
+          ...HEADERS,
+          Cookie: session.allCookies(),
+          Referer: `${DL_BASE_URL}/search/searchInnerDetail.do`,
+        },
+        dispatcher: session._agent,
+        redirect: 'follow',
+        signal: signal ?? ctrl.signal,
+      });
+      if (res.status === 401) {
+        session.invalidate();
+        // 세션 만료는 재시도 허용 (cache 적재 X) — downloader 에서 nonRetryable 미지정 시 백오프 후 재시도
+        throw Object.assign(new Error('NANET 세션 만료'), { reason: 'session_expired' });
+      }
+      return res;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  normalize(searchItem, pdfFile = null, query = '') {
+    return normalizeNanetItem(searchItem, pdfFile, query);
+  }
+}
+
+export default NanetSkill;

package/src/agent/skills/prism.js

@@ -0,0 +1,150 @@
+/**
+ * PRISM (정책연구정보서비스) 수집 플러그인
+ *
+ * prism-dl/src/api.js 를 ESM + Skill 클래스로 포팅
+ * SSL 인증서 오류 대응: undici Agent { rejectUnauthorized: false }
+ */
+import { Agent, fetch } from 'undici';
+import { Skill } from './base.js';
+import { normalizePrismItem } from './_normalize.js';
+
+const SEARCH_URL = 'https://api.prism.go.kr/prism-be-prtl/search/totalSearch.do';
+const DOWNLOAD_URL = 'https://api.prism.go.kr/prism-be-asmt/v1/progress/download-file';
+const HEADERS = {
+  Origin: 'https://www.prism.go.kr',
+  Referer: 'https://www.prism.go.kr/homepage/prtl/totalsearch/list',
+  'Content-Type': 'application/json',
+  'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+};
+
+const dispatcher = new Agent({
+  connect: { rejectUnauthorized: false, connectTimeout: 15_000 },
+  connections: 10,
+  pipelining: 1,
+  keepAliveTimeout: 30_000,
+  keepAliveMaxTimeout: 60_000,
+});
+
+async function fetchJson(url, payload, { timeoutMs = 10_000, signal } = {}) {
+  const ctrl = signal ? null : new AbortController();
+  const timer = ctrl ? setTimeout(() => ctrl.abort(), timeoutMs) : null;
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: HEADERS,
+      body: JSON.stringify(payload),
+      dispatcher,
+      signal: signal ?? ctrl.signal,
+    });
+    const text = await res.text();
+    if (!res.ok) throw new Error(`PRISM HTTP ${res.status}: ${text.slice(0, 200)}`);
+    try { return JSON.parse(text); } catch { throw new Error(`PRISM JSON 파싱 실패: ${text.slice(0, 200)}`); }
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function searchPage(query, { startCount = 0, listCount = 100 } = {}) {
+  const json = await fetchJson(SEARCH_URL, {
+    query, collection: 'report',
+    startCount, listCount: Math.min(listCount, 1000),
+    jrsdInstGrntNo: '', hghrkFwkClsfSysId: '',
+    asmtOtln: '', kywdCn: '', rptpDtlCn: '', thssSmryCn: '',
+  });
+  const report = json.report || {};
+  return {
+    totalCount: Number(report.totalCount || 0),
+    items: Array.isArray(report.searchResultList) ? report.searchResultList : [],
+  };
+}
+
+export class PrismSkill extends Skill {
+  static manifest = {
+    id: 'prism',
+    name: '정책연구정보서비스 (PRISM)',
+    version: '1.0.0',
+    defaultCron: '0 2 * * *',
+    defaultKeywords: [
+      '도시계획', '도시재생', '주거', '교통', '환경', '스마트시티',
+      '토지이용', '도시정책', '공간정책', '주택정책',
+    ],
+    rateLimit: { rps: 1, burst: 3 },
+    requiredEnv: [],
+    capabilities: ['discover', 'download', 'normalize', 'search'],
+  };
+
+  /**
+   * 키워드 목록으로 PRISM 검색 → NormalizedItem 배열 반환
+   */
+  async discover({ keywords = [], limit = 50 }) {
+    const results = [];
+    const seen = new Set();
+
+    for (const kw of keywords) {
+      if (results.length >= limit) break;
+      try {
+        const { items } = await searchPage(kw, { listCount: Math.min(limit - results.length, 100) });
+        for (const raw of items) {
+          const item = this.normalize(raw, kw);
+          if (!seen.has(item.docid)) {
+            seen.add(item.docid);
+            results.push(item);
+          }
+        }
+      } catch (err) {
+        console.warn(`[prism] discover 오류 (${kw}): ${err.message}`);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * 단일 쿼리로 PRISM 검색 (UI 실시간 검색용)
+   * @param {string} query
+   * @param {{ limit?: number }} [options]
+   * @returns {Promise<object[]>} NormalizedItem 배열
+   */
+  async search(query, { limit = 20 } = {}) {
+    const { items } = await searchPage(query, { listCount: Math.min(limit, 100) });
+    const seenDocid = new Set();
+    const seenFile = new Set();
+    return items
+      .map(raw => this.normalize(raw, query))
+      .filter(item => {
+        const fileKey = `${item.fileName}|${item.fileSize}`;
+        if (seenDocid.has(item.docid) || seenFile.has(fileKey)) return false;
+        seenDocid.add(item.docid);
+        seenFile.add(fileKey);
+        return true;
+      });
+  }
+
+  async openDownloadResponse(item, { signal } = {}) {
+    const payload = {
+      asmtId: item.asmtId,
+      fileTypeCd: item.fileTypeCd,
+      fileSn: item.fileSn,
+      fileWkky: item.fileWkky,
+      pdfTrsfYn: item.pdfTrsfYn || 'Y',
+    };
+    const ctrl = signal ? null : new AbortController();
+    const timer = ctrl ? setTimeout(() => ctrl.abort(), 120_000) : null;
+    try {
+      return await fetch(DOWNLOAD_URL, {
+        method: 'POST',
+        headers: HEADERS,
+        body: JSON.stringify(payload),
+        dispatcher,
+        signal: signal ?? ctrl.signal,
+      });
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  normalize(rawItem, query = '') {
+    return normalizePrismItem(rawItem, query);
+  }
+}
+
+export default PrismSkill;