✨ Set up comprehensive Copilot instructions for XBuilder repository

.github/copilot-instructions.md

@@ -0,0 +1,113 @@
+# GitHub Copilot Instructions for XBuilder
+
+XBuilder is a tool for building games to help children learn programming abilities. It's developed based on [spx](https://github.com/goplus/spx), a game engine built on [XGo](https://xgo.dev/).
+
+## Repository Structure
+
+- **`/docs`**: Documentation for XBuilder
+- **`/spx-gui`**: Frontend project (Vue.js + TypeScript)
+- **`/spx-backend`**: Backend project (Go + YAP framework)
+- **`/tools`**: Independent tools that XBuilder depends on
+- **`/scripts`**: Build, deployment, and automation scripts
+
+## Environment Requirements
+
+- **Node.js**: >= 20.11.1
+- **Go**: >= 1.24.0
+
+## General Guidelines
+
+### Code Quality
+- Only add comments to explain the reasoning behind code decisions when the intent is not immediately clear from the code itself
+- Follow existing patterns and conventions within each component
+- Prioritize code readability and maintainability
+- Use meaningful variable and function names
+
+### Security
+- Never commit secrets, API keys, or sensitive configuration
+- Follow security best practices for both frontend and backend code
+- Validate all user inputs appropriately
+
+## Frontend Development (spx-gui)
+
+The frontend uses Vue.js with TypeScript. Follow these specific guidelines:
+
+### TypeScript Guidelines
+- Use `null` to represent the absence of a value. Avoid using `undefined`
+- Compare values with `null` using loose equality (`==` / `!=`) to check for absence
+- Avoid boolean checks like `if (value)` or `if (!value)` for null checks
+- Use strict equality (`===` / `!==`) for all other comparisons
+- Use `PascalCase` for class names, interface names, type aliases, enum names, and Vue component names
+
+### Import Organization
+Keep import statements in this order:
+1. External libraries
+2. Internal libraries: from base to specific (e.g., from `utils` to `models` to `components`)
+3. Local files: relative paths starting with `./` or `../`
+
+### Vue Development
+- Generate accessibility info for interactive elements using `v-radar` directive
+- Follow Vue.js best practices and composition API patterns
+
+### Code Formatting
+- Use Prettier for code formatting: `npx prettier --write <file>`
+
+### Testing
+- Use `describe` to group related tests
+- Check `src/utils/test.ts` for general utility functions
+- Check `src/models/project/index.test.ts` for examples of mock `Project` instances
+- Each test case should be independent and not rely on state from other tests
+- Use the `--run` option to disable watch mode: `npm run test -- --run <file>`
+- Avoid data sharing among test cases
+
+## Backend Development (spx-backend)
+
+The backend is built with Go using the YAP framework. Follow these guidelines:
+
+### Go Development
+- Follow standard Go conventions and idioms
+- Use proper error handling patterns
+- Write clear, self-documenting code
+- Follow the existing project structure and patterns
+
+### Testing
+- Use `github.com/DATA-DOG/go-sqlmock` to mock database interactions
+- Use `github.com/stretchr/testify` to simplify assertions
+- Write comprehensive unit tests for all business logic
+- Follow table-driven test patterns where appropriate
+
+### Dependencies
+Key dependencies include:
+- YAP framework for web handling
+- GORM for database operations
+- Redis for caching
+- OpenAI Go client for AI features
+- Qiniu SDK for cloud services
+
+## Documentation
+- Update documentation when adding new features or changing existing behavior
+- Keep README files current with accurate setup and usage instructions
+- Document any new environment variables or configuration options
+
+## Development Workflow
+- Run tests before committing changes
+- Use appropriate commit message conventions
+- Follow the existing branching strategy
+- Ensure all linting and formatting checks pass
+
+## AI Integration
+XBuilder includes AI-powered features for code generation and interaction. When working with AI-related code:
+- Follow responsible AI practices
+- Implement proper error handling for AI service calls
+- Consider rate limiting and usage quotas
+- Maintain user privacy and data protection standards
+
+## Deployment and Scripts
+- Use provided scripts in `/scripts` directory for common operations
+- Docker configuration is available for containerized deployment
+- Database migrations are handled through the migration system
+- PR preview functionality is available via `pr-preview.sh`
+
+For component-specific detailed guidelines, refer to:
+- Frontend: `spx-gui/.github/instructions/*.md`
+- Backend: `spx-backend/.github/instructions/*.md`

