kis_trader/.agents/AGENTS.md

kis_bot 프로젝트 에이전트 규칙 (필수 준수 사항)

📖 필수 참조 폴더 (docs/like_mcp.md/) 및 문서

이 프로젝트에서 작업할 때는 docs/like_mcp.md/ 디렉토리 내의 핵심 문서들을 항상 인지하고 참조해야 합니다.

필수 문서 목록 (경로: docs/like_mcp.md/)

문서	정확한 파일 경로	용도 및 시점
코드 수정 가이드	docs/like_mcp.md/MODIFICATION_GUIDE.md	[수정 전 필수] 수정 유형별 필수 grep 체크리스트 및 사이드 이펙트 검증 절차
코드 아키텍처 & 의존성 맵	docs/like_mcp.md/code_architecture.md	[구조 파악] 파일 간 import 의존성, 핵심 허브 파일 Top 20, 전략별 모듈 분류
DB ERD & DDL	docs/like_mcp.md/db_erd.md	[DB 참고] MariaDB 테이블 스키마, 컬럼 정의, PK/인덱스 및 관계

---

⚖️ MCP 도구 vs MD 문서 활용 원칙 (토큰 최적화 & 정확도)

프로젝트 분석 및 코드 작성 시, **MCP 도구(kis-code-assistant 등)**와 MD 참조 문서를 아래 역할 분담에 맞춰 사용합니다:

1. 거시적 구조 & 영향 범위 파악 → MD 문서 (docs/like_mcp.md/)
   • 새 대화 시 또는 작업 전 전체적인 지도(Layer, Hub 파일)가 필요할 때 목차 및 관련 섹션을 빠르게 참고합니다.
2. 미시적 코드 & API 조회 → MCP 도구 우선 사용
   • 특정 파일의 소스코드를 보거나 API 스펙을 탐색할 때는 파일 전체를 읽어 토큰을 낭비하지 말고, MCP 도구(read_source_code, search_*_api 등)나 grep_search를 우선 사용하여 실시간 최신 상태를 조회합니다.
3. 수정 전 grep 필수 실행
   • MD 문서는 "어디를 검색할지" 알려주는 지도입니다. 실제 수정을 단행하기 전에는 반드시 MODIFICATION_GUIDE.md에 명시된 필수 grep 명령을 실행하여 관련 파일 목록을 정확히 확정하세요.

---

🔄 코드 변경 시 MD 문서 필수 업데이트 룰 (Stale 방지)

코드를 수정하거나 새로운 기능을 추가한 후(특히 커밋 전/후)에는 반드시 MD 문서와의 완결성을 유지해야 합니다. 아래 상황 발생 시 문서를 무조건 업데이트하세요:

1. 파일 추가/삭제/이동 또는 import 변경 시
   • code_architecture.md 갱신 (스크립트 활용 또는 내용 반영)
2. DB 테이블/컬럼 또는 환경변수(ENV) 추가/변경 시
   • db_erd.md 및 MODIFICATION_GUIDE.md 체크리스트 반영
3. 검증 의무 (실매매 엔진 사전 100% 무결성 검열 필수에 관한 절대 규칙)
   • 코드를 수정하면 실매매/백테스트/웹/파라미터서치 정합성 및 영향도를 100% 검증하고 완료 알림에 변경 내용을 명시합니다.
   • 핵심 실매매 코드 수정 또는 DB 파라미터/환경변수(ENV)/스키마 변경 시에는 반드시 최종 완료 전 python3 -u scripts/test_live_execution_validation.py를 가동하여 전 단계 100% 통과(최종: 통과 / 👑 [최종 판정] 완결!)를 확정 지어야 합니다. 로그: logs/test_live_execution_validation_*.log.

---

🚨 하드코딩 절대 금지 (NO HARDCODING)

• 어떠한 경우에도 코드 내부에 임계값, 비율, 점수, 시간 등의 수치를 직접 하드코딩하지 마세요.
• 숫자값을 추가하거나 수정할 때는 반드시 get_env_float(), get_env_int(), get_env_bool()을 사용하여 DB/Env에서 불러오도록 작성하세요.
  • ❌ if rsi > 78: (절대 금지)
  • ✅ rsi_limit = get_env_float("RSI_LIMIT", 78.0); if rsi > rsi_limit: (필수 적용)
