If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Tencent/QMUI_Android shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Looks unmaintained — solo project with stale commits

• Other licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Tencent/QMUI_Android repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Tencent/QMUI_Android.

What it runs against: a local clone of Tencent/QMUI_Android — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Tencent/QMUI_Android | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 579 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Tencent/QMUI_Android. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Tencent/QMUI_Android.git
#   cd QMUI_Android
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Tencent/QMUI_Android and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Tencent/QMUI_Android(\\.git)?\\b" \\
  && ok "origin remote is Tencent/QMUI_Android" \\
  || miss "origin remote is not Tencent/QMUI_Android (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "arch/src/main/java/com/qmuiteam/qmui/arch/QMUIActivity.java" \\
  && ok "arch/src/main/java/com/qmuiteam/qmui/arch/QMUIActivity.java" \\
  || miss "missing critical file: arch/src/main/java/com/qmuiteam/qmui/arch/QMUIActivity.java"
test -f "arch/src/main/java/com/qmuiteam/qmui/arch/QMUIFragment.java" \\
  && ok "arch/src/main/java/com/qmuiteam/qmui/arch/QMUIFragment.java" \\
  || miss "missing critical file: arch/src/main/java/com/qmuiteam/qmui/arch/QMUIFragment.java"
test -f "arch/src/main/java/com/qmuiteam/qmui/arch/scheme/QMUISchemeHandler.kt" \\
  && ok "arch/src/main/java/com/qmuiteam/qmui/arch/scheme/QMUISchemeHandler.kt" \\
  || miss "missing critical file: arch/src/main/java/com/qmuiteam/qmui/arch/scheme/QMUISchemeHandler.kt"
test -f "arch/src/main/java/com/qmuiteam/qmui/arch/effect/QMUIFragmentEffectRegistry.java" \\
  && ok "arch/src/main/java/com/qmuiteam/qmui/arch/effect/QMUIFragmentEffectRegistry.java" \\
  || miss "missing critical file: arch/src/main/java/com/qmuiteam/qmui/arch/effect/QMUIFragmentEffectRegistry.java"
test -f "arch/src/main/java/com/qmuiteam/qmui/arch/record/QMUILatestVisitStorage.java" \\
  && ok "arch/src/main/java/com/qmuiteam/qmui/arch/record/QMUILatestVisitStorage.java" \\
  || miss "missing critical file: arch/src/main/java/com/qmuiteam/qmui/arch/record/QMUILatestVisitStorage.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 579 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~549d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Tencent/QMUI_Android"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

QMUI Android is a comprehensive UI library that accelerates Android development by providing pre-built UI components (BottomSheet, Tab, rounded ImageView, pull-to-refresh), global style configuration system, and utility methods (device info, keyboard/statusbar management) that work across API 21+. It reduces boilerplate and enables design fidelity without writing foundation code. Modular monorepo: arch/ contains core Activity/Fragment architecture (QMUIActivity.java, QMUIFragment.java, QMUIFragmentPagerAdapter.java), arch-annotation/ defines compile-time annotations for routing (@ActivityScheme, @FragmentScheme, @LatestVisitRecord), and arch-compiler/ implements the annotation processor (SchemeProcessor, LatestVisitProcessor). All three modules are independent and can be consumed separately.

Android developers at Tencent and external teams who need to ship feature-rich Android apps quickly while maintaining consistent design. Product teams that want one global config file to control colors, navigation bars, dialogs, and lists across their entire app.

Actively maintained and production-ready. The codebase is substantial (3M+ lines of Java, 660K+ Kotlin) with proper module structure (core arch/, annotation processor arch-compiler/, annotations arch-annotation/), test coverage (androidTest directory present), and a clear philosophy documented in CONTRIBUTING.md. No signs of abandonment.

Moderate risk: this is a monolithic UI library with many interconnected components, so breaking changes in one module can cascade. The compiler processor (arch-compiler/) adds build-time complexity. No visible CI/CD pipeline config in the file list (missing .github/workflows or similar) suggests potential gaps in automated testing. Last update status and open issue count are not visible from provided data.

The repo appears to be in steady maintenance mode. The presence of Kotlin (664K lines) alongside Java (3M lines) indicates ongoing modernization. The LatestVisitRecord annotation and processor suggest recent work on visit tracking/navigation history. No specific PR/milestone data visible, but the annotation processor architecture is mature.

Clone and explore: git clone https://github.com/Tencent/QMUI_Android.git && cd QMUI_Android. The project uses Gradle (build.gradle.kts files visible). Open in Android Studio. Start with qmuidemo/ (referenced in README) to see component examples. Build with ./gradlew build (standard Gradle wrapper).