.github/copilot.yml

@@ -0,0 +1,14 @@
+knowledge_base:
+  - "COPILOT.md"
+  - "README.md"
+  - "docs/develop/index.md"
+
+conversation_starters:
+  - "How do I set up the XBuilder development environment?"
+  - "Help me understand the XGo language extensions used in this project"
+  - "What's the architecture of the spx game engine integration?"
+  - "How does the AI copilot system work in XBuilder?"
+  - "Guide me through adding a new feature to the game builder interface"
+  - "How do I modify the tutorial system?"
+  - "What are the key components I need to understand for backend development?"
+  - "How does project serialization work for AI context?"

.github/instructions/docs-coding.instructions.md

@@ -0,0 +1,44 @@
+---
+applyTo: '**/docs/**/*.md'
+---
+
+Here are instructions for documentation in XBuilder:
+
+## General Documentation Guidelines
+
+* Write clear, concise documentation appropriate for developers learning game development
+* Use consistent formatting and structure across documentation files
+* Keep examples simple and focused on core concepts
+* Update related documentation when making functional changes
+
+## XBuilder-Specific Guidelines
+
+### Target Audience
+* Primary users are children learning programming through game development
+* Documentation should be accessible to beginners while remaining technically accurate
+* Include step-by-step instructions where appropriate
+* Use encouraging, supportive language
+
+### Technical Accuracy
+* Ensure all code examples are syntactically correct and tested
+* Keep XGo syntax examples consistent with actual implementation
+* Reference current API endpoints and model structures
+* Update documentation when underlying systems change
+
+### Structure & Organization
+* Follow the existing documentation hierarchy in `/docs`
+* Use clear headings and section organization
+* Link related concepts and cross-reference relevant sections
+* Include table of contents for longer documents
+
+### Code Examples
+* Provide working code examples where helpful
+* Use realistic game development scenarios
+* Show both XGo syntax and equivalent Go where relevant
+* Include comments explaining complex concepts
+
+### Development Documentation
+* Keep technical architecture documentation up to date
+* Document API changes and migration paths
+* Include setup and deployment instructions
+* Explain integration points between frontend and backend components

.github/instructions/general.instructions.md

