k-skill 实战解析：court-auction-notice-search——韩国法院不动产拍卖公告查询技能的架构、工作流与反爬防护

k-skill 实战解析court-auction-notice-search——韩国法院不动产拍卖公告查询技能的架构、工作流与反爬防护【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill导读本文围绕 k-skill 仓库中的court-auction-notice-search技能展开该技能将韩国大法院运营的官方「법원경매정보法院拍卖信息」网站courtauction.go.kr的不动产拍卖公告매각공고与案件信息转换为 Agent 可消费的结构化 JSON。文章完整继承快照指令文档 court-auction-notice-search.dolshoi.md 的全部内容并结合 指令文档、README 以及 源码实现 深入讲解三大查询工作流公告列表→案件/物件展开、案件号直查、自由条件检索、三层传输架构直接 HTTP → Runtime 浏览器 → 本地 Playwright、IP 级反爬防护下的限流与调用预算机制以及完整的 Node.js / CLI 实战用法。读完本文你将掌握如何在一个对自动化极其敏感、且没有公开 Open API 的政府站点上安全、合规、可复用地构建 read-only 数据查询能力。技能定位一个没有 Open API 的政府站点上的 read-only 客户端court-auction-notice-search的核心定位是把法院公开的拍卖公告与案件信息转成 Agent 能用的 JSON同时以慢即是稳为设计哲学规避 IP 封禁。快照文档开篇即点明几条关键事实官网没有公开 Open API因此该技能直接调用站点内部的WebSquare JSON XHR endpointWebSquare 是韩国政务站点常见的前端框架其查询按钮实际向后端提交结构化 JSON。一级传输通道是直接 HTTP매각공고拍卖公告、사건案件、물건物件查询的正常路径都不需要真实浏览器。浏览器只在Workflow C 自由条件检索遇到 WAF 型 HTTP 400时作为 fallback 使用推荐顺序为用户已打开的 BrowserOS/runtime CDP →够不到时Chrome CDP → 本地 Playwright launch。站点按 IP 进行非常激进的机器人拦截大约 16 次/30 秒就会触发 1 小时封禁因此本包采用调用间至少 2 秒 jitter、每会话调用预算默认 10 次、data.ipcheck false立即抛错等保守策略。这是参考用工具참고용实际投标前必须回到法院原始拍卖公告复核。这些设计决策在源码中有直接体现。例如 transport/http.js 中CourtAuctionHttpClient的默认值timeoutMs: 15000、minDelayMs: 2000、jitterMs: 1000、maxCallsPerSession: 10与文档描述完全对应请求头中设置了X-Requested-With: XMLHttpRequest、韩语Accept-Language: ko-KR,ko;q0.9,en;q0.8、按 endpoint 动态填充的Referer并在 postJson 中检测payload.data.ipcheck false时立即抛出BLOCKED错误。何时使用与何时不使用快照文档明确给出了使用边界这是 Agent 判断该不该调用本技能的依据应当使用When to use오늘/내일 어디서 부동산 경매 열려?今天/明天哪里有不动产拍卖서울중앙지방법원 2026-04-27 매각공고 보여줘首尔中央地方法院 2026-04-27 的拍卖公告기일입찰 vs 기간입찰만 나눠서 보여줘区分期日投标/期间投标이 매각공고 안의 사건번호/용도/주소/감정평가액 다 보여줘公告中的案件号/用途/地址/评估价사건번호 2024타경100001 진행 상황 알려줘案件 2024타경100001 的进展서울 강남구 아파트 최저가 5억 이하 유찰 1회 이상 물건 찾아줘首尔江南区、最低价 5 亿以下、流拍 1 次以上的物件법원사무소 코드 표 줘给我法院事务所代码表不应使用When not to use动产汽车·工程机械拍卖——不在 v1 范围内一次查询某特定拍卖日期所有法院的日程属于 Workflow D另列 follow-up 议题拍卖物件照片全景/概况/内部URL 暴露follow-up 议题拍卖物件明细书/现状调查书/评估书 PDF 下载follow-up 议题投标书自动填写、自动提交——明确不支持投标必须由人在法院完成。输入参数详解参数说明约束/默认date매각기일拍卖日期月YYYY-MM/YYYYMM或特定日YYYY-MM-DD/YYYYMMDD必填。实际站点搜索按钮按**月YYYYMM**查询因此特定日输入会在月查询结果中按该日过滤courtCode법원사무소코드法院事务所代码如B000210 首尔中央地方法院留空表示全部法院可通过getCourtCodes()或 CLIcodes courts获取bidType投标类型date 기일입찰 期日投标代码000331或period 기간입찰 期间投标代码000332空值表示两种都查caseNumber案件号推荐2024타경100001格式2024-100001也会被自动规范化为2024타경100001参数校验逻辑可在 index.js 中看到toNoticeSearchDate同时接受 6 位月与 8 位日输入ensureCourtCode强制B000210形式正则^B\d{6}$normalizeCaseNumber会把2024-100001、2024_100001、2024 100001统一转成2024타경100001。这意味着上游对输入格式的宽容度远高于用户直觉Agent 可以先做归一化再做请求。官方界面与内部 endpointOfficial surfaces技能所面向的官方页面与内部调用端点如下前两个是用户可手工访问的页面后五个是技能实际 POST 的 XHR endpoint法원경매정보 主页https://www.courtauction.go.kr부동산매각공고不动产拍卖公告入口https://www.courtauction.go.kr/pgj/index.on?w2xPath/pgj/ui/pgj100/PGJ143M01.xmlpgjId143M01경매사건검색拍卖案件搜索入口https://www.courtauction.go.kr/pgj/index.on?w2xPath/pgj/ui/pgj100/PGJ159M00.xmlpgjId159M00POST /pgj/pgj143/selectRletDspslPbanc.on— 拍卖公告列表POST /pgj/pgj143/selectRletDspslPbancDtl.on— 拍卖公告详情案件/物件展开POST /pgj/pgj15A/selectAuctnCsSrchRslt.on— 案件单条查询POST /pgj/pgjsearch/searchControllerMain.on— 物件自由条件检索PGJ151F00 → PGJ151M01POST /pgj/pgjComm/selectCortOfcCdLst.on— 全部法院事务所代码这些 endpoint 路径在源码 transport/http.js 中以ENDPOINT_PATHS常量集中定义并且每个 endpoint 都配了对应的ENDPOINT_REFERER_HINTReferer 提示与ENDPOINT_WARMUP_PATH预热路径。每次postJson前会先执行一次 warmup GET 来建立会话 Cookie——这对应文档中从 warmup 开始的错误排查提示。各 endpoint 的核心请求体字段README 的 Endpoints used 表格做了更细的记录目的请求体核心键拍卖公告列表dma_srchDspslPbanc.{srchYmd, cortOfcCd, bidDvsCd, srchBtnYn:Y}srchYmd与站点搜索按钮一致按月YYYYMM拍卖公告详情dma_srchGnrlPbanc.{cortOfcCd, dspslDxdyYmd, jdbnCd, ...}案件单条dma_srchCsDtlInf.{cortOfcCd, csNo}物件自由检索dma_pageInfo.{pageNo, pageSize, totalYn:Y, ...}dma_srchGdsDtlSrchInfo.{...}canonical body见 canonical-search-body.json由真实浏览器提交捕获法院事务所{}三大查询工作流Workflow A — 拍卖公告 → 案件/物件展开向用户收集**拍卖日期YYYY-MM-DD**与可选法院、投标区分。调用searchSaleNotices({ date, courtCode, bidType })→ 获得该日、该法院的拍卖公告卡片列表。用户选定卡片后把卡片对象或其raw原样传给getSaleNoticeDetail(notice)。响应中items[]含caseNumber、usage、address、appraisedPrice、minimumSalePrice、remarks即文档议题明确要求的全部字段。价格为韩元整数。向用户展示时应同时给出韩式千位逗号格式 亿/万单位换算。源码层面getSaleNoticeDetail的入参构造见 buildNoticeDetailBody它优先从列表行对象的raw中提取cortOfcCd、dspslDxdyYmd、jdbnCd法院的加密 token、bidDvsCd等字段——这正是文档强调把卡片对象或 raw原样传入的原因因为jdbnCd是列表响应中返回的加密令牌外部无法凭空构造。Workflow B — 案件号直接查询向用户收集法院事务所代码案件号2024타경100001。调用getCaseByCaseNumber({ courtCode, caseNumber })。若found:false / status:204说明案件不存在或非公开应请用户核对案件号格式与法院是否正确。若found:true返回结构化字段caseInfo案件名·受理日·请求金额·裁判部·进行状态、items[]拍卖目的物——地址/分配请求终期、schedule[]各拍卖日期的最低价/评估价/结果、claimDeadline、relatedCases、stakeholders。normalizeCaseDetailResponse见 normalize.js把原始响应展开成这份丰富的结构包括相关案件relatedCases、上诉/再上诉appeals、利害关系人stakeholders等子表足以支撑案件进展类的对话式追问。Workflow C — 不动产物件自由条件检索将用户条件映射到searchProperties()的输入region: { sido, sigungu, dong }— 代码或代表静态 sido 代码表中的韩语名。给了区域就走 지번주소 搜索cortStDvs:2不给区域就走拍卖公告模式cortStDvs:1。시군구/읍면동 没有静态表需直接传代码如{ sido:11, sigungu:11680, dong:11680101 }。usage: { large, medium, small }— 用途大/中/小分类代码5 位如 건물20000或大分类韩语名토지/건물/차량및운송장비/기타。priceRange— 最低拍卖价格韩元{ min, max }允许小数。appraisedPriceRange— 评估金额韩元{ min, max }允许小数。saleDate—{ from, to }。flbdCount— 流拍次数{ min, max }仅限整数。area— 面积㎡{ min, max }允许小数。pageSize— 每页结果数只能取upstream PGJ151 下拉框中确认过的10/20/50/100之一默认 10。1等任意值会让 live endpoint 返回 HTTP 400因此会在本地直接拒绝。请求体的构造逻辑集中在 buildPropertySearchBodypageSize通过toPositiveInt(..., { allowed: PAGE_SIZE_VALUES })强校验价格/面积区间通过rangeValue做数值校验flbdCount通过integerOnly: true强制整数。cortStDvs字段根据是否有 region 输入自动切换2地番地址搜索或1公告模式。Workflow C 的 raw 列名规范化响应中items[]将核心 raw 列转为英文键raw 列规范化键saNocaseNumbersrnSaNo/printCsNo→displayCaseNumbermokmulSer/maemulSeritemNumberhjguSido hjguSigu hjguDong daepyoLotno buldNmaddressgamevalAmt/minmaePriceappraisedPrice/minimumSalePriceyuchalCnt/mulStatcd/jinstatCdflbdCount/statusCode/progressStatusCodeboCd/jiwonNm/jpDeptNmcourtCode/courtName/judgeDeptNamelclsUtilCd/mclsUtilCd/sclsUtilCdusageCodes.{large,medium,small}srchHjguSidoCd/SiguCd/DongCdregionCodes.{sido,sigungu,dong}xCordi/yCordi/wgs84Xcordi/Ycordicoordinates/coordinatesWgs84buldList/areaList/jimokListbuildingList/areaList/landCategoryListpjbBuldList/mulBigopropertyDescription/remarks这张映射表在 normalizePropertySearchRow 中逐一实现且对同一字段提供了别名键如flbdCount与failedBidCount、buildings与buildingList方便不同调用方按习惯消费。代码表与 fail-open 设计getUsageCodes()静态返回 4 个大分类10000토지、20000건물、30000차량및운송장비、40000기타与部分代表中/小分类getRegionCodes()返回 19 个 시도市/道 代码。시군구/읍면동 因 upstream 的 cascade XHR 不稳定而未纳入静态表直接传 raw 代码即可。所有未知值fail-open 透传。特别地resolveUsageCode 实现了同名用途代码保护像resolveUsageCode(아파트, large)这样输入名只存在于其他层级时不会错误地返回同名 medium/small 代码而是 fail-open 透传原文避免静默污染请求体。三层传输架构与浏览器 fallback 规则searchProperties()默认先用 direct HTTP。浏览器 fallback 仅在以下两种条件下激活源码见 index.js 的 searchPropertiesWAF 型 HTTP 400UPSTREAM_ERRORstatusCode 400或BLOCKEDipcheckfalse且调用方显式传fallbackOnBlocked: true。若用{ fallback: false }可完全关闭自动 fallback。fallback 激活后浏览器连接的优先级为Runtime 浏览器首选— 通过k-skill-browser-runtime自动探测macOS 上依次尝试 Aside Browser REPL → BrowserOS GUI CDP → Chrome/Chromium CDP其他平台先试 BrowserOS。可通过providerbrowseros/aside/chrome-cdp、cdpUrl选项或KSKILL_BROWSER_PROVIDER、KSKILL_BROWSEROS_CDP_URL、KSKILL_ASIDE_COMMAND环境变量选择。本地 Playwright launch fallback— 所有 runtime provider 都不可达时用chromium.launch({ headless })本地启动浏览器。需要rebrowser-playwright或playwright-core均为 optionalDependency见 package.json。安全边界fallback 清理连到 runtime 的浏览器是用户自有的fallback 结束时只清理 adapter 创建的 page/context/tab并通过runtime.disconnectBrowser断开 automation client绝不关闭 BrowserOS/Aside/Chrome 的 profile本地 launch 的浏览器是本包自己启动的因此会完整关闭 page/context/browserPLAYWRIGHT_UNAVAILABLE模块未安装与UNKNOWN_PROVIDERprovider 名错误会fail-closed 立即抛错而UNAVAILABLE/probe 失败会自动降级到本地 launch不自动绕过 login/CAPTCHA/支付/电子签名/不可逆操作。限流与调用预算机制Throttling and call-budget rules这是本技能保守设计的核心快照文档与源码双重印证调用间最小 2 秒默认可用--min-delay-ms 3000调大。默认每会话预算 10 次调用。需要更多时开新会话new CourtAuctionHttpClient或显式调大maxCallsPerSession。遇到封禁data.ipcheck false时立即抛BLOCKED并停止不做自动重试避免延长封禁。被封禁的 IP约 1 小时后自然恢复等待期间可换其他 IP/网络或由人工用浏览器访问站点并走完解封画面。Workflow C 自由检索被站点 WAF 更严格地对待仅当 direct HTTP 遇到 WAF 型 HTTP 400 时才转 Playwright fallback显式封禁默认立即中止只有用户理解风险并传fallbackOnBlocked:true才重试若 Playwright 模块未安装第一次 HTTP 400 失败会原样抛出。对同一 Playwright 客户端连续调用在 10~15 次间隔调用内是稳定的若需更高 burst应在调用间加 3~5 秒 sleep 并打开新客户端。上述行为的实现位置ensureBudget 负责 jitter 等待与预算检查超限抛BUDGET_EXCEEDEDjitter 实现min [0, jitterMs)随机增量postJson 识别ipcheck false并抛BLOCKED。这也意味着默认节流值是调用间至少 2000ms 0~1000ms jitter 每会话 10 次 15s 超时与 README 中的 Throttling defaults 完全一致。Node.js 实战示例快照文档给出了完整可运行的 Node.js 示例以下是完整继承并加入错误处理的版本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; });更完整的 API 一览README Public API除上述四个函数外还有searchProperties、getBidTypes、getUsageCodes、getRegionCodes、resolveBidTypeCode/describeBidTypeCode、CourtAuctionHttpClient、CourtAuctionPlaywrightClient、isPlaywrightFallbackAvailable()以及createBlockedError/createUpstreamError/createNetworkError错误辅助函数。定制更保守的客户端默认节流是最小 2000ms jitter 0~1000ms 每会话 10 次 15s 超时。需要更保守或更快时可直接构造并注入客户端const { CourtAuctionHttpClient } require(court-auction-notice-search); const client new CourtAuctionHttpClient({ minDelayMs: 3000, // 更慢调用间隔拉长 jitterMs: 2000, maxCallsPerSession: 5, // 更保守每会话最多 5 次 timeoutMs: 30_000 // 超时放宽到 30s }); const notices await searchSaleNotices({ date: 2026-04-27, client });CLI 实战示例CLI 二进制名与 npm 包同名见 package.json 的bin声明全局标志支持--json默认、--pretty、--include-rawfalse、--timeout-ms、--min-delay-ms、--max-calls、-h/--help见 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 响应行的 raw 字段原样用于 detail 调用 # CLI 单次调用中可用 jq 等把 list - detail 串起来 # 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 --prettysearch子命令还支持--region 시도[:시군구raw[:읍면동raw]]、--usage 대[:중[:소]]、--appraised-min/max、--area-min/max、--flbd-min/max、--page、--page-size 10|20|50|100等参数见 cli.js。错误处理模型Block / Error handling错误码触发条件处理建议BLOCKEDdata.ipcheck false等待约 1 小时后换 IP 重试把封禁事实与等待指引原样告知用户BUDGET_EXCEEDED会话调用预算超限这是有意的安全阀。确有必要时用--max-calls 20等调大但必须同时提示封禁风险UPSTREAM_ERROR站点返回一般性错误最常见原因是会话过期或jdbnCd 错误从 warmup 重新开始NETWORK_ERROR超时/连接失败检查网络与超时设置PLAYWRIGHT_UNAVAILABLE想用 Playwright fallback 但模块未安装npm i rebrowser-playwright或npm i playwright-core解决错误对象的构造逻辑在 http.jsBLOCKED错误携带upstreamUrl: courtauction.go.kr与upstreamPayloadUPSTREAM_ERROR从payload.errors.errorMessage提取upstreamMessageNETWORK_ERROR把原始异常放在error.cause。必须向用户声明的诚实框架Mandatory honest framing快照文档要求本技能每次交互都必须向用户说明以下四点这也是任何政府数据工具应有的合规底线数据是法원경매정보 网站公开信息的原样转述实际投标前必须重新核对法院原始公告站点对自动化调用非常敏感快速连续查询可能导致 IP 被封锁 1 小时被锁后同一 IP 需等待约 1 小时价格评估金额·最低拍卖价格、拍卖日期、拍卖场所均以公告时点为准可能因更正、撤回、延期而变化参考响应中的correctionCount、cancellationCount字段本技能是read-only的不自动进行投标。此外快照文档的 Runtime rules 与技能 SKILL.md 中的 Hard rules 还约定了 Agent 的通用安全红线未经用户明确即时批准绝不执行支付、消息/邮件投递、最终提交、取消、公开张贴绝不在聊天、文件或 shell 参数中明文保存凭据绝不绕过法律边界、物理到场要求、CAPTCHA、身份核验或电子签名——遇到这些环节完成最远合法步骤后把下一步官方操作精确打开/准备好交给用户在不可逆外部副作用支付、送达、最终提交、注销、账户变更、公开张贴前调用clarify说明确切目标/金额/载荷/影响并获得批准。完成判定Done when快照文档给出的何时算完成清单可作为 Agent 自检与验收标准已向用户说明 IP 封禁风险以及仅供参考·实际投标前必须核对法院原始公告的提示已展开拍卖公告并返回包含caseNumber/usage/address/appraisedPrice/minimumSalePrice的 JSON案件号直接查询时若found:false已给出用户可执行的后续动作指引遇到封禁时不自动重试、立即停止任务结束后向用户说明剩余调用预算明确后续是否还有查询余量。验证与进一步探索包内自带 lint 与测试可在 packages/court-auction-notice-search 下运行npm run lint # node --check 全部源文件与测试 npm run test # node --test含 index/normalize/transport/cli 四组测试测试夹具fixtures是理解响应结构的绝佳材料notices-sample.json、notice-detail-sample.json、case-found-sample.json、properties-sample.json、blocked.json、canonical-search-body.json由 capture-pgj151-submit.cjs 从真实浏览器提交捕获。建议按以下顺序继续阅读仓库快照指令文档 court-auction-notice-search.dolshoi.md → 技能目录 court-auction-notice-search/instruction.md → 包 README README.md → 门面实现 src/index.js → 传输层 src/transport/http.js 与 src/transport/playwright.js → 响应规范化 src/normalize.js → 代码表 src/codetables/index.js 及其 JSON 数据文件。总而言之court-auction-notice-search提供了一个在无公开 API 激进 IP 反爬 强合规要求三重约束下的政府数据技能范本直接 HTTP 为主通道降低对浏览器的依赖分层 fallback 保证 WAF 场景可用限流/预算/封禁即停的三重防护保护调用方 IPfail-open 的代码表避免静默错误read-only 与诚实框架守住合规底线。这套保守设计 结构化输出 明确边界的组合同样值得在其他政务/金融类数据查询技能中复用。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考