Back to Details

k-schoollunch-menu

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Korean School Lunch Menu (NEIS)

韩国学校午餐菜单（NEIS）

What this skill does

本Skill的功能

나이스(NEIS) 교육정보 개방 포털의 학교기본정보·급식식단정보를 
k-skill-proxy
가 중계하는 HTTP API로 조회한다.
  • 사용자는 시도교육청 이름(자연어)과 학교 이름, 날짜만 말하면 된다.
  • 에이전트는 먼저 
    /v1/neis/school-search
    로 학교를 찾고, 응답의 
    SD_SCHUL_CODE
    ·
    ATPT_OFCDC_SC_CODE
    로 
    /v1/neis/school-meal
    을 호출한다.
  • 인증키(
    KEDU_INFO_KEY
    )는 프록시 서버에만 두고, 클라이언트는 키 없이 프록시 URL만 호출한다.
通过
k-skill-proxy
中转的HTTP API，查询韩国教育信息开放平台（나이스，NEIS）的学校基本信息和餐食菜单信息。
  • 用户只需说出市道教育厅名称（自然语言）、学校名称和日期即可。
  • Agent首先调用
    /v1/neis/school-search
    接口查找学校，然后使用响应中的
    SD_SCHUL_CODE
    和
    ATPT_OFCDC_SC_CODE
    调用
    /v1/neis/school-meal
    接口。
  • 认证密钥(
    KEDU_INFO_KEY
    )仅存放在代理服务器中，客户端无需密钥，只需调用代理URL即可。

When to use

使用场景

  • "서울특별시교육청 미래초등학교 오늘 급식 뭐야?"
  • "○○초 급식 식단 알려줘"
  • "이번 주 화요일 중학교 급식 메뉴"
  • "급식 메뉴 조회해줘" (교육청·학교·날짜 확인 후 진행)
  • "首尔特别市教育厅未来小学今天的餐食是什么？"
  • "○○小学餐食菜单告诉我"
  • "这周二中学的餐食菜单"
  • "帮我查询餐食菜单"（确认教育厅、学校、日期后进行）

Prerequisites

前置条件

  • 인터넷 연결
  • curl
    사용 가능 환경
  • k-skill-proxy
    에 
    KEDU_INFO_KEY
    가 설정된 배포(기본 hosted 또는 self-host)에 접근 가능할 것
  • 网络连接
  • 可使用
    curl
    的环境
  • 能够访问已配置
    KEDU_INFO_KEY
    的
    k-skill-proxy
    部署（默认托管版或自托管版）

Credential requirements

凭证要求

  • 사용자 측 필수 시크릿 없음.
  • KSKILL_PROXY_BASE_URL
    — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted 
    https://k-skill-proxy.nomadamas.org
    를 사용한다.
  • KEDU_INFO_KEY
    는 프록시 운영 서버 환경에만 둔다.
  • 用户端无需任何必要密钥。
  • KSKILL_PROXY_BASE_URL
    — 仅在使用自托管或独立代理时设置。留空则使用默认托管地址
    https://k-skill-proxy.nomadamas.org
    。
  • KEDU_INFO_KEY
    仅存放在代理运营服务器的环境中。

Proxy base URL

代理基础URL

에이전트는 아래처럼 base 를 정한다.
bash
BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
BASE="${BASE%/}"
Agent按以下方式确定基础URL：
bash
BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
BASE="${BASE%/}"

Workflow

工作流程

1) Collect inputs (do not guess)

1) 收集输入（请勿猜测）

다음이 없으면 사용자에게 짧게 묻는다.
  1. 교육청 — 자연어 허용 (예: 
    서울특별시교육청
    , 
    서울
    , 
    경기도교육청
    ).
  2. 학교명 — 자연어 (예: 
    미래초등학교
    , 
    ○○중학교
    ).
  3. 급식일 — 
    YYYYMMDD
    또는 사용자가 말한 날짜를 한국 시간 기준으로 
    YYYYMMDD
    로 정한다. 생략 시 오늘(한국 시간).
교육청 표현이 애매해 
ambiguous_education_office
가 나오면, 응답의 
candidate_codes
를 보여 주고 더 구체적인 이름(예: 
경상북도교육청
vs 
경상남도교육청
)을 받는다.
若缺少以下信息，需简短询问用户：
  1. 教育厅 — 支持自然语言（例如：
    首尔特别市教育厅
    、
    首尔
    、
    京畿道教育厅
    ）。
  2. 学校名称 — 支持自然语言（例如：
    未来小学
    、
    ○○中学
    ）。
  3. 餐食日期 — 格式为
    YYYYMMDD
    ，或根据用户所说日期转换为韩国时间的
    YYYYMMDD
    格式。省略时默认当天（韩国时间）。
若教育厅表述模糊导致返回
ambiguous_education_office
，需展示响应中的
candidate_codes
，并请用户提供更具体的名称（例如：
庆尚北道教育厅
vs 
庆尚南道教育厅
）。

2) Search school (
/v1/neis/school-search
)

2) 搜索学校（
/v1/neis/school-search
）

bash
curl -fsS --get "${BASE}/v1/neis/school-search" \
  --data-urlencode "educationOffice=${EDU_OFFICE}" \
  --data-urlencode "schoolName=${SCHOOL_NAME}"
  • EDU_OFFICE
    , 
    SCHOOL_NAME
    은 사용자 입력을 그대로 넣어도 된다. 프록시가 교육청명을 코드로 해석한다.
  • 응답의 
    resolved_education_office.atpt_ofcdc_sc_code
    로 실제 매칭된 시도교육청 코드를 확인할 수 있다.
