k-skill 地铁失物查询技能：基于 LOST112 与首尔交通公社的官方查询路径实战指南

k-skill 地铁失物查询技能：基于 LOST112 与首尔交通公社的官方查询路径实战指南

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

本篇技术指南聚焦 k-skill 项目中的subway-lost-property技能：当用户询问“在某某地铁站丢了东西怎么找”时，它不会凭空猜测，而是把韩国官方失物查询体系（LOST112 拾得物目录 + 首尔交通公社失物中心）的搜索条件、HTTP 表单载荷（payload）与可运行的curl示例结构化输出给 Agent。读完本文，你将掌握如何通过一行npx命令生成带官方 referer 的完整查询载荷、如何保守地探测官方站点可达性，以及 v1 版本在“安内型/混合型”边界内的设计取舍与失败模式。

技能定位：安内型/混合型的官方查询路径组织器

subway-lost-property是一个面向韩国地铁失物（분실물/유실물）查询场景的 k-skill。其核心定位并非“自动抓取结果”，而是把官方路径结构化，帮助用户（及其 Agent）以最快、最合规的方式进入官方查询入口。

从该技能的 SKILL.md 描述与 skill.json 的 frontmatter 可以看出，它被归类为category: transit、locale: ko-KR、phase: v1，同时注册了lookupprofile，说明其设计意图是作为一种查找类能力被 CLI 组装进多 profile 的指令体系中。

instruction.md明确定义了三条边界：

• 整理 LOST112습득물 목록 조회的搜索条件（对应表单字段的取值）；
• 同时引导首尔交通公社失物中心入口，作为后续确认与补充信息源；
• 因为公开 API 不明确，v1 保持安内型/混合型范围——即不承诺自动结果采集，而是给出一套可执行的官方流程。

触发场景与输入要素

何时使用（When to use）

instruction.md给出了三个典型触发语句：

• “강남역에서 지갑 잃어버렸는데 어디서 찾아?”（在江南站丢了钱包该去哪找？）
• “2호선 지하철 분실물 조회 방법 알려줘”（告诉我 2 号线地铁失物查询方法）
• “서울 지하철 유실물 공식 사이트로 바로 찾게 도와줘”（帮我直接连到首尔地铁失物官网）

当检测到用户需要“按站名/物品名查询地铁失物”时，此技能即被触发。SKILL.md 中的描述还强调：在 돌쇠（Dolshoi）运行时中，可进一步通过官方界面进行后续动作。

输入要素（Inputs）

在源码 subway_lost_property.py 中，SearchQuery数据类以station、item、line、start_date、end_date五个字段承载上述输入，其中start_date/end_date由--days与today计算得出（默认 30 天回溯）。

官方查询面（Official surfaces）与关键表单字段

技能锚定两个官方入口（见instruction.md的 "Official surfaces" 一节）：

1. LOST112 拾得物目录：https://www.lost112.go.kr/find/findList.do
2. 首尔交通公社失物中心：https://www.seoulmetro.co.kr/kr/page.do?menuIdx=541

LOST112 搜索表单中确认的核心字段如下：

在源码 build_search_payload() 中，payload 不止上述字段，还包含完整的表单回填项：

payload = { "pageIndex": "1", "START_YMD": query.start_date.strftime("%Y%m%d"), "END_YMD": query.end_date.strftime("%Y%m%d"), "PRDT_NM": (query.item or "").strip(), "DEP_PLACE": station, "SITE": "V", "PLACE_SE_CD": "", "FD_LCT_CD": "", "FD_SIGUNGU": "", "IN_NM": "", "ATC_ID": "", "F_ATC_ID": "", "PRDT_CL_CD01": "", "PRDT_CL_CD02": "", "PRDT_CL_NM": "", "MENU_NO": "", }

日期字段按%Y%m%d格式化（例如 2026-04-10 →20260410），空字段在生成curl时会被自动跳过（见 build_curl_command() 中的if value判断），避免无意义参数污染请求。

四步工作流：从收集线索到保守引导

instruction.md将整个技能执行流程分为四步，下面结合源码逐一展开。

1) 先收集最少线索（Ask for the minimum clues first）

不要直接推测，而是先向用户确认：

• 在哪个站 / 哪个区间丢失？
• 物品类型是什么？
• 大约何时丢失？
• 属于首尔交通公社（1~8 号线）范围，还是其他运营商？

这一步的意义在于：不同运营商对应不同的失物保管体系，LOST112 的SITE=V聚合了地铁、机场等非警察机构，但最终认领仍需回到具体运营商的失物中心。源码 probe_source() 与official_sources中同时列出 LOST112 与首尔交通公社两个入口，正是为了覆盖这一区分。

2) 生成官方 LOST112 搜索载荷（Generate the official LOST112 search payload）

可以直接使用仓库自带的 helper：

npx -y @nomadamas/k-skill@0 exec subway-lost-property scripts/subway_lost_property.py -- \ --station 강남역 \ --item 지갑 \ --days 14

helper 默认使用SITE=V，并把站名/物品名/期限整理成带 referer 的可运行curl示例。示例curl考虑到官方响应较慢，包含--max-time 60，并将响应 HTML 保存为lost112-search-result.html。

从源码看，build_curl_command() 生成的命令具备以下工程化细节：

