WorkBuddy-QMT Bridge

WorkBuddy/MCP와 대 QMT 내장 Python 간의 네이티브, 실패 시 차단형(fail-closed) 트레이딩 브리지.

중요 위험 고지

이 프로젝트는 모의 또는 실거래 자금 계좌의 주문을 트리거할 수 있으며, 투자 조언을 구성하지 않으며 수익을 보장하지 않습니다. 기본 모드는 OBSERVE_ONLY입니다. 모든 실거래 자금 배포는 먼저 대상 QMT 버전, 증권사 카운터, 계좌 필드, 주문 리턴, 주문 취소 및 복구 절차에 대한 현장 검증을 완료해야 합니다. 저장소의 예제 매핑은 실거래에 직접 사용할 수 없습니다.

현재 버전

• 버전: 0.3.0

• 단계: P1 LIMITED_AUTO 소프트웨어 제어면 완료

• MCP 도구: 29개

• Python: Worker는 3.10 이상 필요

• QMT Adapter: QMT 내장 Python 3.6 환경 호환

• 실행 경계: 127.0.0.1에만 바인딩, xtquant에 의존하지 않음

프로젝트 홈페이지: https://github.com/peppaboar95/workbuddy-qmt-bridge

"P1 완료"는 소프트웨어 측의 구조화된 권한 부여, 한도 예약, 상태 머신, 서킷 브레이커 및 Adapter 재검증이 구현되고 로컬 테스트를 통과했음을 의미할 뿐, 임의의 실거래 자금 카운터가 검증되었음을 의미하지 않습니다.

Related MCP server: IBKR MCP Server

네 가지 모드

SIM_SIGNAL은 "신호만 생성하고 주문하지 않음"이 아닙니다. 실거래 자금 카운터에 잘못 연결된 경우에도 passorder를 호출할 수 있으므로 계좌와 카운터를 반드시 수동으로 확인해야 합니다.

안전 설계

• preview_trade와 submit_trade_intent 2단계 커밋;

• 제출 시 전체 하드 리스크 재실행 및 리스크 결정 지문 비교;

• Worker와 QMT Adapter 양쪽에서 계좌, 모드, 서명, TTL 및 권한 세대 검사;

• LIMITED_AUTO 허가는 계좌, 증권, 액션, 전략/규칙 버전, 거래 창, 주문 유형 및 다층 한도에 바인딩;

• 한도 원자적 예약, 단일 건, 누적 금액, 주문 수, 빈도, 동시성, 포지션 노출, 드로다운 및 연속 실패 제한;

• PRE_SUBMIT 또는 SUBMIT_CALLED 상태는 자동 재전송하지 않으며, 알 수 없는 결과는 SUBMIT_UNKNOWN 유지;

• 서킷 브레이커 발동 후에는 로컬에서만 복구 가능하며 안전하게 OBSERVE_ONLY로 복귀;

• 신용 자동 거래는 기본적으로 꺼져 있으며, 새로운 신용 부채는 추가 명시적 허가와 현장 검증 필요.

설치

일반 사용자는 GitHub Releases에서 설치 ZIP, ZIP 단독 해시 및 전체 해시 목록을 우선 다운로드합니다:

• workbuddy-qmt-bridge-0.3.0.zip

• workbuddy-qmt-bridge-0.3.0.zip.sha256

• SHA256SUMS.txt

해시를 확인한 후 ZIP을 압축 해제하고 "최초 설치 및 구성.cmd"를 더블 클릭합니다. wheel을 수동으로 설치해야 하는 경우 다음을 다운로드합니다:

• workbuddy_qmt_bridge-0.3.0-py3-none-any.whl

Windows PowerShell:

python -m pip install .\workbuddy_qmt_bridge-0.3.0-py3-none-any.whl
workbuddy-qmt setup

소스에서 개발 설치:

git clone https://github.com/peppaboar95/workbuddy-qmt-bridge.git
cd workbuddy-qmt-bridge
python -m pip install -e .