Daily commands: Standard Android project: import into Android Studio, wait for Gradle sync. Run ./gradlew build to compile all modules. To run on device: ./gradlew installDebug (requires connected device/emulator). Annotation processors will execute during compilation automatically.

• arch/src/main/java/com/qmuiteam/qmui/arch/QMUIActivity.java — Base activity class that all QMUI activities inherit from; defines lifecycle and fragment container management
• arch/src/main/java/com/qmuiteam/qmui/arch/QMUIFragment.java — Base fragment class providing lifecycle hooks and effect/scheme handling; core foundation for fragment-based navigation
• arch/src/main/java/com/qmuiteam/qmui/arch/scheme/QMUISchemeHandler.kt — Central routing/deep-linking handler that processes schemes and delegates to activities/fragments
• arch/src/main/java/com/qmuiteam/qmui/arch/effect/QMUIFragmentEffectRegistry.java — Registry for side-effect handling in fragments; enables decoupled event processing and result passing
• arch/src/main/java/com/qmuiteam/qmui/arch/record/QMUILatestVisitStorage.java — Interface for persisting and restoring navigation history; critical for last-visited-fragment recovery
• arch-annotation/src/main/java/com/qmuiteam/qmui/arch/annotation/ActivityScheme.java — Annotation for declaring activity deep-link schemes; processed at compile-time to generate routing tables
• arch-compiler/src/main/java/com/qmuiteam/qmui/arch/SchemeProcessor.java — Annotation processor that generates scheme mapping code; compile-time dependency for scheme-based navigation

Add a new routable Activity with deep-link scheme

1. Create your Activity extending QMUIActivity (arch/src/main/java/com/qmuiteam/qmui/arch/QMUIActivity.java)
2. Annotate the class with @ActivityScheme and define the scheme pattern (arch-annotation/src/main/java/com/qmuiteam/qmui/arch/annotation/ActivityScheme.java)
3. Rebuild the project; annotation processor will generate routing code in arch-compiler (arch-compiler/src/main/java/com/qmuiteam/qmui/arch/SchemeProcessor.java)
4. Launch via QMUISchemeHandler.handle() or use QMUISchemeBuilder to construct and launch the scheme (arch/src/main/java/com/qmuiteam/qmui/arch/scheme/QMUISchemeHandler.kt)

Add a new routable Fragment with scheme support

1. Create your Fragment extending QMUIFragment (arch/src/main/java/com/qmuiteam/qmui/arch/QMUIFragment.java)
2. Annotate the class with @FragmentScheme and optionally @LatestVisitRecord (arch-annotation/src/main/java/com/qmuiteam/qmui/arch/annotation/FragmentScheme.java)
3. Rebuild to generate scheme registry and latest-visit mappings (arch-compiler/src/main/java/com/qmuiteam/qmui/arch/SchemeProcessor.java)
4. Use QMUISchemeBuilder to launch or call Utils fragment transaction methods (arch/src/main/java/com/qmuiteam/qmui/arch/Utils.java)

Handle inter-fragment communication via Effects

1. In source fragment, register an effect listener via QMUIFragmentEffectRegistry (arch/src/main/java/com/qmuiteam/qmui/arch/effect/QMUIFragmentEffectRegistry.java)
2. In target fragment, trigger the effect by calling the registry's emit method with desired data (arch/src/main/java/com/qmuiteam/qmui/arch/effect/QMUIFragmentEffectHandler.java)
3. For result passing, use FragmentResultEffect which wraps Bundle data (arch/src/main/java/com/qmuiteam/qmui/arch/effect/FragmentResultEffect.java)
4. Effects are automatically cleaned up on fragment lifecycle changes (arch/src/main/java/com/qmuiteam/qmui/arch/QMUIFragment.java)

Implement custom Latest Visit storage

1. Create a class implementing QMUILatestVisitStorage interface (arch/src/main/java/com/qmuiteam/qmui/arch/record/QMUILatestVisitStorage.java)
2. Override save() and restore() methods to persist/retrieve navigation state (arch/src/main/java/com/qmuiteam/qmui/arch/record/DefaultLatestVisitStorage.java)
3. Mark fragments/activities with @LatestVisitRecord for code generation (arch-annotation/src/main/java/com/qmuiteam/qmui/arch/annotation/LatestVisitRecord.java)
4. Inject your custom storage via QMUILatestVisit

Annotation processors are non-obvious: if you add new @ActivityScheme or @FragmentScheme annotations, you must rebuild the project (not just re-run) for SchemeProcessor to generate navigation code. Proguard rules (arch/proguard-rules.pro) must be checked when adding new components to avoid obfuscation breaking reflection-based code. The global configuration system mentioned in README is not visible in this file list—it likely lives in a separate qmui-core module not shown here, so modifying styles requires knowledge of that module. Android instrumented tests (src/androidTest/) require a running device/emulator.