• 변수명은 직관적인 대문자 스네이크 케이스(예: MAX_DROP_RATE)로 작성하고 기본값을 설정하세요.
• 신규 env 키 추가 시 4개 세트 등록 의무: 아래 4곳을 한 세트로 반드시 등록하세요.
  1. 코드 내 get_env_* 기본값 지정
  2. database.py ENV 키 목록에 추가
  3. 필요 시 *_env_keys.py 키 목록에 추가
  4. apply 패치 맵에 추가
  • 저장 후 get_env_from_db로 재조회 검증 필수

---

🏗️ 시스템 아키텍처 원칙

SCAN vs TRIGGER 분리

• SCAN 단계: 조건 필터링을 최소화하여 후보를 DB에 최대한 많이 올립니다.
• TRIGGER 단계: 실제 매수 직전 모든 엄격한 필터(보조지표, 호가, 수급 등)를 한 번에 검사합니다.
• 무거운 연산(API 추가 호출, 분봉 분석 등)은 절대 5분 주기 스캔 함수에 넣지 말고, 매수 타점 체크 함수에 넣으세요.

WebSocket 우선, REST 최소화

• REST는 가능하면 WebSocket/캐시/DB 재사용으로 대체하세요.
• REST를 대체할 수 있는 경우에는 최대한 WebSocket을 사용합니다.
• 루프·재큐·벌크 등에서 REST 연타 금지. SafeRequest·기존 세마포어·sleep·쿨다운을 우회하는 새 경로를 만들지 마세요.

공통 코드 함수화

• 여러 전략에서 공통으로 사용할 수 있는 코드는 반드시 공통 함수로 분리하여 재사용하세요.
• 전략별로 동일한 로직을 중복 작성하지 마세요.

손절 및 안전 장치 필수

• 모든 매매 로직에는 손절(Stop-loss) 및 예외 처리 로직이 포함되어야 합니다.
• 코드 작성 후 스스로 아래 항목을 검토하세요:
  1. 손절(Stop-loss) 및 예외 처리 로직이 포함되었는가?
  2. API 호출 제한(429 Error) 및 슬리피지 고려가 되었는가?
  3. None/null로 인한 런타임 오류가 발생하지 않는가?
  4. 기존 로직과 100% 동일한 기능을 수행하는가?

---

🔄 실매↔백테↔파람 정합 규칙 (필수)

• 실매매 기준으로 백테스트, 파라미터서치 코드를 맞춥니다. 백테/파람서치 코드는 실매매 코드와 100% 동일해야 합니다.
• 새로 추가한 코드의 기본값은 항상 DB에 추가해야 하며, 웹 페이지 입력값과 일치해야 합니다.
• 코드 수정 시 실매매·웹 백테스트·파라미터서치의 결과값이 동일해야 하며, 검증을 반드시 거쳐야 합니다.
• 수정 사항이 실매에 영향이 가는지 vs 백테/파라미터에만 영향이 가는지 명확히 분류한 후 보고하고 수정합니다.
• Optuna 파라미터서치 실행 시:
  • 주말/공휴일이면 최근 거래일로만 실행
  • 그리드 변경 후 반드시 새 --study-name 사용 (동일 study 재사용 금지)
  • *_SKIP_HTS_SCAN_DUPES 는 false 유지, 임의로 true로 바꾸지 말 것
  • 호가 후처리 격자(OPTUNA_OB_ENTRY_*)와 캔들 TPE 축을 섞지 말 것. 후처리 재실행 ≠ DB 적용 (docs/옵투나.md)

---

🚫 절대 금지 사항 (위반 시 작업 중지)

봉 정합·진입 정렬

• 신호 = T−1 확정봉, 진입 = T(시가/첫 틱). live_backtest_align=True 잠금.
• 유니버스·신호·진입을 ±1분(또는 ±1봉) 보정·오프셋·슬롯 해킹으로 맞추는 코드 절대 금지.
• WS_CANDLE_FREEZE_ON_CONFIRM 끄기(false) 절대 금지. 사용자 명시 승인 없이 변경 금지.

