韩国法院拍卖信息完整指南：用 court-auction-notice-search 实战 courtauction.go.kr 查询

韩国法院拍卖信息完整指南：用 court-auction-notice-search 实战 courtauction.go.kr 查询

【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill

这篇文章拆解 k-skill 仓库里的court-auction-notice-search技能：它把韩国大法院官方 법원경매정보 站点（courtauction.go.kr）的不动产拍卖公告（매각공고）与案件信息转成 Agent 可消费的结构化 JSON。在站点没有公开 Open API、且按 IP 激进拦截机器人的前提下，告诉你韩国不动产拍卖公告查询、法院拍卖案件号查询这类"无公开 API 站点的数据查询"该怎么安全落地。

明天首尔哪里拍？先说清楚这个矛盾

假设你问 Agent："明天首尔哪里有不不动产拍卖？最低价的物件列一下。"

这句话背后有两个不好搞的事实：

1. courtauction.go.kr 没有公开 Open API。页面上那个"검색（搜索）"按钮，背后是韩国政务站常用的 WebSquare 框架在干活——说白了，点按钮其实是在向后端 POST 一段结构化 JSON。这个技能干的事，就是把这套内部 XHR 端点逆向成客户端，直接发同样的请求。
2. 站点按 IP 拦截机器人拦得非常狠：大约 30 秒内打 16 次，你的 IP 就会被封 1 小时。

所以这不是一个"拿到 API key 就能调"的常规数据源，而是一个必须把"慢"当成设计目标来做的项目。k-skill 里的court-auction-notice-search就是为此而生的：只读、慢速、结构化输出、边界清晰。

一句话说清它能做什么、不能做什么

一句话：把法院拍卖站公开的公告和案件数据变成干净 JSON，同时用保守的限流策略保住你的 IP 不被封。

能做的（v1 范围）：

• 按日期 + 法院 + 投标区分查拍卖公告列表，并展开公告里的案件/物件明细（案件号、用途、地址、评估价、最低价）
• 按法院代码 + 案件号直查案件：案件信息、物件内訳、各次拍卖日期的价格与结果、分配请求期限、相关案件、利害关系人
• 自由条件检索物件：区域、用途、价格区间、面积、流拍次数、拍卖日期
• 静态/动态代码表：60+ 法院事务所代码、投标区分（기일입찰/기간입찰）、用途与 시도 代码
• 三层传输兜底：直接 HTTP 为主，浏览器仅作 WAF 场景的 fallback

不要用来做的事（明确边界）：

• 动产（汽车、工程机械）拍卖——不在 v1 范围
• 某拍卖日所有法院日程一次拉全——官方 follow-up 议题，尚未支持
• 拍卖物件照片 URL、物件明细书/现状调查书/评估书 PDF 下载——同样未支持
• 投标书自动填写、自动提交——明确不支持。投标必须人在法院完成，这是 read-only 的硬边界

最快上手：5 分钟跑通法院拍卖公告查询

装好后（npm install court-auction-notice-search），最小可运行的 Node.js 示例长这样——查公告、展开第一条、打印关键价格：