읽기 전용에서 트레이딩까지

1. setup을 실행하여 로컬 구성, 키, Worker 토큰 및 계좌 격리 디렉터리를 생성합니다;

2. 생성된 qmt_adapter.py와 qmt_adapter.json을 해당 QMT 전략 인스턴스에 배포합니다;

3. OBSERVE_ONLY를 유지하면서 하트비트, 계좌, 포지션, 주문, 체결 및 시세 필드 수집을 완료합니다;

4. 대상 모의 카운터에서 P0 매핑 검증을 완료하고 Profile에 서명합니다;

5. SIM_SIGNAL에서 최소 수량, 주문, 체결, 주문 취소, 재시작 및 알 수 없는 결과 복구 대조를 완료합니다;

6. 실거래 자금 시나리오는 먼저 MANUAL_LIVE 소액 검증을 사용합니다;

7. readiness에 차단 항목이 없고 전략 경계가 명확할 때만 LIMITED_AUTO P1 허가를 생성합니다.

MANUAL_LIVE의 1–60분 시간 권한은 건별 수동 승인만 면제합니다. 각 건은 여전히 재동기화, 미리보기 및 하드 리스크 통과가 필요합니다. LIMITED_AUTO의 허가는 최대 720분이지만 거래일을 넘을 수 없으며, 전체 전략 경계와 누적 예산의 제약을 받습니다.

LIMITED_AUTO P1 절차

1. 로컬에서 Worker와 해당 Adapter를 LIMITED_AUTO로 전환합니다;

2. check_limited_auto_readiness를 호출하여 큐, 스냅샷, 하트비트, 데드 레터 및 SUBMIT_UNKNOWN에 차단이 없음을 확인합니다;

3. 운영자에게 전체 허가 전략을 제시하고 명시적 확인 후 authorize_limited_auto를 호출합니다;

4. 자동 작업은 각 거래에 대해 계속 동기화, 미리보기, 제출을 수행합니다;

5. get_limited_auto_status로 남은 시간, 주문 수, 금액 예산 및 일시 중지 사유를 관찰합니다;

6. 건강, 드로다운 또는 연속 실패 가드가 트리거되면 자동 일시 중지; 조건이 복구된 후에만 명시적으로 resume_limited_auto;

7. 종료 시 revoke_limited_auto를 호출합니다. 허가 철회는 증권사 측의 기존 주문을 자동으로 취소하지 않습니다.

검증 완료 및 미검증

이 버전의 로컬 증분 테스트 범위:

• schema v1에서 v2 마이그레이션;

• 구조화 P1 허가;

• 미리보기, 제출 및 한도 원자적 점유;

• 전략 버전 바인딩;

• 일시 중지, 복구 및 권한 세대 순환;

• Adapter 변조 방지 재검증.

대상 환경에서 여전히 완료해야 할 사항:

• 실제 QMT 및 증권사 구축 능력 매트릭스;

• 실거래 자금 카운터의 주문, 체결, 비고 및 주문 취소 리턴;

• Windows ACL, 백업, 복구 및 SUBMIT_UNKNOWN 훈련;

• 신용 계좌 6가지 액션, 필드 차원, 자격, 한도 및 부채 규칙;

• 소액 수동 실거래 검증.

데이터 및 개인정보

runtime, 데이터베이스, WAL/SHM, 로그, 큐, 실행 로그, 서명 Profile, 키, Worker 토큰, 계좌 번호 및 로컬 MCP 구성은 저장소에 커밋하거나 Issue에 첨부해서는 안 됩니다. 진단 자료는 먼저 비식별화해야 합니다.

문서

• 릴리스 및 설치: docs/README-RELEASE.zh-CN.md

• P1 검증 설명: docs/P1-VALIDATION.zh-CN.md

• 구성 예제: examples/README.md

• 보안 정책: SECURITY.md

License

이 프로젝트는 MIT License를 채택합니다. 자세한 내용은 LICENSE를 참조하십시오.