feat: scaffold watch-screen AI pipeline (mock-runnable skeleton)

Modular async pipeline: FrameSource->Vision->context and STT/text->Brain->TTS.
All stages are Protocols; mock backends run end-to-end with no deps/keys.
Real backends included: mss screen capture, Claude vision+brain (guarded imports).

README.md

@@ -0,0 +1,61 @@
+# watch_sceen_ai
+
+디스코드 화면공유를 **실시간으로 함께 보면서 대화하는 AI**의 골격(skeleton).
+
+지금 단계는 "틀": 파이프라인 구조와 교체 가능한 인터페이스를 먼저 세우고,
+의존성/키/마이크 없이 mock 모드로 전체 흐름이 도는 걸 검증한다.
+
+## 구조
+
+```
+FrameSource ──frames──▶ VisionBackend ──observations──▶ [SharedScreenContext]
+                                                              │
+STT / TextChannel ──utterances──▶ Brain(LLM) ◀───────────────┘
+                                    │
+                                    ▼
+                        TextToSpeech / TextChannel
+```
+
+두 개의 async 루프가 동시에 돈다.
+- 인지 루프: 화면 캡처 → 비전 이해 → 최신 화면 맥락 저장
+- 대화 루프: 음성/텍스트 입력 → 두뇌(LLM, 화면맥락+대화이력) → 음성/텍스트 출력
+
+모든 단계는 `wsai/interfaces.py`의 Protocol이라, 백엔드(mock / 로컬GPU / 클라우드 /
+디스코드 웹캡처 …)를 config에서 바꿔 끼우면 오케스트레이터는 그대로다.
+
+## 실행
+
+```bash
+python -m wsai            # mock 데모 (의존성·키 불필요, 몇 프레임 돌고 종료)
+python -m wsai --live     # 이 PC 화면 캡처 + Claude 눈/두뇌 (Ctrl-C 종료)
+python -m wsai --env      # WSAI_* 환경변수로 조립
+pytest                    # 스모크 테스트
+```
+
+`--live`에 필요한 것: `pip install mss pillow anthropic`, 그리고 `ANTHROPIC_API_KEY`.
+
+## 파일
+
+| 파일 | 역할 |
+|------|------|
+| `wsai/interfaces.py` | 데이터 타입 + 컴포넌트 Protocol |
+| `wsai/pipeline.py` | 오케스트레이터(인지/대화 루프) |
+| `wsai/state.py` | 최신 화면 맥락 공유 저장소 |
+| `wsai/config.py` / `factory.py` | 설정 → 백엔드 조립 |
+| `wsai/backends/mock.py` | 무의존성 mock 전 계열 |
+| `wsai/backends/capture_mss.py` | 로컬 화면 캡처(눈) |
+| `wsai/backends/claude.py` | Claude 비전 + 두뇌 |
+
+## 아직 안 된 것 (다음 단계 후보)
+
+- STT 실제 백엔드(faster-whisper) + 마이크 캡처(sounddevice)
+- TTS 실제 백엔드(MeloTTS 등) — 이 호스트에 기존 자산 있음
+- 디스코드 텍스트 채널 I/O (`factory._text`가 아직 NotImplemented)
+- 화면 변화 감지 → AI가 먼저 말 거는 proactive 모드
+- 캡처 방식 선택: 로컬 화면 vs 디스코드 웹 캡처(Playwright)
+
+## 캡처 방식에 대한 메모
+
+디스코드 봇이 화면공유 **영상 스트림을 직접 수신**하는 건 공식 API 미지원(유저봇은 ToS 위반).
+그래서 현실적 방식은 "통화에 참여해 공유화면을 보는 상태의 화면을 로컬 캡처"하는 것.
+`MSSFrameSource`가 그 기본 구현이고, 필요하면 웹 캡처 소스로 교체 가능.