xiaojilele-glitch/WhyBuddy

A Simple and Universal Product Rehearsal Engine, Speccing Anything. 简洁通用的产品推演引擎，推演万物。

🎯 SlideRule (WhyBuddy)이란?

SlideRule은 오픈소스 제품 리허설 엔진입니다. 제품 아이디어를 설명하는 한 문장을 입력하면 시스템은 완전한 제품 사양, UI 목업, 데이터 모델, 심지어 실행 가능한 웹 앱까지 결정론적이고 단계별로 생성하는 과정을 안내합니다. 모든 것은 브라우저 내에서 이루어집니다. 각 중간 산출물은 다음 단계로 진행하기 전에 명시적인 "게이트"(증거 검사)를 통과해야 하므로 최종 앱은 "LLM이 완료했다고 말함"이 아니라 구체적이고 감사 가능한 작업으로 보장됩니다.

🛠️ 핵심 개념 및 워크플로우

단계	무엇이 일어나는가	누구/구성 요소
의도	한 문장을 입력합니다 (예: "애완동물 클리닉 예약").	클라이언트 UI
컨트롤 플레인	문장은 범위 카드와 가정 카드로 변환되어 리허설을 구동합니다.	`rehearsal_control` (Node/TS)
사양 → 페이지 → 구조 → 바인딩	사양 우선 파이프라인이 요구 사항 사양, 그 다음 UI 페이지, 그 다음 데이터 구조 그래프를 생성하고 마지막으로 모든 것을 바인딩합니다.	`spec-first` 파이프라인 (Python)
가정 검토	숨겨진 모델 분기는 카드로 표시됩니다. 사용자는 계속하기 전에 확인해야 합니다.	`spec.assumptions`
게시 종결	6가지 필수 "스킬"(증거, RBAC, 워크플로우, 데이터, AIGC 등)이 모두 검사됩니다. 게이트가 실패하면 리허설은 개선을 위해 일시 중지됩니다.	`publish closure`
실행 / 개선	완전히 기능하는 웹 앱이 브라우저에서 시작됩니다. 반복, 수리 또는 내보낼 수 있습니다.	브라우저 런타임 + 컨트롤 플레인

전체 루프는 저장소의 Live path 다이어그램에서 시각화되며 호스팅된 데모에서 즉시 시도할 수 있습니다 (백엔드나 API 키 불필요). 키가 제공되면 LLM은 OpenAI 호환 엔드포인트를 통해 브라우저 내에서 실행됩니다.

🚀 내부 작동 방식

계층	기술	역할
프론트엔드	Vite + React (TypeScript)	의도 작성, 리허설 단계 보기, 생성된 앱 실행을 위한 UI.
경량 프록시 서버	Express (Node)	`/api/sliderule` 및 `/api/agent-loop` 엔드포인트를 노출하여 Python 엔진으로 전달합니다.
권위 엔진	FastAPI (Python) – `slide-rule-python`	결정론적 파이프라인, 게이트 검사, 아키텍처 그래프 검증을 구현합니다.
공유 계약	`shared/` (JSON 스키마)	TS와 Python 간에 동일한 데이터 모델을 보장합니다.
스킬 패키지	`skills/sliderule.zip`	자체 포함된 "스킬"로, 모든 TRAE/Claude 스타일 에이전트 호스트에 드롭할 수 있습니다. 문장을 완전한 사양 패키지로 변환합니다.
Docker	`docker‑compose.yml`	원커맨드 개발/프로덕션 스택 (Node + Python, 선택적 MySQL, Redis, Lobster 실행기).

모든 아키텍처 다이어그램은 코드에서 생성되며 (arch_graph.py / arch-graph-ts.mjs), 시각적 표현이 실제 구현에서 벗어나지 않도록 보장합니다.

📦 빠른 시작 (Docker)

# 클론 및 구성
git clone https://github.com/2686521696/WhyBuddy.git && cd WhyBuddy
cp .env.example .env   # OpenAI 호환 LLM_API_KEY 추가

# 스택 빌드 및 실행
docker compose up -d --build

# UI 열기
open http://localhost:3000/agent-loop/sliderule

LLM 키를 생략하면 엔진이 결정론적 템플릿으로 폴백하므로 UI는 탐색용으로 계속 작동합니다.

🧪 소스에서 실행 (Docker 없음)

pnpm install                     # TS 종속성 설치
pnpm run dev:all                 # Vite (3000) + Node 프록시 (3001) + Python FastAPI (9700)

위와 동일한 URL을 엽니다. 저장소는 경량 dev:sliderule 모드 (프론트엔드 + Python만)와 오프라인 데모용 UI 전용 dev:frontend 모드도 제공합니다.

🎓 예제 사용 사례 (README에서)

애완동물 클리닉 예약 및 분류 – 분류 UI를 갖춘 완전한 예약 흐름을 생성합니다.
중고 악기 위탁 판매 – 원장, 감정 워크벤치, 달력 보기를 만듭니다.
대본 살인 이벤트 장소 스케줄링 – 세션 보드, 신청 양식, 카풀 조정을 구축합니다.
필드 수준 권한이 있는 조달 승인 – RBAC로 잠긴 승인 상태 머신을 갖춘 5시스템 모델을 생성합니다.

각 예제는 의도 → 사양 → UI → 실행 가능한 앱의 엔드투엔드 경로를 보여주며, 모두 증거 검사로 게이트됩니다.

📊 프로젝트 규모 (저장소 기준)

9,313개의 추적 파일
3,336개의 TS/TSX 파일 (약 945 k줄의 TypeScript)
817개의 Python 파일 (약 226 k줄의 Python)
2,018개의 테스트 파일
2,205개의 라이브 모듈 (실행 중인 시스템의 일부인 모듈)

🤝 기여

프로젝트는 게이트 병합 워크플로우를 사용합니다:

bash scripts/merge-gated.sh <branch> "msg"   # → pre_main
bash scripts/merge-gated.sh pre_main "msg" main   # → main

로컬에서 pnpm run check && pnpm run test를 실행하고 Python 테스트는 다음 명령으로 실행합니다:

slide-rule-python/.venv/bin/python -m pytest slide-rule-python/tests/ -q

전체 지침은 CONTRIBUTING.md를 참조하세요.

📄 라이선스 및 링크

라이선스: MIT
라이브 데모: https://2686521696.github.io/WhyBuddy/agent-loop/sliderule
메인 저장소: https://github.com/2686521696/WhyBuddy
제품 사이트: https://sliderule.ai
수상: TRAE Pioneer Skill Award 2026‑07

SlideRule은 "원클릭 앱 생성기"가 아닙니다. 그 가치는 코드가 릴리스되기 전에 모든 설계 결정을 가시적이고 감사 가능하며 되돌릴 수 있게 만드는 데 있습니다.