chore(release): prepare v3.0.1

.github/workflows/release.yml

@@ -111,13 +111,14 @@ jobs:
         run: |
           # 在独立 job 中确认消费者能下载各模块；失败后可单独重跑，不会重新上传。
           for module in kit kit-base kit-json kit-mybatis kit-selenium; do
-            extensions=(pom)
-            if [[ $module != kit ]]; then extensions+=(jar); fi
-            for extension in "${extensions[@]}"; do
+            # 父模块仅发布 POM；库模块同时核对主 JAR、源码和 Javadoc。
+            suffixes=(.pom)
+            if [[ $module != kit ]]; then suffixes+=(.jar -sources.jar -javadoc.jar); fi
+            for suffix in "${suffixes[@]}"; do
               # 对 Central 的短暂同步延迟保留有限重试，文件内容无需落盘。
               curl --fail --silent --show-error --location \
                 --retry 12 --retry-all-errors --retry-delay 5 --retry-max-time 180 --max-time 30 \
-                "https://repo.maven.apache.org/maven2/io/allurx/kit/$module/$KIT_VERSION/$module-$KIT_VERSION.$extension" \
+                "https://repo.maven.apache.org/maven2/io/allurx/kit/$module/$KIT_VERSION/$module-$KIT_VERSION$suffix" \
                 --output /dev/null
             done
           done

AGENTS.md

@@ -14,8 +14,13 @@
 - 修改轮询行为时，使用已有 Clock / Sleeper 注入点验证次数、截止与异常边界；修改反射泛型 API 时，同时验证外部调用的编译类型和运行行为。
 - JMH 与 JUnit 独立；普通测试通过不能作为性能证据。
 
