k-skill korean-stock-search 实战指南无需 KRX_API_KEY 的 KRX 韩国股票查询与代理实现剖析【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本文以 k-skill 仓库中的korean-stock-search技能说明文档为核心完整讲解如何通过 k-skill-proxy 的三个 HTTP 端点完成 KRX 上市股票搜索、个股基本资讯与每日行情查询并结合代理服务器源码剖析参数校验、结果打分、缓存策略与上游故障处理机制。读完后你可以直接用 curl 调通全部端点并掌握在 Agent 场景下如何正确解释结果与处理degraded、not_found等失败状态。技能定位与应用边界korean-stock-search是 k-skill한국인을 위한 스킬 모음집中面向金融数据查询的技能。它的默认行为是向https://k-skill-proxy.nomadamas.org/v1/korean-stock/...发起请求完成三类只读查询KRX 上市股票搜索search、个股基本资讯base-info、个股每日行情trade-info。技能说明书korean-stock-search/instruction.md明确了适用与不适用场景适合使用的典型请求삼성전자 종목코드랑 시장구분 찾아줘找一下三星电子的证券代码和市场区分005930 기본정보 보여줘查看 005930 的基本资讯SK하이닉스 20260408 종가/거래량 알려줘查询 SK 海力士 20260408 的收盘价与成交量KOSDAQ 에서 알테오젠 시세 확인해줘在 KOSDAQ 市场确认 Alteogen 的行情明确不属于本技能范围的场景美国/日本/虚拟资产等非韩国股票查询实时成交체결、买卖盘口호가、分钟 K 线查询财务报表与公告原文分析投资建议或买入推荐skill.json中的元数据也印证了这一定位profiles 为proxy与lookup分类finance地区ko-KR见 korean-stock-search/skill.json。核心设计密钥集中在代理层用户零凭证该技能最关键的设计是用户不需要申请KRX_API_KEY也不需要本地安装 MCP 服务器。upstream 方案设计参考了开源项目jjlabsio/korea-stock-mcp但用户侧被完全屏蔽了密钥管理KRX_API_KEY只在 k-skill-proxy 服务器上配置与注入。从代理源码看这一点在三个层面得到确认代理从进程环境变量读取密钥config.krxApiKey trimOrNull(env.KRX_API_KEY)packages/k-skill-proxy/src/server.js#L264每个端点在命中缓存后都会检查config.krxApiKey若缺失直接返回 503upstream_not_configuredpackages/k-skill-proxy/src/server.js#L5337-L5350底层 KRX 请求函数在发请求前再次兜底校验密钥同样抛出 503packages/k-skill-proxy/src/krx-stock.js#L126-L132。代理基地址的选取规则如果设置了KSKILL_PROXY_BASE_URL环境变量则使用其值否则回退到默认地址https://k-skill-proxy.nomadamas.org。此外不需要任何客户端 API 层——直接向代理发 HTTP GET 请求即可。输入参数详解技能定义的全部输入如下参数校验逻辑与默认值均可在代理源码中逐一对应参数说明校验规则与默认值源自源码q股票名或证券代码搜索词仅search端点使用必填缺失时抛错返回 400market市场区分KOSPI|KOSDAQ|KONEXbase-info/trade-info必填search可选缺省时并行查询全部三个市场code证券代码通常为 6 位短代码如005930base-info/trade-info必填支持逗号分隔的多代码入参取第一个bas_dd基准日格式YYYYMMDD可选缺省时取 KSTAsia/Seoul当天日期若传入值不是 8 位数字则 400limit搜索结果条数默认 10范围 120越界返回 400参数归一化函数位于 packages/k-skill-proxy/src/server.js#L1447-L1498normalizeKoreanStockDatebas_dd为空时用getCurrentKstDate()基于Intl.DateTimeFormatAsia/Seoul时区见 packages/k-skill-proxy/src/krx-stock.js#L50-L59计算 KST 当天然后强制匹配^\d{8}$normalizeKoreanStockSearchQuery接受q或query别名bas_dd/basDd/date均可limit默认 10 且上限 20normalizeKoreanStockLookupQuerycode支持codes/codeList/stockCode/stock_code别名逗号分隔并去重后取第一项用于base-info与trade-info。前置条件Prerequisites无。使用者无需准备KRX_API_KEYupstream 密钥仅在代理服务器侧注入。三个受支持的端点与 curl 示例1. 股票搜索GET /v1/korean-stock/search?q{검색어}bas_dd{YYYYMMDD}curl -fsS --get https://k-skill-proxy.nomadamas.org/v1/korean-stock/search \ --data-urlencode q삼성전자 \ --data-urlencode bas_dd202604082. 个股基本资讯GET /v1/korean-stock/base-info?market{KOSPI|KOSDAQ|KONEX}code{종목코드}bas_dd{YYYYMMDD}curl -fsS --get https://k-skill-proxy.nomadamas.org/v1/korean-stock/base-info \ --data-urlencode marketKOSPI \ --data-urlencode code005930 \ --data-urlencode bas_dd202604083. 个股每日行情GET /v1/korean-stock/trade-info?market{KOSPI|KOSDAQ|KONEX}code{종목코드}bas_dd{YYYYMMDD}curl -fsS --get https://k-skill-proxy.nomadamas.org/v1/korean-stock/trade-info \ --data-urlencode marketKOSPI \ --data-urlencode code005930 \ --data-urlencode bas_dd20260408注意中文/韩文等非 ASCII 搜索词务必使用--data-urlencode做 URL 编码这在代理测试中也有覆盖——测试用例会用%EC%82%BC%EC%84%B1%EC%A0%84%EC%9E%90삼성전자 的编码形式注入请求packages/k-skill-proxy/test/server.test.js#L2332-L2341。响应结构逐字段解读三个端点共享统一响应骨架业务数据items/item 回显的query 代理元信息proxy。proxy.cache.hit标识本次是缓存命中还是实时查询ttl_ms为缓存 TTL默认 300000 毫秒。搜索响应{ items: [ { market: KOSPI, code: 005930, standard_code: KR7005930003, name: 삼성전자, short_name: 삼성전자, english_name: Samsung Electronics, listed_at: 1975-06-11 } ], query: { q: 삼성전자, bas_dd: 20260408, limit: 10 }, proxy: { name: k-skill-proxy, cache: { hit: false, ttl_ms: 300000 } } }基本资讯响应{ item: { market: KOSPI, code: 005930, standard_code: KR7005930003, name: 삼성전자, short_name: 삼성전자, english_name: Samsung Electronics, security_group: 주권, section_type: 대형주, stock_certificate_type: 보통주, par_value: 100, listed_shares: 5969782550 }, query: { market: KOSPI, code: 005930, bas_dd: 20260408 }, proxy: { name: k-skill-proxy, cache: { hit: false, ttl_ms: 300000 } } }每日行情响应{ item: { market: KOSPI, code: 005930, standard_code: KR7005930003, base_date: 20260408, name: 삼성전자, close_price: 84000, change_price: 1000, fluctuation_rate: 1.2, open_price: 83000, high_price: 84500, low_price: 82800, trading_volume: 12345678, trading_value: 1030000000000, market_cap: 500000000000000 }, query: { market: KOSPI, code: 005930, bas_dd: 20260408 }, proxy: { name: k-skill-proxy, cache: { hit: false, ttl_ms: 300000 } } }行情字段由normalizeTradeItem从 KRX 原始字段映射而来TDD_CLSPRC→close_price、CMPPREVDD_PRC→change_price、FLUC_RT→fluctuation_rate、TDD_OPNPRC/TDD_HGPRC/TDD_LWPRC→开高低、ACC_TRDVOL/ACC_TRDVAL→量额、MKTCAP→market_cappackages/k-skill-proxy/src/krx-stock.js#L87-L116。映射时对数字做了去千分位逗号的解析parseNumber保证返回的是纯数字而非字符串。Upstream 实现KRX API 如何被真正调用代理到 KRX 的完整数据流在 packages/k-skill-proxy/src/krx-stock.js 中要点如下按市场分表的上游 URL。KRX 的 dbg 数据接口为三个市场提供了不同路径源码中维护了静态映射packages/k-skill-proxy/src/krx-stock.js#L5-L15市场基本资讯 upstream每日行情 upstreamKOSPIstk_isu_base_infostk_bydd_trdKOSDAQksq_isu_base_infoksq_bydd_trdKONEXknx_isu_base_infoknx_bydd_trd三者均挂在data-dbg.krx.co.kr/svc/apis/sto/下请求仅带basDd查询参数并在请求头中以AUTH_KEY携带 API 密钥。搜索是全市场快照 本地打分而非服务端模糊查询。searchStocks对选定市场未指定market时为 KOSPI/KOSDAQ/KONEX 全部三个用Promise.allSettled并发拉取该市场当日的基本资讯快照然后在本地执行匹配打分packages/k-skill-proxy/src/krx-stock.js#L264-L325搜索词与code/standard_code/name/short_name/english_name任一字段完全相等忽略大小写得 100 分按空白切分后每个 token 都出现在某个字段中得 50 分未命中得 -1 分并过滤最后按分数降序、同分按韩文localeCompare排序后截取前limit条。这种设计解释了为什么搜索是确定性的、可缓存的也解释了文档中종목명이 모호하면 먼저search로 시장/종목코드를 좁힌 뒤股票名模糊时先收窄这一响应策略的必要性。degraded 的部分故障语义。只要有一个市场拉取成功search就返回 200并附带upstream: { degraded: true, requested_markets, successful_markets, failed_markets }只有全部市场都失败时才向上抛错、由路由层转成 502。failed_markets中每一项包含code/status_code/message序列化信息serializeKrxError。代理测试对这一行为有专门断言当另一个市场失败时search 响应会带出 degraded 元数据packages/k-skill-proxy/test/server.test.js#L2477。trade-info 的短代码回退匹配。fetchTradeInfo先用 6 位短代码ISU_SRT_CD直接匹配当日行情快照若无直接命中会再拉一次基本资讯快照用 12 位标准代码ISU_CD如KR7005930003做二次匹配并把基本资讯中的名称、上市股数等补进行情结果packages/k-skill-proxy/src/krx-stock.js#L168-L191。这层回退让只有短代码的用户也能查到行情。网络层细节。krxRequest通过fetchWithRetry发起请求超时设为 20 秒AbortSignal.timeout(20000)上游返回非 2xx 时抛upstream_error502响应体缺少OutBlock_1数组时抛krx_api_error502——KRX 的数据就装在OutBlock_1里。缓存策略与失败模式缓存键与命中回显。每个路由用makeCacheKey({ route, ...参数 })生成缓存键search 会把q转小写后再拼入键保证大小写不敏感的命中。命中缓存的响应会带proxy.cache.hittrue。测试中验证了带空格/别名的两种请求qvsquerydate会归一化为同一查询packages/k-skill-proxy/test/server.test.js#L2332-L2341。degraded 响应不进缓存。缓存层显式拒绝写入error或upstream.degradedtrue的载荷cache.set返回 false见 packages/k-skill-proxy/test/server.test.js#L247-L251search 路由也只有在!result.upstream?.degraded时才写缓存packages/k-skill-proxy/src/server.js#L5389-L5395。此外测试还覆盖了按客户端 IP解析cf-connecting-ip与x-forwarded-for链的限流行为超限返回rate_limited。完整失败模式对照表与文档 Failure modes 一节一致且全部可在路由源码中对应到具体分支条件HTTP 状态error 标识源码位置q/market/code/bas_dd格式错误或limit越界400bad_requestserver.js#L5306-L5314代理未配置KRX_API_KEY503upstream_not_configuredserver.js#L5337-L5350部分市场 upstream 失败200upstream.degradedtruefailed_marketskrx-stock.js#L315-L322全部市场 upstream 失败 / KRX 返回错误502upstream_error/krx_api_errorkrx-stock.js#L143-L156该基准日/市场下找不到该股票404not_foundserver.js#L6324-L6330特别注意 404 分支的两个细节base-info的提示语是기준일 X 에 Y 시장 종목 Z 을(를) 찾지 못했습니다而trade-info的提示语额外说明了휴장일이거나 데이터가 아직 없을 수 있습니다可能是休市日或数据尚未生成server.js#L6417-L6423。响应策略与输出规范Agent 必读技能文档对拿到数据之后怎么讲给出了明确的行为规范这部分是技能质量的核心查询顺序股票名模糊时先走search收窄市场/证券代码再进入base-info或trade-info部分故障要如实说明看到upstream.degradedtrue与failed_markets时要在答案中一并说明哪些市场查询失败不要过度承诺时效trade-info是日别 snapshot不能表述为实时盘口/成交休市日处理bas_dd为休市日或盘前时该日期可能无数据应回退到最近营业日重试此时trade-info可能以 404not_found而非 502 结束数字呈现用 원/주/억/조 等易读单位简短解读同时保留原始数字免责声明答案末尾简短附上KRX 공식 데이터 기준 / 투자 조언 아님以 KRX 官方数据为准 / 非投资建议。紧凑答案要求Keep the answer compact答案只保留股票名/市场/证券代码、基准日、收盘价/涨跌幅/成交量/市值仅在需要时补充上市日/上市股数/面值出现多个候选时只展示前 35 个交由用户选择。完成判据Done when模糊搜索词已先经search收窄已按需用base-info与trade-info整理核心数值全程保持了用户无需KRX_API_KEY也能查询的体验已简短标注数据出处。合规与法律边界SKILL.md 声明本技能只读查询专用read-only 조회 전용且与 KRX、交易所、上市公司或任何数据提供方无官方关系。korean-stock-search/references/DISCLAIMER.md 进一步约束了使用边界公开市场信息的自动收集仅限个人、非组织性的信息查询用途禁止组织性/大规模爬取禁止构建或再分发行情数据库不得绕过访问控制、封锁或 quota查询结果仅为投资参考信息不构成投资劝诱、咨询或收益保证该免责声明引用了韩国大法院判例2005도1637、2021도1533与商标法、信息通信网法、著作权法相关条款作为背景但明确声明其本身不是法律保证。小结korean-stock-search展示了 k-skill 代理型技能的典型形态把有密钥门槛的上游 APIKRX Open API参考设计来自jjlabsio/korea-stock-mcp收敛到一个统一代理后面用户侧只剩三个 GET 请求和一组被严格归一化、有默认值、有明确失败码的查询参数。源码层面值得复用的点在于全市场快照加本地确定性打分的搜索实现、短代码到标准代码的两级回退匹配、degraded 不缓存的缓存策略以及对 400/404/502/503 各失败分支的清晰划分——这些设计让该技能既能在 Agent 对话中给出紧凑可靠的答复又能把上游的部分故障透明地暴露给调用方。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考