# pi-kiwoom-cli

설치된 `kiwoomcli`를 Pi 에이전트가 안전하고 예측 가능하게 사용할 수 있도록 안내하는 스킬 패키지입니다.

> [!WARNING]
> 이 스킬은 실계좌 주문을 전송할 수 있습니다. 처음에는 실계좌와 모의계좌 주문 정책을 모두 기본값인 `deny`로 유지하고, 모의계좌에서 충분히 검증하세요.

## 패키지와 CLI의 관계

- `kiwoomcli`: 키움 REST API를 실제로 호출하는 CLI
- `pi-kiwoom-cli`: Pi 에이전트가 `kiwoomcli`를 사용하는 절차와 안전 정책을 제공하는 스킬

이 패키지는 CLI 실행 파일, App Key/Secret 또는 계좌 정보를 포함하지 않습니다. 키움증권 공식 제품이 아니며, Kiwoom 및 키움증권 관련 명칭은 각 권리자에게 귀속됩니다.

## 사전 요구사항

먼저 키움증권의 [Kiwoom REST API 사용자 가이드](https://github.com/Kiwoom-Securities/Kiwoom-REST-API)를 따라 다음 준비를 완료하세요.

1. Python과 `uv` 설치
2. `uv tool install kwcli`로 CLI 설치
3. App Key/Secret 발급
4. 터미널에서 `kiwoomcli setup`을 직접 실행해 인증 설정
5. `kiwoomcli auth status`로 인증 상태 확인

다음 명령이 정상적으로 동작해야 합니다.

```bash
kiwoomcli --help
kiwoomcli auth status
```

대화형 초기 설정은 이 스킬의 지원 범위 밖입니다. App Key/Secret을 Pi 대화에 입력하지 마세요.

## 설치

npm에서 전역 Pi 패키지로 설치합니다.

```bash
pi install npm:pi-kiwoom-cli
```

특정 프로젝트에만 설치하려면 `-l`을 사용합니다.

```bash
pi install -l npm:pi-kiwoom-cli
```

영구 설치 없이 시험할 수도 있습니다.

```bash
pi -e npm:pi-kiwoom-cli
```

Git 저장소에서 설치하려면 다음과 같이 실행합니다.

```bash
pi install git:github.com/wjdhan/pi-kiwoom-cli
```

## 사용 예시

Pi에 자연어로 요청하면 스킬이 적절한 `kiwoomcli` 명령을 선택하고 현재 `--help`를 확인한 후 실행합니다.

```text
삼성전자 현재가를 조회해줘.
내 모의계좌의 보유 종목을 보여줘.
저장된 조건검색식 목록을 조회해줘.
삼성전자 10주 지정가 매수 주문을 미리보기 해줘.
```

설치 또는 인증 문제를 확인하려면 다음과 같이 요청할 수 있습니다.

```text
kiwoomcli 상태를 진단해줘.
```

## 지원 기능

- 인증 수명주기 관리 및 상태 진단
- OpenAPI 스펙 탐색
- 국내 주식, 시세, 호가, 캔들, ETF, ELW, 투자자, 순위, 업종, 공매도, 대차거래 및 테마 조회
- 계좌, 잔고, 손익 및 거래 내역 조회
- 종료 조건이 있는 WebSocket 및 조건검색 스트림
- 국내 주식, 신용 및 금 현물 주문 조회·미리보기·실행

다음 기능은 의도적으로 지원 범위에서 제외합니다.

- 대화형 초기 설정(`kiwoomcli setup`)
- `--watch`를 사용하는 무제한 스트림 수집
- 조건검색식 생성 및 수정(영웅문 HTS에서 수행)

## 실제 주문 정책

실계좌와 모의계좌에 서로 다른 주문 정책을 설정할 수 있습니다.

```text
KIWOOMCLI_SKILL_REAL_ORDER_POLICY=deny|ask|allow
KIWOOMCLI_SKILL_DEMO_ORDER_POLICY=deny|ask|allow
```

환경변수가 없거나 값이 유효하지 않으면 두 정책 모두 `deny`로 처리합니다.

- `deny`: 실제 주문을 차단하며 `--confirm` 없는 주문 미리보기는 허용합니다.
- `ask`: 전체 주문표를 표시하고 해당 주문에 대한 새로운 승인을 요구합니다.
- `allow`: 추가 승인 없이 실제 주문을 전송할 수 있습니다.

에이전트는 이 환경변수를 읽기만 하며 직접 설정하거나 변경하지 않습니다. 정책은 일반 주식, 신용 및 금 현물의 매수·매도·정정·취소 주문에 모두 적용됩니다.

예를 들어 모의계좌 주문은 매번 확인하고 실계좌 주문은 차단하려면 Pi를 시작하기 전에 다음과 같이 설정합니다.

```bash
export KIWOOMCLI_SKILL_REAL_ORDER_POLICY=deny
export KIWOOMCLI_SKILL_DEMO_ORDER_POLICY=ask
pi
```

`allow`는 추가 승인을 생략하므로 자동 실행의 영향을 이해한 경우에만 사용하세요. 자연어 요청으로 `deny` 정책을 우회할 수 없습니다.

## 보안 주의사항

- App Key/Secret을 대화, 로그 또는 저장소에 노출하지 마세요.
- `kiwoomcli auth export`는 자격 증명이 포함된 파일을 만들 수 있습니다.
- 계좌 및 실시간 계좌 이벤트에는 보유자산, 주문번호와 같은 민감한 금융정보가 포함될 수 있습니다.
- 실제 주문 전에는 대상 프로필이 `real`인지 `demo`인지 확인하세요.
- Pi 패키지의 스킬은 에이전트에게 시스템 명령 실행을 지시할 수 있으므로 설치 전에 내용을 검토하세요.

## 점진적 공개

메인 스킬에는 명령 라우팅, 실행 절차, 개인정보 보호, 스트림 및 주문 안전 규칙을 둡니다. 각 CLI 명령의 상세 도움말은 별도의 참조 파일에 두고 필요할 때만 불러옵니다.

```text
pi-kiwoom-cli/
├── package.json
└── skills/
    └── kiwoom-cli/
        ├── SKILL.md
        └── references/
            ├── auth/
            ├── spec/
            ├── streams/
            ├── accounts/
            ├── orders/
            └── ...
```

참조 문서는 `kiwoomcli --help`를 바탕으로 작성했습니다. 스킬은 명령 실행 전에 `kiwoomcli <command> --help`로 설치된 CLI의 현재 문법을 다시 확인합니다.

## 로컬 개발

체크아웃을 영구 설치 없이 불러옵니다.

```bash
pi -e .
```

로컬 패키지로 설치합니다.

```bash
pi install .
```

npm에 포함될 파일을 확인합니다.

```bash
npm run pack:dry-run
```

## 라이선스

[MIT](LICENSE)