bash
curl -fsS --get "${BASE}/v1/neis/school-search" \
  --data-urlencode "educationOffice=${EDU_OFFICE}" \
  --data-urlencode "schoolName=${SCHOOL_NAME}"
  • EDU_OFFICE
    和
    SCHOOL_NAME
    可直接使用用户输入内容，代理会将教育厅名称解析为对应代码。
  • 通过响应中的
    resolved_education_office.atpt_ofcdc_sc_code
    可确认实际匹配的市道教育厅代码。

3) Disambiguate when multiple schools match

3) 多学校匹配时进行歧义消除

schoolInfo
본문에서 
row
가 여러 개면 사용자에게 **학교명·주소(
ORG_RDNMA
등)**를 보여 주고 하나를 고르게 한다.
한 건뿐이면 그 row의 
ATPT_OFCDC_SC_CODE
, 
SD_SCHUL_CODE
를 다음 단계에 쓴다.
若
schoolInfo
正文的
row
包含多条记录，需向用户展示**学校名称、地址（
ORG_RDNMA
等）**并请用户选择其中一个。
若仅一条记录，则使用该row中的
ATPT_OFCDC_SC_CODE
和
SD_SCHUL_CODE
进入下一步。

4) Fetch meal (
/v1/neis/school-meal
)

4) 获取餐食信息（
/v1/neis/school-meal
）

bash
curl -fsS --get "${BASE}/v1/neis/school-meal" \
  --data-urlencode "educationOfficeCode=${ATPT}" \
  --data-urlencode "schoolCode=${SD}" \
  --data-urlencode "mealDate=${YYYYMMDD}"
  • ATPT
    / 
    SD
    는 3단계에서 확정한 코드.
  • 조식·중식·석식만 보고 싶으면 
    mealKindCode=1|2|3
    (선택).
bash
curl -fsS --get "${BASE}/v1/neis/school-meal" \
  --data-urlencode "educationOfficeCode=${ATPT}" \
  --data-urlencode "schoolCode=${SD}" \
  --data-urlencode "mealDate=${YYYYMMDD}"
  • ATPT
    / 
    SD
    为步骤3中确定的代码。
  • 若仅需查看早餐、午餐、晚餐，可添加
    mealKindCode=1|2|3
    （可选）。

5) Summarize for the user

5) 为用户总结信息

  • mealServiceDietInfo
    안의 
    row
    를 기준으로 요약한다.
  • 메뉴 문자열(
    DDISH_NM
    등)의 
    <br/>
    는 줄바꿈으로 바꿔 읽기 쉽게 한다.
  • 칼로리·영양 정보 필드가 있으면 한두 줄로 덧붙인다.
  • NEIS가 빈 결과를 주면 "해당 일자 급식 데이터 없음" 가능성을 안내한다.
  • 以
    mealServiceDietInfo
    中的
    row
    为基础进行总结。
  • 将菜单字符串（如
    DDISH_NM
    ）中的
    <br/>
    替换为换行符，提升可读性。
  • 若存在卡路里、营养信息字段，可添加1-2行补充说明。
  • 若NEIS返回空结果，需告知用户“该日期无餐食数据”的可能性。

Upstream reference

上游参考

Done when

完成标准

  • 교육청·학교·날짜를 확인했다.
  • 학교 검색으로 단일 학교를 확정했다(또는 사용자가 선택했다).
  • 급식 API 호출에 성공했고, 메뉴를 사용자 친화적으로 정리했다.
  • 已确认教育厅、学校、日期信息。
  • 通过学校搜索确定了单一学校（或由用户选择）。
  • 成功调用餐食API，并将菜单整理为用户友好的形式。

Failure modes

失败场景

  • 프록시에 
    KEDU_INFO_KEY
    미설정 → 
    503
    / 
    upstream_not_configured
  • 교육청 이름이 여러 시도에 걸침 → 
    400
    / 
    ambiguous_education_office
  • 학교명이 여러 건 — 사용자 선택 없이 임의로 고르지 말 것
  • 공휴일·방학·미제공 일자로 빈 급식
  • NEIS API 일시 장애·호출 제한
  • 代理未配置
    KEDU_INFO_KEY
    → 返回
    503
    / 
    upstream_not_configured
  • 教育厅名称对应多个市道 → 返回
    400
    / 
    ambiguous_education_office
  • 学校名称匹配多条记录 — 请勿在未获得用户选择的情况下随意指定
  • 节假日、假期、未提供餐食的日期返回空结果
  • NEIS API临时故障、调用受限

Notes

注意事项

  • 학교 코드를 사용자에게 외우게 하지 않는다. 항상 
    school-search
    → 
    school-meal
    순서를 따른다.
  • Raw JSON을 그대로 붙여 넣지 말고 요약 위주로 답한다.
  • 자세한 엔드포인트·필드는 
    docs/features/k-schoollunch-menu.md
    와 
    docs/features/k-skill-proxy.md
    를 참고한다.
  • 不要让用户记忆学校代码，务必遵循
    school-search
    → 
    school-meal
    的调用顺序。
  • 请勿直接粘贴原始JSON，应以总结内容为主进行回复。
  • 详细的端点、字段信息请参考
    docs/features/k-schoollunch-menu.md
    和
    docs/features/k-skill-proxy.md
    。