org.eu.mumulhl.ciyue/AGENTS.md

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 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.