• Annotation Processing (Compile-time Code Generation) — QMUI's routing and navigation system (@ActivityScheme, @FragmentScheme) relies on annotation processors to generate boilerplate code at compile-time rather than runtime; understanding this pattern is essential to extending the framework.
• Fragment Lifecycle & State Management — QMUIFragment.java wraps Android's Fragment lifecycle with additional hooks for QMUI-specific behavior; misunderstanding lifecycle can cause memory leaks and UI state loss in QMUI apps.
• Adapter Pattern for ViewPager — QMUIFragmentPagerAdapter extends the standard FragmentPagerAdapter with QMUI optimizations for tab/carousel UIs; knowing the adapter pattern is needed to customize pagination behavior.
• Global Configuration / Theme System — QMUI's core feature is a single config file controlling all colors, dialogs, lists, and navigation bars globally; understanding how config is loaded and applied is essential for theming and customization.
• Device & Runtime Information API — QMUI reads android.os.Build fields and system settings (fullscreen gesture detection) to adapt UI for different devices; knowing what device info is available helps choose the right component for hardware capabilities.
• Proguard/R8 Code Obfuscation Rules — arch/proguard-rules.pro prevents reflection-based QMUI code from being obfuscated during release builds; misconfiguring this can break routing and component discovery.

• alibaba/Tangram-Android — Alternative modular UI framework with card-based layout system; solves similar 'reduce boilerplate' problem but with data-driven card/component paradigm instead of Activity/Fragment inheritance.
• airbnb/epoxy — RecyclerView DSL and modeling library that shares QMUI's goal of reducing layout boilerplate; complements QMUI for list-based UIs.
• ReactiveX/RxAndroid — Reactive extensions library that many QMUI users combine with QMUIActivity/QMUIFragment for lifecycle-aware event handling and async operations.
• google/android-architecture-components — Official Architecture Components (LiveData, ViewModel, Room) that are commonly paired with QMUI base classes for state management and persistence.
• Tencent/QMUI_iOS — Sister project providing the same UI philosophy and components for iOS; teams building cross-platform apps use both QMUI_Android and QMUI_iOS in parallel.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add instrumented tests for QMUISwipeBackActivityManager and SwipeBackLayout gesture handling

The arch module contains SwipeBackLayout.java and QMUISwipeBackActivityManager.java which handle critical gesture recognition and activity stack management, but arch/src/androidTest only has a placeholder ExampleInstrumentedTest.java. Adding comprehensive instrumented tests would catch regressions in swipe-back behavior across different Android versions and device configurations.

• [ ] Create arch/src/androidTest/java/com/qmuiteam/qmui/arch/SwipeBackLayoutTest.java with tests for touch event handling, velocity calculations, and visual state transitions
• [ ] Create arch/src/androidTest/java/com/qmuiteam/qmui/arch/QMUISwipeBackActivityManagerTest.java with tests for activity stack management, multiple activity scenarios, and edge cases
• [ ] Add assertion helpers for SwipeBackgroundView.java rendering state verification
• [ ] Document expected swipe-back behavior in arch/src/androidTest as regression test reference

Add annotation processor integration tests for SchemeProcessor and LatestVisitProcessor

The arch-compiler module contains SchemeProcessor.java and LatestVisitProcessor.java which perform compile-time code generation via annotations (ActivityScheme, FragmentScheme, LatestVisitRecord), but there are no visible integration tests verifying the generated code correctness. This is critical since broken annotation processing silently fails during compilation.

• [ ] Create arch-compiler/src/test/java/com/qmuiteam/qmui/arch/SchemeProcessorTest.java using compile-testing library to verify ActivityScheme and FragmentScheme annotations generate correct routing code
• [ ] Create arch-compiler/src/test/java/com/qmuiteam/qmui/arch/LatestVisitProcessorTest.java to verify LatestVisitRecord annotation generates correct storage implementation in record/ package
• [ ] Add test fixtures in arch-compiler/src/test/resources with sample annotated classes
• [ ] Verify generated code in arch/src/main matches processor output expectations

Add comprehensive documentation for QMUIFragmentEffectRegistry and effect handling system

The arch/src/main/java/com/qmuiteam/qmui/arch/effect/ directory contains a sophisticated effect system (QMUIFragmentEffectRegistry, QMUIFragmentEffectHandler, FragmentResultEffect, MapEffect) that appears undocumented. Contributors cannot understand how to properly implement custom effects or integrate with the system without inline code examination.