OHLC 폴백 금지

• 틱 청산/진입 ON이면 봉 OHLC(high/low)로 체결·max_price·PnL을 채우지 마세요.
• OHLC 폴백으로 숫자를 변조하는 것은 실매와 다른 엔진을 만드는 행위입니다.

HTS 조건식과 코드 분리

• HTS는 후보 유니버스 참고용입니다. 그리드를 HTS 밴드에 맞추라고 강제하지 말 것.
• *_SKIP_HTS_SCAN_DUPES 는 사용자가 언급하기 전까지 false 유지. 임의로 true로 바꾸지 말 것.

DB 쿼리 안전 규칙

• SQL 전 반드시 SHOW COLUMNS FROM <table>로 실제 컬럼 확인. 추측 SELECT 금지.
• PyMySQL: SQL 문자열의 %는 포맷으로 해석됨. LIKE '20260712%' 금지 → LIKE %s + ('20260712%',) 또는 %%.
• 실패 시 원인 고친 뒤 1회만 재실행. 같은 가정으로 날짜/strategy만 바꿔 반복 금지.

---

🔍 근본원인 먼저, 땜빵 금지

• 증상을 가리는 땜빵용 코딩은 지양합니다. 항상 근본원인을 먼저 찾고 초등학생도 이해하기 쉽게 설명 후 설계하고 보고합니다.
• 버그 발견 시 해당 함수를 따라가 면밀히 분석 후 세 가지 근본적인 대안을 제시하도록 합니다.
• 추측성 대안을 제시하지 말고, 코드를 구석구석 면밀히 분석한 후에 진행하세요.
• "일단 재시도·재발급·봉수 늘리기·±1 보정"으로 증상만 가리기 금지.
• API 관련 코드를 작성/수정할 때는 본인의 지식에 의존하지 말고 반드시 연동된 MCP 도구를 우선 호출하여 스펙을 확인하세요.
• 시간이 오래 걸려도 좋으니 불필요하게 토큰을 낭비하지 말고, 끝까지 딥다이브하여 근본적인 원인을 찾아내어 해결하세요.

---

🤖 AI 에이전트 행동 및 도구 사용 원칙 (Behavior & Tool Execution Rules)

에이전트는 사용자(USER)와의 페어 프로그래밍 및 코드 관리에서 최고의 품질과 토큰 효율을 발휘하기 위해 아래 지침을 100% 준수합니다.

1. 🛠️ 도구 사용 기본 규칙 (Tool Calling)

• 파이썬 임시 구동 시 python -c 인라인 실행 절대 금지 (No Inline Python in Shell): 복잡한 다중 줄이나 따옴표/퍼센트(%) 기호가 포함된 파이썬 구문을 터미널에서 python -c "..."로 구동하면 셸 인식 및 줄바꿈 오류로 인해 명령이 멈추거나 터미널이 꼬이므로 절대 금지합니다. 반드시 scratch/ 폴더나 임시 스크립트(.py) 파일로 작성(PYTHONPATH=. 또는 sys.path 설정 필수 포함)한 뒤 단건 파일 실행(python script.py)으로 구동하세요.
• 내부 도구명 언급 금지: 사용자에게 설명할 때 replace_file_content 도구를 사용하여... 또는 grep_search를 호출하여...와 같이 내부 도구 이름을 직접 텍스트로 언급하지 마세요. 대신 "파일을 수정하겠습니다", "코드를 검색하여 파악하겠습니다" 처럼 자연스럽고 친절한 언어로 소통하세요.
• 불필요한 도구 호출 자제: 일반적인 질의응답이나 이미 대화 및 문서로 알고 있는 내용, 단순 설명은 불필요하게 도구를 낭비하지 말고 즉시 답변하세요.
• 작업 목적 사전 설명: 도구(검색, 읽기, 수정, 실행 등)를 사용하기 전에 왜 그 작업이 필요하며 목표 달성에 어떻게 기여하는지 한 문장으로 명쾌하게 먼저 설명하세요.

