From cd322f68f320505c9d667a680644ebbdf86c445e Mon Sep 17 00:00:00 2001 From: Masterain Date: Mon, 25 Aug 2025 16:36:25 -0700 Subject: [PATCH 1/3] Create copilot-instructions.md --- .github/copilot-instructions.md | 132 ++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..dea4e84 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,132 @@ +Your task is to "onboard" this repository to Copilot coding agent by adding a .github/copilot-instructions.md file in the repository that contains information describing how a coding agent seeing it for the first time can work most efficiently. + +You will do this task only one time per repository and doing a good job can SIGNIFICANTLY improve the quality of the agent's work, so take your time, think carefully, and search thoroughly before writing the instructions. + + +- Reduce the likelihood of a coding agent pull request getting rejected by the user due to generating code that fails the continuous integration build, fails a validation pipeline, or having misbehavior. +- Minimize bash command and build failures. +- Allow the agent to complete its task more quickly by minimizing the need for exploration using grep, find, str_replace_editor, and code search tools. + + + +- Instructions must be no longer than 2 pages. +- Instructions must not be task specific. + + + + +Add the following high level details about the codebase to reduce the amount of searching the agent has to do to understand the codebase each time: + + +- **Repository Purpose**: Snap.Hutao.Server is the backend **API server** for the Snap Hutao toolkit (an open-source Genshin Impact utility). It provides server-side support for features like user accounts (passport system), game data synchronization (e.g. uploading and analyzing wish/gacha logs and Spiral Abyss statistics), community features, and integrations (such as Discord bot commands, OAuth login via GitHub, etc.). In short, this repository implements the **Hutao API** services that the Snap Hutao client and other tools interact with. +- **Project Scope & Tech Stack**: This repository is a **C# ASP.NET Core** web server project (approximately 18 stars, multiple contributors). It targets **.NET 9.0** (the latest stable .NET at time of writing) and uses modern C# 10+ features and patterns. The codebase primarily consists of C# (~98%) with a small amount of HTML/CSS (for Swagger UI customization). Key frameworks and libraries include **ASP.NET Core Web API**, **EF Core (Entity Framework Core)** with a MySQL 8 database backend, **Quartz** for scheduled jobs, **Disqord** for a built-in Discord bot, **Swashbuckle** for API documentation (Swagger UI), and **Sentry** for logging. The project follows **modern C# coding style** (idiomatic async/await, nullable reference types, expression-bodied members, etc.) and employs **StyleCop Analyzers** and .editorconfig rules to enforce consistent code style and formatting. +- **Repository Structure & Size**: The repository is moderately sized and organized under a single solution. It consists of one main ASP.NET Core project (`Snap.Hutao.Server`) containing all server code. There are supportive configuration files (Dockerfile, docker-compose, etc.) and no additional submodules. Snap.Hutao.Server is part of the Snap Hutao ecosystem: it depends on a separate **Snap.Metadata** project’s data (game metadata) and works in tandem with the Snap Hutao client. The default and only main branch is **`main`**, which is used for all development and contributions (all pull requests should target `main`). + + + +Add information about how to build and validate changes so the agent does not need to search and find it each time. + + +- **Prerequisites**: Ensure **.NET SDK 9.0** (or latest stable .NET) is installed. The project also requires access to a **MySQL 8** database (two schemas are used: a primary application database and a metadata database) and a **Redis** server for caching or ephemeral data. These services are not included in the repository code and must be available in the environment. No secrets or sensitive credentials are committed in the repo – you will need to provide configuration values (such as database connection strings, JWT keys, third-party API keys) via environment variables or a local `appsettings.json` file before running the server. (By default, secrets like database passwords, SMTP keys, ReCaptcha keys, etc. are expected to be supplied at runtime through environment or a `.env` file for Docker.) +- **Initial Setup**: Before building, set up configuration: + - For local development, create an `appsettings.json` (or `appsettings.Development.json`) in the `Snap.Hutao.Server` project directory with the required settings. At minimum, define a **ConnectionStrings** section with `"PrimaryMysql8"` and `"MetadataMysql8"` entries pointing to your MySQL databases. Also provide an `"App"` section with all fields required by `AppOptions` (e.g. `JwtRaw` for JWT signing key, `MailerSecret`, `ReCaptchaKey`, `RedisAddress`, `RSAPrivateKey`, `CdnEndpoint`, `CdnToken`, `OAuthStateEncryptKey`, and nested options for Afdian, Discord, GenshinPizzaHelper, Smtp, Github OAuth, etc.). In a development environment, you can set these via user-secrets or environment variables as well. **Note:** The repository does not include these values, and the server will throw exceptions (or fail to start) if they are missing. Always configure the necessary environment before running or testing the server. + - Alternatively, you can use the provided **Docker** setup for a consistent environment. The repo contains a `docker-compose.yml` and a `Dockerfile`. Prepare a `.env` file in the project root with all required environment variables (matching the keys in `AppOptions` and connection strings) and then run `docker-compose up --build`. This will launch the `homa-server` container (the Snap.Hutao.Server app) and a Redis service. You will still need a running MySQL server accessible to the container (update connection strings accordingly, e.g., using `host.docker.internal` if MySQL is on host). The Docker image uses **mcr.microsoft.com/dotnet/aspnet:9.0** as the base, so it expects .NET 9 and will expose the server on port 80 (mapped to host port as configured in compose or `run.sh`). +- **Building the Project**: This is a standard .NET project, so use the **dotnet CLI** or an IDE like Visual Studio. Always restore and build to catch any errors: + 1. Run `dotnet restore` in the repository root or in `src/Snap.Hutao.Server` to restore NuGet packages. + 2. Run `dotnet build src/Snap.Hutao.Server/Snap.Hutao.Server.sln -c Debug` (for a Debug build) or `-c Release` for a Release build. You can also build the project file directly (`Snap.Hutao.Server.csproj`). The build should succeed without errors. The project is using C# latest features and analyzers; treat analyzer warnings seriously as they enforce coding standards (the build may be configured to treat warnings from StyleCop as errors, so ensure your code conforms to the style rules to avoid build failures). + - **Note on Code Style**: The repository maintains strict code style guidelines (see the `.editorconfig` and StyleCop settings). Always format code and fix styling issues (naming, spacing, documentation) before committing. You can run `dotnet format` to auto-format according to .editorconfig rules. For any new code, follow conventions used in existing code (e.g. file header comments, XML documentation on public members, use of `var` vs explicit types, etc.). This will reduce the chance of CI failures due to style checks. +- **Testing and Validation**: Currently, there is no separate unit test project in this repository (no automated test suite is provided). Validation of changes is primarily done via building the project and running the server to perform manual or integration tests: + - **Run the Server (Development)**: After building, you can run the server directly. Use `dotnet run -c Debug --project src/Snap.Hutao.Server/Snap.Hutao.Server/Snap.Hutao.Server.csproj` (or launch via an IDE). In Development mode, the server listens on `http://localhost:5076` and `https://localhost:7076` (as configured in `Properties/launchSettings.json`). The Swagger UI will be available at `/swagger` (e.g., http://localhost:5076/swagger) for exploring the API. Ensure that you have provided all required config (otherwise the server might fail on startup when setting up services like database contexts or OAuth). + - **Run the Server (Docker)**: Alternatively, to replicate a production-like environment, use `docker-compose up`. This will build and run the server in a container. By default, the docker setup maps the server to port 9378 on the host (see `run.sh` and `docker-compose.yml`). After the container starts, access `http://localhost:9378/doc` for the Swagger UI (the API documentation is served under `/doc` in the container configuration). + - **Manual Testing**: Once the server is running, you can test endpoints via Swagger or HTTP client. For example, you can try the health of the API by hitting the Swagger UI or some open endpoint (if any). Many endpoints require authentication (JWT Bearer tokens via the Passport system), so you might create a test user account using the Passport (account) API, then test authorized endpoints like retrieving gacha logs, etc. If you’ve made changes to any logic, verify those changes by calling the relevant endpoint and checking the response or database effect. +- **Database Migrations**: The project uses EF Core Code First Migrations (see the `Migrations/` directory for migration classes). When you modify any model classes under `Model/Entity/`, you should create a new migration and update the database: + - To add a migration, run `dotnet ef migrations add -s src/Snap.Hutao.Server/Snap.Hutao.Server.csproj` (the design-time factory will look for `appsettings.json` for connection strings, so ensure it’s configured). Then run `dotnet ef database update` to apply it to your local database. The application, when running in **Release** configuration, will automatically apply pending migrations on startup (see `Program.cs` where `MigrateDatabase(app)` is called under a RELEASE conditional). However, during development (Debug configuration), you need to apply migrations manually. Always include new migration files in your pull request if you change the data schema. +- **Continuous Integration (CI)**: Any code changes should pass the build and basic validation checks before submission: + - The repository previously included a GitHub Actions workflow to build and publish a Docker image on pushes to main. While this workflow might be disabled (renamed) at present, you should still ensure your changes do not break the Docker build process. In practice, this means the project must build successfully in Release mode and produce a working self-contained publish output. You can simulate this by running `dotnet publish -c Release` and ensuring it completes without errors. The Docker build (as defined in `Dockerfile`) essentially runs `dotnet restore`, `dotnet build`, and `dotnet publish`; if those succeed locally, the CI pipeline should also succeed. + - Since there are no automated tests, the primary CI gating factor is compile/build success (and adherence to style rules). Make sure **all build warnings and StyleCop issues are resolved**. In this project, treat a clean build (no warnings) as a requirement for a successful contribution. +- **Running Lint/Analysis**: Apart from StyleCop analyzers (which run during build), you can also run static analyzers or linters if needed. For example, running `dotnet analyzers` (if configured) or checking for any TODO/FIXME comments in the code can be useful. The codebase occasionally marks workarounds or important notes (search the code for keywords like "HACK", "TODO" for any relevant guidance). +- **After Making Changes**: If you implement a new feature or bug fix: + - Rebuild the project to catch any syntax or reference errors. + - Run the server and manually test the affected endpoints or logic. For instance, if you change how a particular service works (e.g., the GachaLog processing algorithm), upload sample data via that endpoint and verify the output or database entries. + - Ensure that any new dependencies are added to the project file and restore correctly. Also update documentation or comments if applicable (the repository values clear documentation, as seen by XML comments on public APIs and the provided README/docs links). + - Double-check formatting (you can use `dotnet format` or an IDE’s Code Cleanup) to match the repository’s style before committing. + + + +List key facts about the layout and architecture of the codebase to help the agent find where to make changes with minimal searching. + + +- **Solution & Project Structure**: The code is organized under `src/Snap.Hutao.Server/`. There is a Visual Studio solution file **`Snap.Hutao.Server.sln`** in this directory which contains a single C# project **`Snap.Hutao.Server.csproj`** (located in the `Snap.Hutao.Server/` subfolder). All source code is under `src/Snap.Hutao.Server/Snap.Hutao.Server/`. The project follows typical ASP.NET Core structure: + - The entry point is **`Program.cs`** in the project root, which configures the web application, services, and middleware. (Notably, there is no separate Startup.cs; configuration is done inline in Program using the WebApplication builder pattern.) + - **Configuration Files**: The project expects configuration from `appsettings.json` (not committed) and environment variables. It includes a `Properties/launchSettings.json` (for local dev server settings such as ports and ASPNETCORE_ENVIRONMENT). The `Dockerfile` and `docker-compose.yml` in `src/Snap.Hutao.Server/` are used to containerize the app; they refer to the project’s context and require an `.env` file for secrets. + - **Controllers**: Located in the `Controller/` namespace (e.g., `Snap.Hutao.Server.Controller`). Controllers are decorated with `[ApiController]` and define the API endpoints. They are grouped by domain: + - For example, `PassportController` (and related controllers under **Authorization** namespace) handle user registration, login, token refresh, etc. (the “胡桃账户” / Passport API). + - `GachaLogController` handles endpoints for uploading and retrieving wish (gacha) logs. + - `SpiralAbyssController` for Spiral Abyss statistics endpoints. + - `RoleCombatController` for character battle statistics (剧演统计) endpoints. + - `AnnouncementController` for game announcements, `DistributionController` for client software distribution management, `RedeemController` for redemption code features, and others like `ServicesController` (maintenance/admin interfaces), `OAuthController` (third-party login integration, e.g., GitHub OAuth as shown in code), etc. + - Each controller typically uses services from the `Service/` layer and repositories (the EF Core contexts) to fulfill requests. Controllers often have attributes like `[Authorize]` where authentication is needed and use `ApiExplorerSettings(GroupName=...)` to categorize them under Swagger UI sections (like "Passport", "GachaLog", etc.). + - **Services & Business Logic**: Under `Service/` namespace. This contains the core business logic, often organized by feature: + - For example, `PassportService` (in `Service/Authorization`) manages user accounts and authentication logic, `GachaLogService` processes and stores gacha log data, `SpiralAbyssStatisticsService` handles abyss stats, `RankService` (in `Service/Ranking`) might handle leaderboard computations, `MailService` for sending emails (probably verification or newsletters via SMTP), `ReCaptchaService` to verify Google ReCaptcha, `GithubService` for GitHub OAuth integration, etc. + - Many services are registered in DI (Dependency Injection) in Program.cs with appropriate lifetimes (Scoped/Singleton/Transient). When modifying or adding a new feature, locate the relevant service or create a new one and register it in Program.cs’s service configuration. + - Some services interface with external systems: e.g., `DiscordService` integrates with Discord (using the Disqord library) and is likely responsible for the bot functionality configured in Program.cs (`ConfigureDiscordBot`). `AfdianWebhookService` might handle webhooks from the Afdian donation platform. Ensure that when adding features related to these external systems, you use the existing patterns (e.g., see how `GithubService` implements `IOAuthProvider` for OAuth flows). + - **Data Models**: Under `Model/` namespace: + - `Model/Entity/` contains **Entity Framework Core entity classes** that map to database tables. For instance, `Entity.Passport` might contain `HutaoUser` (user accounts), `RefreshToken` entities, etc., `Entity.GachaLog` for wish records, `Entity.SpiralAbyss` for abyss records, etc. Each subfolder under Entity corresponds to a domain area’s tables. + - `Model/Context/` has the EF Core **DbContext** classes: `AppDbContext` for the primary application database and `MetadataDbContext` for the separate metadata database (likely read-only game data such as character info, etc.). These are configured in Program.cs with connection strings "PrimaryMysql8" and "MetadataMysql8" respectively. The contexts use MySQL provider (Pomelo.EntityFrameworkCore.MySql) and likely have migrations set up for the AppDbContext. + - `Model/Response/` classes define unified response shapes. Notably, the project returns a standard structure with a `ReturnCode` and message. For example, `Response` might wrap data with a retcode and message (following a pattern where `retcode` 0 indicates success). The controllers use these to return consistent JSON responses. If you introduce new API endpoints, use the existing `Response.Success()` / `Response.Fail()` helpers to conform to this format. + - `Model/Upload/` might have classes that represent payloads for certain endpoints (e.g., structures for uploading abyss stats or gacha logs). + - `Model/ReCaptcha/Geetest` classes suggest support for an alternative captcha (Geetest), possibly used in regions where Google is not accessible. Keep these in mind if working on captcha/verification logic. + - **Identity**: The project uses ASP.NET Core Identity for user management (configured with `.AddIdentityCore` in Program.cs). The main user entity is `HutaoUser` (likely found in `Model/Entity/Passport/`), and Identity is backed by the AppDbContext. Password rules are configured (8+ chars, etc.) and JWT Bearer authentication is used for API auth. If implementing features around authentication, ensure to leverage Identity properly (e.g., creating users via UserManager if present or directly via context). + - **Options/Configuration Classes**: Under `Option/` namespace. These classes map to configuration sections: + - For example, `AppOptions` aggregates all top-level settings under the "App" section (like JWT secret, mail secrets, etc.), and includes nested option classes like `DiscordOptions`, `GithubOptions`, `AfdianOptions`, `SmtpOptions`, etc. The configuration binding is done in Program (e.g., `appBuilder.Configuration.GetSection("App").Get()` and then added to DI). When adding new configuration settings, extend these classes and the corresponding JSON structure. + - The presence of `Afdian2Options`, `GenshinPizzaHelperOptions`, etc. indicate multiple external service configs. Ensure any new config you introduce has a corresponding entry in `AppOptions` and is documented for deployment. + - **Jobs and Scheduled Tasks**: There is a `Job/` directory (as referenced by Quartz setup). Quartz is configured in Program to schedule certain jobs (like refreshing statistics periodically, cleaning up old records, etc.). E.g., `GachaLogStatisticsRefreshJob`, `SpiralAbyssRecordCleanJob`, `RoleCombatStatisticsRefreshJob`, etc. These jobs likely correspond to classes in `Job/` or `Service/*` that implement an interface for Quartz. If changing any scheduled task, update the Quartz cron schedule in Program accordingly. When adding long-running tasks, consider using Quartz to schedule them rather than inlining in request handling. + - **Discord Integration**: Under `Discord/` namespace. This includes classes like `HutaoServerBot`, command modules, etc., using the Disqord library. The Program.cs configures the Discord bot with token and intents (coming from AppOptions->Discord config). If your changes might affect the Discord bot (e.g., a feature that should also output to Discord), look at how commands are defined (perhaps in `HutaoServerCommands` or similar) and how the bot is started. Generally, treat the Discord bot as a separate concern triggered by events, but sharing the same DI container and services. + - **Utilities and Core**: A `Core/` folder might exist for utility classes (e.g., `AsyncLock`, helper extensions, etc.). Use these utilities rather than writing new ones if they solve your problem. For instance, use the provided thread-safe lock or caching utilities if available. + - **Static Files & Swagger**: The `wwwroot/` directory contains static content served by the app. Notably, `wwwroot/css/style.css` might override Swagger UI styles (Program injects `style.css` into Swagger UI). If you modify API documentation or need to add static assets (like images or HTML), place them here and ensure they are included in publish output. + - **Root of Repository**: Contains general files like: + - `.editorconfig` – defines coding style conventions (e.g., indentation, spacing, naming rules, file headers, etc.). This works with analyzers to enforce style. Always follow these rules; for example, it may require UTF-8 file encoding, end-of-file newline, specific naming patterns (perhaps fields start with \_ etc.), documentation on public members, etc. +- **Relevant Workflows and Checks**: Prior to merging, changes should pass the implicit checks: + - Compilation success (no errors or warnings) in both Debug and Release. (Run both if your changes might affect conditional compilation symbols or configuration-specific behavior. E.g., the database migration is only invoked in Release – you can test run with `dotnet run -c Release` to ensure migrations apply without error.) + - Basic sanity tests (the application should start up without exceptions when given proper config, and core endpoints should function). + - If possible, run the application integrated with a test database to verify EF migrations and queries succeed. For instance, after changes, run `dotnet ef migrations list` to ensure EF is not throwing any model compatibility errors. + - **Style & Linting**: Check that no StyleCop warnings appear on build. Common style issues might include missing XML comments on public classes/methods, naming conventions not followed, or spacing issues. These must be resolved as the project strives for clean and uniform code. + - The repository’s GitHub Actions (if re-enabled) would fail a PR if the Docker image build fails, so essentially treat the Docker build steps as a required check. This means after your changes, the commands in the Dockerfile (restore, build, publish) should execute without issues. (For example, ensure that any new files are included in the project file so that `dotnet publish` picks them up, and that no step requires missing environment variables at build time.) +- **Dependencies and External Services**: + - The project has some dependencies that are not obvious just from the file structure. For example, it relies on **MySQL** – you must have a MySQL 8.x server and update `PrimaryMysql8`/`MetadataMysql8` connection strings accordingly to run or test the server. It also relies on **Redis** – a running Redis instance is expected (the address is configured via `RedisAddress` in AppOptions; in development you might set it to `localhost:6379` or use the docker-compose which starts one). If these services are not available, certain features (like caching or possibly some state management) won’t work properly. + - **Third-Party Integrations**: Features like OAuth login (GitHub), ReCaptcha verification, email sending (SMTP), and Discord bot require credentials/tokens to function. These are configured via AppOptions. If working on those areas, remember to provide dummy or test tokens for local testing and ensure you don’t hard-code any sensitive info. All such secrets should remain configurable and not in code. + - **Snap.Metadata**: The Metadata database is used for static game data (characters, items, etc.). The Snap.Hutao.Server uses `MetadataDbContext` to read from it. This implies the data schema for metadata is expected (likely provided by the Snap.Metadata repository). If your changes involve game data (for example, adding a new field that requires game metadata), consider whether it should be fetched from the metadata DB or added to it. Do not assume this data is in the same DB as the main app – it’s separate for read-only access. + - Keep in mind that **internationalization** might be a factor: Snap Hutao is used by a global community. The code currently mixes Chinese and English (e.g., API descriptions and messages). If you add user-facing messages or logs, include both Chinese and English or follow the existing pattern (some responses combine both languages for clarity). +- **Summaries of Key Files**: + - *Program.cs*: sets up all services, authentication (JWT Bearer with a symmetric key from `JwtRaw`), identity, Quartz jobs, and the HTTP request pipeline (including CORS, static files, Swagger at `/doc`, etc.). It also configures the Discord bot host. The `app.Run()` at the end starts the Kestrel server. When making global changes (like adding a new service or middleware), Program.cs is the place to modify. + - *Dockerfile*: uses multi-stage build (SDK then runtime image). It expects the project in `src/Snap.Hutao.Server/` and will run the published DLL. If you add new project dependencies (like additional projects or tools), update Dockerfile as needed. Generally, no changes are needed here unless you change ports or the build output. + - *docker-compose.yml*: defines how to run the server with Redis. It maps `.env` and uses host networking to reach services. If adding new dependent services (e.g., a local MySQL for testing or another cache), you might extend this file. + - *launchSettings.json*: mainly for local development convenience (HTTP ports and enabling the browser launch of Swagger). If you need to test different environment modes or ports, you can adjust here, but normally this can remain as is. + - *.editorconfig*: contains style rules (e.g., using directives placement, naming conventions such as private fields prefixed with `_`, indentation = 4 spaces, end files with newline, etc.). The coding agent should **always trust these style rules** when generating code. For example, if the editorconfig requires using `this.` prefix or specific casing, follow that to avoid style warnings. + - *Migrations/*: auto-generated EF migration classes for the AppDbContext schema. These filenames indicate the date (e.g., `20250713022540_StoreDeviceInfoInRefreshToken.cs`). If you see a migration class, it shows how the schema evolved. When altering entity models, ensure to add a new migration rather than editing these. The presence of a recent migration (e.g., mid-2025) means the schema is up-to-date as of that date. + - *Other Notable Files*: The repository might include utility scripts or tools (for example, a `tools/` directory or scripts for data processing). If present, check if they are relevant to the server’s operation. For instance, if there’s a script to update abyss data or game constants, use it rather than manual changes. Always search the repository for any existing functionality before implementing something new to avoid duplicating logic. + + + + + +- Perform a comprehensive inventory of the codebase: + - **Read all documentation files**: Start with README.md (though minimal) and any docs in this repo. Check for a CONTRIBUTING.md or comments at the top of files for hints. The Snap.Hutao ecosystem might document processes on their site, but if not found, proceed with standard conventions. + - **Search the codebase for special notes**: Look for markers like "TODO", "HACK", "FIXME", or comments in Chinese that might explain tricky parts. This can prevent introducing changes that break intended workarounds. For example, if a service method has a comment about a known issue or a temporary fix, consider that in your changes. + - **Examine build and setup scripts**: We have `Dockerfile`, `docker-compose.yml`, and `run.sh`. These indicate how the app is built and run in different scenarios. `run.sh` suggests a local way to build and run the Docker image (deleting any old container, building a new image tag, and running it). Understand that the server listens on port 80 inside the container (mapped to 8080 in run.sh and 9378 in compose) – do not hardcode ports in code; rely on configuration. + - **Inspect GitHub workflows**: Although the workflow file is disabled (named `.discard`), reading it reveals that any push/PR triggers a Docker image build. This implies that your changes should always keep the project buildable in isolation. No step should require manual intervention or an interactive prompt, etc. The agent can replicate the CI by running the same steps (checkout code, `docker build` or dotnet publish). + - **Check configuration and linting files**: Open `.editorconfig` to know style requirements (for example, it may enforce using `private readonly` fields, file headers with copyright notice, etc. – follow these exactly in new code). Also check if there’s any StyleCop settings file or analyzers config (perhaps in .csproj they might treat warnings as errors or specify analyzer rule severity). + - **Examine project files** (`.csproj`): to see included PackageReferences (which NuGet packages are used) and ProjectReferences (if any, though here it's a single project). This helps understand dependencies versions and any build props (like LangVersion, Nullable enable, etc.). For instance, ensure to target the same C# version as set in the project (likely latest by default). +- For each key file or area: + - Ask yourself if an agent making changes would need information from this file to succeed. If yes, ensure it’s documented above. For example, knowledge of `AppOptions` is crucial if adding a new config value, so we described how to add to AppOptions and configuration. Another example: understanding the standardized `Response` format is important when adding a new endpoint, so we note how responses are constructed. + - Document commands or info in detail: e.g., we provided exact dotnet CLI commands for build and run. If a command does not work out-of-the-box, we either provided prerequisites (like "install .NET 9 SDK") or alternatives (like using Docker if local setup is too complex). We explicitly noted the need to supply config to avoid the agent wasting time debugging runtime errors due to missing secrets. + - If any errors were known or likely, we have indicated them along with workarounds: for instance, the server will throw if DB is not reachable – the workaround is ensuring the DB is running and connection string is correct. We also mention how to apply migrations if one encounters an EF schema error. + - Provide any additional tips: We have instructed to trust the style rules, to use existing utilities and patterns, and to always double-check success by building and optionally running the app. +- **Minimize unnecessary exploration**: With the above information, the agent should rarely need to search the codebase aimlessly. Trust the outlined structure to navigate directly to relevant areas: + - Need to modify an API behavior? Go to the corresponding Controller and Service as described. + - Need to adjust database schema? Edit entity in Model/Entity and add a migration as explained. + - Unsure about a command or build step? Follow the provided BuildInstructions sequence (restore -> build -> run or test). + - The agent should rely on these instructions as accurate. Only if something is unclear or an operation fails despite following them should the agent search the repository or internet for clarification. +- **Final Advice**: Always trust these instructions when working on this repository. The coding agent should use the information here as the single source of truth about building, running, and modifying Snap.Hutao.Server. Only perform additional searches or use exploration tools if the information in these instructions is incomplete or proven to be incorrect in practice. By adhering to this guide, the agent will work efficiently and avoid common pitfalls (like missing config or style errors), leading to successful contributions. + + From acfa2b0c470ea34b51e5fcb8344c80a3614c4013 Mon Sep 17 00:00:00 2001 From: Masterain Date: Mon, 25 Aug 2025 16:40:06 -0700 Subject: [PATCH 2/3] Update .github/copilot-instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index dea4e84..4085e47 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,7 +1,3 @@ -Your task is to "onboard" this repository to Copilot coding agent by adding a .github/copilot-instructions.md file in the repository that contains information describing how a coding agent seeing it for the first time can work most efficiently. - -You will do this task only one time per repository and doing a good job can SIGNIFICANTLY improve the quality of the agent's work, so take your time, think carefully, and search thoroughly before writing the instructions. - - Reduce the likelihood of a coding agent pull request getting rejected by the user due to generating code that fails the continuous integration build, fails a validation pipeline, or having misbehavior. - Minimize bash command and build failures. From 8fdb51214f008fa61f1797a371ba3c566310ceb8 Mon Sep 17 00:00:00 2001 From: Masterain Date: Mon, 25 Aug 2025 16:40:45 -0700 Subject: [PATCH 3/3] Update .github/copilot-instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4085e47..409dfb9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,14 +1,3 @@ - -- Reduce the likelihood of a coding agent pull request getting rejected by the user due to generating code that fails the continuous integration build, fails a validation pipeline, or having misbehavior. -- Minimize bash command and build failures. -- Allow the agent to complete its task more quickly by minimizing the need for exploration using grep, find, str_replace_editor, and code search tools. - - - -- Instructions must be no longer than 2 pages. -- Instructions must not be task specific. - - Add the following high level details about the codebase to reduce the amount of searching the agent has to do to understand the codebase each time: