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/lingochamp/okdownload 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.

GO — Healthy across all four use cases

• 7 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Concentrated ownership — top contributor handles 71% of recent commits

_{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 lingochamp/okdownload repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/lingochamp/okdownload.

What it runs against: a local clone of lingochamp/okdownload — 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 lingochamp/okdownload | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 1311 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of lingochamp/okdownload. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/lingochamp/okdownload.git
#   cd okdownload
#
# 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 lingochamp/okdownload and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1311 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1281d)"
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/lingochamp/okdownload"
  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).

OkDownload is a production-grade Android download engine that handles reliable, resumable, and parallel multi-threaded file downloads with granular progress tracking per block. It extends FileDownloader's architecture with improvements to stability, flexibility, and performance, supporting single downloads, download queues, and batch operations with persistent database state management. Multi-module Gradle project: core download engine lives in the main source tree (Java-heavy), with benchmark/ module for performance testing (Kotlin-based MainActivity.kt), and sample apps demonstrating use cases. Architecture separates HTTP transport layer (leveraging OkHttp presumably), task state management via persistent database, and callback-driven progress reporting. CI configuration in .gitlab-ci.yml and .travis.yml suggests dual-pipeline maturity.

Android app developers building features that require robust file downloading—from simple single-file downloads to complex queue management scenarios. Particularly valuable for apps needing resumable downloads, bandwidth control, and detailed progress callbacks at block-level granularity rather than just file-level.

Production-ready and actively maintained. The README explicitly recommends following the latest release version (not legacy 1.0.0/2.0.0) due to continuous GitHub-flow development. CI/CD is configured via .gitlab-ci.yml and .travis.yml, codecov integration is active, and the project uses Semantic Versioning with detailed CHANGELOG.md. Last visible activity shows organized module structure and recent Kotlin migration (116K Kotlin vs 1.1M Java, indicating modern tooling adoption).

Low to moderate risk for new projects. The codebase is 1.2M+ LOC with established patterns, but the README's emphasis on 'always use latest version' suggests historical breaking changes. Single-maintainer heritage (Jacksgong) visible in config files could pose maintenance risk if abandoned. Dependency surface area is typical for Android (support libs, test frameworks) but explicit version pinning in root project config should be verified before production use.

The project shows active Kotlin adoption (116K Kotlin LOC) with benchmark module using Kotlin, indicating modernization efforts. The benchmark app with Material Design components (ic_dashboard_black_24dp.xml, activity_main.xml) suggests ongoing performance validation and UI framework updates. No specific PR/issue data visible, but the organized copyright config and linting setup (lint.xml, proguard rules) indicate active quality gates.

git clone https://github.com/lingochamp/okdownload.git
cd okdownload
./gradlew build
./gradlew installDebug  # Deploy benchmark app to connected device

The project uses Gradle with rootProject.ext configuration (check build.gradle root for version properties). Kotlin compilation is enabled via kotlin-android and kotlin-android-extensions plugins.

Daily commands: For development: ./gradlew build compiles the library. For testing the benchmark app: ./gradlew benchmark:installDebug then manually launch on device, or ./gradlew benchmark:connectedAndroidTest for instrumented tests. The benchmark module uses testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner" for on-device testing.