+## 分支与合并
+- 短期功能、修复和依赖更新分支合入 `dev` 时使用 `Squash and merge`，每个 PR 保持一个完整意图。
+- `dev` 与 `main` 是长期分支；`dev → main` 的发布 PR 使用 `Create a merge commit`，保留共同祖先，避免后续发布 PR 重复包含已压缩的提交。执行合并前核对 PR 的 base/head，并显式选择对应方式，不依赖 GitHub 默认选项。
+- 发布验证完成后，将已验证的 `main` 发布提交同步回 `dev`：已包含时无需合并，可快进时使用 fast-forward，已分叉时使用普通 merge，保留 `dev` 的后续改动；不用 Squash。`dev` 更新后推送并核对 CI，具体步骤见发布文档。
+
 ## 发布
 - 执行发布前读取 [CI/CD 与发布流程](docs/ci-cd.md#release)。用户明确要求发布指定版本时，按该流程完成本次发布所需的版本修改、验证、提交与推送、合入 main、创建并推送 tag 和结果核实；范围明确时不逐步重复确认。
 - 创建并推送正式 tag 前，由执行发布的 Agent 主动查询最终 main 发布提交 SHA 对应的 CI，等待其成功；缺少结果、运行中或未成功均不能视为通过，也不能用其他提交的成功结果代替。发布提交发生变化后重新核对；该检查由发布执行者负责，当前 CD 不查询此前的 CI 结果。
 - 普通 CI 可使用 `-Prelease -Dgpg.skip=true` 执行到 `verify`，验证 sources / Javadoc 等发布产物；该命令不签名、不上传。正式发布启用 release profile，不跳过签名；发布相关变更须核验这些实际产物。
-- Central 上传、校验和公开发布分别核实；以 pom.xml 中发布插件配置及最终可下载组件为准，不能只凭 deploy 成功判断公开发布完成。确认 Central 制品可公开下载且 GitHub Release 已创建后，再报告发布完成，并提供版本、commit、tag 和发布链接。
+- Central 上传、校验和公开发布分别核实；以 pom.xml 中发布插件配置及最终可下载组件为准，不能只凭 deploy 成功判断公开发布完成。确认 Central 制品可公开下载且 GitHub Release 已创建，审核发布说明的变更范围并补齐破坏性变更的迁移要点后，再报告发布完成，并提供版本、commit、tag 和发布链接。

docs/ci-cd.md

@@ -37,6 +37,21 @@ including on failure. Tests use the module path; the real Chrome test skips unle
 `kit.selenium.chromePath` is supplied. Normal CI does not verify real browser startup
 or database compatibility. See [the workflow](../.github/workflows/ci.yml) for the invocation.
 
+## Branches and merges
+
+`dev` and `main` are long-lived branches. Use the merge policy recorded in
+[AGENTS.md](../AGENTS.md#分支与合并):
+
+| Integration | Merge method |
+| --- | --- |
+| Short-lived feature, fix or dependency-update branch → `dev` | **Squash and merge**; keep one logical change per PR |
+| Release from `dev` → `main` | **Create a merge commit**; preserve shared ancestry between releases |
+| Synchronize the verified `main` release commit → `dev` | Fast-forward when possible; use a normal merge commit if the branches have diverged; do nothing if already included |
+
+Squashing a long-lived branch can make later PRs include already-squashed commits
+and repeat conflicts. See [GitHub's guidance on long-running branches](https://docs.github.com/en/pull-requests/reference/pull-request-merges#squashing-and-merging-a-long-running-branch).
+Check the PR's base/head and explicitly select the appropriate merge method.
+
 ## GitHub setup
 
 Create the `maven-central` Environment with:
@@ -52,11 +67,16 @@ The token must be authorized for `io.allurx.kit`; publish the corresponding publ
 GPG key as required by Central. `setup-java` creates Maven settings with server ID
 `central`, matching the POM, and imports the signing key for the publishing job.
 
-Limit the Environment to `v*` tags and choose Environment approval rules according
-to repository policy. After a successful live CI run, configure its check as a branch
-requirement for `dev` and `main`; protect release tags against updates and deletion.
+Limit the Environment to tags matching `v*`. Require a pull request and a successful
+`verify` check from GitHub Actions before merging into `main`; no additional human
+approval or strict branch-update requirement is needed for this workflow. Protect
+`v*` release tags against updates and deletion while allowing new tags to be created.
 Repository settings and secrets are configured separately from source changes.
 
+In **Settings → General → Pull Requests**, enable **Allow squash merging** and
+**Allow merge commits**, and disable **Allow rebase merging**. These repository-wide
+options make both methods available; the merger follows the policy above for each PR.
+
 Actions are pinned to commit SHAs. Dependabot proposes weekly Maven and Actions
 version updates to `dev`. Maven plugin versions, including the Help plugin used for
 release version checks, are managed in the root POM; workflows invoke the goals
@@ -76,9 +96,9 @@ include the workflow files in the release commit.
 2. Update the root POM's project version and all four child POMs' parent versions
    together. Run root `verify` with `release` unchecked and fix relevant failures.
    `install` is only needed by other local projects; it is not a release prerequisite.
-3. Commit and push the release changes, wait for CI, then integrate them into `main`
-   according to the repository's review and merge rules. Update local `main` and
-   confirm a clean working tree.
+3. Commit and push the release changes, wait for CI, then
+   merge the `dev` → `main` release PR with **Create a merge commit**. Update local
+   `main` with `git pull --ff-only` and confirm a clean working tree.
 4. Record the final release commit SHA. Query the `CI` workflow run for that exact
    commit on `main` and wait for successful completion. A missing, pending, failed,
    cancelled or skipped run does not satisfy this check. A green result for another
@@ -87,8 +107,15 @@ include the workflow files in the release commit.
 5. Create the annotated `vMAJOR.MINOR.PATCH` tag on that verified commit and push
    that exact tag to trigger the `Release` workflow.
 6. Follow both release jobs through completion. Confirm that the public Central
-   artifact checks pass and the GitHub Release exists, then report the version,
-   commit SHA, tag and release links.
+   artifact checks pass and the GitHub Release exists. Review the generated notes
+   against this release's changes, correct unrelated history, and add migration
+   guidance for breaking changes.
+7. Update local `dev` from `origin/dev` with `git pull --ff-only`, then synchronize
+   the verified `main` release commit into it. If already included, no merge is
+   needed. Otherwise, fast-forward when possible or use a normal merge commit to
+   preserve subsequent work on `dev`; do not squash. If `dev` advances, push it and
+   wait for its CI to pass. Then report the version, release commit SHA, tag and
+   release links.
 
 The person or agent performing the release owns step 4. Git tag operations and the
 current release workflow do not query earlier CI results. The release workflow
@@ -98,7 +125,8 @@ performs its own build and tests after the tag is pushed.
 
 A request such as “帮我把当前工程发布为 vX.Y.Z” authorizes the necessary version
 updates, verification, commits, pushes, integration into `main`, tag creation and
-push, and publication checks for that release. The agent follows the shared
+push, publication checks, and synchronization of the verified release commit back
+into `dev`. The agent follows the shared
 procedure, queries and waits for CI itself, and completes the authorized steps
 without requesting confirmation for each one. If the version or release scope is
 materially unclear, establish it before the dependent actions.
@@ -144,10 +172,10 @@ The workflow has two jobs:
    One `clean deploy` builds, tests, generates sources/Javadoc, signs and publishes
    through the Central plugin, waiting for `PUBLISHED`. Logs and Surefire reports
    are retained for 90 days when report upload succeeds.
-2. **`github-release`** downloads the five POMs and four main JARs from public Maven
-   Central, then creates the GitHub Release with generated notes. An existing release
-   is preserved. Rerunning only this job repeats the public checks and GitHub Release
-   creation without rebuilding or deploying.
+2. **`github-release`** downloads the five POMs and twelve main, sources and Javadoc
+   JARs from public Maven Central, then creates the GitHub Release with generated
+   notes. An existing release is preserved. Rerunning only this job repeats the
+   public checks and GitHub Release creation without rebuilding or deploying.
 
 The [release workflow](../.github/workflows/release.yml) owns the publishing command
 and its options.
@@ -163,9 +191,10 @@ and its options.
   Maven log and deployment status in Central Portal first. Follow an in-progress
   deployment there; do not blindly rerun the entire release or upload the version again.
 - If the `publish` job failed but Central reports `PUBLISHED`, manually confirm that
-  the five POMs and four main JARs can be downloaded from public Maven Central. Then,
-  if the GitHub Release is missing, finish with
+  the five POMs and twelve main, sources and Javadoc JARs can be downloaded from
+  public Maven Central. Then, if the GitHub Release is missing, finish with
   `gh release create <tag> --repo allurx/kit --verify-tag --generate-notes`.
+  Review the generated notes using the same release procedure.
 - If only the final GitHub Release job failed, rerunning that failed job is sufficient.
 
 Published Central coordinates are immutable. Fix faulty public content in a new version.

kit-base/pom.xml

@@ -4,7 +4,7 @@
     <parent>
         <groupId>io.allurx.kit</groupId>
         <artifactId>kit</artifactId>
-        <version>3.0.0</version>
+        <version>3.0.1</version>
     </parent>
 
     <artifactId>kit-base</artifactId>

kit-json/pom.xml

@@ -4,7 +4,7 @@
     <parent>
         <groupId>io.allurx.kit</groupId>
         <artifactId>kit</artifactId>
-        <version>3.0.0</version>
+        <version>3.0.1</version>
     </parent>
 
     <artifactId>kit-json</artifactId>

kit-mybatis/pom.xml

@@ -4,7 +4,7 @@
     <parent>
         <groupId>io.allurx.kit</groupId>
         <artifactId>kit</artifactId>
-        <version>3.0.0</version>
+        <version>3.0.1</version>
     </parent>
 
     <artifactId>kit-mybatis</artifactId>

kit-selenium/pom.xml

@@ -4,7 +4,7 @@
     <parent>
         <groupId>io.allurx.kit</groupId>
         <artifactId>kit</artifactId>
-        <version>3.0.0</version>
+        <version>3.0.1</version>
     </parent>
 
     <artifactId>kit-selenium</artifactId>

pom.xml

@@ -4,7 +4,7 @@
 
     <groupId>io.allurx.kit</groupId>
     <artifactId>kit</artifactId>
-    <version>3.0.0</version>
+    <version>3.0.1</version>
     <packaging>pom</packaging>
     <name>kit</name>
 
@@ -20,7 +20,7 @@
 
     <properties>
         <gson.version>2.14.0</gson.version>
-        <guava.version>33.6.0-jre</guava.version>
+        <guava.version>33.7.1-jre</guava.version>
         <jackson-bom.version>3.2.2</jackson-bom.version>
         <jetbrains.annotations.version>26.1.0</jetbrains.annotations.version>
         <jmh.version>1.37</jmh.version>
@@ -29,10 +29,10 @@
         <maven-central-publishing-plugin.version>0.11.0</maven-central-publishing-plugin.version>
         <maven-clean-plugin.version>3.5.0</maven-clean-plugin.version>
         <maven-compiler-plugin.version>3.16.0</maven-compiler-plugin.version>
-        <maven-deploy-plugin.version>3.1.4</maven-deploy-plugin.version>
+        <maven-deploy-plugin.version>3.2.0</maven-deploy-plugin.version>
         <maven-gpg-plugin.version>3.2.8</maven-gpg-plugin.version>
         <maven-help-plugin.version>3.5.2</maven-help-plugin.version>
-        <maven-install-plugin.version>3.1.4</maven-install-plugin.version>
+        <maven-install-plugin.version>3.2.0</maven-install-plugin.version>
         <maven-jar-plugin.version>3.5.1</maven-jar-plugin.version>
         <maven-javadoc-plugin.version>3.12.0</maven-javadoc-plugin.version>
         <maven-resources-plugin.version>3.5.0</maven-resources-plugin.version>
@@ -41,8 +41,8 @@
         <maven.compiler.release>25</maven.compiler.release>
         <mybatis.version>3.5.19</mybatis.version>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <selenium-java.version>4.48.0</selenium-java.version>
-        <slf4j-api.version>2.0.18</slf4j-api.version>
+        <selenium-java.version>4.49.0</selenium-java.version>
+        <slf4j-api.version>2.0.19</slf4j-api.version>
     </properties>
 
     <licenses>