chore: add AGENTS.md

2026-02-12 19:37:10 +08:00
parent bd05737365
commit e351f4bf0b
1 changed files with 75 additions and 0 deletions
@@ -0,0 +1,75 @@
+# Ciyue Project Context
+
+## Project Overview
+
+**Ciyue** is a comprehensive dictionary application built with **Flutter**. It is designed to support **MDX/MDD** dictionary formats and offers a modern user experience with **Material You** design.
+
+### Key Features
+*   **Multi-Platform:** Android, Windows, Linux.
+*   **Dictionary Support:** MDX/MDD formats, multi-dictionary search.
+*   **AI Integration:** AI-powered translation (OpenAI, Gemini, DeepSeek, etc.) and word explanation.
+*   **Tools:** Text-to-speech (TTS), word book (bookmarks), history.
+*   **Theming:** Dynamic colors (Material You) and dark mode support.
+
+### Architecture & Tech Stack
+*   **Framework:** Flutter (Dart).
+*   **State Management:** `provider`.
+*   **Database:** `drift` (SQLite abstraction) with migration support.
+*   **Navigation:** `go_router`.
+*   **Networking:** `dio` with `talker_dio_logger` for logging.
+*   **WebView:** `flutter_inappwebview` for rendering dictionary content.
+*   **Localizations:** `flutter_localizations` with `.arb` files (managed via Weblate).
+*   **Build/CI:** GitHub Actions, `just` command runner.
+
+## Building and Running
+
+### Prerequisites
+*   **Flutter SDK:** Version constraint `>=3.4.0 <4.0.0` (CI uses `3.38.5`).
+*   **Just:** Command runner for simplified scripts.
+*   **Platform Requirements:**
+    *   **Linux:** `libgtk-3-dev`, `libgstreamer1.0-dev`, `libayatana-appindicator3-dev`, etc.
+    *   **Android:** Android SDK, Java 21 (for build).
+    *   **Windows:** Visual Studio with C++ workload.
+
+### Common Commands (via `just`)
+The project uses `justfile` to manage common development tasks.
+
+| Task | Command | Description |
+| :--- | :--- | :--- |
+| **Code Generation** | `just build_runner` | Runs `dart run build_runner build` (Essential for Drift, Freezed, etc.) |
+| **Migrations** | `just make-migrations` | Generates database migrations using Drift. |
+| **Icons** | `just icon` | Generates app launcher icons. |
+| **Count Code** | `just count-codes` | Counts lines of code excluding generated files. |
+
+### Standard Flutter Commands
+*   **Run:** `flutter run`
+*   **Analyze:** `flutter analyze`
+*   **Format:** `dart format .` (CI enforces formatting on `.dart` files)
+*   **Test:** `flutter test`
+
+### Build Artifacts
+*   **Android:** `flutter build apk --flavor full-dev`
+*   **Windows:** `flutter build windows`
+*   **Linux:** `flutter build linux`
+
+> **Note:** CI builds use `--dart-define` flags to inject build info (Hash, Timestamp, Dev mode).
+
+## Development Conventions
+
+### Code Style
+*   **Linter:** Uses `flutter_lints` with `prefer_double_quotes: true`.
+*   **Formatting:** Enforced via `dart format`.
+*   **Analysis:** `analysis_options.yaml` excludes generated files and platform folders from analysis.
+
+### Database (Drift)
+*   **Schema:** Managed in `lib/database/` and `drift_schemas/`.
+*   **Migrations:** Must be generated using `just make-migrations` when schema changes.
+
+### Translations
+*   **Source:** `.arb` files in `lib/l10n/`.
+*   **Management:** **Do NOT edit `.arb` files directly.** Use [Weblate](https://hosted.weblate.org/engage/ciyue/) for translations.
+
+### Contribution Guidelines
+*   **Commits:** Use clear, descriptive commit messages.
+*   **Testing:** Ensure `flutter test` passes before submitting.
+*   **Issues:** Search existing issues before creating new ones.