@@ -0,0 +1,67 @@
+---
+applyTo: '**'
+---
+
+Here are general instructions for the XBuilder repository:
+
+## Project Overview
+
+XBuilder is a comprehensive game development platform that allows users (primarily children) to create games using Go/XGo language and the spx game engine through a visual interface.
+
+## Development Principles
+
+* **Educational Focus**: Remember that end users are children learning programming
+* **Code Clarity**: Prioritize readable, maintainable code over complex optimizations  
+* **Minimal Changes**: Make surgical, targeted changes that preserve existing functionality
+* **Cross-Component Awareness**: Consider impact across frontend, backend, and documentation
+* **Testing**: Thoroughly test changes, especially for core functionality
+
+## Repository Structure
+
+* **spx-gui/**: Frontend Vue.js/TypeScript application
+* **spx-backend/**: Backend Go services and APIs
+* **docs/**: Documentation and guides
+* **tools/**: Independent utilities and build tools
+* **scripts/**: Automation and deployment scripts
+
+## Key Technologies & Concepts
+
+### XGo Language
+* Extension of Go language for game development
+* Used in the spx game engine
+* Follow documented syntax, do not invent new language features
+
+### spx Game Engine  
+* Scratch-like game development framework
+* Provides APIs for sprites, sounds, stages, and game logic
+* Core to the XBuilder platform functionality
+
+### AI Copilot Integration
+* Advanced AI assistance system built into the platform
+* Uses templated system prompts with embedded knowledge
+* Provides context-aware help for game development
+
+## Development Workflow
+
+1. **Understand Context**: Read relevant documentation and existing code patterns
+2. **Plan Changes**: Design minimal, targeted modifications
+3. **Test Early**: Run tests frequently during development
+4. **Validate Integration**: Ensure frontend-backend compatibility
+5. **Update Documentation**: Keep docs current with functional changes
+
+## Common Patterns
+
+### Error Handling
+* Use appropriate error handling for each language/framework
+* Provide meaningful error messages for debugging
+* Consider user experience for error scenarios
+
+### API Design
+* Maintain consistency with existing patterns
+* Consider backward compatibility for API changes
+* Document changes that affect other components
+
+### Code Organization
+* Follow existing package/module structure
+* Use established naming conventions
+* Keep related functionality grouped logically

.github/instructions/go-coding.instructions.md

@@ -0,0 +1,50 @@
+---
+applyTo: '**/spx-backend/**/*.go'
+---
+
+Here are instructions for Go development in the XBuilder spx-backend:
+
+## General Go Guidelines
+
+* Follow standard Go conventions and idioms
+* Use `gofmt` for code formatting
+* Write clear, descriptive variable and function names
+* Keep functions small and focused on a single responsibility
+* Use Go modules properly with semantic versioning
+
+## XBuilder-Specific Guidelines
+
+### XGo Language Support
+* XGo is an extension of Go - use standard Go syntax unless XGo-specific features are required
+* When working with XGo syntax or spx APIs, refer to the embedded knowledge base in `internal/embkb`
+* Do not invent XGo syntax - stick to documented features or fall back to standard Go
+
+### Project Structure
+* Respect the existing layered architecture: controllers, services, models
+* Place new functionality in appropriate packages
+* Use dependency injection patterns established in the codebase
+
+### AI Copilot Integration  
+* When modifying copilot-related code, understand the system prompt templating system
+* Changes to embedded knowledge base require careful testing
+* Preserve existing copilot tool definitions and APIs
+* Test copilot functionality after making changes to related systems
+
+### Database & Models
+* Use the established model patterns for projects, sprites, sounds, stages
+* Follow existing database interaction patterns
+* Use proper error handling for database operations
+* Consider impact on API responses when modifying models
+
+### API Development
+* Maintain consistency with existing REST API patterns  
+* Use proper HTTP status codes
+* Validate input parameters thoroughly
+* Consider frontend impact when modifying API responses
+* Document API changes that affect the spx-gui component
+
+### Error Handling
+* Use Go's error handling idioms consistently
+* Provide meaningful error messages for debugging
+* Handle edge cases gracefully
+* Log errors appropriately for debugging without exposing sensitive information

.github/instructions/scripts-tools.instructions.md

@@ -0,0 +1,52 @@
+---
+applyTo: '**/scripts/**/*,**/tools/**/*'
+---
+
+Here are instructions for scripts and tools in XBuilder:
+
+## General Guidelines
+
+* Write portable scripts that work across different environments
+* Include clear usage instructions and examples
+* Use appropriate shebang lines and make scripts executable
+* Handle errors gracefully with meaningful error messages
+
+## Script Development
+
+### Build Scripts
+* Maintain compatibility with existing CI/CD pipelines
+* Test scripts on multiple platforms when possible
+* Use environment variables for configuration where appropriate
+* Document required dependencies and prerequisites
+
+### Deployment Scripts
+* Follow security best practices for deployment automation
+* Use proper secret management techniques
+* Include rollback procedures where applicable
+* Test deployment scripts in staging environments
+
+### Development Tools
+* Keep tools focused on specific, well-defined tasks
+* Provide help/usage information for command-line tools
+* Use consistent argument parsing and option handling
+* Include appropriate logging and debugging output
+
+## XBuilder-Specific Guidelines
+
+### Build System Integration
+* Understand the multi-component build process (frontend + backend)
+* Coordinate builds between spx-gui and spx-backend components  
+* Handle dependency management for both Node.js and Go modules
+* Support development and production build configurations
+
+### Environment Setup
+* Provide clear setup instructions for development environments
+* Handle version requirements for Node.js (>=20.11.1) and Go (>=1.24.0)
+* Include database setup and migration procedures
+* Document configuration requirements for local development
+
+### Tool Compatibility
+* Ensure tools work with the existing XGo language toolchain
+* Support the spx game engine build requirements
+* Integrate properly with the AI copilot development workflow
+* Handle asset processing and game file generation