2. ✏️ 코드 수정 및 오류 해결 규칙 (Making Code Changes)

• 채팅창 코드 전문 출력 금지: 사용자가 "채팅창에 출력해줘"라고 명시하지 않는 한, 긴 코드를 대화창에 텍스트로 장황하게 늘어놓지 마세요. 반드시 편집 도구(Edit Tools)를 사용하여 실제 파일에 직접 안전하게 반영하세요.
• 동일 파일 수정의 묶음(Batch) 처리: 같은 파일 내에서 여러 군데를 뜯어고쳐야 할 때, 수정을 여러 턴에 걸쳐 잘게 쪼개어 부르지 말고 단일 도구 호출(한 번의 패치)에 묶어서 통합 적용하세요.
• 수정 전 조회(Read-before-Edit) 의무화: 신규 파일을 만들거나 파일 맨 끝에 간단한 줄을 추가하는 경우를 제외하고는, 코드를 수정하기 전에 반드시 해당 파일 또는 대상 섹션의 원본 소스를 먼저 읽고 문맥을 완전히 파악한 뒤 수정하세요. (근거 없는 눈대중 수정 절대 금지)
• 오류 수정 3회 루프 제한 (Anti-Loop): 코드 변경 후 린트(Lint)나 문법/런타임 에러가 터졌을 때 확실한 해결 방안이 섰을 때만 수정하세요. 근거 없이 '이렇게 해볼까' 식으로 무리한 시도를 되풀이하지 말 것. 특히 동일한 파일에서 오류 고치기를 3회 이상 반복(Loop)하지 마세요. 3번째 패치 후에도 실패하면 즉시 중단하고 사용자에게 상황을 명명백백히 설명한 뒤 다음 행동 지시를 받으세요.
• 즉시 구동 보장 (Executable Quality): 생성하거나 수정한 코드는 사용자가 언제든 터미널을 열어 실행하거나 실매매/백테스트 엔진에 올려도 오류가 없도록 온전하고 실행 가능한 상태로 완성되어야 합니다.
• 기존 코드 구조 존중 (No Over-engineering): 잘 작동하는 코드를 '더 나은 구조'를 명목으로 임의로 클래스화하거나 불필요하게 복잡하게 바꾸지 마세요. 기존의 함수형·절차적 구조를 최대한 유지하는 것이 기본 원칙입니다.
• 핵심 로직 변경 시 선보고·승인 대기: 매매 로직, 청산 우선순위, 공통 인프라 등 핵심 로직을 변경해야 할 때는 코드를 바로 수정하지 말고, 먼저 왜 변경이 필요한지 이유를 설명하고 사용자의 승인을 받은 뒤 수정하세요. (단순 버그 수정이나 오타 교정은 즉시 수정 가능)
• 주석 및 로거 절대 유지: 기존에 작성된 주석(Comments)과 로거(Logger) 코드는 수정과 무관하게 절대 삭제하지 마세요. 새 코드를 추가하거나 수정하더라도 기존 주석과 로그는 그대로 보존합니다.
• 테스트 실행 시 백그라운드 + 로그 경로 안내: 테스트 코드를 돌릴 때는 백그라운드로 실행하고, tail -f로 볼 수 있는 로그 파일 경로를 반드시 함께 안내하세요.
• 🚨 [절대 규칙] 작업 흐름 단절 금지 & 끝까지 자동 보정 완수 (Never Break Flow & Autonomous Retry):
  • 스크립트 구동, 테스트 검증, DB 반영 등의 작업을 수행할 때 실행 중 오류가 터지거나 탈락하더라도 사용자에게 로그만 넘기며 대화 턴을 멈추고 흐름을 끊지 마세요.
  • 에이전트는 단일 대화 턴 내부에서 스스로 실패 로그와 원인 규명 ➔ 코드 보정 ➔ 즉각 재시도의 루프를 주도적으로 돌려 100% 정상 완수될 때까지 끝까지 책임을 관철한 뒤, 최종 통과된 완공 상태만 보고해야 합니다.
  • 단기 파괴검사나 수 초 내로 끝나는 검증·진단 모듈 구동 시에는 동기식 실행 대기 시간을 충분히 부여하여 에이전트가 실행 결과를 즉각 회수하고, 스스로 100% 정합성 통과를 확정한 후 대화 턴을 마무리하세요.
• 🚨 [절대 규칙] 핵심 코드·DB 변경 시 실매매 엔진 최종 검증 의무화 (Mandatory Live Execution Validation):
  • 전략, 주문, 호가 필터, WS 구독/해제, 공통 인프라 등 핵심 실매매 코드를 수정하거나, 데이터베이스(ENV 파라미터, 스키마, 테이블 등)에 변화가 생겼을 때는 반드시 최종 완료 직전에 아래 검증 스크립트를 최소 1회 실행하여 100% 무결성을 증명해야 합니다.
  • 실행 커맨드: python3 -u scripts/test_live_execution_validation.py
  • 로그: logs/test_live_execution_validation_YYYYMMDD_HHMMSS.log
  • 한 단계라도 탈락이나 에러가 발생할 경우 작업을 마쳐서는 안 되며, 끝까지 자동 보정 완수 규칙에 따라 원인 수정 후 1회만 재검증을 돌려 100% 최종 완공 판정(최종: 통과 / 👑 [최종 판정] 완결!)을 확인한 뒤 보고하세요.

3. 🔎 검색 및 코드 탐색 규칙 (Searching & Reading)

• 효율적인 타겟팅 최우선: 무작정 루트 디렉토리를 통으로 긁는 것보다, code_architecture.md나 MCP 도구, 정밀 정규식 검색 등을 우선 활용하여 목표 범위를 날카롭게 압축하세요.
• 문맥 확보를 위한 충분한 범위 일괄 읽기: 파일을 조사할 때는 15~20줄씩 쪼개어 여러 턴을 낭비하지 말고, 문맥과 의존성을 안심하고 파악할 수 있도록 처음부터 필요한 충분한 크기(섹션/블록)를 큼직하게 잡고 한 번에 조회하세요.
• 목적 달성 시 즉시 탐색 종료: 수정이나 답변을 하기에 합리적이고 충분한 위치와 정보를 찾았다면, 불필요한 추가 조회 도구 호출을 중단하고 즉시 코드 수정이나 답변 작성 단계로 진입하세요.

---

🌐 백테스트 웹페이지 운영 및 UI 동기화 규칙 (Web UI & Service Rules)

1. 🖥️ 백테스트 웹 서비스 재시작 및 브라우저 검증

• 웹 UI/API 수정 후 필수 재시작: 웹 서버 코드나 UI 스크립트(backtest_web.py, 템플릿 등)를 수정한 뒤에는 반드시 아래 명령어를 가동하여 서비스를 새로고침하고 active 상태를 확인하세요.
  • 명령어: sudo systemctl restart kis_backtest_web.service
  • 주의: 웹과 무관한 실매매 봇 전용 로직만 고쳤다면 불필요하게 실매매 서비스를 재시작하지 마세요.
• 전용 URL 브라우저 확인: 브라우저나 HTTP 검증 시 반드시 http://192.168.0.149:5050/ 주소만 사용하세요. (127.0.0.1이나 localhost는 브라우저 연결 에러 유발로 금지)
• 진정한 검증 완결: 단순 curl 200 OK 응답만으로 완료라 단정하지 말고, 실제 브라우저/화면상에서 버튼·탭 전환 시 콘솔 Uncaught/ReferenceError 오류가 없는지 100% 확인한 뒤 보고하세요.

2. 🔄 탭 UI 통합 변경 및 국장/해외 동기화

• 전 전략 탭 UI 일치 원칙: 백테스트 웹페이지 내 한 전략의 UI(인풋 폼, 가상거래내역, 실거래내역 테이블 등)를 수정했다면, 모멘텀·돌파·스캘핑·꼬리잡기 등 다른 전략 탭도 100% 동일한 구조와 스펙으로 함께 변경해야 합니다.
• 해외 전략 탭(US_*) UX 동기화: 해외 전략 웹 탭, Optuna, Top5 보기, 수익률 카드 등은 국장 탭과 동일한 UX로 맞추는 것이 기본 원칙입니다. 임의로 생략하거나 단축해서는 안 되며, 통화(USD) 표기나 시간 분리 등 필연적 차이가 있을 때만 선보고 및 문구 기재 후 반영합니다.
• UI 덮어쓰기 금지: Optuna 파라미터 폼 채우기나 종목 적용 후 페이지 리로드로 폼 수치가 기존 DB 핀셋 설정에 도로 덮어씌워져 유실되지 않도록 검증(하드새로고침 ➔ 종목선택 ➔ Optuna 수치 유지)을 의무화하세요.

---

🚨 증권사 API 인프라 보호 및 DB 안전 조회 규칙 (Infrastructure & DB Safety)

1. 🛡️ 키움/KIS API 유량 및 approval 키 보호 (폭주 절대 금지)

• API 에러 ≠ 데이터 없음: 키움 return_code=5(유량 한도 초과)나 429 Error를 '빈 봉/데이터 없음'으로 착각하여 루프·재큐·벌크 요청으로 API를 무한히 연타하지 마세요. 유량 초과 시 백오프(Backoff), 세마포어, 실패 상한선 도달 시 재큐 정지가 필수입니다.
• WS approval_key 단일 공유 캐시 준수: KIS WebSocket 실시간 접속키(approval_key)는 공용 KISApprovalManager(공유 캐시)를 사용하여 전 연결이 1개의 키를 나누어 씁니다. 모듈이 돌아갈 때마다 매번 새 키를 REST로 발급받아 타 소켓을 끊기거나 무효화하는 행위를 절대 금지합니다. (응급 재발급은 기본 6시간 1회 하드캡 지킬 것)
• 백테스트 REST 웜업 최소화: 전일 장 시작 시가 보강 REST는 짧은 1차(기본 700봉)만 기본 적용하고, 실패할 때만 해당 종목에 한해 1회만 증량(1,500봉) 재시도하세요.

2. 🗄️ DB 임시 조회(Ad-hoc) 및 SQL 쿼리 안전 수칙

• 추측 SELECT 금지 (SHOW COLUMNS 필수): TradeDB로 SQL을 날리기 전에는 반드시 SHOW COLUMNS FROM <table>로 실제 컬럼 스키마를 확인하세요.
  • 대표적 오류 사례: target_candidates 테이블에는 strategy_id 컬럼이 없음 (code/name/score/price/scan_time/updated_at 등만 존재).
  • 🚨 [필수 준수 템플릿]: 아래와 같이 반드시 SHOW COLUMNS로 정확한 테이블명과 컬럼명을 딕셔너리로 받아 확인한 후(문법 고정)에만 본 쿼리를 실행하여 에러를 원천 차단하세요. 따옴표 사용에도 유의하세요.

    # 임시 조회 스크립트 작성 시 고정 문법 (python -c 대신 반드시 파일로 작성)
    from database import TradeDB
    db = TradeDB()
    try:
        cols1 = [dict(r)["Field"] for r in db.conn.execute("SHOW COLUMNS FROM ws_price_validation").fetchall()]
        print(f"ws_price_validation cols: {cols1}")
    
        cols2 = [dict(r)["Field"] for r in db.conn.execute("SHOW COLUMNS FROM ls_ws_ticks").fetchall()]
        print(f"ls_ws_ticks cols: {cols2}")
    
        # 확인된 컬럼명(cols1, cols2)을 기반으로 이후 SELECT/조회 실행
    finally:
        db.close()
    

• PyMySQL % 포맷 충돌 회피: PyMySQL 실행 시 SQL 문자열 안의 % 기호는 문자열 포맷팅으로 해석됩니다. LIKE '20260712%' 식의 쿼리를 금지하고 반드시 파라미터 바인딩(LIKE %s, ('20260712%',)) 또는 %%를 사용하세요.
• 에러 반복 금지: Unknown column이나 not enough arguments for format string 에러가 났을 때 똑같은 가정을 두고 날짜나 전략명만 바꿔가며 실패 쿼리를 수차례 연타하지 마세요. 원인을 규명한 뒤 1회만 고쳐서 재실행하세요.

