/api/meta/capabilities — LLM 친화적 디스커버리 엔드포인트 #62

New issue

Closed

opened 2026-04-26 04:35:29 +09:00 by xhh · 0 comments

xhh commented

2026-04-26 04:35:29 +09:00

Owner

Claude 스킬(매크로 리포트, 종목 분석 등) 이 시작 시점에 "이 플랫폼에서 어떤 데이터를 받을 수 있는지" 한 번에 파악하기 위한 마크다운 응답 엔드포인트.

동기

매 스킬 실행마다 같은 웹서치를 반복하는 비용을 줄이는 것이 본 플랫폼의 핵심 목표(통합 로드맵). 그러려면 스킬이 '먼저 우리 API 부터 본다' 는 흐름이 강제되어야 하는데, 그 첫 신호가 capabilities 디스커버리.

스킬 프롬프트에 한 줄 추가: "시작 시 GET /api/meta/capabilities 를 fetch 해 가능한 데이터 파악"
응답이 마크다운이라 LLM 이 그대로 컨텍스트에 흡수, JSON 파싱 단계 불필요
새 엔드포인트/데이터 소스가 추가되면 자동으로 capabilities 에 반영 → 스킬 프롬프트는 안 건드려도 최신 능력 인지

응답 설계 (목표 < 800 토큰)

사용 가능한 엔드포인트 1줄 요약 (path + 한 줄 설명)
데이터 소스 표 (카테고리 / 심볼 수 / 시작일)
최근 추가 (직전 N개 릴리스의 신규 데이터)
데이터 없으면 안내 (web search → POST /api/meta/data-gaps 으로 기록 — #15 연동)

동적 생성 권장: meta_symbols + meta_coverage + 라우터 OpenAPI 메타데이터 + 정적 템플릿 조합. 매 호출 새로 생성해도 비용 적음 (DB 쿼리 한두 개).

구현 스코프

api/routers/system.py::meta_capabilities 신규 (또는 별도 meta.py)
응답: Response(media_type="text/markdown") 로 직접 마크다운
OpenAPI 에서는 responses={200: {"content": {"text/markdown": {}}}} 명시
회귀 테스트: 응답에 핵심 키워드("엔드포인트", "데이터 소스", 주요 path 들) 포함 검증
README 에 "스킬 통합 가이드" 짧은 섹션 추가 (capabilities 부터 시작하라)

선행 / 관련

후속: #6 (스킬 시범 전환) — 이 엔드포인트가 있어야 스킬에서 호출
짝꿍: #15 (data_gaps 피드백 루프) — capabilities 가 read, data_gaps 가 write. 둘이 합쳐 "능력 광고 + 빈틈 수집" 의 양면

완료 기준

GET /api/meta/capabilities 가 마크다운 반환
새 엔드포인트/모델 추가 시 capabilities 응답이 자동 반영 (정적 템플릿이 아닌 동적 생성)
회귀 테스트 통과
토큰 길이 < 800 (응답 라인수 적정선 확인)
README 에 스킬 통합 진입 가이드 1단락

Claude 스킬(매크로 리포트, 종목 분석 등) 이 시작 시점에 "이 플랫폼에서 어떤 데이터를 받을 수 있는지" 한 번에 파악하기 위한 마크다운 응답 엔드포인트. ## 동기 매 스킬 실행마다 같은 웹서치를 반복하는 비용을 줄이는 것이 본 플랫폼의 핵심 목표(통합 로드맵). 그러려면 스킬이 **'먼저 우리 API 부터 본다'** 는 흐름이 강제되어야 하는데, 그 첫 신호가 capabilities 디스커버리. - 스킬 프롬프트에 한 줄 추가: "시작 시 GET /api/meta/capabilities 를 fetch 해 가능한 데이터 파악" - 응답이 마크다운이라 LLM 이 그대로 컨텍스트에 흡수, JSON 파싱 단계 불필요 - 새 엔드포인트/데이터 소스가 추가되면 자동으로 capabilities 에 반영 → 스킬 프롬프트는 안 건드려도 최신 능력 인지 ## 응답 설계 (목표 < 800 토큰) - **사용 가능한 엔드포인트 1줄 요약** (path + 한 줄 설명) - **데이터 소스 표** (카테고리 / 심볼 수 / 시작일) - **최근 추가** (직전 N개 릴리스의 신규 데이터) - **데이터 없으면** 안내 (web search → POST /api/meta/data-gaps 으로 기록 — #15 연동) 동적 생성 권장: `meta_symbols` + `meta_coverage` + 라우터 OpenAPI 메타데이터 + 정적 템플릿 조합. 매 호출 새로 생성해도 비용 적음 (DB 쿼리 한두 개). ## 구현 스코프 - `api/routers/system.py::meta_capabilities` 신규 (또는 별도 `meta.py`) - 응답: `Response(media_type="text/markdown")` 로 직접 마크다운 - OpenAPI 에서는 `responses={200: {"content": {"text/markdown": {}}}}` 명시 - 회귀 테스트: 응답에 핵심 키워드("엔드포인트", "데이터 소스", 주요 path 들) 포함 검증 - README 에 "스킬 통합 가이드" 짧은 섹션 추가 (capabilities 부터 시작하라) ## 선행 / 관련 - 후속: #6 (스킬 시범 전환) — 이 엔드포인트가 있어야 스킬에서 호출 - 짝꿍: #15 (data_gaps 피드백 루프) — capabilities 가 read, data_gaps 가 write. 둘이 합쳐 "능력 광고 + 빈틈 수집" 의 양면 ## 완료 기준 - [ ] `GET /api/meta/capabilities` 가 마크다운 반환 - [ ] 새 엔드포인트/모델 추가 시 capabilities 응답이 자동 반영 (정적 템플릿이 아닌 동적 생성) - [ ] 회귀 테스트 통과 - [ ] 토큰 길이 < 800 (응답 라인수 적정선 확인) - [ ] README 에 스킬 통합 진입 가이드 1단락