5 次查询看懂韩国法院不动产拍卖：court-auction-notice-search 完全指南

5 次查询看懂韩国法院不动产拍卖：court-auction-notice-search 完全指南

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

假设你在首尔打算参与不动产拍卖，开口就是一句："江南区这个月哪些法院在拍？有没有最低价 5 亿以下、流拍至少 1 次的房子？"这正是 k-skill 仓库（面向韩国场景的 Agent 技能集）中court-auction-notice-search包要解决的问题：它把韩国大法院运营的官方「법원경매정보（法院拍卖信息）」站点courtauction.go.kr上的不动产拍卖公告（매각공고）与案件信息，转成 Agent 可直接消费的结构化 JSON。

官方的难点在于：站点没有公开 Open API，而且对自动化调用的 IP 级拦截非常激进。所以这个包的核心命题不是"怎么查到"，而是"怎么查得慢、查得稳、查得合规"。

项目速览：它是什么，不是什么

• 定位：一个 read-only 客户端，把法院公开的拍卖公告与案件信息转成结构化 JSON，供人或 Agent 查询使用。
• 解决的痛点：站点无 Open API，只能直连其内部 WebSquare（韩国政务站点常见前端框架）的 JSON XHR 端点；且据仓库指令文档记载，约 16 次/30 秒的密集调用就会触发约 1 小时的 IP 封禁。
• 与同类方案的关键差异：一级传输通道是直接 HTTP，三条查询主路径都不需要真实浏览器；浏览器只在自由条件检索被 WAF 拦截时才作为 fallback 出现。
• 设计哲学：慢即是稳（slow is stable）——调用间至少 2 秒加随机抖动、每会话 10 次调用预算、检测到封禁立即抛错停止，宁可慢也不抢。
• 明确边界：参考用工具（참고용）。动产（汽车、工程机械）拍卖、公告照片、评估书 PDF、投标书自动填写全部不在范围内，投标必须由人在法院完成。

能力全景：一张图看懂功能地图

参数与输入规范：该传什么格式

五个内部端点路径与请求体核心键（见 src/transport/http.js 的ENDPOINT_PATHS常量）：

📌 注意jdbnCd（审判部代码）：它是列表响应里返回的加密令牌，外部无法凭空构造。这就是为什么详情查询推荐把列表的卡片对象（含raw）原样传入，而不是自己拼参数——构造逻辑见 src/index.js 的buildNoticeDetailBody。

实战 Walkthrough：从第一次调用到 CLI

最小可运行示例：三步拿到一个月公告列表

// Node 18+，先执行：npm install court-auction-notice-search const { getCourtCodes, searchSaleNotices } = require("court-auction-notice-search"); async function main() { // 1. 动态加载法院事务所代码表 const courts = await getCourtCodes(); console.log(`加载 ${courts.count} 个法院事务所`); // 2. 查询首尔中央地方法院 2026 年 4 月的全部拍卖公告 const notices = await searchSaleNotices({ date: "2026-04", // 整月查询；传 "2026-04-27" 则查整月后按当天过滤 courtCode: "B000210", // 首尔中央地方法院 bidType: "date" // 仅期日投标；改 "period" 查期间投标 }); console.log(`매각공고（拍卖公告）${notices.count} 件`); } main().catch((error) => { if (error.code === "BLOCKED") { // 被站点封禁 IP：立即停止，约 1 小时后再试或换网络 console.error("[BLOCKED] IP 被封锁，请约 1 小时后重试"); } else { console.error(error); } process.exitCode = 1; });

多工作流串联：公告 → 详情 → 案件