• README.md: Primary documentation entry point with links to wiki for simple and advanced use guidelines, debugging, and import instructions—essential for understanding the public API surface.
• benchmark/src/main/java/cn/dreamtobe/okdownload/benchmark/MainActivity.kt: Concrete Kotlin reference implementation demonstrating all major features (single download, queue, progress tracking, content URIs, notifications) with Material Design UI.
• CHANGELOG.md: Critical for understanding versioning stability concerns and breaking changes, explicitly recommended in README as the version decision guide.
• [.gitlab-ci.yml and .travis.yml](https://github.com/lingochamp/okdownload/blob/master/.gitlab-ci.yml and .travis.yml): Defines automated build, test, and release pipelines; shows testing scope and deployment targets (jcenter, mavenCentral, Sonatype snapshots).
• .idea/codeStyles/Project.xml: Enforces code formatting rules for all contributors; essential to match before submitting PRs to avoid CI/linting failures.
• benchmark/build.gradle: Shows dependency declarations, SDK versions, and test configuration; template for adding new modules or updating library versions.
• [art/.gif and art/.png](https://github.com/lingochamp/okdownload/blob/master/art/.gif and art/.png): Visual documentation of all major feature flows (single download, queue, block-level progress, notifications)—quick reference for feature discovery.

For new download features: Start in the core library source (main module, Java packages cn.dreamtobe.okdownload.*), focusing on task enqueuing and HTTP layer. For UI/sample changes: Edit benchmark/src/main/java/cn/dreamtobe/okdownload/benchmark/MainActivity.kt. For documentation: Update README.md, README-zh.md, or contribute to /wiki/ (linked but not in repo). For styling/linting: Modify .idea/codeStyles/Project.xml and benchmark/lint.xml. For CI changes: Edit .gitlab-ci.yml or .travis.yml.

Kotlin-Java interop: The library is 90% Java but benchmark is pure Kotlin; ensure your IDE is configured for both (check .idea/compiler.xml settings). Version pinning: Dependencies use rootProject.ext.* variables (compileSdkVersion, sourceCompatibility, etc.) defined in root build.gradle—modifying a single source won't work without updating there. Test instrumentation: The project uses Android instrumentation tests (testInstrumentationRunner), which require a connected device or emulator; JUnit tests alone won't validate download behavior. ProGuard/minification: benchmark/proguard-rules.pro exists but minifyEnabled false in the example—production apps must test with minification enabled. SQLite persistence: The download state machine relies on database transactions; network interruptions during DB writes could corrupt task state (look for transaction guards in core code). Copyright headers: .idea/copyright/apache2.xml enforces Apache 2.0 headers on new files; files without headers may fail CI checks.

• Resumable/Range-based HTTP Downloads — OkDownload's core feature—allows pausing and resuming downloads by requesting specific byte ranges (HTTP 206 Partial Content); understanding this is essential to grasp why the library persists byte offsets and block boundaries.
• Parallel/Multi-threaded Downloading — The library splits files into blocks downloaded in parallel to increase throughput; understanding thread pools, synchronization, and race conditions is critical when debugging concurrent download failures.
• Callback/Listener Pattern (Progress Reporting) — OkDownload reports progress at block-level granularity via listeners (visible in /art/listener.png); knowing how to implement and chain callbacks is essential for integrating with UI frameworks.
• Task State Machine (Download Lifecycle) — Downloads transition through states (pending → running → paused → finished/failed); understanding the valid transitions prevents concurrent modification bugs and ensures proper cleanup on cancellation.
• SQLite Transactions & ACID Compliance — OkDownload persists download task state in SQLite; network interruptions or crashes mid-write can corrupt the database; understanding transaction isolation prevents tasks from getting stuck in invalid states.
• Content Provider URIs (Android) — The benchmark app demonstrates downloads to Content URIs (/art/content-uri.gif); necessary for saving to external storage, DocumentProvider, or cloud storage without raw file paths.
• Dependency Injection (Component Swapping) — Advanced guidelines mention injecting custom components (HTTP client, database, thread pool strategy); the architecture is designed to be testable via DI—essential for extending or mocking the library.

• lingochamp/FileDownloader — The predecessor to OkDownload; understanding its design and limitations (mentioned as 'FileDownloader2' in README) helps contextualize why OkDownload exists.
• square/okhttp — OkDownload's HTTP transport layer likely depends on OkHttp; essential for understanding request/response handling and SSL/TLS configuration in downloads.
• square/retrofit — Alternative HTTP client library for Android; often confused with download solutions but optimized for REST APIs rather than large file transfers.
• greenrobot/greenDAO — ORM library commonly used for SQLite persistence in Android; relevant since OkDownload maintains task state in a database (inferred from 'remit database delay milliseconds' config mention).
• google/ExoPlayer — While focused on media streaming, ExoPlayer's segmented download and retry logic patterns overlap with OkDownload's multi-threaded resumable downloads.

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 benchmark module to root build.gradle dependencies and create performance regression tests

The benchmark module exists but isn't integrated into the main build system or CI pipeline. This is valuable because a download engine's performance is critical, and there are no automated performance benchmarks in the CI workflow (.travis.yml, .gitlab-ci.yml). Adding proper benchmark integration would help catch performance regressions and validate the 'Fast and Powerful' claim.

• [ ] Add benchmark module as a dependency in root build.gradle with proper configuration inheritance
• [ ] Create a benchmarkTest task in the benchmark/build.gradle that runs with specific performance thresholds
• [ ] Update .travis.yml and .gitlab-ci.yml to execute benchmark tests on each commit
• [ ] Add performance baseline metrics to CHANGELOG.md for each release
• [ ] Document benchmark results in a BENCHMARKS.md file with instructions for local benchmark runs

Replace deprecated Android Support libraries with AndroidX in benchmark module

The benchmark/build.gradle still uses deprecated com.android.support:appcompat-v7, design, and constraint-layout dependencies. AndroidX migration is complete in the Android ecosystem, and keeping legacy libraries creates compatibility issues, increases APK size, and violates modern Android best practices. This is a concrete, high-impact refactoring.

• [ ] Update benchmark/build.gradle to replace dep.supportV7, dep.supportDesign, and dep.supportConstraintLayout with androidx.appcompat:appcompat, androidx.design:design, and androidx.constraintlayout:constraintlayout equivalents
• [ ] Update benchmark/src/main/AndroidManifest.xml to remove any support library references
• [ ] Replace testInstrumentationRunner 'android.support.test.runner.AndroidJUnitRunner' with 'androidx.test.runner.AndroidJUnitRunner'
• [ ] Update benchmark/src/main/java import statements from android.support.* to androidx.*
• [ ] Test the benchmark app on multiple Android versions (API 21+) to ensure compatibility

Add unit tests for benchmark module's MainActivity and create integration tests with okdownload core

The benchmark/src/main/java/cn/dreamtobe/okdownload/benchmark/MainActivity.kt exists but has no corresponding test files. Given that this is a download engine repo, the benchmark module should validate that it correctly measures download performance using the core okdownload library. This is valuable for ensuring benchmark reliability and catching regressions in the API contract.

• [ ] Create benchmark/src/test/java/cn/dreamtobe/okdownload/benchmark/MainActivityTest.kt with unit tests for UI initialization and state management
• [ ] Create benchmark/src/androidTest/java/cn/dreamtobe/okdownload/benchmark/DownloadBenchmarkInstrumentationTest.kt to test actual download scenarios against okdownload core
• [ ] Add test dependencies to benchmark/build.gradle (AndroidX Test, JUnit4, Espresso)
• [ ] Implement tests that verify download progress callbacks, completion handlers, and error scenarios are properly measured
• [ ] Add test execution to CI pipelines in .travis.yml and .gitlab-ci.yml

• Add unit test coverage for benchmark/src/main/java/cn/dreamtobe/okdownload/benchmark/MainActivity.kt lifecycle callbacks (onCreate, onPause, onResume). Currently no test files exist for the benchmark module.: Kotlin code in the repo lacks test coverage, and the benchmark app is the reference implementation—covering it ensures feature demonstrations don't regress.
• Write a troubleshooting guide documenting the 'Why Choose OkDownload' wiki link (linked in README but not mirrored in repo docs). Include comparison table vs alternatives (Retrofit, DownloadManager, FileDownloader).: New users can't evaluate the library without navigating to external wiki; a local TROUBLESHOOTING.md or COMPARISON.md would reduce onboarding friction.
• Add Gradle property documentation: create a gradle.properties.example file documenting all rootProject.ext.* variables (compileSdkVersion, minSdkVersion, sourceCompatibility, dep.* library versions) with their current values and rationale.: Contributors cloning the repo have no visibility into which SDK versions/library versions are pinned; this causes local build failures or accidental version downgrades in PRs.

The OkDownload benchmark module shows moderate security posture. Main concerns include outdated Android Support libraries (should migrate to AndroidX), disabled code obfuscation in release builds, and committed IDE configuration files. The lack of integrated security scanning in CI/CD pipelines is also notable. The codebase itself appears to follow reasonable practices with no obvious injection vulnerabilities or hardcoded secrets visible in the file structure provided. Recommendations focus on modernizing dependencies, enabling code protection mechanisms, and implementing automated security scanning.

• Medium · Outdated Build Tools and SDK Configuration — benchmark/build.gradle, gradle/dependencies.gradle. The build.gradle file references potentially outdated support libraries (supportV7, supportDesign) and uses 'android.support.test.runner.AndroidJUnitRunner' which is deprecated. Android Support libraries have been superseded by AndroidX. This may expose the application to known vulnerabilities in older library versions. Fix: Migrate from Android Support libraries to AndroidX libraries. Update to 'androidx.test.runner.AndroidJUnitRunner' and use latest stable versions of all dependencies.
• Low · Missing ProGuard Configuration for Release Builds — benchmark/build.gradle. The benchmark module has minifyEnabled set to false in release builds. This means the application code is not obfuscated, making it easier for attackers to reverse-engineer the application logic and identify potential vulnerabilities. Fix: Enable minifyEnabled for release builds and ensure ProGuard/R8 rules are properly configured to obfuscate code while maintaining functionality. Review 'proguard-rules.pro' for completeness.
• Low · Potential Exposure of IDE Configuration Files — .idea/ directory contents. .idea/ directory and other IDE configuration files are committed to the repository. While not directly a security vulnerability, this can expose development environment details and potentially sensitive paths or configurations. Fix: Add IDE configuration files to .gitignore: '.idea/', '*.iml', '.gradle/', 'build/', and other IDE-specific directories.
• Low · Missing Security Testing Configuration — .gitlab-ci.yml, .travis.yml. The codebase lacks explicit security scanning and testing configurations. No SAST (Static Application Security Testing) tools are configured in the CI/CD pipeline. Fix: Integrate security scanning tools such as: dependency-check for vulnerable dependencies, lint security rules for Android, and OWASP guidelines enforcement in CI/CD pipelines.
• Low · Incomplete Dependency Version Management — benchmark/build.gradle, gradle/dependencies.gradle. Dependencies are imported via 'dep' variable from gradle/dependencies.gradle, but the actual version specifications are not visible in the provided file structure. This makes it difficult to assess if known vulnerable versions are in use. Fix: Maintain a comprehensive dependency audit. Regularly check for known vulnerabilities using 'gradle dependencyCheckAnalyze' or similar tools. Document all dependency versions and their security status.

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.