ev-subsidy-status基于环境部无公害汽车综合网站的无登录韩国电动车补贴查询方案【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本指南深入解析 k-skill 仓库中ev-subsidy-status包对应根目录ev-subsidy-statusSkill的实现与使用它如何在不登录、不依赖用户浏览器、不使用代理与 API Key 的前提下直接读取韩国环境部无公害汽车综合网站ev.or.kr公开的电动车购买补贴发放现状公告、受理、出库、出库剩余台数并支持按车型与细分车型查询国费、地方费补贴。读完本文你将掌握该工具的全部 CLI 命令与参数、direct-http与browser双传输机制、pnp4web保护 HTML 的还原原理、返回数据字段语义、状态判定规则以及错误码体系可直接复现官方文档示例并在 Agent 场景中正确消费其结果。一、工具定位面向韩国地方自治团体的电动车补贴查询ev-subsidy-status包目录是一个以 Node.js 18 运行的命令行工具与库其核心目标是用一行命令回答我所在地区还能不能申请电动车补贴、还剩多少台这类问题。它的特点与边界在官方 README.md 中明确界定查询环境部无公害汽车综合网站公开的购买补贴发放现状全程无需登录也不使用用户浏览器默认传输方式为direct-http从公开响应中读取官方pnp4web.js字符表在不执行远程代码的前提下还原被保护的 HTML不使用代理也不使用 API Key官方页面结构一旦变化可通过--transport browser显式选择诊断用浏览器路径官方页面提供的是公告、受理、出库、出库剩余台数而非韩元余额仅在指定--model时才在 direct-http 路径下额外查询模型级国费、地方费与合计并给出剩余换算值输入名称匹配到多个细分模型时返回全部候选绝不任意挑选其中一个换算值不是精确的可支配预算余额。在仓库中它同时以 Skill 形态存在ev-subsidy-status/SKILL.md供 Agent 在回答用户所在地区电动车补贴问题时调用并在无公害汽车综合网站页面进行后续动作时使用官方表层界面。二、快速开始安装与三个核心命令包声明在 package.json 中bin入口为src/cli.jsmain为src/index.js运行时要求 Node.js 18运行时依赖仅有k-skill-browser-runtimebrowser 路径使用。官方 README 给出的三条基础命令可直接运行通过npx免全局安装# 查询某地区某车型某年的补贴发放现状 npx ev-subsidy-status status --region 경기 성남시 --vehicle passenger --year 2026 # 查询某地区指定模型的补贴并输出 JSON npx ev-subsidy-status status --region 서울 강남구 --model 모델명 --json # 按关键词搜索地区解决同名区划歧义 npx ev-subsidy-status regions --query 중구第一条命令会输出类似下方的人类可读结果格式来自 cli.js 的 formatStatus경기 성남시 전기승용 보조금 현황 조회: 2026-07-18T20:00:0009:00 민간공고대수: 1,949대 (우선 55, 법인·기관 0, 택시 20, 일반 1,043) 접수대수: ... 출고대수: ... 출고잔여대수: ... 상태: closed 접수방법: ... 비고: ...输出末尾会强制附上免责声明출고잔여대수는 실제 신청 가능 대수와 다를 수 있으며 정확한 원화 예산 잔액이 아닙니다.出库剩余台数可能与实际可申请台数不同也不是精确韩元预算余额以及官方来源 URL 与 KST 查询时刻——这正是源码中保守回答设计原则的体现。三、命令与参数全解CLI 参数解析实现在 cli.js 的 parseArgs 与 printHelp 中。工具提供两个子命令子命令说明status查询指定地区的补贴发放现状默认命令可省略regions按查询词搜索地区候选返回sido_name/local_code等字段3.1 全局参数参数别名类型说明默认值--region region-rstring查询地区建议시도 시군구格式如경기 성남시无status 必填--query text-qstringregions命令的地区搜索词无regions 必填--vehicle type--vehicle-typestring车型passenger/승용、cargo/화물、bus/승합passenger--year year-number基准年度默认 Asia/Seoul 当前年当前年--category category-string类别过滤默认allall--model model-string指定模型后查询地方自治团体的模型级补贴与剩余换算值无--transport transport-stringdirect-http默认或browserdirect-http--provider provider-stringbrowser 传输下的浏览器供应方auto、aside、browseros、chrome-cdp依运行时--cdp-url url-string用户自行启动的 Chrome/BrowserOS CDP 地址无--timeout ms-number页面等待超时毫秒源码默认 30000ms30000--json-flag输出 JSON 而非人类可读文本关regions命令还支持位置参数npx ev-subsidy-status regions 중구与--query 중구等价见 cli.js parseArgs。3.2 车型别名的归一化车型解析位于 constants.js resolveVehicleType支持韩英双语别名不支持的车型会抛出VEHICLE_TYPE_NOT_AVAILABLE错误key页面标签carTypeCode支持别名passenger전기승용电动乘用11passenger、car、승용、전기승용、전기차cargo전기화물电动货车12cargo、truck、화물、전기화물bus전기승합电动客车13bus、van、승합、전기승합3.3 地区名的归一化与歧义处理地区输入会经过 parse.js normalizeRegionKey 做归一化去除空白、将경기도→경기、충청북도→충북、제주특별자치도→제주等全称折叠为标准名并剥离특별시/광역시/특별자치시/도等后缀。constants.js的SIDO_ALIASESconstants.js内置 17 个市道首尔、釜山、大邱、仁川、光州、大田、蔚山、世宗、京畿、江原、忠北、忠南、全北、全南、庆北、庆南、济州的全部常用写法。对于중구、강서구这类多个市道共有的区名系统会抛出REGION_AMBIGUOUS此时应先用regions找到候选并让用户指定市道npx ev-subsidy-status regions --query 중구四、双传输架构direct-http 与 browser传输选择逻辑位于 index.js browserRequested当显式指定transport: browser或传入page、runtime、provider、cdpUrl任一选项时走浏览器路径否则走直连 HTTP 路径。4.1 direct-http解析 pnp4web 字符表不执行远程代码这是默认且推荐的路径instruction.md 对其行为做了明确描述源码在 http.js 与 pnp.js向https://ev.or.kr/nportal/buySupprt/initSubsidyPaymentCheckAction.do发送POST表单字段为car_type车型码、year1年度以及全国地区条件localDo_cdall、local_cd1allhttp.js fetchDecodedStatusHtml若响应含meta namepenc标记说明正文被pnp4web保护则从 HTML 中提取官方pnp4web.js的 URLpnp.js extractPnpScriptUrl只解析脚本中声明的var In[...]片段字符表与o0~o6七个字母表parsePnpAlphabets绝不通过eval/vm执行远程代码从页面onload中提取受保护 payload按其首字符选择字符表、次字符做轮转位移再进行类 Base64 解码还原出 UTF-8 HTMLdecodePnpPayload在还原后的表格中定位含출고잔여的表extractStatusRows解析十列官方行并从公告下载函数goDownloadFile(...)的参数中读取地区代码若响应不含penc标记页面未被保护则直接作为明文处理。请求带默认请求头与 30 秒超时http.js DEFAULT_TIMEOUT_MS超时会转为UPSTREAM_TIMEOUT。该路径全程无浏览器、无登录、无代理、无 API Key是 README 所述即使没有用户浏览器也应正常工作的默认路径。注意官方公开的是 keyless 页面因此本工具不使用k-skill-proxy。4.2 browser诊断用浏览器路径当官方页面结构变更、需要诊断渲染结果或核对模型级换算时可显式选择浏览器路径npx ev-subsidy-status status --region 경기 성남시 --transport browser --provider auto npx ev-subsidy-status status --region 경기 성남시 --transport browser --provider aside npx ev-subsidy-status status --region 경기 성남시 --transport browser --provider browseros npx ev-subsidy-status status --region 경기 성남시 --transport browser --provider chrome-cdp该路径通过k-skill-browser-runtimepackage.json 依赖^0.4.0连接用户自己启动的 Aside Browser、BrowserOS 或 Chrome CDP 会话相关实现见 browser.js withAutomationPage。其设计原则在 instruction.md 的 Optional browser behavior 中有明确约束页面加载使用domcontentloaded刻意不用networkidle因为pnp4web存在后台请求会导致永不静默通过轮询显式等待目标 selector 与地区行出现waitFor 默认 300ms 轮询间隔用渲染后option的 label/value 动态解析地区代码resolveRegion不关闭用户已有的标签页与个人资料只清理本 Skill 创建的页面/上下文并仅对支持的 client 执行disconnect绝不绕过登录、CAPTCHA、支付、电子签名与最终提交等边界——检测到 CAPTCHA 立即抛CAPTCHA_DETECTED并停止assertPublicStatusPage。浏览器上下文固定使用ko-KR语言与Asia/Seoul时区、1280×900 视口browser.js withAutomationPage保证页面渲染与解析结果一致。五、返回数据结构与字段语义status命令的 JSON 结果由 parse.js buildStatusResult 组装顶层结构如下{ query: { region: 경기 성남시, year: 2026, vehicle_type: passenger, category: all, model: null }, region: { sido_name: 경기, sido_code: 41000, local_name: 성남시, local_code: 41130 }, status: { sido_name: 경기, local_name: 성남시, vehicle_label: 전기승용, notice_files: [{ label: 본공고 1, title: , onclick: goDownloadFile(...) }], application_method: 출고등록순, notice_count: { total: 1949, priority: 55, corporate: 0, reserved: 20, general: 1043 }, application_count: { total: 1745, priority: 550, corporate: 49, reserved: 60, general: 1086 }, delivered_count: { total: 1740, priority: 549, corporate: 49, reserved: 60, general: 1082 }, delivery_remaining_count: { total: 209, priority: 0, corporate: 0, reserved: 0, general: 867 }, note: ★ 공고 마감 ★ 추경예산 확보 후 재공고 예정, warnings: [] }, availability: { label: closed, basis: [note:closed], warnings: [], official_remaining_count: 209, pending_application_count: 5, actual_application_count_known: false }, remaining_budget: { exact_available: false, exact_amount_krw: null, reason: ..., model_equivalent_estimate_krw: null, estimate_assumptions: [] }, source: { name: 환경부 무공해차 통합누리집, url: https://ev.or.kr/..., fetched_at: 2026-07-18T20:00:0009:00 }, transport: direct-http, warnings: [] }关键语义说明四个台数对象均保留전체total/ 우선priority/ 법인·기관corporate/ 예약 대상군reserved/ 일반general五个槽位乘用车的reserved同时以taxi别名返回货车的以small_business别名返回parse.js categoryCountsForVehiclesource.fetched_at是 KST 格式的查询时刻formatKstUTC9pending_application_count 受理台数 - 出库台数表示在办申请量actual_application_count_known: false表明公开数据无法给出精确的实际可申请台数remaining_budget.exact_available恒为false因为公开发放现状无法精确计算韩元预算余额当目标群数值出现负数、或分项之和与总数不一致时不做修正原样返回并追加 warningcountWarnings。六、状态判定非注明优先于剩余台数availability.label的判定逻辑在 availability.js classifyAvailability优先级如下instruction.md 亦有说明优先级判定依据비고 原文正则label1含마감/소진/접수 종료/신청 종료closed2含접수 예정/추경 예정/추가 공고 예정/재공고 예정scheduled3含접수 중/신청 기간/접수 기간/신청 가능open4无明确措辞但剩余台数为正unknown_with_remaining_count5无任何依据unknown两条铁律备注原文优先于数字即使剩余台数为正只要备注写明마감/소진就判定为closed并附 warning出库剩余台数为正但备注为截止/耗尽availability.js。测试 index.test.js availability gives explicit closure text precedence 验证了일반 접수 마감, 추경 공고 예정在剩余 20 台时仍判为closed。不编造可申请性无明确措辞时绝不擅自说可申请只报unknown_with_remaining_count。七、模型级补贴与剩余换算值model 查询指定--model后即便在 direct-http 路径下也会以POST请求官方模型补贴弹窗面https://ev.or.kr/nportal/buySupprt/psPopupLocalCarModelPrice.do表单为year年度local_cd地区代码car_type11|12|13见 constants.js MODEL_SUBSIDY_PATH 与 http.js fetchDecodedModelHtml。模型表解析parse.js parseModelSubsidyRows会读取제조사/모델/국비/지방비/합계等表头并按输入名做模糊匹配金额解析parseMoneyKrw自动识别억원、만원单位——例如1,200만원解析为 12,000,000 韩元测试见 index.test.js。行为细节输入名命中多个细分模型时返回model_subsidy_candidates全部候选及各自换算值不任意挑选并追加警告提示用户区分 trim 级补贴http.js getSubsidyStatusHttp恰好命中唯一细分模型时额外返回model_subsidy与remaining_budget.model_equivalent_estimate_krw模型查询失败不影响地区级台数结果只附加model_lookup_error与警告。model_equivalent_estimate_krw的计算在 estimate.js estimateModelEquivalent공식 출고잔여대수官方出库剩余台数× 선택 모델의 국비지방비所选模型国费地方费其附带的三条假设estimate_assumptions剩余台数全部划拨给所选模型、按已确认的单台国费地方费计算、不反映购买者特性追加支持与目标群间数量转换。官方 README 与源码均强调这不是地方自治团体的精确预算余额切勿向用户表述为精确可用预算。测试 index.test.js model equivalent is clearly separate from exact budget 专门断言exact_availablefalse、exact_amount_krwnull与换算值并存的边界。八、错误码体系与失败模式错误构造与包装位于 errors.jsCLI 失败时以 JSON 输出{ error: { code, message, details } }cli.js formatError。完整错误码清单instruction.md Failure modes错误码触发场景REGION_REQUIRED未输入查询地区REGION_AMBIGUOUS同名区划存在于多个市道需连同市道一起输入REGION_NOT_FOUND官方地区列表中找不到该地区YEAR_NOT_AVAILABLE请求年度不在页面可选列表VEHICLE_TYPE_NOT_AVAILABLE车型不受支持或页面无此车型项BROWSER_UNAVAILABLE没有可连接的用户浏览器UPSTREAM_BLOCKED空壳响应、被拦截或异常页面CAPTCHA_DETECTED出现 CAPTCHA工具不绕过AUTH_REQUIRED公开页面变为登录流程工具不绕过RESULT_EMPTY目标地区无结果行DOM_CHANGED官方页面选择器或表格结构变化UPSTREAM_DECODE_FAILEDpnp4web字符表或保护 payload 格式变化MODEL_LOOKUP_FAILED模型补贴表读取失败UPSTREAM_TIMEOUT官方站点响应超时其中UPSTREAM_DECODE_FAILED与DOM_CHANGED是官方脚本或表格结构变化时的哨兵错误指示需要切换到 browser 路径诊断详见 http.js、pnp.js。九、源码结构地图若需深入阅读仓库中与本文相关的核心文件路径如下包根packages/ev-subsidy-status/package.json、packages/ev-subsidy-status/README.mdCLI 层cli.js参数解析、人类可读/JSON 输出、错误格式化入口分发index.js根据选项选择传输路径直连 HTTP 路径http.js表单提交、地区解析、模型表抓取pnp4web 解码器pnp.js字符表解析与 payload 还原浏览器路径browser.jsDOM 求值操作、地区/车型联动选择、与 k-skill-browser-runtime 的连接常量与别名constants.jsURL、车型定义、市道别名解析与装配parse.js、availability.js、estimate.js测试test/index.test.js数值解析、状态判定、金额单位、CLI 参数、输出披露共 11 个用例Skill 侧ev-subsidy-status/SKILL.mdSkill 元数据与硬性规则、ev-subsidy-status/instruction.mdAgent 操作指引与本文各节一一对应十、在 Agent 场景中的使用建议综合官方 README、instruction.md 与源码行为将ev-subsidy-status用于 Agent 或自动化流程时应注意默认走 direct-http优先使用--transport direct-http默认确认结果中transport为direct-http确保在无浏览器环境可用地区输入规范尽量传市道 市郡区重名区划先用regions消歧解读优先级先看availability.label与status.note原文再看台数备注为closed时即使剩余为正也不要说可申请保守披露始终附带出库剩余台数≠实际可申请台数≠精确韩元余额的警示并给出官方来源 URL 与 KST 查询时刻模型换算有假设引用remaining_budget.model_equivalent_estimate_krw时说明计算假设不表述为精确预算余额多候选时把model_subsidy_candidates全部列出让用户选择不绕过边界遇到CAPTCHA_DETECTED、AUTH_REQUIRED时停止并如实上报遵守 Skill 中不绕过登录、验证码、支付、电子签名边界的硬性规则结构变化时切换诊断出现DOM_CHANGED或UPSTREAM_DECODE_FAILED时用--transport browser --provider aside|browseros|chrome-cdp连接用户浏览器核验官方页面现状。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考