k-skill seoul-weather-risk 深度解析基于 ASK 서울 的行政洞级气象风险时段只读查询实践【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本文以开源仓库k-skill中的seoul-weather-risk技能为主线讲解如何将首尔自然语言行政洞名행정동确定性解析为place_id并通过 hostedk-skill-proxy只读查询 ASK 서울 的weather_place_risk_window单产品获取按place_id与forecast_at为粒度的暴热、寒潮、暴雨、大雪、强风风险候选时段。读完本文你将掌握该技能的安装方式、fast path 与 full-contract 两条查询路径、preflight/catalog/describe合同诊断流程、行政洞映射与别名规则、时间窗交集重试机制以及全部失败模式与安全边界并能对照仓库源码与测试用例理解其底层实现。技能定位与数据产品seoul-weather-risk是一个面向韩国用户的只读查询技能见 skill.json类别public-data、语言ko-KR、阶段live-client。它只处理一个数据产品weather_place_risk_window场所别气象风险预想时段。基于预报值将暴热폭염、寒潮한파、暴雨호우、大雪대설、强风강풍候选通过阈值筛选后生成属于预报基准参考信息而非气象厅기상청官方特报。数据粒度grain每个place_id与每个forecast_at一行。典型提问잠실본동에서 오늘 방문·이동에 주의할 기상 위험 시간대와 근거를 알려줘.查询蚕室本洞今日出行需注意的气象风险时段与依据。该技能是单产品契约若 bundle 中混入其他产品、或缺少该产品helper 会以响应合同错误response_contract_invalid中止绝不静默降级。核心保证有三条见 instruction.md默认 helper 只调用 hostedk-skill-proxy不读取用户 API Key 或当前工作目录下的.env失败或未就绪状态绝不用 fixture 或推测值代替。整体架构与调用链从源码 seoul_weather_risk.py 看helper 是一个纯标准库实现的只读 HTTPS 客户端urllib.request调用链为CLI / Agent │ npx -y nomadamas/k-skill0 exec seoul-weather-risk scripts/seoul_weather_risk.py ▼ seoul_weather_risk.py本地行政洞→place_id 解析、参数校验、响应契约校验 ▼ k-skill-proxy默认 https://k-skill-proxy.nomadamas.org ▼ ASK Seoul 上游proxy 运营环境中保管专用服务密钥proxy 仅暴露三条只读 routeDEFAULT_PROXY_BASE_URL 与PROXY_ROUTE_ROOT定义于源码头部Route用途GET /v1/ask-seoul/weather-risk/bundle查询 bundle 及其中产品集合GET /v1/ask-seoul/weather-risk/product查询单产品 metadatagrain、公开列、blockersGET /v1/ask-seoul/weather-risk/data查询数据页支持place_id等过滤、分页 cursor关于该路线的设计动机可参考 fast path 设计文档它旨在削减常规今日风险提问中重复的 bundle/product metadata 往返同时不再恢复本地直连或用户 API Key 路径。整体能力说明见 功能指南。环境要求与安装前置条件网络连接Node.js含npx通用安装与安全/密钥策略请先阅读 install.md 与 security-and-secrets.md。安装技能npx --yes skills add NomaDamas/k-skill --skill seoul-weather-risk -g环境变量一般用户无需任何环境变量。唯一可选变量是KSKILL_PROXY_BASE_URL仅在自建/自托管 proxy 时设置留空时使用默认 hosted originhttps://k-skill-proxy.nomadamas.org该值必须是HTTPS origin。源码 _api_config 会严格校验非 HTTPS 且非本地回环127.0.0.1/localhost/::1会被拒绝带路径、query、fragment 或内嵌用户名密码也会被拒绝为invalid_proxy_base_url环境变量取值为off/false/0/disable/disabled/none时视为禁用 proxy抛出proxy_disabled该值不得写入命令行参数、文档或日志。用户侧不存在 API Key 流程ASK 서울 专用服务密钥只放在 proxy 运营环境并通过 Marketplace 的k-skill-proxy:seoul-weather-riskprincipal 授予skill:seoul-weather-risk:readscope仅允许 bundle、product、data 读取拒绝其他 Marketplace API。任何模式下都不得将密钥打印、写日志或写入技能文件。测试 test_parser_has_no_credential_or_base_url_option 专门断言解析器没有任何 key/url 相关选项。行政洞名称到 place_id 的确定性解析这是本技能最核心的工程点用户不需要知道内部place_idhelper 在本地将自然语言行政洞名转换为标准place_id格式seoul_admd_ 10 位数字见 _load_location_mapping且只向 proxy 发送place_id绝不上送行政洞/自治区字符串。测试 test_query_maps_admin_dong_to_place_id_before_proxy_request 验证了请求 query 中只有place_id与limit。映射 reference文件admin-dong-place-map.json版本kma_admin_dong_grid_20260325源码常量 LOCATION_MAPPING_VERSION规模427 个首尔行政洞place_id全局唯一字段契约每行恰含admin_dong、gu、place_id三个非空字符串缺失/多余字段、重复place_id、重复洞,区组合都会抛location_mapping_invalid测试 test_admin_dong_reference_has_expected_version_and_unique_place_ids 断言版本号、427 行数、427 个唯一place_id并验证신사동同时存在于 강남구 与 관악구。匹配优先级规范名 确定性别名 失败解析函数 _resolve_admin_dong 的完整规则输入规范化先做 Unicode NFC 归一化兼容 NFD 输入测试 test_resolve_admin_dong_normalizes_unicode_nfc再去除首尾与内部多余空白测试 test_resolve_admin_dong_normalizes_internal_whitespace。官方行政洞名精确匹配优先匹配到的结果优先于任何别名解析测试 test_location_indexes_retain_colliding_aliases_and_resolve_exact_first 验证别名与规范名冲突时取规范名。仅在无精确匹配时应用确定性别名_alias_keys别名只允许两类变换数字前的제可省略如성수2가제3동→성수2가3동源码用正则제(?\d)只删数字前的제제기동这类非数字제绝不省略见测试 test_resolve_admin_dong_does_not_omit_non_numeric_je数字分隔符三种写法等价.句点、·间隔点、省略如종로1.2.3.4가동、종로1·2·3·4가동、종로1234가동三者等价测试 test_resolve_admin_dong_accepts_numeric_punctuation_aliases。超出以上规则的别名一律不生成。候选冲突处理若别名阶段命中多个候选则用--gu收窄不带--gu仍冲突时保留为ambiguous_admin_dong绝不任意选择。无法解析即失败拼写错误、相似名、生活圈/俗称、部分名称如성수동、종로一律不做 fuzzy match 或猜测直接返回unknown_admin_dong。同音/同名人동명이명首尔存在同名的行政洞典型如신사동강남구 与 관악구 各有一个。处理方式是先向用户确认自治区再带--gu查询npx -y nomadamas/k-skill0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- query --fast \ --product-id weather_place_risk_window \ --admin-dong 신사동 \ --gu 강남구 \ --limit 100测试 test_resolve_admin_dong_requires_gu_for_duplicate_name 确认不带--gu时会抛出ambiguous_admin_dong且details.candidates中包含两个候选含各自gu与place_id供用户选择。自动化调用直接使用 place_id既有自动化脚本可继续用--filter place_idseoul_admd_...直查例如npx -y nomadamas/k-skill0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- query \ --product-id weather_place_risk_window \ --filter place_idseoul_admd_1171065000 \ --from 2026-08-11 \ --to 2026-08-17 \ --limit 100但--admin-dong与--filter place_id...不得同时使用否则返回conflicting_location_input测试 test_query_rejects_admin_dong_with_place_id_filter。同样--gu不能脱离--admin-dong单独使用返回invalid_location_input测试 test_query_rejects_gu_without_admin_dong。查询工作流fast path 与 full-contract标准用户查询fast path用户询问今日风险时段的默认路径是只执行一次query --fastnpx -y nomadamas/k-skill0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- query --fast \ --product-id weather_place_risk_window \ --admin-dong 잠실본동 \ --from 2026-08-12 \ --to 2026-08-12 \ --limit 100fast path 的设计要点详见 fast path 设计文档 与源码 run保留本地 bundled 行政洞映射、日期与 limit 校验只调用一次 hosted data route/v1/ask-seoul/weather-risk/data省略 bundle、product metadata 两次往返--fast下不支持--filter源码 L501-L502 会抛fast_query_filter_unsupported只允许--admin-dong、--gu、日期、--limit、--cursor测试 test_fast_query_uses_only_data_route_without_metadata_round_trips 验证fast 查询仅命中 data route 一次且请求中不携带任何Authorization头place_id已被解析为seoul_admd_1171065000잠실본동。需要任意--filter、或需要检查发布契约时去掉--fast走 full-contract 查询先查 bundle再查 product最后查 data见测试 test_query_uses_narrow_proxy_paths_without_user_bearer_authnpx -y nomadamas/k-skill0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- query \ --product-id weather_place_risk_window \ --admin-dong 잠실본동 \ --from 2026-08-11 \ --to 2026-08-17 \ --limit 100日期范围的语义--from YYYY-MM-DD扩展为当日00:00:00--to YYYY-MM-DD扩展为当日23:59:59源码 _time_bound显式给出具体时刻如2026-08-11 09:00:00则原样保留不扩展测试 test_query_keeps_explicit_datetime_bounds_unchanged自然语言中的今天/明天/本周应在调用前由 Agent 转换为 KST 显式区间。服务窗口交集重试422 处理ASK 서울 的 serving window 并非从午夜开始例如数据当日 17:00 才开放。当请求区间不被接受、上游返回422 query_window_unavailable时helper 会自动做一次交集重试从错误响应的detail中提取requested_from_at/requested_to_at/available_from_at/available_to_at/publication_id字段清单见源码 QUERY_WINDOW_DETAIL_FIELDS通过 _intersect_query_window 计算请求区间与可用窗口的交集支持 ISO 与YYYY-MM-DD HH:MM:SS两种时间戳排序键见 _window_sort_key若交集存在则仅重试一次用交集覆盖from/to_retry_query_after_unavailable_window若请求区间与可用窗口无交集则直接以query_window_unavailable中止并携带available_from_at/available_to_at。测试覆盖完整如请求2026-08-24全天、可用窗口2026-08-24 17:00:00起则自动以17:00:00–23:59:59重查test_query_clips_calendar_day_to_available_window完全无交集时失败并保留可用窗口信息test_query_window_without_overlap_fails_with_available_bounds。注意带--cursor的分页请求不做窗口交集重试测试 test_paged_query_does_not_retry_unavailable_window错误详情中缺失可用窗口信息时也不重试test_query_window_problem_without_available_bounds_does_not_retry。绝不填充不存在时间段的推测数据。合同诊断仅在需要时fast path 返回product_not_ready或契约错误时不要用 fixture/推测值替代而是按下述顺序诊断仅在这类场景执行普通提问不执行1. preflight仅检查环境配置不发起网络请求npx -y nomadamas/k-skill0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- preflight返回status: ok、mode: hosted_proxy、live_network: false、proxy_base_url_configured: true源码 run。live_network: false仅表示未联网不代表数据已就绪。测试 test_preflight_is_user_secret_free_and_offline 还验证 preflight 不会泄露任何用户密钥。2. catalog检查 bundle 就绪状态npx -y nomadamas/k-skill0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- catalog重点查看registration_readybundle 是否可用于当前查询、products是否恰为weather_place_risk_window单产品、blockers未解决的发版阻塞原因、publication_id当前发布版本标识。bundle 校验函数 _validate_bundle 要求产品集合严格等于单产品集合任何 drift 都会以response_contract_invalid失败关闭测试 test_bundle_single_product_drift_fails_closed。3. describe查看产品契约npx -y nomadamas/k-skill0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- describe --product-id weather_place_risk_window返回 grain、主键、时间轴、公开列及证据 metadata。metadata.columns列出可过滤的公开列测试 fixture 中包含place_id、forecast_at、risk_labels。registration_ready为false或blockers非空时不得视为查询成功。分页与 cursor 纪律data 响应中next_cursor只能原样复用于同一产品的下一页publication 变更后 cursor 会以409 cursor_expired过期——此时应回到第一页重新查询不要无限重试旧 cursor。响应解读数据响应是单页 JSON字段含义如下字段含义publication_id该页数据所属的发布版本续页时须保持一致row_count实际行数必须等于rows长度源码 _validate_data 强校验rows行列表含place_id、forecast_at、risk_labels等公开列has_more/next_cursor是否还有下一页 / 下一页游标两者必须一致forecast_at风险候选的预报时刻即本产品的时间轴risk_labels暴热/寒潮/暴雨/大雪/强风等风险候选标签向用户汇报时Done when 要求见 instruction.md必须包含实际响应的publication_id、时间轴forecast_at、usage与行数同时绝不把503未就绪产品及认证/权限/配额错误表述为成功。失败模式全表helper 把所有错误归一为结构化 JSON{error: {code, message, details}}写入 stderr进程退出码 2见 run。各 code 及含义错误码HTTP说明与应对invalid_limit—--limit超出1..500默认100invalid_location_input/conflicting_location_input—行政洞·自治区·直接place_id输入组合错误如--gu无--admin-dong或两者与place_id过滤器混用unknown_admin_dong/unknown_gu—reference 中不存在的行政洞/自治区错别字、生活圈、部分名如성수동一律归为unknown_admin_dong不猜测ambiguous_admin_dong—同名人或别名候选冲突需--gu从details.candidates中查看可选自治区location_mapping_invalid—bundled 行政洞 reference 的版本/模式/行数契约错误proxy_disabled/invalid_proxy_base_url—proxy 环境配置错误KSKILL_PROXY_BASE_URL被禁用或非合法 HTTPS originunauthorized/api_key_missing401认证失败/缺少密钥forbidden/api_key_forbidden403权限不足unknown_product404未知产品cursor_expired409publication 变更导致 cursor 失效需从头重新分页query_window_unavailable422请求区间与当前可用预报窗口无交集查看details.available_from_at/available_to_at在可用区间内查询。若本可相交则此错误已是 helper 自动交集重试一次后的结果rate_limited429超限流遵守响应中的Retry-After后重试product_not_ready503产品未发布就绪用catalog查registration_ready与blockersupstream_not_configured503proxy 运营环境未配置 ASK 서울 专用服务密钥或 originresponse_contract_invalid/malformed_response—单产品契约或 API 响应契约漂移如非 JSON、缺字段、row_count与rows长度不符、has_more与next_cursor不一致network_error—无法连接 proxyHTTP 错误到 code 的映射见源码 STATUS_CODES测试 test_http_problem_statuses_are_typed_and_preserve_safe_details 验证 401/403/404/409/429/503 均被类型化并安全保留request_id、product_id、Retry-After等详情。安全与使用边界该技能在设计上刻意收窄了攻击面边界包括不接受table name、SQL、join、sort、aggregate 等任意查询输入不猜测未知产品或过滤器进行纠正不做行政洞模糊匹配或从歧义候选中任意挑选生活圈/俗称/部分名不当作行政洞helper 在本地 reference 解析place_idproxy 侧只收到place_id不跟随重定向源码 _NoRedirect 阻断所有重定向防止读请求被静默转发到未审查的 origin测试 test_redirect_is_not_followed_through_proxy_client代理仅暴露bundle、单产品及数据查询不向上游传递非允许字段bundle 产品集合不等于单产品时以response_contract_invalid中止_validate_bundlelive 失败绝不用 fixture/synthetic 结果替代响应中必须明确该产品是预报阈值参考信息不替代气象厅官方特报响应头Content-Type非 JSON 也会以malformed_response失败见 _request_json。测试 test_local_direct_settings_are_ignored_and_hosted_proxy_remains_the_only_route 还证明即便环境里存在KSKILL_LOCAL_DIRECT、ASK_SEOUL_SKILL_API_BASE_URL、MARKETPLACE_API_KEY等遗留配置helper 仍只走 hosted proxy 且不携带任何Authorization头。使用前检查清单常规用户查询只执行一次query --fast仅当 fast path 失败或需显式检查发布契约/就绪状态时才按preflight → catalog → describe顺序诊断诊断时确认catalog的registration_readytrue且blockers为空describe中确认公开列与forecast_at时间轴行政洞名歧义时指定--gu汇报时包含publication_id、row_count、forecast_at、risk_labels明确告知用户这是预报参考信息而非官方特报不将错误响应改写为成功数据或推测值。延伸阅读技能详细执行契约seoul-weather-risk/instruction.md功能使用指南docs/features/seoul-weather-risk.mdHelper 源码seoul-weather-risk/scripts/seoul_weather_risk.py单测用例seoul-weather-risk/tests/test_seoul_weather_risk.py行政洞映射 referenceseoul-weather-risk/references/admin-dong-place-map.jsonfast path 设计文档docs/superpowers/specs/2026-08-12-seoul-weather-risk-fast-path-design.md通用安装指南docs/install.md安全与密钥策略docs/security-and-secrets.md【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考