const { searchSaleNotices, getSaleNoticeDetail } = require("court-auction-notice-search"); const notices = await searchSaleNotices({ date: "2026-04-27", courtCode: "B000210", // 首尔中央地方法院 bidType: "date" // 기일입찰（期日投标） }); console.log(`매각공고 ${notices.count}건`); const detail = await getSaleNoticeDetail(notices.items[0]); for (const it of detail.items) { console.log(it.caseNumber, it.usage, it.address); console.log(` 评估 ${it.appraisedPrice} / 最低 ${it.minimumSalePrice}`); }

CLI 路径同样齐备，二进制名与包同名。比如查公告列表：court-auction-notice-search notices --date 2026-04 --court-code B000210 --pretty；查案件：court-auction-notice-search case --court-code B000210 --case-number "2024타경100001" --pretty。全局参数支持--json（默认）、--pretty、--include-raw=false、--timeout-ms、--min-delay-ms、--max-calls，见 src/cli.js。

法院拍卖怎么查：三种问法对应三种查法

问"某天某法院拍什么"：公告列表 → 详情展开

典型问法："今天/明天哪里有不动产拍卖？""서울중앙지방법원 2026-04-27 매각공고 보여줘。"

调用链是两步：searchSaleNotices({ date, courtCode?, bidType? })拿卡片列表；用户选中某条后，把卡片对象（或它的raw）原样传给getSaleNoticeDetail(notice)。

这里有个坑：详情接口需要一个叫jdbnCd的字段——它是法院（审判部）的加密令牌，外部无法凭空构造，只能从列表响应里带回来复用。所以"原样传卡片对象"不是偷懒，而是必需。详情响应的items[]会给出caseNumber、usage、address、appraisedPrice、minimumSalePrice、remarks六件套。

常用输入参数一览（定义与校验逻辑在 src/index.js）：

问"某案件进展如何"：案件号直查

典型问法："사건번호 2024타경100001 진행 상황 알려줘。"

调用getCaseByCaseNumber({ courtCode, caseNumber })，一次拿回：caseInfo（案件名·受理日·请求金额·审判部·进行状态）、items[]（拍卖目的物：地址、分配请求期限）、schedule[]（每个拍卖日的最低价/评估价/结果）、claimDeadline、relatedCases、stakeholders。

两种结果分支要提前想好：found:false / status:204表示案件不存在或未公开——正确动作是请用户核对案件号格式与法院，而不是反复重试；found:true则按上面的字段向用户叙述进展。规范化逻辑在 src/normalize.js 的normalizeCaseDetailResponse。

问"某类符合条件的房子"：自由条件检索

典型问法："서울 강남구 아파트 최저가 5억 이하 유찰 1회 이상 물건 찾아줘（江南区公寓、最低价 5 亿以下、流拍 1 次以上）"。

调用searchProperties()，条件映射如下：

这里再解释两个词：fail-open（代码表不认识的输入不做猜测、按原值透传，宁可查空也不静默改错你的请求）和WAF 型 HTTP 400（站点 WAF——Web 应用防火墙——拒绝请求返回的 400，区别于普通业务错误）。自由检索的完整请求体是照着真实浏览器提交捕获的 canonical body 构造的，夹具见packages/court-auction-notice-search/test/fixtures/canonical-search-body.json。

它实际 POST 的内部端点集中定义在 src/transport/http.js 的ENDPOINT_PATHS：

为什么它跑得这么慢：慢即是稳

这个包的设计哲学就是慢即是稳。默认节流值写死在CourtAuctionHttpClient构造函数里（src/transport/http.js）：

• 调用间至少 2000ms + 0~1000ms jitter。jitter（抖动）是随机追加的等待量，让调用间隔不规则、不像机器节奏——对抗按"固定频率"识别机器人的检测。
• 每会话预算 10 次调用。ensureBudget()在每次postJson前检查，超限抛BUDGET_EXCEEDED。需要更多？开新客户端，或显式调大maxCallsPerSession。
• 封禁即停：只要响应里出现data.ipcheck === false，立刻抛BLOCKED并停止，绝不自动重试——自动重试只会把封禁拖得更久。

补充两条实战经验：被封的 IP 约 1 小时后自然恢复，等待期间可换网络，或人工用浏览器走完解封画面；同一个 Playwright 客户端连续调用在 10~15 次间隔调用内稳定，更高的 burst 需求要加 3~5 秒 sleep 并换新客户端。

💡 想更保守（或更快）时，自己构造客户端注入即可：

const { CourtAuctionHttpClient, searchSaleNotices } = require("court-auction-notice-search"); const client = new CourtAuctionHttpClient({ minDelayMs: 3000, // 间隔拉长 jitterMs: 2000, maxCallsPerSession: 5, // 更保守的会话预算 timeoutMs: 30_000 }); const notices = await searchSaleNotices({ date: "2026-04-27", client });

CLI 里对应--min-delay-ms 3000、--max-calls 5。

三层传输与浏览器兜底：direct HTTP、runtime 浏览器、本地 Playwright

正常路径完全不需要浏览器——公告、案件、物件三条查询走直接 HTTP：先发一次 warmup GET 建立会话 Cookie（这对应"从 warmup 重新开始"的排错提示），再按端点带上X-Requested-With: XMLHttpRequest、韩语Accept-Language和按端点填充的Referer发 POST。

浏览器只在searchProperties()的两种情形下激活（源码在 src/index.js 的searchProperties）：

1. 直接 HTTP 撞出WAF 型 HTTP 400（UPSTREAM_ERROR+statusCode === 400）；
2. 遇到BLOCKED，且调用方显式传了fallbackOnBlocked: true。

传{ fallback: false }可以整体关掉自动兜底。兜底激活后的连接优先级：

1. 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环境变量控制。
2. 本地 Playwright launch：所有 runtime provider 都够不到时，才chromium.launch({ headless })自己起一个。依赖rebrowser-playwright或playwright-core（均为 optionalDependency，未安装则兜底静默不可用）。

⚠️ 清理边界（安全红线）：连上的 runtime 浏览器是用户自己的，结束时只清理 adapter 建的 page/context/tab，用runtime.disconnectBrowser断开自动化客户端，绝不关闭用户的 BrowserOS/Aside/Chrome 配置；本地 launch 的浏览器是包自己起的，所以 page/context/browser 全部关闭。PLAYWRIGHT_UNAVAILABLE（模块没装）与UNKNOWN_PROVIDER（provider 名写错）走fail-closed立即抛错；UNAVAILABLE/探测失败则自动降级到本地 launch。全程不绕过登录、CAPTCHA、支付或电子签名。

读懂返回结果：核心字段、韩元展示与 raw 列名规范化

所有响应都经过 src/normalize.js 洗一遍：剥离 HTML 标签、把"1,234,567"这类字符串解析成数字、YYYYMMDD转YYYY-MM-DD、空值统一为null。

价格是韩元整数。向用户展示时建议同时给韩式千位逗号格式 + 억/만 单位换算，比如5,000,000,000원→ "50 亿韩元"。公告卡片上的correctionCount/cancellationCount（更正/撤回次数）值得留意——它提示数据可能已变动。

自由检索响应items[]把站点原始列名映射成英文键，映射思路如下（实现见normalizePropertySearchRow）：

同一字段还提供别名键（如flbdCount与failedBidCount），方便不同调用方按习惯取。原始响应始终可用raw字段拿到（includeRaw: false可关闭）。

代码表方面：getUsageCodes()静态返回 4 个大分类（10000=토지、20000=건물、30000=차량및운송장비、40000=기타）及部分代表中/小分类；getRegionCodes()返回 19 个 시도。시군구/읍면동 因上游级联 XHR 不稳定而不进静态表，直接传 raw 代码。未知值一律 fail-open 透传；resolveUsageCode还有同名保护——resolveUsageCode("아파트", "large")这种"名字只存在于其他层级"的情况不会错拿同名的 medium/small 代码，而是原样透传。

IP 被封了怎么办：错误码自救手册

错误对象的构造逻辑集中在 src/transport/http.js 的三个create*Error工厂：BLOCKED携带upstreamUrl: "courtauction.go.kr"与upstreamPayload；UPSTREAM_ERROR从payload.errors.errorMessage提取上游消息。

合规与诚实底线：read-only 与投标前复核

这个技能要求每次交互都向用户声明四件事，这也是任何政府数据工具该有的底线：

1. 数据是 법원경매정보 站点公开信息的原样转述，实际投标前必须回法院原始公告复核；
2. 站点对自动化极其敏感，快速连续查询可能导致 IP 被封锁 1 小时；
3. 价格（评估价/最低拍卖价）、拍卖日期、拍卖场所均以公告时点为准，可能因更正、撤回、延期而变；
4. 技能是read-only的，绝不自动投标。

k-skill 的通用安全红线（见 SKILL.md 的 Hard rules）同样适用：未经用户明确即时批准，不执行支付、消息/邮件投递、最终提交、取消、公开张贴；不在聊天、文件或 shell 参数里明文存放凭据；不绕过 CAPTCHA、身份核验、电子签名或法律边界——遇到这些环节，做到最远的合法步骤，再把下一步官方操作原样交给用户。

任务结束的自检清单（Done when）也很明确：已告知封禁风险与"仅供参考·投标前核对原文"；公告已展开且caseNumber/usage/address/appraisedPrice/minimumSalePrice齐备；found:false时给了用户可执行的后续动作；封禁时没有自动重试；任务后告知剩余调用预算。

总结与仓库推荐阅读顺序

court-auction-notice-search给出了一个可复用的范本：在"无公开 API + 激进 IP 反爬 + 强合规要求"三重约束下，用直接 HTTP 为主通道降低浏览器依赖、分层 fallback保住 WAF 场景、限流/预算/封禁即停三件套保护调用方 IP、fail-open 代码表避免静默错误、read-only + 诚实框架守住合规底线。这套"保守设计 + 结构化输出 + 明确边界"的组合，值得在任何政务/金融数据查询项目里抄作业。

建议按这个顺序读仓库：

1. 快照指令文档 court-auction-notice-search.dolshoi.md
2. 技能指令 instruction.md
3. 包 README（API 一览、端点表、兜底规则最完整）
4. 门面实现 src/index.js（参数校验与请求体构造）
5. 传输层 src/transport/http.js 与src/transport/playwright.js
6. 规范化 src/normalize.js
7. 测试夹具packages/court-auction-notice-search/test/fixtures/（notices-sample.json、case-found-sample.json、canonical-search-body.json等，理解响应结构的最好材料）

包内自带验证命令：在packages/court-auction-notice-search下npm run lint与npm run test即可。

【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill