# TOOLS.md - Local Notes

환경 세팅 메모. 관리자님 자산 관련 파일과 명령어 위치.

## Stock Data

모든 경로는 `agents/stock/workspace/` 기준.

- `memory/portfolio.json` — 보유 종목 **v2 스키마 스냅샷** (`accounts.{일반,ISA,가희_일반,가희_ISA}.positions`). 참고용. 실제 리포트 숫자는 항상 키움 REST 실시간 조회.
- `state/portfolio_daily_snapshot.json` — 일별 owner-그룹 스냅샷. v4 스키마: `{date: {owner: {holdings: {stock:{...}}, deposit: int, trade_journal: [...], realized_pl_total: int, realized_fees_total: int}}}`. 전날대비 순자산(평가+예수금) + 월별 실현손익/회전율/수수료 통계용. `stock_portfolio_report.py`가 작성. legacy v1/v2/v3 호환.
- `state/kiwoom_tokens/{일반,ISA,가희_일반,가희_ISA}.json` — 키움 REST OAuth 토큰 캐시 (계좌별 분리). `expires_dt` 기준 자동 갱신.
- `state/ipo_calendar_sync.json` — 공모주 캘린더 동기화 상태.
- `state/behive_watchlist.json` — **비하이브 종목분석 워치리스트**. 관리자님이 "OO 목표가 얼마야?" 같은 비하이브 분석 관련 질문하면 `skills/behive-watchlist` 사용. 종목별 목표/매입/손절/요약/출처영상 포함.
- `state/behive_youtube_seen.json` / `state/behive_last_fetch.json` — 비하이브 스크립트 내부 상태.
- `/Users/snowoyh/.openclaw/credentials/kiwoom.json` — 키움 자격증명 (계좌별 AppKey/SecretKey 분리 v2 스키마). 예제: `kiwoom.json.example`.

## Scripts (python3)

- `scripts/kiwoom_client.py {token|accounts|summary|balance|positions}` — 키움 REST 조회 전용 클라이언트. 잔고/보유/계좌평가. **주문 함수 절대 부재**(매매 절대 원칙, SOUL.md 참조). 자세한 사용법은 `skills/kiwoom-rest`.
- `scripts/stock_portfolio_report.py {run|send} [--by-account]` — 리포트 생성/이메일. 평일 20:10 launchd로 `send`. owner 그룹(본인 / 가희)별 블록 표시가 기본 (그룹 내 종목 합산), `--by-account`는 owner 블록 안에서 4계좌별 분리 뷰까지.
- `scripts/ipo_calendar_sync.py` — 공모주 일정 구글 캘린더 등록. 매월 1일 cron.
- `scripts/behive_youtube_digest.py {fetch|save|email|notify|list|show|remove}` — 비하이브투자자문 '종목분석' 영상 감지·요약·워치리스트 저장·이메일/텔레그램 발송. 평일 07/12/18시 cron.

## 관리자님 관련

- 잔고·보유·수익률 질문이 들어오면 **키움 REST로 실시간 조회**. `memory/portfolio.json`은 스냅샷이라 stale 할 수 있음.
- 이메일 수신자: `mini.snowoyh@gmail.com` (리포트 발송 대상)

## 증권사

- 키움증권. iMessage 체결통보 파싱은 2026-04-24 REST API 연동으로 폐기됨 — 모든 체결·잔고 정보는 `kiwoom_client.py`로 조회.

## Playwright MCP (브라우저 자동화)

OpenClaw가 `openclaw.json` 의 MCP 서버 `playwright`로 노출. 도구는 `playwright__browser_*` prefix로 약 23개.

- **탐색:** `navigate / navigate_back / tabs / wait_for`
- **관찰:** `snapshot` (접근성 트리 — 클릭 대상 ref 식별에 **우선 사용**) / `take_screenshot` / `console_messages` / `network_requests` / `network_request`
- **조작:** `click / type / fill_form / press_key / hover / select_option / drag / drop / file_upload / handle_dialog / resize / close`
- **평가:** `evaluate` (페이지 JS 컨텍스트) / `run_code_unsafe` (Playwright 코드 직접 — **RCE 등급, 마지막 수단**)

**표준 흐름:** `navigate` → `snapshot`으로 ref 확보 → `click`/`type`/`fill_form` → `wait_for`로 결과 대기 → `snapshot` 또는 `network_requests`로 검증. 스크린샷은 사람 보고용이지 다음 동작 분기 근거로 쓰지 말 것.

**운영 특성:**
- 기본값 `--headless --isolated`. 매 세션 쿠키·로그인 폐기.
- 영속 로그인 필요한 사이트는 시도 전 **코디에게 `user-data-dir` 분리·등록 요청**.
- 첫 호출 시 npx spawn 1~2초 지연.
- **키움 영웅문·HTS는 보안프로그램이 Playwright 탐지·차단할 가능성 큼 → 시도 자제**. 잔고·시세는 항상 `kiwoom_client.py` REST 우선.
- 공동인증서·OTP·CAPTCHA 화면이 나오면 **즉시 중단하고 관리자님께 보고**, 우회 시도 X.

**활용 시나리오 (레이 맥락):**
- DART 공시 검색·본문 추출·PDF 다운로드 (정정·합병·유상증자 키워드 모니터링)
- 네이버 증권 외국인·기관 매매동향 등 키움 REST에 없는 보조 지표 스크래핑
- 비하이브 페이지 보조(댓글·공지 등 유튜브 자막 외 정보) — 기존 `behive_youtube_digest`와 상호 보완
- 종목별 공시·뉴스 변화 감지 → 워치리스트 알림 보강 (LLM 미경유 모니터에 결과만 넘김)
- 매매(주문) 흐름에는 **절대 사용 금지** — 주문은 `orders/kiwoom_order.py` REST 한 경로만 (SOUL.md 매매 원칙 참조)
