# scratch_ai_assistant **Repository Path**: giteevip2018_admin/scratch_ai_assistant ## Basic Information - **Project Name**: scratch_ai_assistant - **Description**: Scratch AI Assistant packaged for Windows - **Primary Language**: Unknown - **License**: GPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-03-31 - **Last Updated**: 2026-03-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README [๐Ÿ‡จ๐Ÿ‡ณ ็ฎ€ไฝ“ไธญๆ–‡](README.md) | [๐Ÿ‡บ๐Ÿ‡ธ English](README_en.md) # Scratch Socratic AI Assistant (Compiler and Tutor) This is a **next-generation graphical programming platform** designed specifically for "youth technology & programming education." The platform seamlessly embeds a deeply modified Scratch 3.0 frontend editor (featuring a floating sidebar). Behind the scenes, it integrates a "Socratic" Large Language Model (LLM) tutor that guides students in computational thinking. It also compiles the natural pseudo-code or Markdown code blocks generated by the LLM into standard SB3 AST structures in milliseconds, enabling blocks to be **instantly rendered on the canvas**! ## Core Architecture Design - `app.py`: A Microservice core bus based on Flask. Provides `/api/chat` and `/api/compile_sb3_block` endpoints. (Port **5001**) - `ai_persona.txt / ai_persona.md`: The brain and control map of the AI tutor. It supports extreme, strict constraints on the AI's response length and tone, **taking effect immediately without needing to restart the backend!** - `scratch-gui/`: A frontend project heavily re-engineered based on the official React boilerplate. It integrates the exclusively developed `AiChatSidebar`โ€”a conflict-free block stream rendererโ€”as well as a silent background pre-loading engine for AST structures. (Port **8601**) ## โœจ Recent Optimizations (Updates) 1. **AI Persona Persistence**: The system prompt is now independently saved to `ai_persona.md` with hot-reload support, applying any edits instantly. 2. **Standalone Executable Integration**: Supports full-stack packaging using PyInstaller (Python backend) and Electron (Node frontend) into a zero-configuration, standalone ready-to-use application for Windows, enabling rapid distribution. 3. **UI/UX Refinements**: Polished and optimized the visual presentation styles (CSS) and state logic of the `AiChatSidebar`. --- ## ๐Ÿ› ๏ธ Installation and Setup Open your terminal and execute: ```bash git clone https://github.com/nijisakai/scratch_ai_assistant.git cd scratch_ai_assistant ``` --- ## ๐Ÿš€ Step 1: Start the AI Microservice Backend (Python) This is the pivotal service that must be started first to handle intelligent chats and AST compilation. 1. **Install Dependencies**: ```bash pip install flask flask-cors dashscope python-dotenv ``` 2. **Environment Variables and Run** (Bind your LLM API Key where appropriate): ```bash # Depending on specific logic, if you use env vars like DASHSCOPE_API_KEYS, you may declare them via an .env file or command line. python app.py ``` > **You will see `๐Ÿš€ Scratch AI Assistant - Backend started on port 5001` upon success.** --- ## ๐Ÿš€ Step 2: Start the Scratch GUI Frontend (Node + React) While keeping the Python backend above running, **open a new terminal window**, and enter the `scratch-gui` subdirectory: 1. **Install NPM Packages** (Dependencies are heavy; initial installation takes a while): ```bash cd scratch-gui npm install ``` 2. **Start Hot-Reload Service**: ```bash npm start ``` Once the application launches, open your browser and navigate to **`http://localhost:8601`** to embark on a brand new AI-assisted creative journey! ๐ŸŒŸ --- ## ๐Ÿ“š Citation Instructions If you use this project in your research, papers, or practical applications, please cite or give credit: > Chen Hongyu (Beijing Normal University). Scratch Socratic AI Assistant. GitHub: https://github.com/nijisakai/scratch_ai_assistant ## ๐Ÿ“ Author & Contact - **Author**: Hongyu Chen (BNU) - **Email**: hychen@mail.bnu.edu.cn