Xime/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This workspace contains two related repositories. Xime/ is the Android input method built with Kotlin, Jetpack Compose, Gradle, CMake, and JNI. Its main app code lives in Xime/app/src/main/java, Android resources in Xime/app/src/main/res, bundled Rime/config assets in Xime/app/src/main/assets, JVM tests in Xime/app/src/test, and instrumented tests in Xime/app/src/androidTest. Shared plugin APIs are in Xime/plugin-core, sample plugins in Xime/plugins, and docs/screenshots in Xime/docs.

winxime/ is the Windows/Rust TSF implementation. Rust crates live under winxime/crates, installer WiX files under winxime/crates/winxime-server/wix, runtime resources under winxime/resources, and vendored/native dependencies under winxime/librime and winxime/rime-wubi.

Build, Test, and Development Commands

Run commands from the relevant subproject directory.

• Android build: cd Xime; .\gradlew.bat assembleDebug --quiet builds debug APKs.
• Android unit tests: cd Xime; .\gradlew.bat :app:testDebugUnitTest runs JVM tests.
• Android instrumented tests: cd Xime; .\gradlew.bat :app:connectedDebugAndroidTest requires a device or emulator.
• Docs: cd Xime; pnpm docs:dev serves VitePress docs locally.
• Windows build: cd winxime; cargo build --quiet validates the Rust workspace.
• Windows package: cd winxime; .\msi-build.ps1 creates an MSI. .\rebuild.ps1 rebuilds/registers locally; automated agents should not run it unless explicitly asked.

Coding Style & Naming Conventions

Use Kotlin/JVM 17 and Rust 2021. Follow existing package namespaces such as com.kingzcheung.xime.* and Compose naming conventions: composables and screens use PascalCase, helpers/managers use descriptive PascalCase class names, and tests end in Test. Keep Gradle Kotlin DSL files as *.gradle.kts. In Rust, keep crate names kebab-case and modules snake_case. For winxime, do not introduce unwrap() or expect().

Testing Guidelines

Add or update tests when changing input logic, settings parsers, plugins, speech, association, or IPC behavior. Android unit tests use JUnit, Mockito, coroutines-test, and Compose test utilities; instrumented tests live in androidTest. Rust changes should at minimum pass cargo build --quiet; add crate-level tests where behavior is pure and deterministic.

Commit & Pull Request Guidelines

Recent history uses Conventional Commit-style subjects such as feat(settings): ..., docs(readme): ..., and chore(config): ...; keep scopes specific. PRs should describe the user-visible change, list commands run, link related issues, and include screenshots or screen recordings for keyboard/settings UI changes.

Security & Configuration Tips

Do not commit local signing material such as Xime/app/keystore.properties; use keystore.properties.example as the template. Treat winxime/librime as read-only unless the task explicitly targets native dependency updates. Automated agents should not commit changes unless requested.