court-auction-notice-search基于 WebSquare XHR 直连与 Playwright 兜底的韩国法院不动产拍卖公告查询方案【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本文围绕 k-skill 仓库中的court-auction-notice-search技能技能指令位于 instruction.md对应 npm 包源码位于 packages/court-auction-notice-search系统讲解如何让 Agent 在没有官方 OPEN API 的前提下将韩国法院官方「법원경매정보courtauction.go.kr」网站的不动产拍卖公告매각공고与案件信息以结构化 JSON 的形式稳定、合规地取回。读完本文你将掌握五种内部 XHR 端点的直接 HTTP 调用方式、三层浏览器兜底runtime CDP → 本地 Playwright的触发条件、IP 级反爬护栏调用间隔 jitter、会话预算、ipcheck阻断识别以及 Node.js API 与 CLI 两条使用路径并理解为什么这个技能被设计为“慢即是快”的 read-only 工具。技能定位无官方 API 下的“合规最近邻”方案court-auction-notice-search是 k-skill 仓库中面向韩国不动产司法拍卖的专项技能其 skill.json 元数据skill.json将其归类为real-estate类别、ko-KR语言环境、v1 阶段并以 Read-only, slow-by-design (~2s/call) to avoid IP blocks 作为核心设计约束。该技能解决的现实问题是法院拍卖信息网没有对外提供的官方 OPEN API因此包内通过逆向其页面内部使用的WebSquare JSON XHR 接口来完成数据获取。这一点在指令文档中有明确说明也是整个实现的事实基础。具体来说courtauction.go.kr是一个基于 WebSquare 框架构建的站点所有列表/详情/检索动作都通过形如/pgj/pgj143/*.on的 JSON 端点完成——包内将这些端点按用途封装为以下五个见 src/transport/http.js 的ENDPOINT_PATHS常量用途方法与路径请求体核心键拍卖公告列表POST /pgj/pgj143/selectRletDspslPbanc.ondma_srchDspslPbanc.{srchYmd, cortOfcCd, bidDvsCd, srchBtnYn:Y}拍卖公告详情案件/物件展开POST /pgj/pgj143/selectRletDspslPbancDtl.ondma_srchGnrlPbanc.{cortOfcCd, dspslDxdyYmd, jdbnCd, ...}案件单件查询POST /pgj/pgj15A/selectAuctnCsSrchRslt.ondma_srchCsDtlInf.{cortOfcCd, csNo}物件自由条件检索POST /pgj/pgjsearch/searchControllerMain.ondma_pageInfodma_srchGdsDtlSrchInfocanonical body法院事务所代码全量POST /pgj/pgjComm/selectCortOfcCdLst.on{}其中自由条件检索的 canonical 请求体dma_pageInfodma_srchGdsDtlSrchInfo结构是 2026-05-08 通过真实浏览器提交捕获见 scripts/capture-pgj151-submit.cjs并固化在测试夹具 canonical-search-body.json 中用于请求构造的回归验证。需要强调的是该技能默认无需真实浏览器即可运行拍卖公告、案件、物件查询的正常路径全部走直接 HTTP浏览器只在 Workflow C 自由检索遭遇 WAF 型 HTTP 400 时作为兜底登场。同时站点对 IP 的机器人拦截非常激进文档记载约 16 次/30 秒即可触发 1 小时封禁因此包内采用“保守三件套”调用间最小 2 秒 jitter、会话内调用预算默认 10 次、data.ipcheck false立即抛错停止。输入参数date / courtCode / bidType / caseNumber技能的输入集中在四个字段语义与校验规则在 src/index.js 中均有对应实现date必填——拍卖期日支持YYYY-MM/YYYYMM月份或YYYY-MM-DD/YYYYMMDD特定日。注意一个关键设计网站实际搜索按钮是按月YYYYMM查询的因此传入特定日时实现会先查当月、再按dspslDxdyYmd过滤出该日的公告。测试 index.test.js 明确验证了“请求体始终携带srchYmd: 202604再按精确日过滤”的行为date: 2026-04-27得到 2 条结果而date: 2026-04-28在同月结果中过滤出 0 条。courtCode——法院事务所代码格式为B000210 首尔中央地方法院可通过getCourtCodes()或 CLI 的codes courts动态获取留空表示不按法院过滤。校验正则^B\d{6}$src/index.js。bidType——投标区分date 기일입찰代码000331或period 기간입찰代码000332空值表示两种都查。解析逻辑支持别名/代码/韩文名三种输入并 fail-opensrc/codetables/index.js完整映射见 bid-types.json。caseNumber——案件编号推荐2024타경100001格式2024-100001、2024_100001等变体会被自动规范化为2024타경100001src/index.js。三个核心工作流A公告→案件/物件、B案件号直查、C自由条件检索指令文档定义了三条工作流分别对应三种查询入口Workflow A——拍卖公告 → 案件/物件展开。先以searchSaleNotices({ date, courtCode, bidType })拿到公告卡片列表用户选中卡片后将卡片对象或其raw字段原样传给getSaleNoticeDetail(notice)。响应中的items[]每条包含caseNumber、usage、address、appraisedPrice、minimumSalePrice、remarks六个字段——注意这里的appraisedPrice鉴定评估价与minimumSalePrice最低拍卖价均为韩元整型展示给用户时应同时给出韩式千分位逗号与 억/만 单位换算。规格化逻辑见 src/normalize.js。Workflow B——按案件号直查。调用getCaseByCaseNumber({ courtCode, caseNumber })。若返回found:false / status:204说明案件不存在或未公开应向用户复核案件号格式与法院是否匹配若found:true则响应会填充caseInfo案件名·受理日·请求金额·裁判部·进行状态、items[]拍卖目的物——地址/分配请求权申报期限、schedule[]各拍卖期日的最低拍卖价/鉴定价/结果、claimDeadline、relatedCases、stakeholders等结构化字段规格化见 src/normalize.js。其中schedule[]的resultCode字段可直接用于判断“유찰流拍”历史——这正是“유찰 1 次以上”这类用户诉求的数据来源。Workflow C——不动产物件自由条件检索。这是条件最丰富的入口输入映射在 buildPropertySearchBody 中逐项实现支持维度包括region: { sido, sigungu, dong }——sido 可用代码11或韩文名서울특별시解析代表静态表有 19 个市道只要提供了任意地区信息请求体即切换为地番地址检索模式cortStDvs:2否则使用公告模式cortStDvs:1。市郡区/邑面洞因上游级联 XHR 不稳定而未纳入静态表直接传原始代码如{ sido:11, sigungu:11680, dong:11680101 }。usage: { large, medium, small }——5 位上游代码如20000건물或大分类韩文名토지/건물/차량및운송장비/기타。resolveUsageCode采用严格层级匹配若输入名称在别的层级才存在例如아파트在 medium/small 层级都有同名代码不会静默返回错误层级的代码而是 fail-open 原样透传让上游报错而非悄悄查错src/codetables/index.js。priceRange最低拍卖价韩元允许小数、appraisedPriceRange鉴定评估价韩元、saleDate: { from, to }、flbdCount: { min, max }流拍次数仅接受整数、area: { min, max }面积 ㎡允许小数、pageSize必须为10/20/50/100之一默认 10——传1等任意值会被上游以 HTTP 400 拒绝因此客户端在本地就拦截。请求体另外固定携带mvprpRletDvsCd:00031R、cortAuctnSrchCondCd:0004601、pgmId:PGJ151F01、statNum:1等站点要求的常量以及notifyLoc:off见 src/index.js。Workflow C 的响应会做一层“上游韩文原始列 → 英文键”的归一化src/normalize.js覆盖saNo→caseNumber、srnSaNo/printCsNo→displayCaseNumber、hjguSidohjguSiguhjguDongdaepyoLotnobuldNm→address、gamevalAmt→appraisedPrice、minmaePrice→minimumSalePrice、yuchalCnt→flbdCount、mulStatcd→statusCode、jinstatCd→progressStatusCode、boCd→courtCode、jiwonNm→courtName、lcl/mcl/sclUtilCd→usageCodes.{large,medium,small}、xCordi/yCordi→coordinates、wgs84Xcordi/Ycordi→coordinatesWgs84、buldList/areaList/jimokList→buildingList/areaList/landCategoryList、pjbBuldList→propertyDescription、mulBigo→remarks等。三层传输直接 HTTP → runtime CDP → 本地 Playwright这是本技能最值得展开的架构设计。直接 HTTP 客户端CourtAuctionHttpClientsrc/transport/http.js的每次调用都遵循固定的“会话协议”Warmup暖机——首次调用前先以 GET 访问对应该端点的页面/pgj/index.on?w2xPath...完成会话 Cookie 的建立通过set-cookie收集进 cookieJar后续 POST 请求头会带上Cookie、Referer按端点分别指向 PGJ143M01/PGJ159M00/PGJ151F00 页面、Origin、X-Requested-With: XMLHttpRequest等真实浏览器语义头。Budget 检查——会话内调用数达到maxCallsPerSession默认 10即抛BUDGET_EXCEEDED两次调用之间按minDelayMs jitter(0~jitterMs)的随机值等待默认 2000ms 0~1000ms。响应判读——非 2xx 抛UPSTREAM_ERROR附带statusCode响应体errors.errorMessage存在抛UPSTREAM_ERRORdata.ipcheck false抛BLOCKED并立即停止绝不自动重试src/transport/http.js。CourtAuctionPlaywrightClientsrc/transport/playwright.js与 HTTP 客户端保持相同的postJson(endpointKey, body)签名但页面内通过page.evaluate中的fetch发起同源 POST。它的浏览器获取路径是平台感知的三级优先级Runtime 浏览器首选——通过k-skill-browser-runtime连接用户已运行的浏览器会话macOS 上依次尝试 Aside Browser REPL → BrowserOS GUI CDP → Chrome/Chromium CDP其他平台优先 BrowserOS。可用provider/cdpUrl选项或KSKILL_BROWSER_PROVIDER/KSKILL_BROWSEROS_CDP_URL/KSKILL_ASIDE_COMMAND环境变量选择。本地 Playwright launch——若 runtime provider 全部不可达UNAVAILABLE/探针失败则用rebrowser-playwright或playwright-core的chromium.launch({ headless })直接拉起本地浏览器。关键的安全性设计通过 runtime/CDP 连接的浏览器是用户自有财产兜底结束时只清理本适配器创建的 page/context/tab 并断开自动化客户端runtime.disconnectBrowser绝不关闭用户的浏览器应用只有本地 launch 的浏览器才会被整体 close。而PLAYWRIGHT_UNAVAILABLE模块未安装与UNKNOWN_PROVIDER配置了错误的 provider则 fail-closed 立即抛错不静默降级src/transport/playwright.js。Workflow C 的 fallback 触发条件非常克制仅限两种情况src/index.js直接 HTTP 遭遇WAF 型 HTTP 400UPSTREAM_ERROR且statusCode 400遭遇BLOCKEDipcheckfalse且用户明确传入fallbackOnBlocked: true默认不降级因为ipcheckfalse是站点的显式封禁信号盲目换通道反而会加剧风险。此外searchProperties连续使用同一 Playwright 客户端调用时在 10~15 次间隔调用内保持稳定若需要更高频的突发调用文档建议在调用间插入 3~5 秒 sleep 并新建客户端。代码表bid-types / usage-codes / region-codes技能内置三张静态代码表src/codetables/其中法务事务所代码表为动态加载codes courts走getCourtCodes()实时获取覆盖 60 个法院bid-types기일입찰000331别名date、기간입찰000332别名period见 bid-types.json。usage-codes4 个大分类10000토지、20000건물、30000차량및운송장비、40000기타从上游selectLclLst.on响应捕获外加部分代表性中/小分类。region-codes19 个市道代码韩文名从上游selectAdongSdLst.on捕获市郡区/邑面洞未纳入。所有代码表解析均遵循fail-open 原则未知代码原样透传交由上游决定成败绝不静默改写。对应测试见 index.test.js验证了resolveBidTypeCode(date)→000331、resolveBidTypeCode(기일입찰)→000331、resolveBidTypeCode(000999)→000999fail-open等行为。限流与调用预算规则指令文档明确了四条不可违背的护栏它们同时是源码中ensureBudget()的实现逻辑src/transport/http.js调用间最小 2 秒默认minDelayMs: 2000如需更保守可传--min-delay-ms 3000或构造new CourtAuctionHttpClient({ minDelayMs: 3000 })。会话预算默认 10 次。超出时抛BUDGET_EXCEEDED确有更多查询需求时应新建会话new CourtAuctionHttpClient或显式调高maxCallsPerSessionCLI 对应--max-calls 20但必须同时向用户说明封禁风险。遇data.ipcheck false立即抛BLOCKED并停止不自动重试避免延长封禁。被封禁的 IP 大约 1 小时后自然恢复等待期间可换 IP/网络或由用户用浏览器访问站点通过解封画面。Workflow C 自由检索对 raw HTTP 更严格站点 WAF 拦截故searchProperties()仅对 WAF 型 HTTP 400 启用 Playwright 兜底fallbackOnBlocked: true需用户明确授权未安装rebrowser-playwright/playwright-core时第一次 HTTP 400 失败会直接抛出。Node.js 使用示例包的主入口是 src/index.js完整 API 面包括searchSaleNotices、getSaleNoticeDetail、getCaseByCaseNumber、searchProperties、getCourtCodes、getBidTypes、getUsageCodes、getRegionCodes、resolveBidTypeCode、CourtAuctionHttpClient、CourtAuctionPlaywrightClient等。以下为指令文档给出的可运行示例const { searchSaleNotices, getSaleNoticeDetail, getCaseByCaseNumber, getCourtCodes } require(court-auction-notice-search); async function main() { const courts await getCourtCodes(); console.log(법원사무소 ${courts.count}개 로드됨); const notices await searchSaleNotices({ date: 2026-04-27, courtCode: B000210, bidType: date }); console.log(서울중앙지방법원 매각공고 ${notices.count}건); if (notices.items.length 0) { const detail await getSaleNoticeDetail(notices.items[0]); for (const item of detail.items) { console.log( ${item.caseNumber} (${item.usage}) — 감정 ${item.appraisedPrice}원 / 최저 ${item.minimumSalePrice}원 ); console.log( 주소: ${item.address}); } } const caseInfo await getCaseByCaseNumber({ courtCode: B000210, caseNumber: 2024타경100001 }); if (caseInfo.found) { console.log(사건명: ${caseInfo.caseInfo.caseName}); console.log(매각기일 횟수: ${caseInfo.schedule.length}); } } main().catch((error) { if (error.code BLOCKED) { console.error([BLOCKED] 사이트가 1시간 차단했습니다. 다른 IP에서 다시 시도하거나 1시간 뒤 재시도하세요.); } else { console.error(error); } process.exitCode 1; });一个重要的调用细节getSaleNoticeDetail的入参最省事的方式是直接把searchSaleNotices返回的列表项对象传进去——函数会自动提取其raw字段src/index.js若没有raw也可以手动提供{ courtCode, saleDate, judgeDeptCode }键值其中judgeDeptCode即上游加密令牌jdbnCd必须来自列表响应缺失时函数会明确报错提示。CLI 使用示例包通过 bin 暴露同名命令court-auction-notice-searchpackage.json参数解析与子命令实现在 src/cli.js# 1. 법원사무소 코드표 court-auction-notice-search codes courts --pretty | head -40 # 2. 입찰구분 (정적 코드) court-auction-notice-search codes bid-types --pretty court-auction-notice-search codes usages --pretty court-auction-notice-search codes regions --pretty # 3. 매각공고 목록 court-auction-notice-search notices --date 2026-04 --court-code B000210 --bid-type date --pretty # 4. 매각공고 상세 — list 응답의 row 의 raw 필드를 그대로 detail 호출에 사용한다. # (CLI 단발 호출에서는 list - detail 으로 결과를 파이프할 수 있도록 jq 등을 함께 사용) # 5. 사건번호 직접 조회 court-auction-notice-search case --court-code B000210 --case-number 2024타경100001 --pretty # 6. 자유 조건검색 court-auction-notice-search search --sido 서울특별시 --sigungu 11680 --usage-large 건물 --usage-medium 21200 \ --price-min 100000000 --price-max 500000000 --sale-from 2026-05-01 --sale-to 2026-05-20 --prettyCLI 的全局参数还包括--json默认输出 JSON、--include-rawfalse剥离raw透传字段、--timeout-ms默认 15000、--min-delay-ms默认 2000、--max-calls默认 10。search子命令还支持--region 시도[:시군구[:읍면동]]冒号三元组缩写、--usage 대[:중[:소]]缩写、--appraised-min/--appraised-max鉴定评估价区间、--flbd-min/--flbd-max流拍次数、--area-min/--area-max面积、--page、--page-size等参数src/cli.js。错误模型与处理规范技能定义了五类可编程错误码调用方应据此决定交互策略error.code BLOCKED——data.ipcheck false站点已按 IP 封禁。等待约 1 小时后换 IP 重试并把封禁事实与等待指引原样告知用户。error.code BUDGET_EXCEEDED——会话调用预算耗尽。这是有意的安全设计确有必要时用--max-calls 20之类调高但需同步提示封禁风险。error.code UPSTREAM_ERROR——站点返回一般性错误。会话过期或jdbnCd错误是最常见原因应从 warmup 重新开始。error.code NETWORK_ERROR——超时/连接失败error.cause携带原始错误。error.code PLAYWRIGHT_UNAVAILABLE——需要显式使用 Playwright 兜底但模块未安装用npm i rebrowser-playwright或npm i playwright-core解决。诚实性框架为什么必须反复强调“仅供参考”指令文档将以下四条列为强制告知义务Mandatory honest framing这也对应包 README 中 What this is (and isnt) 的边界声明README.md数据是法院拍卖信息网站公开信息的照搬实际投标前必须再次核实法院原文拍卖公告。站点对自动化调用高度敏感快速连续查询可能导致 IP 被封锁约 1 小时。价格鉴定评估价/最低拍卖价、拍卖期日、拍卖场所以公告发布时点为准可能因更正、撤回、延期而变化——应提醒用户参考响应中的correctionCount、cancellationCount字段。本技能是read-only的不自动化投标本身。投标必须由人在法院现场完成。同样明确的是技能“不做”的边界动产汽车/工程机械拍卖不在 v1 范围按日期批量拉取全部法院日程Workflow D、公开拍卖物件照片 URL、下载物件明细书/现状调查书/鉴定评估书 PDF 均为后续跟进议题不提供投标书自动填写与自动提交。完成判定Done whenAgent 使用该技能完成任务时应满足以下收尾条件已向用户告知 IP 封禁风险与“仅供参考·投标前须核对法院原文公告”已展开拍卖公告并返回含caseNumber/usage/address/appraisedPrice/minimumSalePrice的结构化 JSON按案件号直查时若found:false已给出后续行动指引遇封禁立即停止且不自动重试并在任务结束后明确告知用户剩余调用预算为追加查询留出余地。小结court-auction-notice-search是一套在“无官方 API 站点强反爬”双重约束下打磨出的务实方案用内部 WebSquare XHR 端点替代官方 API、用 warmup/Referer/Cookie 模拟真实浏览器会话、用 jitter 与预算把流量压到站点容忍阈值之下、用三层浏览器兜底吸收 WAF 不确定性再用 fail-open 与 fail-closed 双重策略守住“宁可不查也不乱查”的正确性底线。从技能指令instruction.md、包源码src/index.js到回归测试test/index.test.js仓库内部形成了一条完整、可审计的证据链可供后续接入真实业务或继续扩展 Workflow D 时参考。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考