From bb965c061e302d4d23c8ff6eb6b46efa7351c27e Mon Sep 17 00:00:00 2001
From: claude-bot <claude-bot@tkrmagid.kr>
Date: Thu, 30 Apr 2026 03:31:43 +0900
Subject: [PATCH] Improve Windows Python setup guidance

---
 .env.example                       |  1 +
 README.md                          | 17 ++++++++++++-----
 src/python-runtime.ts              |  7 ++++---
 src/services/python-json-worker.ts | 16 +++++++++++++++-
 4 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/.env.example b/.env.example
index 7579972..31c4063 100644
--- a/.env.example
+++ b/.env.example
@@ -9,6 +9,7 @@ OLLAMA_NUM_CTX=4096
 
 LOCAL_AI_VENV_PATH=.local-ai/.venv
 LOCAL_AI_CACHE_DIR=.local-ai/cache
+# Windows면 보통 `py -3`
 LOCAL_AI_PYTHON=
 LOCAL_STT_MODEL=tiny
 LOCAL_STT_DEVICE=auto
diff --git a/README.md b/README.md
index 4879f0f..fca382c 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,12 @@ ollama pull qwen3:0.6b
 bun run setup:local-ai
 ```
 
+Windows에서 `python` 에러가 나면 `.env` 에 먼저 이 값을 넣습니다:
+
+```env
+LOCAL_AI_PYTHON=py -3
+```
+
 그다음 로컬 장치 확인:
 
 ```bash
@@ -123,16 +129,17 @@ OLLAMA_MODEL=qwen3:1.7b
 
 1. `bun install`
 2. `ollama pull qwen3:0.6b`
-3. `bun run setup:local-ai`
-4. `bun run devices`
-5. 필요하면 `.env` 에 `LOCAL_AUDIO_SOURCE` 설정
-6. `bun run start:local`
+3. Windows면 `.env` 에 `LOCAL_AI_PYTHON=py -3` 추가
+4. `bun run setup:local-ai`
+5. `bun run devices`
+6. `.env` 에 `LOCAL_AUDIO_SOURCE` 설정
+7. `bun run start:local`
 
 ## Windows 메모
 
 - `bun run devices` 와 Windows 로컬 녹음은 `ffmpeg`가 필요합니다.
 - 출력 장치 직접 선택은 아직 미구현이라 시스템 기본 출력 장치로 재생됩니다.
-- Python 탐지가 안 되면 `.env` 에 `LOCAL_AI_PYTHON=py -3` 또는 `LOCAL_AI_PYTHON=python` 을 넣으면 됩니다.
+- Python 탐지가 안 되면 `.env` 에 `LOCAL_AI_PYTHON=py -3` 를 넣으면 됩니다.
 
 ## 설계 메모
 
diff --git a/src/python-runtime.ts b/src/python-runtime.ts
index 48d4bcb..cab3af9 100644
--- a/src/python-runtime.ts
+++ b/src/python-runtime.ts
@@ -18,7 +18,7 @@ function canRun(command: string, args: string[]): boolean {
   const result = spawnSync(command, [...args, "--version"], {
     encoding: "utf8",
   });
-  return result.status === 0;
+  return result.error == null && result.status === 0;
 }
 
 export function resolveLocalAiVenvPath(config: AppConfig): string {
@@ -83,8 +83,9 @@ export function resolvePythonLaunch(config: AppConfig, options?: { preferVenv?:
     [
       "Python 실행 파일을 찾지 못했습니다.",
       "1. Python 3.11 이상을 설치",
-      "2. 필요하면 `.env` 에 `LOCAL_AI_PYTHON=python` 또는 `LOCAL_AI_PYTHON=py -3` 설정",
-      "3. 그 다음 `bun run setup:local-ai` 실행",
+      "2. Windows면 `py -3 --version` 이 되는지 먼저 확인",
+      "3. 되면 `.env` 에 `LOCAL_AI_PYTHON=py -3` 설정",
+      "4. 그 다음 `bun run setup:local-ai` 실행",
     ].join("\n"),
   );
 }
diff --git a/src/services/python-json-worker.ts b/src/services/python-json-worker.ts
index f48f304..5f87dc7 100644
--- a/src/services/python-json-worker.ts
+++ b/src/services/python-json-worker.ts
@@ -172,7 +172,21 @@ export class PythonJsonWorker {
     });
 
     child.on("error", (error) => {
-      this.rejectAll(error as Error);
+      const spawnError = error as NodeJS.ErrnoException;
+      if (spawnError.code === "ENOENT") {
+        this.rejectAll(
+          new Error(
+            [
+              `Python 실행에 실패했습니다: ${launch.command}`,
+              "Windows면 `.env` 에 `LOCAL_AI_PYTHON=py -3` 를 넣고 다시 실행하세요.",
+              "최초 1회는 `bun run setup:local-ai` 를 먼저 실행해야 합니다.",
+            ].join("\n"),
+          ),
+        );
+        return;
+      }
+
+      this.rejectAll(spawnError);
     });
 
     this.child = child;