sh-notice-search 实战指南用 Node.js 直接查询首尔 SH 公社公开公告【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇技术指南围绕sh-notice-search——k-skill 仓库中面向首尔住宅都市开发公社SH서울주택도시개발공사的公开公告查询客户端展开讲解如何通过其 JS API 与 CLI 直接抓取 SH 公开 HTML 公告板完成公告列表检索、详情正文提取与附件元数据解析。读完本文你将掌握该客户端的全部参数语义、分类别名映射、状态分类器原理、底层 HTML 解析机制及其明确的合规边界可直接落地到 Agent 或自动化脚本中。一、模块定位与能力边界sh-notice-search是一个无需认证的公开 HTML 公告查询客户端对应 k-skill 中的sh-notice-searchskill技能清单见 sh-notice-search/skill.json完整使用说明见 sh-notice-search/instruction.md。它的设计目标非常克制只读查询不做任何事务性动作。模块明确承诺的能力包括按关键词检索 SH 公开公告/通知列表按官方公告板分类주택임대、주택분양、주택매입/주거복지、토지、상가/공장 等筛选从详情页提取正文、담당부서负责部门、등록일登记日期、조회수浏览量与真实附件文件名解析附件的官方预览地址preview_url。同时模块明确不做以下事情청약 신청认购申请、登录、文书提交、支付、My Page 查询、通知发送等流程的自动化。数据源是 SH 的公开 HTML 页面不需要代理、不需要 API Key、不需要任何密钥。这一点在 packages/sh-notice-search/README.md 的 Source 一节与 skill 的 instruction 中均有反复强调也是后续所有设计如不暴露直链下载地址的出发点。二、数据来源与关键发现2.1 公开公告板的 URL 结构模块直接抓取的列表/详情页地址格式为https://www.i-sh.co.kr/app/lay2/program/.../www/brd/.../{list,view}.do以默认分类주택임대为例src/index.js 中的CATEGORY_CONFIGS给出了精确路径列表页/app/lay2/program/S1T294C297/www/brd/m_247/list.do?multi_itm_seq2详情页/app/lay2/program/S1T294C297/www/brd/m_247/view.do?multi_itm_seq2seqseq其中multi_itm_seq2是 주택임대 分类的官方标识每个分类对应独立的板面路径与multi_itm_seq详见第五节分类映射。2.2 srchWord 与 srchTp 的配套约束这是 SH 公告板最重要的一个使用细节SH 要求关键词搜索必须同时提供srchWord与srchTp两个参数否则srchWord会被忽略。instruction.md 记录了一次真实冒烟测试2026-05-15仅带srchWord행복주택而不带srchTp时返回的是整个 주택임대 板的全部公告数加上srchTp0后才收窄结果集。因此客户端在存在关键词时总是携带srchTp且默认按标题搜索搜索范围srchTp值JS 侧写法标题搜索默认0searchType: title/srchTp: 0正文搜索1searchType: content/srchTp: 1URL 构建逻辑见 buildSearchUrl仅当keyword非空时才写入srchWord与srchTp。对应测试 test/index.test.js 验证了srchWord、srchTp0、multi_itm_seq2三个参数同时出现。三、环境要求与快速上手sh-notice-search是一个 npm 包package.json发布版本 0.4.0要求Node.js 18engines.node字段标准入口为src/index.js并暴露sh-notice-search的 bin 命令。安装npm install sh-notice-search依赖 Node 18 的原生fetch代码通过global.fetch获取也允许调用方注入自定义 fetcher见第九节。最简用法——先搜列表再取第一条的详情const { searchNotices, getNoticeDetail } require(sh-notice-search) const list await searchNotices({ keyword: 행복주택, category: 임대, page: 1 }) const detail await getNoticeDetail({ seq: list.items[0].seq, category: 임대 })注意list.items[0].seq是字符串类型的公告序号详情查询直接复用即可。四、JS API 参数详解两个核心异步函数searchNotices(options)与getNoticeDetail(options)。参数经 normalizeSearchOptions / normalizeDetailOptions 统一归一化支持多组别名。4.1 searchNotices 参数参数别名默认值说明keywordq/query/srchWordnull搜索关键词上限 100 字符超长直接抛错categorykind/noticeTyperent주택임대分类键或别名见第五节searchTypesrchTp/type有关键词时0标题(0)或正文(1)搜索pagepageNo1页码范围 1–1000非数字抛错pageSizelimit10返回行数上限 10SH 板每页固定 10 行status—null状态筛选open/진행、closed/마감、announced/당첨자timeoutMs—20000请求超时毫秒上限 120000fetcher—global.fetch自定义 fetch 实现测试注入用signal——外部 AbortSignalincludeHtml—false为true时在结果中附带原始 HTML便于诊断非法输入均有明确报错例如page: abc报Provide valid page.未知分类报Unsupported SH category: ...未知状态报Unsupported SH status: ...测试见 test/index.test.js。4.2 getNoticeDetail 参数参数别名说明seqnoticeSeq/id公告序号必填仅允许 1–20 位数字categorykind/noticeType分类缺省rent此外同样支持timeoutMs、fetcher、signal、includeHtml。五、CLI 使用详解CLI 入口为 src/cli.js安装包后可直接调用sh-notice-search命令输出为格式化 JSON。三种典型用法# 按关键词搜索列表 sh-notice-search 행복주택 --category 임대 --limit 5 # 分类 状态筛选 sh-notice-search 매입임대 --category 주거복지 --status 진행 # 按 seq 取详情 sh-notice-search --seq 304371 --category 임대完整选项如下--help可随时查看选项别名说明--query text-q/--keyword关键词存在时默认标题搜索--search-type type--srch-tptitle/제목或content/내용--category category--kindall、rent/임대、sale/분양、welfare/주거복지、land/토지等--status status—open/진행、closed/마감、announced/당첨자标题分类器--page number—页码默认 1--limit number--page-size返回行数被 SH 固定页大小 10 截断--seq number--id传该值则走详情查询--include-html—输出中附带原始 HTMLCLI 还支持detail seq的写法parseArgs中检测detail/--detail标记后的数字参数。出错时输出堆栈并设置进程退出码 1见 run。六、返回字段详解6.1 列表项字段列表解析见 parseListRows每行包含字段类型说明seqstring公告序号来自getDetailView(...)调用numberstring公告栏编号titlestring标题去掉 NEW 徽标文本departmentstring담당부서 负责部门registered_datestring登记日期如2026-05-14viewsnumber浏览量is_newboolean是否带 NEW 标记category/category_namestring分类键 / 官方分类名status/status_basisstring推断状态 / 恒为title_text_classifierdetail_urlstring官方详情页 URL顶层返回结构还包含query回显本次查询参数、summarypage、page_size、returned_count、total_count、sourcename: sh-public-html、proxy: false、原始url以及warnings数组便于调用方自检。6.2 详情字段详情解析见 parseDetailHtmlgetNoticeDetail返回{ notice, query, source }其中notice包含seq、title、registered_date、views、department、category、category_namecontent_text剥离脚本、样式与标签后的纯文本正文attachments附件元数据数组detail_url、warningsincludeHtml开启时还有html。6.3 附件元数据每个附件包含字段说明filename真实文件名如2025년 2차 행복주택 예비3차 계약결과.pdffile_seqSH 侧文件序号file_size字节数file_type类型标识如Apreview_url官方SH 预览/转换地址/app/com/util/htmlConverter.do?...刻意不暴露直接下载 URLdownload_url因为 SH 的文件下载行为可能与会话/策略相关直链并不稳定正确做法是把官方detail_url/preview_url交给用户浏览器处理。测试 test/index.test.js 专门断言download_url键不存在。七、分类别名映射表分类归一化由 normalizeCategory 完成别名经CATEGORY_ALIAS索引映射到官方板面。完整配置见 CATEGORY_CONFIGS分类键官方板面multi_itm_seq支持别名all전체multi_itm_seqs1,2,4,8,16,32,64,128,256,512all、전체sale주택분양1sale、분양、주택분양、분양주택rent주택임대2rent、임대、주택임대、임대주택purchase주택매입512purchase、매입、주택매입、매입임대、welfare、주거복지movein입주안내4movein、입주、입주안내land토지8land、토지commercial상가/공장16commercial、상가、공장compensation보상/이주32compensation、보상、이주design현상설계64design、현상설계、설계etc기타256etc、기타重要提示주거복지并不是 SH 公告板的公开标签而是面向用户的友好别名当前映射到 SH 公开的주택매입板multi_itm_seq512。使用该别名时应在答复中向用户说明这一映射关系instruction.md 明确要求如此。别名匹配前会先做归一化normalizeToken去掉所有空白、trim、转小写因此 임대 、임대等价。八、状态分类器原理SH 公开列表没有一等公民的状态字段没有접수중/마감之类的列因此模块采用保守的标题文本分类器classifyNoticeStatus推断状态触发关键词标题内出现announced당첨、발표closed마감、계약결과、결과、완료、종료open모집공고、입주자 모집、신청、접수、공고unknown以上均未命中状态筛选在解析后进行statusMatches并把status_basis标记为title_text_classifier以便下游感知其推断性质一旦传入了status参数返回的warnings中也会追加说明。响应时务必向用户披露“状态系从标题推断除非公告正文写明确切日期”。测试 test/index.test.js 验证了계약결과标题被归为closed而open筛选返回空的行为。九、源码级实现原理9.1 请求构建与容错URL 构建buildSearchUrl用标准URL对象拼接base config.path /list.do再按需写入multi_itm_seq(s)、page、srchWord、srchTpbuildDetailUrl类似地拼view.do与seq。fetch 注入fetchText优先使用调用方注入的fetcher否则回退global.fetch请求头固定携带user-agent: Mozilla/5.0 (compatible; k-skill/sh-notice-search)与accept: text/html,...。测试验证了该 UA 头test/index.test.js。超时createTimeoutSignal在支持AbortSignal.timeout的运行时用其实现超时默认 20 秒。HTTP 错误非 2xx 响应抛出带状态码与前 200 字节正文的错误信息。9.2 HTML 解析的关键策略列表解析优先定位div idlistTb内的tbody逐tr提取。判定有效行的关键是找到getDetailView(seq)JS 调用单元格不足 5 列的行跳过标题会去掉NEW徽标。总数通过총 strongN/strong 건正则提取。文本清洗stripTags先移除script/style再剥标签decodeHtml完整处理数字实体十进制/十六进制与amp;、lt;、gt;、quot;、nbsp;等常见实体。附件解析parseAttachments是本模块最有辨识度的部分有两条严格规则只认带existFile(N)onclick 的真实附件锚点并显式过滤.pdf/.hwp等图标模板文本——测试 fixture 中专门把图标模板注释掉以验证其不会被误解析test/index.test.js附件文件名、大小、类型优先来自页面内嵌的downListJSON 元数据并与htmlConverter.do预览链接按file_seq配对。预览链接白名单normalizeAttachmentPreviewUrl只接受www.i-sh.co.kr同源且路径为/app/com/util/htmlConverter.do的链接防止被注入外部地址——测试用evil.example替换后断言preview_url为空test/index.test.js。9.3 异常面检测与 warnings当响应缺少预期的列表/详情标记时buildUnexpectedHtmlWarnings 会扫描页面中的NetFunnel、captcha/보안문자、로그인、점검、대기열、차단等关键词给出形如unexpected SH list HTML; possible block/maintenance markers: NetFunnel, 로그인, 점검的警告。测试用一份含“서비스 점검 안내 / NetFunnel 대기열 또는 로그인”的拦截页验证了该行为test/index.test.js它让调用方在遇到限流/维护页时能快速识别而不是得到静默的空结果。十、测试与质量保障测试文件 test/index.test.js 使用 Node 内置node:testnode:assert/strictnpm test即运行package.json 中scripts.test为node --test覆盖参数归一化关键词默认标题搜索、韩英分类别名、状态别名、非法输入抛错URL 构建hostname、路径、srchTp、multi_itm_seq与seq参数列表/详情 HTML 解析总数、行字段、详情字段、附件配对拦截页检测列表与详情的 warnings端到端通过注入的假fetcher走通searchNotices→getNoticeDetailCLIparseArgs解析与--help输出。十一、失败模式与使用注意综合 README 的 Boundaries、instruction 的 Failure modes 与源码实现接入时需注意SH 可能变更板面路径、表格标记、JS 函数或downList结构导致解析部分失败或完全失败——务必把warnings纳入处理逻辑IP 限流、NetFunnel 节流、维护页或临时 4xx/5xx会阻塞实时抓取模块只做被动检测warnings不得绕过CAPTCHA、登录或排队保护pageSize/limit超过 10 无意义SH 板每页固定返回 10 行追加结果请翻页page关键词必须与srchTp成对出现客户端已默认处理附件预览/下载受 SH 当前直链与下载策略约束应把官方 URL 交还用户浏览器状态为标题推断结果非官方字段答复时需披露。结语sh-notice-search的价值在于把“SH 公开公告查询”这件容易被各种反爬策略与 HTML 结构变化困扰的事情收敛为一个参数规范、边界清晰、可测试的 Node 客户端官方 URL 直连、无需代理与密钥、srchWordsrchTp配套、真实附件锚点识别、拦截页警告配合完整的单元测试与 skill 说明文档sh-notice-search/instruction.md无论是嵌入 Agent 技能还是独立脚本使用都能在合规前提下稳定读取 SH 的 청약·주택 공고 信息。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
sh-notice-search 实战指南：用 Node.js 直接查询首尔 SH 公社公开公告
sh-notice-search 实战指南用 Node.js 直接查询首尔 SH 公社公开公告【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇技术指南围绕sh-notice-search——k-skill 仓库中面向首尔住宅都市开发公社SH서울주택도시개발공사的公开公告查询客户端展开讲解如何通过其 JS API 与 CLI 直接抓取 SH 公开 HTML 公告板完成公告列表检索、详情正文提取与附件元数据解析。读完本文你将掌握该客户端的全部参数语义、分类别名映射、状态分类器原理、底层 HTML 解析机制及其明确的合规边界可直接落地到 Agent 或自动化脚本中。一、模块定位与能力边界sh-notice-search是一个无需认证的公开 HTML 公告查询客户端对应 k-skill 中的sh-notice-searchskill技能清单见 sh-notice-search/skill.json完整使用说明见 sh-notice-search/instruction.md。它的设计目标非常克制只读查询不做任何事务性动作。模块明确承诺的能力包括按关键词检索 SH 公开公告/通知列表按官方公告板分类주택임대、주택분양、주택매입/주거복지、토지、상가/공장 等筛选从详情页提取正文、담당부서负责部门、등록일登记日期、조회수浏览量与真实附件文件名解析附件的官方预览地址preview_url。同时模块明确不做以下事情청약 신청认购申请、登录、文书提交、支付、My Page 查询、通知发送等流程的自动化。数据源是 SH 的公开 HTML 页面不需要代理、不需要 API Key、不需要任何密钥。这一点在 packages/sh-notice-search/README.md 的 Source 一节与 skill 的 instruction 中均有反复强调也是后续所有设计如不暴露直链下载地址的出发点。二、数据来源与关键发现2.1 公开公告板的 URL 结构模块直接抓取的列表/详情页地址格式为https://www.i-sh.co.kr/app/lay2/program/.../www/brd/.../{list,view}.do以默认分类주택임대为例src/index.js 中的CATEGORY_CONFIGS给出了精确路径列表页/app/lay2/program/S1T294C297/www/brd/m_247/list.do?multi_itm_seq2详情页/app/lay2/program/S1T294C297/www/brd/m_247/view.do?multi_itm_seq2seqseq其中multi_itm_seq2是 주택임대 分类的官方标识每个分类对应独立的板面路径与multi_itm_seq详见第五节分类映射。2.2 srchWord 与 srchTp 的配套约束这是 SH 公告板最重要的一个使用细节SH 要求关键词搜索必须同时提供srchWord与srchTp两个参数否则srchWord会被忽略。instruction.md 记录了一次真实冒烟测试2026-05-15仅带srchWord행복주택而不带srchTp时返回的是整个 주택임대 板的全部公告数加上srchTp0后才收窄结果集。因此客户端在存在关键词时总是携带srchTp且默认按标题搜索搜索范围srchTp值JS 侧写法标题搜索默认0searchType: title/srchTp: 0正文搜索1searchType: content/srchTp: 1URL 构建逻辑见 buildSearchUrl仅当keyword非空时才写入srchWord与srchTp。对应测试 test/index.test.js 验证了srchWord、srchTp0、multi_itm_seq2三个参数同时出现。三、环境要求与快速上手sh-notice-search是一个 npm 包package.json发布版本 0.4.0要求Node.js 18engines.node字段标准入口为src/index.js并暴露sh-notice-search的 bin 命令。安装npm install sh-notice-search依赖 Node 18 的原生fetch代码通过global.fetch获取也允许调用方注入自定义 fetcher见第九节。最简用法——先搜列表再取第一条的详情const { searchNotices, getNoticeDetail } require(sh-notice-search) const list await searchNotices({ keyword: 행복주택, category: 임대, page: 1 }) const detail await getNoticeDetail({ seq: list.items[0].seq, category: 임대 })注意list.items[0].seq是字符串类型的公告序号详情查询直接复用即可。四、JS API 参数详解两个核心异步函数searchNotices(options)与getNoticeDetail(options)。参数经 normalizeSearchOptions / normalizeDetailOptions 统一归一化支持多组别名。4.1 searchNotices 参数参数别名默认值说明keywordq/query/srchWordnull搜索关键词上限 100 字符超长直接抛错categorykind/noticeTyperent주택임대分类键或别名见第五节searchTypesrchTp/type有关键词时0标题(0)或正文(1)搜索pagepageNo1页码范围 1–1000非数字抛错pageSizelimit10返回行数上限 10SH 板每页固定 10 行status—null状态筛选open/진행、closed/마감、announced/당첨자timeoutMs—20000请求超时毫秒上限 120000fetcher—global.fetch自定义 fetch 实现测试注入用signal——外部 AbortSignalincludeHtml—false为true时在结果中附带原始 HTML便于诊断非法输入均有明确报错例如page: abc报Provide valid page.未知分类报Unsupported SH category: ...未知状态报Unsupported SH status: ...测试见 test/index.test.js。4.2 getNoticeDetail 参数参数别名说明seqnoticeSeq/id公告序号必填仅允许 1–20 位数字categorykind/noticeType分类缺省rent此外同样支持timeoutMs、fetcher、signal、includeHtml。五、CLI 使用详解CLI 入口为 src/cli.js安装包后可直接调用sh-notice-search命令输出为格式化 JSON。三种典型用法# 按关键词搜索列表 sh-notice-search 행복주택 --category 임대 --limit 5 # 分类 状态筛选 sh-notice-search 매입임대 --category 주거복지 --status 진행 # 按 seq 取详情 sh-notice-search --seq 304371 --category 임대完整选项如下--help可随时查看选项别名说明--query text-q/--keyword关键词存在时默认标题搜索--search-type type--srch-tptitle/제목或content/내용--category category--kindall、rent/임대、sale/분양、welfare/주거복지、land/토지等--status status—open/진행、closed/마감、announced/당첨자标题分类器--page number—页码默认 1--limit number--page-size返回行数被 SH 固定页大小 10 截断--seq number--id传该值则走详情查询--include-html—输出中附带原始 HTMLCLI 还支持detail seq的写法parseArgs中检测detail/--detail标记后的数字参数。出错时输出堆栈并设置进程退出码 1见 run。六、返回字段详解6.1 列表项字段列表解析见 parseListRows每行包含字段类型说明seqstring公告序号来自getDetailView(...)调用numberstring公告栏编号titlestring标题去掉 NEW 徽标文本departmentstring담당부서 负责部门registered_datestring登记日期如2026-05-14viewsnumber浏览量is_newboolean是否带 NEW 标记category/category_namestring分类键 / 官方分类名status/status_basisstring推断状态 / 恒为title_text_classifierdetail_urlstring官方详情页 URL顶层返回结构还包含query回显本次查询参数、summarypage、page_size、returned_count、total_count、sourcename: sh-public-html、proxy: false、原始url以及warnings数组便于调用方自检。6.2 详情字段详情解析见 parseDetailHtmlgetNoticeDetail返回{ notice, query, source }其中notice包含seq、title、registered_date、views、department、category、category_namecontent_text剥离脚本、样式与标签后的纯文本正文attachments附件元数据数组detail_url、warningsincludeHtml开启时还有html。6.3 附件元数据每个附件包含字段说明filename真实文件名如2025년 2차 행복주택 예비3차 계약결과.pdffile_seqSH 侧文件序号file_size字节数file_type类型标识如Apreview_url官方SH 预览/转换地址/app/com/util/htmlConverter.do?...刻意不暴露直接下载 URLdownload_url因为 SH 的文件下载行为可能与会话/策略相关直链并不稳定正确做法是把官方detail_url/preview_url交给用户浏览器处理。测试 test/index.test.js 专门断言download_url键不存在。七、分类别名映射表分类归一化由 normalizeCategory 完成别名经CATEGORY_ALIAS索引映射到官方板面。完整配置见 CATEGORY_CONFIGS分类键官方板面multi_itm_seq支持别名all전체multi_itm_seqs1,2,4,8,16,32,64,128,256,512all、전체sale주택분양1sale、분양、주택분양、분양주택rent주택임대2rent、임대、주택임대、임대주택purchase주택매입512purchase、매입、주택매입、매입임대、welfare、주거복지movein입주안내4movein、입주、입주안내land토지8land、토지commercial상가/공장16commercial、상가、공장compensation보상/이주32compensation、보상、이주design현상설계64design、현상설계、설계etc기타256etc、기타重要提示주거복지并不是 SH 公告板的公开标签而是面向用户的友好别名当前映射到 SH 公开的주택매입板multi_itm_seq512。使用该别名时应在答复中向用户说明这一映射关系instruction.md 明确要求如此。别名匹配前会先做归一化normalizeToken去掉所有空白、trim、转小写因此 임대 、임대等价。八、状态分类器原理SH 公开列表没有一等公民的状态字段没有접수중/마감之类的列因此模块采用保守的标题文本分类器classifyNoticeStatus推断状态触发关键词标题内出现announced당첨、발표closed마감、계약결과、결과、완료、종료open모집공고、입주자 모집、신청、접수、공고unknown以上均未命中状态筛选在解析后进行statusMatches并把status_basis标记为title_text_classifier以便下游感知其推断性质一旦传入了status参数返回的warnings中也会追加说明。响应时务必向用户披露“状态系从标题推断除非公告正文写明确切日期”。测试 test/index.test.js 验证了계약결과标题被归为closed而open筛选返回空的行为。九、源码级实现原理9.1 请求构建与容错URL 构建buildSearchUrl用标准URL对象拼接base config.path /list.do再按需写入multi_itm_seq(s)、page、srchWord、srchTpbuildDetailUrl类似地拼view.do与seq。fetch 注入fetchText优先使用调用方注入的fetcher否则回退global.fetch请求头固定携带user-agent: Mozilla/5.0 (compatible; k-skill/sh-notice-search)与accept: text/html,...。测试验证了该 UA 头test/index.test.js。超时createTimeoutSignal在支持AbortSignal.timeout的运行时用其实现超时默认 20 秒。HTTP 错误非 2xx 响应抛出带状态码与前 200 字节正文的错误信息。9.2 HTML 解析的关键策略列表解析优先定位div idlistTb内的tbody逐tr提取。判定有效行的关键是找到getDetailView(seq)JS 调用单元格不足 5 列的行跳过标题会去掉NEW徽标。总数通过총 strongN/strong 건正则提取。文本清洗stripTags先移除script/style再剥标签decodeHtml完整处理数字实体十进制/十六进制与amp;、lt;、gt;、quot;、nbsp;等常见实体。附件解析parseAttachments是本模块最有辨识度的部分有两条严格规则只认带existFile(N)onclick 的真实附件锚点并显式过滤.pdf/.hwp等图标模板文本——测试 fixture 中专门把图标模板注释掉以验证其不会被误解析test/index.test.js附件文件名、大小、类型优先来自页面内嵌的downListJSON 元数据并与htmlConverter.do预览链接按file_seq配对。预览链接白名单normalizeAttachmentPreviewUrl只接受www.i-sh.co.kr同源且路径为/app/com/util/htmlConverter.do的链接防止被注入外部地址——测试用evil.example替换后断言preview_url为空test/index.test.js。9.3 异常面检测与 warnings当响应缺少预期的列表/详情标记时buildUnexpectedHtmlWarnings 会扫描页面中的NetFunnel、captcha/보안문자、로그인、점검、대기열、차단等关键词给出形如unexpected SH list HTML; possible block/maintenance markers: NetFunnel, 로그인, 점검的警告。测试用一份含“서비스 점검 안내 / NetFunnel 대기열 또는 로그인”的拦截页验证了该行为test/index.test.js它让调用方在遇到限流/维护页时能快速识别而不是得到静默的空结果。十、测试与质量保障测试文件 test/index.test.js 使用 Node 内置node:testnode:assert/strictnpm test即运行package.json 中scripts.test为node --test覆盖参数归一化关键词默认标题搜索、韩英分类别名、状态别名、非法输入抛错URL 构建hostname、路径、srchTp、multi_itm_seq与seq参数列表/详情 HTML 解析总数、行字段、详情字段、附件配对拦截页检测列表与详情的 warnings端到端通过注入的假fetcher走通searchNotices→getNoticeDetailCLIparseArgs解析与--help输出。十一、失败模式与使用注意综合 README 的 Boundaries、instruction 的 Failure modes 与源码实现接入时需注意SH 可能变更板面路径、表格标记、JS 函数或downList结构导致解析部分失败或完全失败——务必把warnings纳入处理逻辑IP 限流、NetFunnel 节流、维护页或临时 4xx/5xx会阻塞实时抓取模块只做被动检测warnings不得绕过CAPTCHA、登录或排队保护pageSize/limit超过 10 无意义SH 板每页固定返回 10 行追加结果请翻页page关键词必须与srchTp成对出现客户端已默认处理附件预览/下载受 SH 当前直链与下载策略约束应把官方 URL 交还用户浏览器状态为标题推断结果非官方字段答复时需披露。结语sh-notice-search的价值在于把“SH 公开公告查询”这件容易被各种反爬策略与 HTML 结构变化困扰的事情收敛为一个参数规范、边界清晰、可测试的 Node 客户端官方 URL 直连、无需代理与密钥、srchWordsrchTp配套、真实附件锚点识别、拦截页警告配合完整的单元测试与 skill 说明文档sh-notice-search/instruction.md无论是嵌入 Agent 技能还是独立脚本使用都能在合规前提下稳定读取 SH 的 청약·주택 공고 信息。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考