• -fsS：静默但保留错误输出；
• --http1.1、--tls-max 1.2：限定协议与 TLS 版本，规避官方旧服务器兼容性问题；
• --retry 1：单次重试；
• --max-time 60：整体超时上限（源码常量LOST112_CURL_MAX_TIME = 60）；
• -A "Mozilla/5.0"：设置基础 User-Agent；
• --referer https://www.lost112.go.kr/：携带官方 referer，提高请求被接受的几率（referer 常量见 subway_lost_property.py）；
• 非空 payload 字段逐项--data-urlencode；
• --output lost112-search-result.html落盘响应。

测试 test_subway_lost_property.py 对这一行为做了精确断言：命令中不包含-L（不跟随重定向）、--max-time值为60、--referer指向 LOST112 根域、--output文件名为lost112-search-result.html、payload 中含SITE=V、URL 收尾于findList.do。

3) 可选：实时探测官方站点可达性（Verify live reachability）

npx -y @nomadamas/k-skill@0 exec subway-lost-property scripts/subway_lost_property.py -- \ --station 강남역 \ --item 지갑 \ --days 14 \ --verify-live

--verify-live仅保守地检查官方页面是否可访问：probe_source()使用 15 秒--max-time的轻量探测（见 subway_lost_property.py），成功则标记reachable并记录抓取字节数；失败时区分timeout（curl 返回码 28 或 stderr 含 "timed out"）与error两类状态。站点慢时如实报告 timeout，并转为人工打开（manual open）流程。

测试 test_subway_lost_property.py 覆盖了两条路径：成功抓取标记reachable，以及CalledProcessError(28, ...)被归类为timeout。

4) 保守引导用户（Guide the user conservatively）

• 先在 LOST112 用站名原样搜索；
• 无结果时，改用去掉“역”的关键字（如강남）重新搜索；
• 必要时追加线路名搜索；
• 同时打开首尔交通公社失物中心页面，确认后续流程。

这一“降级搜索”策略在源码中体现为 expand_station_keywords()：输入강남역会生成["강남역", "강남"]两个建议关键词；若提供--line（如2호선），还会追加到suggested_keywords中并去重（见 build_search_plan()）。

CLI 输出结构：一个自包含的 JSON 计划

不带--verify-live时，CLI 通过main()输出完整 JSON 计划（ensure_ascii=False，便于韩文直接可读），结构见 SearchPlan.to_dict()：

{ "query": { "station": "강남역", "item": "지갑", "line": null, "start_date": "2026-04-10", "end_date": "2026-04-24" }, "payload": { "pageIndex": "1", "START_YMD": "20260410", "END_YMD": "20260424", "PRDT_NM": "지갑", "DEP_PLACE": "강남역", "SITE": "V", "...": "..." }, "suggested_keywords": ["강남역", "강남"], "official_sources": [ { "name": "LOST112 습득물 목록", "url": "https://www.lost112.go.kr/find/findList.do", "purpose": "...", "status": "not_checked" }, { "name": "서울교통공사 유실물센터", "url": "https://www.seoulmetro.co.kr/kr/page.do?menuIdx=541", "purpose": "...", "status": "not_checked" } ], "guidance": ["..."], "cautions": ["..."], "curl_example": "curl ..." }

guidance数组中的引导文本与cautions数组中的边界声明（v1 为安内型/混合型、不保证自动结果采集、站点慢则转 manual open）均由 build_search_plan() 动态生成。测试 test_subway_lost_property.py 验证了 JSON 输出中query.station、payload.SITE、curl_example与official_sources的存在性。

完成标准（Done when）与失败模式（Failure modes）

完成标准，三条缺一不可：

• 用户能直接打开官方查询路径；
• 用户已获得 LOST112 搜索条件（SITE=V、站名、物品名、期限）；
• 自动查询的保证范围与 manual fallback 已被清楚说明。

失败模式，需如实向用户说明：

• 官方站点响应慢或 timeout（由--verify-live探测并如实上报）；
• 站名与实际保管场所标注不一致导致搜索结果为空（对应关键词降级策略）；
• 因缺少公开 API，自动结果采集不稳定（这是 v1 保持安内型范围的根本原因）。

设计约束与扩展方向（Notes）

• v1 范围：仅安全引导官方网页流程；helper 只使用官方 HTTPS 入口（见源码LOST112_LIST_URL、SEOUL_METRO_LOST_CENTER_URL常量，均为https://）。
• 扩展前置条件：若要扩展为全自动查询，需先重新验证 CAPTCHA、会话（session）与动态请求的稳定性。
• 运行时集成：通过 k-skill CLI（@nomadamas/k-skill@0）分发与执行。exec子命令从打包的技能目录解析脚本、依据 shebang 自动选择 Python/Node/Bash 运行器（见 execute.js），支持用KSKILL_PYTHON环境变量覆盖 Python 解释器；--之后的所有参数原样透传给脚本。仓库根目录的 scripts/subway_lost_property.py 则是指向技能内同名脚本的薄封装入口，便于直接在仓库内调试与运行 test_subway_lost_property.py。

综上，subway-lost-property是一个克制而完整的“官方路径组织器”：它不越界承诺自动采集，而是把 LOST112 表单字段、referer 请求、降级关键词与可达性探测全部固化为可复现的代码与 JSON 输出，让 Agent 在真实网络环境下也能以保守、合规的方式引导用户找回失物。

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