3. ⏳ 파라미터 서치(Optuna) 및 백테스트 토큰·시간 절약

• 휴장일 보정 실행: 주말이나 공휴일에는 end=오늘로 돌려 빈 봉 에러나 0건으로 통째 재실행하는 낭비를 저지르지 마세요. 반드시 최근 거래일을 기준으로 종료 시점(end)을 보정하여 1회에 완공하세요.
• 그리드 변경 시 새 study-name 사용: Optuna 탐색 범위(categorical, TPE 등)나 그리드가 바뀌면 동일한 --study-name 재사용 시 dynamic value space error가 나므로, 반드시 새로운 스터디명을 부여하여 돌려야 합니다.
• 긴 잡은 백그라운드 구동: 오래 걸리는 Optuna 나 백테스트는 nohup으로 돌리고 로그 파일 경로를 안내하세요. for+sleep 식의 무의미한 루프 대기를 걸지 마세요.

---

🚨 [절대규칙] Optuna 백테스트 웹 UI 잡 트래킹 실행 방법

문제: nohup bash 직접 실행 시 웹 UI에 잡이 보이지 않음

nohup bash scripts/run_optuna_*.sh 또는 python3 kis_trader/backtest/param_search_optuna.py를 쉘에서 직접 실행하면 웹 UI의 프로그레스바 및 최근 잡 목록에 절대 표시되지 않습니다.

웹 UI 잡 시스템은 optuna_web_jobs.py의 파일 기반 잡 트래킹(logs/optuna_web_jobs/*.json)을 통해서만 작동합니다.

✅ 올바른 실행 방법: 웹 API(curl)로 실행

쉘에서 실행하면서 웹 UI에도 표시하려면 반드시 웹 서버의 /api/optuna/start 엔드포인트를 통해 실행해야 합니다.

# 단일 전략 실행 (웹 UI에 표시됨)
curl -s -X POST http://192.168.0.149:5050/api/optuna/start \
  -H "Content-Type: application/json" \
  -d '{"strategy":"momentum","start":"2026-08-07","end":"2026-08-07","trials":200,"mode":"fast"}' | python3 -m json.tool

# 4전략 순차 실행 (strategies 배열로 전달)
curl -s -X POST http://192.168.0.149:5050/api/optuna/start \
  -H "Content-Type: application/json" \
  -d '{"strategies":["momentum","breakout","scalp","tail"],"start":"2026-08-07","end":"2026-08-07","trials":200,"mode":"fast"}' | python3 -m json.tool

# 진행 상황 확인 (job_id는 응답에서 확인)
curl -s http://192.168.0.149:5050/api/optuna/status/<job_id> | python3 -m json.tool

# 잡 목록 확인
curl -s http://192.168.0.149:5050/api/optuna/jobs | python3 -m json.tool

후처리(호가/휩쏘) 단독 실행은 직접 실행 허용

메인 TPE와 달리 후처리 모듈(apply_optuna_ob_consensus.py, apply_optuna_whipsaw_consensus.py)은 수 초~수 분 내에 끝나므로 직접 실행 허용합니다. 단, 결과 JSON은 별도로 웹 UI 결과 탭에 표시됩니다.

# 후처리는 직접 실행 허용
python3 scripts/apply_optuna_ob_consensus.py --strategy MOMENTUM --n-trials 1000
python3 scripts/apply_optuna_whipsaw_consensus.py --strategy MOMENTUM --n-trials 500

스크립트 작성 시 curl API 사용 원칙

에이전트가 Optuna 메인 TPE 실행 스크립트(.sh)를 작성할 때는 반드시:

• ❌ nohup python3 kis_trader/backtest/param_search_optuna.py ... (직접 실행 금지)
• ✅ curl -X POST http://192.168.0.149:5050/api/optuna/start -d '...' (API 통해 실행)

단, 메인 TPE가 이미 실행 중일 때 curl API는 "이미 실행 중" 에러를 반환하므로, 순차 실행 스크립트에서는 완료 폴링(/api/optuna/status/<job_id>) 후 다음 전략 시작 로직이 필요합니다.