feat: vscode backend debug config

.vscode/extensions.json

@@ -2,6 +2,8 @@
   // See http://go.microsoft.com/fwlink/?LinkId=827846
   // for the documentation about the extensions.json format
   "recommendations": [
-    "mrmlnc.vscode-json5"
+    "mrmlnc.vscode-json5",
+    "ms-python.python",
+    "ms-python.debugpy"
   ]
 }

.vscode/launch.json

@@ -50,5 +50,21 @@
         "http://127.0.0.1:7777/**"
       ]
     },
+    {
+      "name": "Debug Python Backend (Attach)",
+      "type": "debugpy",
+      "request": "attach",
+      "connect": {
+        "host": "localhost",
+        "port": 5678
+      },
+      "pathMappings": [
+        {
+          "localRoot": "${workspaceFolder}/backend",
+          "remoteRoot": "."
+        }
+      ],
+      "justMyCode": false
+    }
   ]
 }

backend/main.py

@@ -36,6 +36,20 @@
 auto_include_routers(api, prefix, "app/controller")
 app_logger.info("All routers loaded successfully")
 
+# Check if debug mode is enabled via environment variable
+if os.environ.get('ENABLE_PYTHON_DEBUG') == 'true':
+    try:
+        import debugpy
+        DEBUG_PORT = int(os.environ.get('DEBUG_PORT', '5678'))
+        app_logger.info(f"Debug mode enabled - Starting debugpy server on port {DEBUG_PORT}")
+        debugpy.listen(("localhost", DEBUG_PORT))
+        app_logger.info(f"Debugger ready for attachment on localhost:{DEBUG_PORT}")
+        #📝 In VS Code: Run 'Debug Python Backend (Attach)' configuration
+        # Don't wait for client automatically - let it attach when ready
+    except ImportError:
+        app_logger.info("⚠️  debugpy not available, install with: uv add debugpy")
+    except Exception as e:
+        app_logger.info(f"⚠️  Failed to start debugpy: {e}")
 
 
 dir = pathlib.Path(__file__).parent / "runtime"

backend/pyproject.toml

@@ -19,6 +19,7 @@ dependencies = [
     "traceroot>=0.0.7",
     "nodejs-wheel>=22.18.0",
     "numpy>=1.23.0,<2.0.0",
+    "debugpy>=1.8.17",
 ]