From 0621e40afae66d78091ae47d7989e4f9beabc36f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:49:45 +0000 Subject: [PATCH 1/3] Initial plan From b2cab74bc1778cdd2c3bf0d0df4f69bdfdbde645 Mon Sep 17 00:00:00 2001 From: niupilot Date: Thu, 18 Sep 2025 09:53:35 +0000 Subject: [PATCH 2/3] feat: add comprehensive GitHub Copilot coding instructions - Add root-level copilot-instructions.md covering entire repository - Add Go coding guidelines for spx-backend to complement existing test instructions - Add tools directory instructions for Go and TypeScript development - Follow established patterns from existing spx-gui instructions - Cover frontend (Vue.js/TypeScript), backend (Go/YAP), and tools components Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: niupilot --- .github/copilot-instructions.md | 113 ++++++++++++++++++ .../instructions/go-coding.instructions.md | 42 +++++++ .../instructions/tools-coding.instructions.md | 37 ++++++ 3 files changed, 192 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 spx-backend/.github/instructions/go-coding.instructions.md create mode 100644 tools/.github/instructions/tools-coding.instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..2472569c9 --- /dev/null +++ b/.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 ` + +### 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 ` +- 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` \ No newline at end of file diff --git a/spx-backend/.github/instructions/go-coding.instructions.md b/spx-backend/.github/instructions/go-coding.instructions.md new file mode 100644 index 000000000..85e935150 --- /dev/null +++ b/spx-backend/.github/instructions/go-coding.instructions.md @@ -0,0 +1,42 @@ +--- +applyTo: '**/*.go' +--- + +Here are instructions for Go development in spx-backend: + +* Follow standard Go conventions and idioms consistently. + +* Use proper error handling patterns: + - Return errors as the last return value + - Wrap errors with context using `fmt.Errorf("operation failed: %w", err)` + - Handle errors at appropriate levels, don't ignore them + +* Structure and organization: + - Keep functions focused and single-purpose + - Use meaningful package names that describe functionality + - Group related functionality in appropriate packages + +* Use the YAP framework patterns established in the codebase: + - Follow existing routing and handler patterns + - Use established middleware patterns + - Maintain consistency with existing API design + +* Database operations: + - Use GORM for database interactions following existing patterns + - Implement proper transaction handling where needed + - Use prepared statements and parameterized queries + +* Dependencies management: + - Prefer standard library when possible + - Use established dependencies already in go.mod + - Follow dependency injection patterns used in the codebase + +* Configuration: + - Use the existing config system in `internal/config` + - Don't hardcode values, use configuration or constants + - Follow environment-based configuration patterns + +* Logging and monitoring: + - Use structured logging where available + - Log errors appropriately with sufficient context + - Follow existing patterns for monitoring and metrics \ No newline at end of file diff --git a/tools/.github/instructions/tools-coding.instructions.md b/tools/.github/instructions/tools-coding.instructions.md new file mode 100644 index 000000000..8e5bde7c7 --- /dev/null +++ b/tools/.github/instructions/tools-coding.instructions.md @@ -0,0 +1,37 @@ +--- +applyTo: '**' +--- + +Here are instructions for development in the tools directory: + +* Tools should be self-contained and focused on specific functionality. + +* Follow the language-specific conventions: + - For Go code: Follow standard Go idioms and the patterns established in spx-backend + - For TypeScript code: Follow the patterns established in spx-gui + +* Each tool should have: + - Clear documentation in its README.md + - Proper error handling + - Appropriate logging for debugging + +* Build and deployment: + - Use build scripts where provided (e.g., build.sh) + - Ensure tools can be built and run independently + - Document any dependencies and setup requirements + +* Testing: + - Write tests for critical functionality + - Use appropriate testing frameworks for each language + - Ensure tools are testable in isolation + +* For spxls (Language Server): + - Follow Language Server Protocol specifications + - Maintain compatibility with existing editor integrations + - Handle client-server communication robustly + +* For AI tools: + - Implement proper rate limiting and backoff strategies + - Handle API failures gracefully + - Maintain security best practices for API communications + - Follow established patterns for WebAssembly integration where applicable \ No newline at end of file From 490fd6e54353957d18b7f668983a1dabf044fa69 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:56:36 +0000 Subject: [PATCH 3/3] Set up comprehensive Copilot instructions for XBuilder repository Co-authored-by: nighca <1492263+nighca@users.noreply.github.com> --- .github/copilot.yml | 14 +++ .../instructions/docs-coding.instructions.md | 44 +++++++++ .github/instructions/general.instructions.md | 67 +++++++++++++ .../instructions/go-coding.instructions.md | 50 ++++++++++ .../scripts-tools.instructions.md | 52 ++++++++++ COPILOT.md | 97 +++++++++++++++++++ 6 files changed, 324 insertions(+) create mode 100644 .github/copilot.yml create mode 100644 .github/instructions/docs-coding.instructions.md create mode 100644 .github/instructions/general.instructions.md create mode 100644 .github/instructions/go-coding.instructions.md create mode 100644 .github/instructions/scripts-tools.instructions.md create mode 100644 COPILOT.md diff --git a/.github/copilot.yml b/.github/copilot.yml new file mode 100644 index 000000000..fecafcc18 --- /dev/null +++ b/.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?" \ No newline at end of file diff --git a/.github/instructions/docs-coding.instructions.md b/.github/instructions/docs-coding.instructions.md new file mode 100644 index 000000000..e27e71281 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.github/instructions/general.instructions.md b/.github/instructions/general.instructions.md new file mode 100644 index 000000000..2508c136b --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.github/instructions/go-coding.instructions.md b/.github/instructions/go-coding.instructions.md new file mode 100644 index 000000000..3ca9b37a5 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.github/instructions/scripts-tools.instructions.md b/.github/instructions/scripts-tools.instructions.md new file mode 100644 index 000000000..aee554033 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/COPILOT.md b/COPILOT.md new file mode 100644 index 000000000..8340ae22f --- /dev/null +++ b/COPILOT.md @@ -0,0 +1,97 @@ +# XBuilder - Copilot Instructions + +XBuilder is a comprehensive game development platform that allows users to create games using Go/XGo language and the spx game engine. This repository contains both frontend and backend components along with documentation and tools. + +## Project Overview + +XBuilder consists of several key components: +- **spx-gui**: Frontend Vue.js/TypeScript application for the visual game builder interface +- **spx-backend**: Backend Go services providing APIs, project management, and AI copilot integration +- **docs**: Comprehensive documentation including development guides and tutorials +- **tools**: Independent utilities and build tools +- **scripts**: Automation scripts for building, deploying, and maintenance + +## Architecture & Key Technologies + +- **Frontend**: Vue.js 3 with TypeScript, using Composition API +- **Backend**: Go 1.24+ with custom XGo language extensions +- **Game Engine**: spx - a Scratch-like game development framework +- **AI Integration**: Advanced copilot system for assisting game development +- **Build System**: Node.js 20.11.1+ and Go modules + +## Development Guidelines + +### General Principles +- Make minimal, surgical changes that preserve existing functionality +- Follow existing code patterns and conventions within each component +- Prioritize code clarity and maintainability over cleverness +- Test changes thoroughly, especially when modifying core functionality + +### Language-Specific Guidelines + +#### Go/XGo (spx-backend) +- XGo is an extension of Go - use standard Go syntax unless XGo-specific features are needed +- Follow standard Go conventions: package names lowercase, exported functions PascalCase +- Use the spx game engine APIs as documented in the codebase +- When working with copilot system prompts, understand the templating system used +- Respect the existing embedded knowledge base (embkb) structure + +#### TypeScript/Vue.js (spx-gui) +- Follow the existing instruction files in `spx-gui/.github/instructions/` +- Use `null` for absence of values, avoid `undefined` +- Keep imports organized: external libraries, internal libraries, local files +- Use PascalCase for classes, interfaces, types, enums, and Vue components +- Apply `v-radar` directive for accessibility on interactive elements + +#### Documentation +- Follow existing documentation structure and style +- Update related docs when making functional changes +- Use clear, concise language appropriate for developers learning game development +- Include code examples where helpful + +## Project-Specific Context + +### Game Development Focus +- Users are primarily children learning programming through game development +- XBuilder provides a Scratch-like visual interface with underlying XGo code generation +- The platform emphasizes educational value and ease of use + +### AI Copilot Integration +- Sophisticated copilot system helps users with game development +- System prompts are templated and include embedded knowledge about XGo syntax and spx APIs +- Different copilot modes: standard assistance, workflow guidance, and code generation +- Context includes project information, game files, and user instructions + +### Key Features +- Visual game builder with code generation +- Project management and collaboration features +- Tutorial system with guided learning experiences +- Real-time AI assistance for coding and debugging +- Asset management for sprites, sounds, and other game resources + +## Common Development Tasks + +### When modifying spx-backend: +- Understand the model layer (projects, sprites, sounds, stages) +- Be careful with API changes that affect the frontend +- Test copilot functionality if modifying AI-related code +- Consider impact on embedded knowledge base + +### When modifying spx-gui: +- Test both desktop and mobile interfaces +- Verify accessibility features work correctly +- Ensure tutorial system continues to function +- Test project serialization and AI context generation + +### When updating documentation: +- Keep technical accuracy with current implementation +- Maintain beginner-friendly explanations +- Update related tutorial content if applicable + +## Testing & Validation + +- Run existing test suites before and after changes +- Test cross-component functionality (frontend-backend integration) +- Verify AI copilot features work correctly with changes +- Manual testing of game creation and editing workflows +- Validate build and deployment processes \ No newline at end of file