const { searchSaleNotices, getSaleNoticeDetail, getCaseByCaseNumber, searchProperties } = require("court-auction-notice-search"); async function main() { // 第 1 步：公告列表。注意每次调用消耗一次预算，调用间自动等待 2s + 0~1s 抖动 const notices = await searchSaleNotices({ date: "2026-04-27", courtCode: "B000210" }); // 第 2 步：把列表卡片对象（含 raw）原样传给详情 API 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.address}`); console.log(` 评估 ${item.appraisedPrice} 元 / 最低 ${item.minimumSalePrice} 元`); } } // 第 3 步：案件号直查，"2024-100001" 也会自动规范成 "2024타경100001" const caseInfo = await getCaseByCaseNumber({ courtCode: "B000210", caseNumber: "2024타경100001" }); if (!caseInfo.found) { // found:false / status:204：案件不存在或非公开，提示用户核对案件号与法院 console.error("未查到案件，请核对案件号格式与法院代码"); return; } console.log(`案件名：${caseInfo.caseInfo.caseName}，共 ${caseInfo.schedule.length} 个拍卖日`); // 第 4 步（可选）：自由条件检索——江南区、5 亿以下、流拍 1 次以上 const props = await searchProperties({ region: { sido: "서울특별시", sigungu: "11680" }, usage: { large: "건물", medium: "21200" }, priceRange: { min: 100000000, max: 500000000 }, flbdCount: { min: 1 } }); console.log(`检索到 ${props.count} 件`); } main().catch((error) => { console.error(error); process.exitCode = 1; });

上例共 4 次调用，默认 10 次预算内绰绰有余。searchProperties的响应会把韩文 raw 列规范化成英文键：saNo→caseNumber、gamevalAmt/minmaePrice→appraisedPrice/minimumSalePrice、yuchalCnt→flbdCount、mulBigo→remarks等，且同一字段提供别名（如flbdCount与failedBidCount），映射逻辑在 src/normalize.js。

自定义客户端与 CLI 进阶

默认节流是"调用间至少 2000ms + 0~1000ms 抖动 + 每会话 10 次 + 15s 超时"。需要更保守时，自行构造客户端并注入任意查询函数：

const { CourtAuctionHttpClient, searchSaleNotices } = require("court-auction-notice-search"); const client = new CourtAuctionHttpClient({ minDelayMs: 3000, // 调用间隔拉到 3 秒 jitterMs: 2000, // 再叠加 0~2000ms 随机增量 maxCallsPerSession: 5, // 会话预算减半，更保守 timeoutMs: 30000 // 单请求超时放宽到 30 秒 }); const notices = await searchSaleNotices({ date: "2026-04-27", client });

CLI 二进制名与 npm 包同名，全局标志支持--json（默认）、--pretty、--include-raw=false、--timeout-ms、--min-delay-ms、--max-calls：

# 法院事务所代码表（动态，60+） court-auction-notice-search codes courts --pretty | head -40 # 静态代码表 court-auction-notice-search codes bid-types --pretty court-auction-notice-search codes usages --pretty court-auction-notice-search codes regions --pretty # 拍卖公告列表 court-auction-notice-search notices --date 2026-04 --court-code B000210 --bid-type date --pretty # 案件号直查 court-auction-notice-search case --court-code B000210 --case-number "2024타경100001" --pretty # 自由条件检索 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 --pretty

search子命令还支持--region <시도[:시군구raw[:읍면동raw]]>、--appraised-min/max、--area-min/max、--flbd-min/max、--page-size 10|20|50|100等参数。浏览器 fallback 的 provider 可用KSKILL_BROWSER_PROVIDER、KSKILL_BROWSEROS_CDP_URL、KSKILL_ASIDE_COMMAND环境变量选择。

架构与防护机制：它为什么不会被封

⚠️ 站点按 IP 做非常激进的机器人拦截，以下机制全部围绕"保护调用方 IP"设计，实现在 src/transport/http.js：

1. 会话预热：每次postJson先对对应入口页（如/pgj/index.on?w2xPath=...PGJ143M01.xml&pgjId=143M01）做一次 GET warmup，收集会话 Cookie，再发真实 POST；客户端维护自己的 cookieJar，同一预热页只预热一次。
2. 预算与抖动检查：ensureBudget先查callsSoFar是否超过maxCallsPerSession（默认 10），超限抛BUDGET_EXCEEDED；再计算等待时长 = 2000ms +[0, 1000ms)随机增量 − 距上次调用的已流逝时间，不足则补等。
3. 请求头伪装：携带X-Requested-With: XMLHttpRequest、韩语Accept-Language: ko-KR,ko;q=0.9,en;q=0.8、按端点动态填充的Referer；物件自由检索还附加submissionid: mf_wfm_mainFrame_sbm_selectGdsDtlSrch与sc-userid: SYSTEM，模拟真实浏览器按钮提交。
4. 一级通道直接 HTTP：公告列表、详情、案件查询的正常路径都不需要真实浏览器。
5. fallback 触发条件极窄：只有两种情况才转浏览器——UPSTREAM_ERROR且statusCode === 400（WAF 型拦截），或BLOCKED且调用方显式传了fallbackOnBlocked: true；{fallback:false}可完全关闭自动 fallback。
6. 浏览器两层降级链：fallback 激活后，优先连接用户已打开的 runtime 浏览器（k-skill-browser-runtime自动探测，macOS 依次试 Aside Browser REPL → BrowserOS GUI CDP → Chrome/Chromium CDP，其他平台先试 BrowserOS）；全部不可达（UNAVAILABLE/探测失败）时，降级到本地chromium.launch({headless})，需要rebrowser-playwright或playwright-core（均为 optionalDependency）。
7. 清理安全边界：连到 runtime 的浏览器是用户自有的，fallback 结束只清理 adapter 创建的 page/context/tab 并断开 automation client，绝不关闭 BrowserOS/Aside/Chrome 的 profile；本地 launch 的浏览器则完整关闭 page/context/browser。PLAYWRIGHT_UNAVAILABLE（模块未装）与UNKNOWN_PROVIDER（provider 名错误）fail-closed 立即抛错，不会静默降级。
8. 稳定性参考：同一 Playwright 客户端在 10~15 次间隔调用内稳定；需要更高 burst 时，调用间加 3~5 秒 sleep 并打开新客户端。

错误处理与使用边界：被封就停

该用：问"今天/明天哪里有不动产拍卖"、指定法院与日期的公告列表、期日/期间投标分开看、按案件号查进展、按区域 + 价格 + 流拍次数找物件。

不该用：动产（汽车、工程机械）拍卖（v1 范围外）；单日全法院日程（Workflow D，另列 follow-up）；物件照片与评估书 PDF 下载（follow-up）；投标书自动填写/提交——明确不支持。

合规红线（技能 SKILL.md 的 Hard rules 与 instruction.md 的诚实框架要求每次交互都声明）：

1. 数据是官网公开信息的原样转述，实际投标前必须重新核对法院原始公告；
2. 价格（评估金额、最低卖出价）、拍卖日期与场所均以公告时点为准，可能因更正、撤回、延期而变化（参考correctionCount、cancellationCount字段）；
3. 本技能是read-only，不自动投标；
4. 未经用户明确即时批准，不执行支付、消息/邮件投递、最终提交、取消、公开张贴；不在聊天、文件或 shell 参数中保存明文凭据；不绕过法律边界、物理到场要求、CAPTCHA、身份核验或电子签名——遇到这些环节，完成最远合法步骤后把下一步官方操作交给用户。

自检清单与延伸阅读

任务完成前，对照这份自检清单（源自指令文档的 Done when）：

• 已向用户说明 IP 封禁风险，以及"仅供参考、投标前必须核对法院原始公告"；
• 已展开拍卖公告，返回含caseNumber/usage/address/appraisedPrice/minimumSalePrice的 JSON；
• 案件号直查若found:false，已给出可执行的后续动作（核对案件号格式与法院代码）；
• 遇到封禁时立即停止，没有自动重试；
• 任务结束后已告知用户剩余调用预算。

建议按此顺序阅读仓库，由浅入深：

1. court-auction-notice-search/instruction.md —— 完整指令文档：边界、工作流、限流规则
2. court-auction-notice-search/SKILL.md —— Agent 元数据与硬性安全规则
3. packages/court-auction-notice-search/README.md —— Public API、端点表、错误模型、节流默认值
4. packages/court-auction-notice-search/src/index.js —— 门面层：参数校验、请求体构造、fallback 决策
5. packages/court-auction-notice-search/src/transport/http.js —— 主传输：warmup、预算、请求头、错误构造
6. packages/court-auction-notice-search/src/transport/playwright.js —— 浏览器 fallback 客户端
7. packages/court-auction-notice-search/src/codetables/index.js —— 代码表解析、层级匹配与 fail-open
8. packages/court-auction-notice-search/test/fixtures/ —— 响应样例夹具，其中canonical-search-body.json由 capture-pgj151-submit.cjs 从真实浏览器提交捕获，是理解请求体结构的最佳材料

在包目录下执行npm run lint（node --check 全部源文件）与npm run test（node --test，含 index/normalize/transport/cli 四组）即可本地验证。

一句话收尾

没有公开 API、IP 反爬激进、合规要求严格——court-auction-notice-search在"慢即是稳"的哲学下给出了一份可复用的政务数据技能范本：直接 HTTP 降依赖、分层 fallback 保可用、限流预算封禁即停护 IP，保守设计与明确边界同样值得你的下一个政府/金融查询技能借鉴。

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