docs(guidelines): 添加项目开发指南和CLAUDE工作指导文档

- 创建 AGENTS.md 包含仓库结构、构建命令、编码规范和提交指南
- 添加 CLAUDE.md 为AI助手提供项目架构、构建工具链和库设计说明
- 文档涵盖Gradle模块组织、版本管理、发布配置和测试指导原则
- 详细说明BaseRecyclerViewAdapterHelper4库的核心组件和API设计模式
- 提供数据模式、适配器变体、组合模式和加载状态管理的技术细节

Author: limuyang2

AGENTS.md

@@ -0,0 +1,37 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This is an Android Gradle project with Kotlin DSL build files. `settings.gradle` includes two modules:
+
+- `library/`: the reusable RecyclerView adapter library published as `io.github.cymchad:BaseRecyclerViewAdapterHelper4`.
+- `app/`: the sample Android application demonstrating library usage.
+
+Main source lives under `app/src/main/java` and `library/src/main/java`. Android resources are under each module's `src/main/res`. Keep public library APIs in the `com.chad.library.adapter4` namespace and sample-only code in `com.chad.baserecyclerviewadapterhelper`.
+
+## Build, Test, and Development Commands
+Use the Gradle wrapper from the repository root:
+
+- `./gradlew assembleDebug`: builds debug artifacts for all modules.
+- `./gradlew :app:assembleDebug`: builds the sample app.
+- `./gradlew :library:assembleRelease`: builds the release AAR for the library.
+- `./gradlew clean`: removes generated build output.
+- `./gradlew test`: runs JVM unit tests when test sources exist.
+- `./gradlew connectedAndroidTest`: runs instrumentation tests on a connected device or emulator when present.
+
+The project targets Java 17 via Gradle toolchains. Dependencies and plugin versions are centralized in `gradle/libs.versions.toml`.
+
+## Coding Style & Naming Conventions
+Use Kotlin for new code unless working in an existing Java file. Follow Android/Kotlin conventions: 4-space indentation, `UpperCamelCase` classes, `lowerCamelCase` functions and properties, and package names matching module namespaces. Prefer clear adapter, view holder, and load-state names that match existing patterns such as `BaseQuickAdapter`, `QuickViewHolder`, and `DefaultTrailingLoadStateAdapter`.
+
+Keep resources lowercase with underscores, for example `brvah_trailing_load_more.xml`. Avoid unrelated formatting churn in mixed Java/Kotlin files.
+
+## Testing Guidelines
+No test directories are currently checked in. Add unit tests under `module/src/test` and Android tests under `module/src/androidTest` when changing behavior. Name tests after the unit under test and expected behavior, for example `BaseDifferAdapterTest`. Run `./gradlew test` before submitting logic changes, and use `connectedAndroidTest` for RecyclerView or UI behavior that needs Android runtime coverage.
+
+## Commit & Pull Request Guidelines
+Recent history uses Conventional Commit-style messages, often scoped, such as `fix(adapter): ...`, `refactor(loadState): ...`, and `docs(README): ...`. Keep commits focused and use scopes that match affected areas.
+
+Pull requests should include a concise description, linked issues when applicable, test results, and screenshots or recordings for sample app UI changes. For library API changes, document migration notes and update README or wiki references when needed.
+
+## Security & Configuration Tips
+Do not commit `local.properties`, signing keys, Sonatype credentials, or generated publishing output. Publishing credentials are loaded from local properties or environment-specific configuration.

CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+BRVAH (BaseRecyclerViewAdapterHelper) — a RecyclerView Adapter helper library for Android (current major version: **v4.x**, published as `io.github.cymchad:BaseRecyclerViewAdapterHelper4`). v4 was rewritten to be fully compatible with `ConcatAdapter`, to split functionality into modules, and to support flexible multi-type layouts plus strengthened up/down load-more.
+
+The repository contains **two Gradle modules**:
+- `:library` — the published library (namespace `com.chad.library.adapter4`). This is the artifact.
+- `:app` — the demo application that exercises every library feature (`com.chad.baserecyclerviewadapterhelper`). `demo/` holds a prebuilt APK only.
+
+## Build & Toolchain
+
+Gradle with Kotlin DSL (`settings.gradle`, `build.gradle.kts`, `gradle/libs.versions.toml`). Toolchain and SDK versions are pinned per module:
+
+- **JDK 17** toolchain for both modules (CI uses temurin 17).
+- `:library` — `compileSdk = 35`, `minSdk = 19`, depends only on `androidx.annotation`, `androidx.recyclerview`, and `compileOnly` `databinding-runtime`. No AndroidX app deps — it is a pure library.
+- `:app` — `compileSdk/targetSdk = 36`, `minSdk = 23`, uses viewBinding + dataBinding, Moshi (KSP codegen). All third-party demo deps live here, never in `:library`.
+
+Common commands (run from repo root):
+
+```bash
+./gradlew :library:compileDebugKotlin        # what CI runs — fastest library sanity check
+./gradlew :library:assembleRelease           # build the AAR
+./gradlew :app:assembleDebug                 # build the demo APK
+./gradlew clean
+```
+
+There is **no test source set** — there are no unit or instrumented tests in either module. Verify changes by compiling and/or running the demo app.
+
+### Publishing / versioning
+- Library version lives in `library/build.gradle.kts` as `val versionName` (currently `4.4.1`). The `:app` `versionName` (`4.3.2`) is independent — update them separately.
+- Publishing is configured with `maven-publish` + `signing`. Credentials/signing keys are read from `local.properties` (`signing.keyId`, `signing.password`, `signing.secretKeyRingFile`, `ossrhUsername`, `ossrhPassword`). The active publish repository is the local `$rootDir/Repo` folder (Maven Central upload block is commented out).
+- ProGuard consumer rules ship via `consumerProguardFiles("proguard-rules.pro")` in `:library`, so consumers auto-import them; the file itself is mostly a placeholder.
+
+## Library architecture
+
+Everything is under `com.chad.library.adapter4`. The design centers on one abstract base plus adapter composition via `ConcatAdapter`.
+
+### `BaseQuickAdapter<T, VH>` (the base class)
+`BaseQuickAdapter.kt` is the foundation for all adapters. Two things define it:
+
+1. **Two data modes**, decided at construction by whether a `DiffUtil.ItemCallback<T>`/`AsyncDifferConfig<T>` is supplied:
+   - *Diff mode* — backs `items` with `AsyncListDiffer` (async diffing, no jank). Mutating ops (`submitList`, `add`, `set`, `removeAt`, `swap`, `move`, …) rebuild a mutable list and re-submit.
+   - *Plain mode* (`mDiffer == null`) — backs `items` with a plain `List<T>` and calls the corresponding `notifyItem*` directly.
+   Every mutating method branches on `mDiffer == null`; when touching one, update **both** branches.
+
+2. **Sealed RecyclerView.Adapter overrides.** `getItemCount()`, `getItemViewType()`, `onCreateViewHolder()`, and `onBindViewHolder()` are `final`. Subclasses implement the **protected** variants instead (`onCreateViewHolder(context, parent, viewType)`, `onBindViewHolder(holder, position, item[, payloads])`, `getItemCount(items)`, `getItemViewType(position, list)`). Do not try to override the final ones.
+
+Other base-class responsibilities: optional **state/empty view** (`isStateViewEnable` + `stateView`, shown when `items` is empty via `StateLayoutVH`), item **animations** (`animationEnable` + `itemAnimation`/`setItemAnimation(AnimationType)`), and click listeners (item / item-child by view id, stored in a `SparseArray`). `items` setter is `@Deprecated` at **ERROR level** — use `submitList()` to replace data.
+
+### Adapter variants (all extend `BaseQuickAdapter`)
+- **`BaseMultiItemAdapter<T>`** — multi view-type layouts. Register each type with `addItemType(viewType, OnMultiItemAdapterListener)` and decide types via `onItemViewType { position, list -> }`. The listener (or `OnMultiItem` subclass, which grants `adapter`/`context`) provides `onCreate`/`onBind` per type.
+- **`BaseNodeAdapter`** — tree/expandable lists. Subclasses implement `getChildNodeList()` and `isInitialOpen()`; `open()`/`close()`/`openOrClose()`/`closeAll()` drive expansion. Open/closed state is tracked by a custom `NodeSet` matched through `isSameNode()` (override for value-based nodes; default is `===`). See the bilingual KDoc on `isSameNode` — it must uniquely identify a node or expand/collapse state leaks across nodes.
+- **`BaseSingleItemAdapter<T, VH>`** — exactly one item (headers/footers). All list mutation methods throw; use `item`/`setItem()` only.
+- **`BaseDifferAdapter`** — deprecated; `BaseQuickAdapter` now subsumes it.
+
+### Composition: `QuickAdapterHelper`
+`QuickAdapterHelper` wraps a content adapter in a `ConcatAdapter` and exposes `helper.adapter` to set on the `RecyclerView`. Layout order: `LeadingLoadStateAdapter` → before-adapters → **content adapter** → after-adapters → `TrailingLoadStateAdapter`. Built via `QuickAdapterHelper.Builder(contentAdapter)` with optional leading/trailing load-more, then `.build()` or `.attachTo(recyclerView)`. This is the canonical way to get header/footer and up/down load-more in v4 — header/footer are separate small adapters prepended/appended, not built-in fields of the base adapter.
+
+### Load more (`loadState/`)
+- `LoadState` — sealed type: `None`, `NotLoading(endOfPaginationReached)`, `Loading`, `Error`.
+- `LoadStateAdapter<VH>` — base for a load-more adapter; toggles its single item on/off via `displayLoadStateAsItem()`.
+- `TrailingLoadStateAdapter` (tail) / `LeadingLoadStateAdapter` (head), each with a `Default…` implementation. Trailing supports `isAutoLoadMore`, `preloadSize`, and `checkDisableLoadMoreIfNotFullPage()`.
+
+### Supporting utilities
+- `viewholder/QuickViewHolder` — convenience `ViewHolder` with cached `findViewById` and chained setters (`setText`, `setVisible`, …).
+- `layoutmanager/QuickGridLayoutManager` — `GridLayoutManager` that grants full span to adapters implementing `FullSpanAdapterType`, and to `BaseQuickAdapter` view types for which `isFullSpanItem(type)` is true (the empty/state view is full-span by default). Use it (or your own `SpanSizeLookup`) when an item must span all columns.
+- `dragswipe/QuickDragAndSwipe` + `DragSwipeExt.kt` — drag-and-swipe on top of `ItemTouchHelper`.
+- `animation/*` — `ItemAnimator` implementations (`AlphaIn`, `ScaleIn`, `SlideIn{Left,Right,Bottom}`).
+- `util/AdapterUtils.kt` — `ViewGroup.getItemView(layoutResId)` and `ViewHolder.asStaggeredGridFullSpan()`.
+
+### Internal resource IDs
+The library declares IDs in `library/src/main/res/values/ids.xml` (e.g. `BaseQuickAdapter_empty_view`, `BaseQuickAdapter_key_multi`) used for internal view tagging and the empty-view `viewType`. The `EMPTY_VIEW` companion constant points at `R.id.BaseQuickAdapter_empty_view`.
+
+## Conventions
+
+- **Bilingual KDoc.** Public API documentation is written in **both Chinese and English** (Chinese typically first, then English). Match this style when adding or editing public APIs.
+- **Builder/`apply` chaining.** Setters in `BaseQuickAdapter` and `QuickAdapterHelper.Builder` return `apply`/the builder for fluent config.
+- Keep `:library` dependency-free of UI libs — it should only depend on AndroidX `annotation`/`recyclerview` (plus `compileOnly` databinding). Put demo-only dependencies in `:app`.