Skip to content

AGENTS.md

Latest commit

 

History

History
93 lines (70 loc) · 5.29 KB

AGENTS.md

File metadata and controls

93 lines (70 loc) · 5.29 KB
Raw

Repository Guidelines

本文档面向贡献者，概述本仓库的模块结构、开发流程，便于快速上手并保持一致的协作质量。

Build, Test, and Development Commands

使用 Android Studio 或命令行 Gradle：

./gradlew assembleDebug          # 构建 Debug APK
./gradlew test                   # 运行所有模块的 JVM 单元测试
./gradlew connectedDebugAndroidTest  # 运行设备/模拟器上的仪器测试
./gradlew lint                   # 运行 Android Lint

构建应用不再需要在 app/ 下提供 google-services.json。 本 fork 已移除 Web 服务和 web-ui/，构建不再需要本地 pnpm。

Coding Style & Naming Conventions

本仓库使用 .editorconfig 统一格式：

  • Kotlin/Gradle 脚本：4 空格缩进，最大行长 120。
  • XML/JSON：2 空格缩进。
  • Markdown/YAML：2 空格缩进，允许尾随空格（用于对齐）。

命名习惯：模块名为小写目录（如 ai/、speech/），Kotlin 类遵循 PascalCase，测试类以 *Test 结尾。

Testing Guidelines

测试框架以 JUnit/AndroidX Test 为主。未设定强制覆盖率门槛，但新逻辑应配套新增/更新测试。测试文件命名建议：

  • 单元测试：FooTest.kt
  • 仪器测试：FooInstrumentedTest.kt 或 *Test.kt

Module Structure

  • app: Main application module with UI, ViewModels, and core logic
  • ai: AI SDK abstraction layer for different providers (OpenAI, Google, Anthropic)
  • common: Common utilities and extensions
  • document: Document parsing module for handling PDF, DOCX, PPTX, and EPUB files
  • highlight: Code syntax highlighting implementation
  • material3: Material color utility extensions used by the app UI
  • search: Search functionality SDK for multiple providers (Exa, Tavily, Zhipu, Bing, Brave, SearXNG, and others)
  • speech: Speech module for TTS and ASR implementations
  • workspace: Sandboxed per-workspace file system and shell execution environment exposed to the AI as tools.

Concepts

  • Assistant: An assistant configuration with system prompts, model parameters, and conversation isolation. Each assistant maintains its own settings including temperature, context size, custom headers, tools, memory options, regex transformations, and prompt injections (mode/lorebook). Assistants provide isolated chat environments with specific behaviors and capabilities. (app/src/main/java/me/rerere/rikkahub/data/model/Assistant.kt)

  • Conversation: A persistent conversation thread between the user and an assistant. Each conversation maintains a list of MessageNodes in a tree structure to support message branching, along with metadata like title, creation time, update time, pin status, chat suggestions, optional conversation-level system prompt, and prompt injection bindings. ( app/src/main/java/me/rerere/rikkahub/data/model/Conversation.kt)

  • UIMessage: A platform-agnostic message abstraction that encapsulates chat messages with different types of content parts (text, images, documents, reasoning, tool calls/results, etc.). Each message has a role (USER, ASSISTANT, SYSTEM, TOOL), creation timestamp, model ID, token usage information, and optional annotations. UIMessages support streaming updates through chunk merging. (ai/src/main/java/me/rerere/ai/ui/Message.kt)

  • MessageNode: A container holding one or more UIMessages to implement message branching functionality. Each node maintains a list of alternative messages and tracks which message is currently selected (selectIndex). This enables users to regenerate responses and switch between different conversation branches, creating a tree-like conversation structure. (app/src/main/java/me/rerere/rikkahub/data/model/Conversation.kt)

  • Message Transformer: A pipeline mechanism for transforming messages before sending to AI providers ( InputMessageTransformer) or after receiving responses (OutputMessageTransformer). Transformers can modify message content, add metadata, apply templates, handle special tags, convert formats, and perform OCR. Common transformers include:

    • TemplateTransformer: Apply Pebble templates to user messages with variables like time/date
    • ThinkTagTransformer: Extract <think> tags and convert to reasoning parts
    • RegexOutputTransformer: Apply regex replacements to assistant responses
    • DocumentAsPromptTransformer: Convert document attachments to text prompts
    • Base64ImageToLocalFileTransformer: Convert base64 images to local file references
    • OcrTransformer: Perform OCR on images to extract text

    Output transformers support visualTransform() for UI display during streaming and onGenerationFinish() for final processing after generation completes. (app/src/main/java/me/rerere/rikkahub/data/ai/transformers/Transformer.kt)

Internationalization

  • String resources are usually located in app/src/main/res/values*/strings.xml; feature modules such as search may also maintain their own values*/strings.xml
  • Use stringResource(R.string.key_name) in Compose
  • Page-specific strings should use page prefix (e.g., setting_page_)
  • If the user does not explicitly request localization, prioritize implementing functionality without considering localization. (e.g Text("Hello world"))
  • For locale-tui operations, use the locale-tui-localization skill.