• [ ] Create docs/EFFECT_SYSTEM.md explaining the Effect interface, handler registration pattern, and lifecycle
• [ ] Document QMUIFragmentResultEffectHandler.java with code examples for passing data between fragments via effects
• [ ] Document QMUIFragmentMapEffectHandler.java with examples for coordinating multiple fragment state changes
• [ ] Add inline JavaDoc to QMUIFragmentEffectRegistry.java explaining the registration and dispatch mechanism
• [ ] Create a code example in qmuidemo showing custom Effect implementation using the three built-in handler types

• Add unit tests for BaseProcessor.java and SchemeProcessor.java in arch-compiler/src/test/ to verify annotation processing logic (test infrastructure exists but no test files visible).
• Document the annotation processor workflow: create a PROCESSOR_GUIDE.md explaining how @ActivityScheme flows through SchemeProcessor to generate navigation code, with code examples from the actual processor.
• Extend QMUIFragmentPagerAdapter with support for lazy-loading fragments (currently no visible LazyFragment lifecycle in QMUIFragment.java); add a LazyLoadingFragmentPagerAdapter subclass with onFragmentVisible/onFragmentHidden callbacks.

QMUI_Android is a UI library with a moderate security posture. The primary concerns are around the advanced scheme-based navigation system which could be vulnerable to intent injection attacks if not properly validated, and annotation processor code generation which requires careful validation. The codebase lacks visibility into dependency versions and detailed ProGuard configuration. No obvious hardcoded credentials, SQL injection risks, or critical misconfigurations were detected in the visible file structure. The framework's device information collection should be properly documented for user privacy compliance. Overall, the library appears well-structured but would benefit from enhanced input validation in the navigation and scheme handling components.

• Medium · Potential Intent-based Navigation Vulnerability — arch/src/main/java/com/qmuiteam/qmui/arch/scheme/. The codebase contains an extensive scheme-based navigation system (QMUISchemeHandler, QMUISchemeBuilder, etc.) that processes URL schemes and intents. Without proper validation of scheme sources and parameters, this could be exploited for intent injection attacks, allowing malicious apps to trigger unintended navigation or pass arbitrary data to activities/fragments. Fix: Implement strict validation of all scheme sources and parameters. Verify intent origins, sanitize all incoming scheme data, use allowlists for valid schemes, and validate all bundle parameters before processing.
• Medium · Annotation Processor Code Generation Risks — arch-compiler/src/main/java/com/qmuiteam/qmui/arch/. The arch-compiler module uses annotation processing to generate code (SchemeProcessor, LatestVisitProcessor). Generated code could potentially contain security vulnerabilities if processor logic doesn't properly validate or sanitize inputs during code generation, potentially leading to injection vulnerabilities in generated classes. Fix: Review annotation processors for proper input validation. Ensure generated code properly escapes all dynamic content, uses proper security patterns, and follows safe code generation practices. Add unit tests for processor edge cases.
• Medium · Swipe-Back Feature Information Disclosure — arch/src/main/java/com/qmuiteam/qmui/arch/SwipeBackLayout.java, SwipeBackgroundView.java, QMUISwipeBackActivityManager.java. The SwipeBackLayout and QMUISwipeBackActivityManager classes implement gesture-based activity navigation. This could potentially allow users to unintentionally reveal sensitive UI elements or activity states during swipe gestures, especially in multi-user or shared device scenarios. Fix: Implement proper state management to prevent sensitive data display during swipe animations. Consider adding privacy mode options that disable gesture navigation, and ensure background activities don't expose sensitive information during transitions.
• Low · Missing Dependency Version Specification — build.gradle.kts files (all modules). The provided dependency file content is empty. Without explicit dependency versions pinned in build files, the project may be vulnerable to transitive dependency attacks or unexpected breaking changes from dependency updates. Fix: Explicitly specify and lock all dependency versions. Use dependency constraints and verification to ensure reproducible builds. Regularly audit and update dependencies to patch known vulnerabilities.
• Low · ProGuard Configuration Exposure — arch/proguard-rules.pro. The arch/proguard-rules.pro file is present but content not visible. Improper ProGuard configuration could fail to obfuscate sensitive code patterns, method names, or class hierarchies, potentially aiding reverse engineering. Fix: Review and strengthen ProGuard rules. Ensure all sensitive classes, methods, and string resources are properly obfuscated. Use -printconfiguration to verify effective rules and regularly test against reverse engineering tools.
• Low · Device Information Collection — README.md (Privacy & Security section), arch/src/main/java/com/qmuiteam/qmui/arch/Utils.java (likely). Per the README, the framework reads android.os.Build fields (brand, model, etc.) for device differentiation. While legitimate, this data collection should be transparent to users and comply with privacy regulations. Fix: Document all device information collection clearly in privacy policy. Implement user consent for analytics. Use Android's Privacy Dashboard features and ensure compliance with GDPR/CCPA regulations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.