From ba938ef9b53acfa19489a0ec175663e8568e484e Mon Sep 17 00:00:00 2001
From: Alex Li <github@alexv525.com>
Date: Sat, 4 Jul 2026 23:35:11 +0800
Subject: [PATCH 1/6] =?UTF-8?q?=F0=9F=93=9D=20Add=20agent=20contribution?=
 =?UTF-8?q?=20guidelines=20(AGENTS.md)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/PULL_REQUEST_TEMPLATE.md |   1 +
 AGENTS-ZH.md                     | 115 ++++++++++++++++++++
 AGENTS.md                        | 175 +++++++++++++++++++++++++++++++
 CONTRIBUTING-ZH.md               |   2 +
 CONTRIBUTING.md                  |   2 +
 5 files changed, 295 insertions(+)
 create mode 100644 AGENTS-ZH.md
 create mode 100644 AGENTS.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index e4613ca37..27270d694 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -3,6 +3,7 @@
 ### New Pull Request Checklist
 
 - [ ] I have read the [Documentation](https://pub.dev/documentation/dio/latest/)
+- [ ] I have read the [Agent Contribution Guidelines](https://github.com/cfug/dio/blob/main/AGENTS.md) (required if any part of the change was produced with AI assistance)
 - [ ] I have searched for a similar pull request in the [project](https://github.com/cfug/dio/pulls) and found none
 - [ ] I have updated this branch with the latest `main` branch to avoid conflicts (via merge from master or rebase)
 - [ ] I have added the required tests to prove the fix/feature I'm adding
diff --git a/AGENTS-ZH.md b/AGENTS-ZH.md
new file mode 100644
index 000000000..e3f892182
--- /dev/null
+++ b/AGENTS-ZH.md
@@ -0,0 +1,115 @@
+# Agent 贡献规范
+
+Language: [English](AGENTS.md) | 简体中文
+
+本文档定义了 AI agent（及操作它们的人）在本仓库工作时须遵守的规则——无论您是提交拉取请求，还是在本地协助维护者开发。本文档是对 [贡献指南](CONTRIBUTING-ZH.md) 和 [兼容性政策](COMPATIBILITY_POLICY.md) 的补充，且绝不凌驾于它们之上。
+
+dio 是 Dart/Flutter 生态中被依赖最多的包之一。一次草率的改动就可能破坏数以万计的下游项目。在这里贡献不是儿戏：每一个改动都必须有动机、有测试、保持兼容。
+
+## 1. 动机优先——禁止臆想式改动
+
+**不要凭空制造工作。** 只有解决真实存在的问题的改动才会被接受。
+
+- 每个非琐碎的改动都必须能追溯到具体动机：一个可复现的 bug、一个被接受的 issue/discussion、一份 RFC 式的提案、或维护者的明确要求。「这看起来有用」不是动机。
+- 落地一个 feature 之前，必须在 issue 或 PR 描述中回答以下问题——答不上来就不要开 PR：
+  1. 当前的 dio 有什么做不到（或做得不好）的？
+  2. 谁需要它？在什么真实场景中需要？
+  3. 为什么它必须进入 dio 本体，而不是通过 interceptor、adapter、transformer 或独立的包来实现？dio 被有意设计为可扩展的，大多数需求靠扩展点即可满足，无需改动核心。
+  4. 代价是什么——API 面、维护负担、兼容性风险？
+- 一个 PR 只解决一件事。不要把多个互不相关的功能或修复捆绑进同一个 PR。捆绑式的「改进大礼包」可能不经审阅直接关闭。
+- 任何面向用户的 feature，在动手写代码**之前**必须先开 issue 讨论，除非维护者已经明确提出需求。没有事先讨论、缺乏明确动机的 feature PR 既浪费您的 token 也浪费维护者的时间，可能被直接关闭。
+
+## 2. 逻辑改动必须有测试
+
+每个行为上的改动都必须由测试证明。
+
+- 任何逻辑改动都需要新增测试或调整现有测试，且测试必须「没有此改动则失败、有此改动则通过」。Bug 修复必须附带能复现原始报告的回归测试。
+- CI 会在每个 PR 上报告覆盖率差异。改动代码的覆盖率不得倒退；新增的代码路径（包括错误路径）必须被覆盖。
+- 测试必须**有效且不重复**：
+  - 断言可观察的行为，而不是实现细节。
+  - 不要为了抬高覆盖率数字而添加只是重复执行已覆盖路径的测试。
+  - 先搜索现有测试套件——优先扩展已有的测试分组，而不是创建近乎重复的文件。
+- 把测试放在正确的位置：
+  - 包内特有的行为 → `<package>/test/`。
+  - 必须在所有 adapter/平台上一致的行为 → 共享的 `dio_test` 包。
+- 在声称检查通过之前，先在本地实际运行：
+
+  ```bash
+  melos run format   # 或 format:fix
+  melos run analyze
+  melos run test     # 或指定目标：test:vm / test:web / test:flutter
+  ```
+
+- 没有运行过测试就绝不声称测试通过。没有实际完成的 PR checklist 条目绝不打勾。谎报验证状态可能导致 PR 被直接关闭。
+
+## 3. 兼容性不容侵犯——避免 breaking change
+
+dio 的公开 API 是与庞大下游生态的契约。除非维护者另有决定，请把每个公开符号都视为冻结的。
+
+- **默认不做破坏性改动。** 优先做加法：带安全默认值的新可选命名参数、新的类、新的扩展点。
+- 在非 major 版本中，绝不改变公开方法签名、移除/重命名公开符号、改变默认行为、或改变抛出的异常类型。
+- 如果某个 API 确实必须移除，先废弃并保持其可用：
+
+  ```dart
+  @Deprecated('Use XXX instead. This will be removed in 7.0.0')
+  ```
+
+  废弃标注必须写明替代方案和移除版本，且只在下一个 major 版本中移除，同时在 `dio/doc/migration_guide.md` 中补充对应条目。
+- 不得抬高任何包的 Dart/Flutter SDK 最低约束，除非 [兼容性政策](COMPATIBILITY_POLICY.md) 或其列出的例外情况要求如此。CI 会针对最低支持的 SDK 运行测试；不要使用超出包下限的语言/库特性。
+- 同样警惕**行为性**的 breaking change：改变默认值、header 规范化、重定向/错误语义、interceptor 的时序或顺序，即使签名未变也可能破坏下游。
+- 如果破坏性改动确实不可避免，请停下来开 issue 交由维护者决定。不要单方面提交。
+
+## 4. 先理解，再改动
+
+- 编辑之前先阅读周边代码和既有模式。遵循现有的风格、命名和模块边界。
+- 解决根因，而不是症状。收到症状报告时，先定位真正的缺陷再打补丁。
+- 绝不臆测 API——无论是 dio 的内部实现还是第三方包。不确定时去读真实源码（依赖位于 `~/.pub-cache/hosted/pub.dev/<包名>-<版本>/`）以及该包自带的测试/示例。如果 `dart analyze` 提示某个成员不存在，回到源码确认，而不是反复尝试各种变体。
+- 保持最小 diff。只改本次改动必须涉及的文件。禁止顺手重构、对未涉及代码重新格式化、升级依赖，或夹带与所述目的无关的 `.gitignore`/CI 修改。
+
+## 5. 只接受生产级质量
+
+- 不接受半成品：不留 `TODO`/`FIXME`，不把 mock 或简化实现当成完整功能提交，不写「以后再优化」的代码。
+- 显式处理边界条件和错误路径；绝不静默吞掉错误。
+- 如果确实无法完整完成某项工作，明确说明并指出边界——不要假装已经完成。
+
+## 6. 仓库结构与工作流
+
+本项目是使用 [Melos](https://melos.invertase.dev) 管理的单体仓库：
+
+| 路径 | 包 |
+|---|---|
+| `dio/` | 核心包 |
+| `plugins/web_adapter/` | `dio_web_adapter` |
+| `plugins/cookie_manager/` | `dio_cookie_manager` |
+| `plugins/http2_adapter/` | `dio_http2_adapter` |
+| `plugins/native_dio_adapter/` | `native_dio_adapter` |
+| `plugins/compatibility_layer/` | `dio_compatibility_layer` |
+| `dio_test/` | 供所有 adapter 共享的测试套件 |
+| `example_dart/`、`example_flutter_app/` | 示例 |
+
+设置：
+
+```bash
+dart pub global activate melos
+melos bootstrap
+```
+
+每个包独立管理版本、独立发布。注意各包的 **SDK 下限不同**（见各自的 `pubspec.yaml`）。
+
+## 7. Changelog、提交与 PR 卫生
+
+- 更新**每个被改动的包**的 `CHANGELOG.md`，写在 `## Unreleased` 小节下（替换掉 `*None.*`）。每项改动一条简明的 bullet，面向下游用户撰写。不要修改版本号——发版由维护者完成。
+- 提交信息和 PR 使用英文。PR 标题遵循仓库现有风格（参考 `git log`），并引用相关 issue。
+- 如实填写 PR 模板。公开 API 变化时检查文档（`README.md`、`README-ZH.md`、API 文档注释、示例）。
+- 欢迎 agent 辅助的 PR，但提交 PR 的人对它负全责：您必须理解每一行代码、能在 review 中为其答辩，并对 review 意见作出实质性回应。「这是 AI 写的」不是对 review 问题的回答。
+
+## 8. 可能被直接关闭的情形
+
+为了把维护者的时间留给用心的贡献，出现以下情形的 PR 可能会不经详细审阅直接关闭：
+
+- 没有说明动机、没有事先讨论的功能堆砌。
+- 多个不相关改动捆绑在一起。
+- 逻辑改动没有测试，或测试没有任何有效断言。
+- 无关的文件搅动（把格式化清扫、`.gitignore`、CI、文档重组夹带进功能性 PR）。
+- 虚假勾选 checklist 条目（例如没跑过测试却声称已运行）。
+- 未经维护者事先同意的公开 API 破坏性改动。
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..bc6ff32b9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,175 @@
+# Agent Contribution Guidelines
+
+Language: English | [简体中文](AGENTS-ZH.md)
+
+This document defines the rules for AI agents (and the humans operating them)
+working on this repository — whether you are contributing a pull request or
+assisting a maintainer locally. It supplements, and never overrides,
+[CONTRIBUTING.md](CONTRIBUTING.md) and the
+[Compatibility Policy](COMPATIBILITY_POLICY.md).
+
+dio is one of the most depended-on packages in the Dart/Flutter ecosystem.
+A single careless change can break tens of thousands of downstream projects.
+Contributions here are not a playground: every change must be motivated,
+tested, and compatible.
+
+## 1. Motivation first — no speculative changes
+
+**Do not invent work.** A change is only acceptable when it solves a problem
+that actually exists.
+
+- Every non-trivial change must be traceable to a concrete motivation:
+  a reproducible bug, an accepted issue/discussion, an RFC-style proposal,
+  or an explicit maintainer request. "This seems useful" is not a motivation.
+- Before implementing a feature, answer these questions in the issue or the
+  PR description — if you cannot, do not open the PR:
+  1. What cannot be done (or is done poorly) with the current dio?
+  2. Who needs this, and in which real-world scenario?
+  3. Why does it belong in dio itself, instead of an interceptor, an adapter,
+     a transformer, or a separate package? dio is intentionally extensible;
+     most needs are served by its extension points without core changes.
+  4. What is the cost — API surface, maintenance burden, compatibility risk?
+- One PR, one concern. Do not bundle several unrelated features or fixes
+  into a single PR. Bundled "improvement packs" might be closed unreviewed.
+- For any user-facing feature, open an issue for discussion **before**
+  writing code, unless a maintainer has already asked for it. Feature PRs
+  without prior discussion or clear motivation waste both your tokens and
+  the maintainers' time, and might be closed.
+
+## 2. Tests are mandatory for logic changes
+
+Every behavioral change must be proven by tests.
+
+- Any change to logic requires new tests or adjustments to existing tests
+  that fail without the change and pass with it. Bug fixes must include a
+  regression test that reproduces the original report.
+- CI reports coverage diffs on every PR. Coverage of changed code must not
+  regress; new code paths (including error paths) must be covered.
+- Tests must be **effective and non-duplicated**:
+  - Assert observable behavior, not implementation details.
+  - Do not add tests that merely re-execute existing covered paths to
+    inflate coverage numbers.
+  - Search the existing suites first — extend an existing test group
+    instead of creating a near-duplicate file.
+- Put tests in the right place:
+  - Package-specific behavior → `<package>/test/`.
+  - Behavior that must hold across all adapters/platforms → the shared
+    `dio_test` package.
+- Run the checks locally before claiming they pass:
+
+  ```bash
+  melos run format   # or format:fix
+  melos run analyze
+  melos run test     # or targeted: test:vm / test:web / test:flutter
+  ```
+
+- Never state that tests pass without having run them. Never check a PR
+  checklist item you have not actually done. Misreporting verification
+  status may lead to the PR being closed.
+
+## 3. Compatibility is sacred — avoid breaking changes
+
+dio's public API is a contract with an enormous downstream. Treat every
+public symbol as frozen unless a maintainer decides otherwise.
+
+- **Default to non-breaking.** Prefer additive changes: new optional named
+  parameters with safe defaults, new classes, new extension points.
+- Never change public method signatures, remove/rename public symbols,
+  change default behavior, or alter thrown exception types in a
+  non-major release.
+- If an API must go away, deprecate first and keep it working:
+
+  ```dart
+  @Deprecated('Use XXX instead. This will be removed in 7.0.0')
+  ```
+
+  Deprecations state their replacement and the removal version, and are
+  only removed in the next major release, together with an entry in
+  `dio/doc/migration_guide.md`.
+- Do not raise the minimum Dart/Flutter SDK constraint of any package
+  unless required by the [Compatibility Policy](COMPATIBILITY_POLICY.md)
+  or its listed exceptions. CI tests against the minimum supported SDK;
+  do not use language/library features beyond a package's lower bound.
+- Watch for **behavioral** breaking changes too: changing defaults, header
+  normalization, redirect/error semantics, or timing/ordering of
+  interceptors can break downstream even when signatures are untouched.
+- If a breaking change is genuinely unavoidable, stop and raise it in an
+  issue for maintainers to decide. Do not merge-request it unilaterally.
+
+## 4. Understand before you change
+
+- Read the surrounding code and existing patterns before editing. Match
+  the existing style, naming, and module boundaries.
+- Fix root causes, not symptoms. When a symptom is reported, locate the
+  actual defect before patching.
+- Never guess an API — neither dio's internals nor third-party packages.
+  Read the actual source (dependencies live in
+  `~/.pub-cache/hosted/pub.dev/<package>-<version>/`) and the package's
+  own tests/examples when unsure. If `dart analyze` says a member does
+  not exist, go back to the source instead of retrying variations.
+- Keep diffs minimal. Touch only files required by the change. No drive-by
+  refactoring, reformatting of untouched code, dependency bumps, or
+  `.gitignore`/CI edits that are unrelated to the stated purpose.
+
+## 5. Production quality only
+
+- No placeholder work: no `TODO`/`FIXME` left behind, no mocked or
+  simplified logic presented as complete, no "will optimize later" code.
+- Handle edge cases and error paths explicitly; never swallow errors
+  silently.
+- If you cannot finish something completely, say so explicitly and state
+  the boundary — do not pretend it is done.
+
+## 6. Repository layout and workflow
+
+This is a [Melos](https://melos.invertase.dev) mono-repo:
+
+| Path | Package |
+|---|---|
+| `dio/` | The core package |
+| `plugins/web_adapter/` | `dio_web_adapter` |
+| `plugins/cookie_manager/` | `dio_cookie_manager` |
+| `plugins/http2_adapter/` | `dio_http2_adapter` |
+| `plugins/native_dio_adapter/` | `native_dio_adapter` |
+| `plugins/compatibility_layer/` | `dio_compatibility_layer` |
+| `dio_test/` | Shared test suites for all adapters |
+| `example_dart/`, `example_flutter_app/` | Examples |
+
+Setup:
+
+```bash
+dart pub global activate melos
+melos bootstrap
+```
+
+Each package versions and releases independently. Note that packages have
+**different SDK lower bounds** (see each `pubspec.yaml`).
+
+## 7. Changelog, commits, and PR hygiene
+
+- Update the `CHANGELOG.md` of **every package you changed**, under the
+  `## Unreleased` section (replace `*None.*`). One concise bullet per
+  change, written for downstream users. Do not bump version numbers —
+  releases are done by maintainers.
+- Write commits and PRs in English. Keep the PR title in the repository's
+  existing style (see `git log`), and reference the related issue.
+- Fill in the PR template truthfully. Check the docs when public APIs
+  changed (`README.md`, `README-ZH.md`, API docs comments, examples).
+- Agent-assisted PRs are welcome, but the human submitting the PR owns it:
+  you must understand every line, be able to defend it in review, and
+  respond to review feedback substantively. "The AI wrote it" is not an
+  answer to a review question.
+
+## 8. Patterns that may lead to closure
+
+To keep maintainer time for well-cared contributions, PRs exhibiting these
+patterns might be closed without detailed review:
+
+- Feature dumps with no stated motivation or prior discussion.
+- Multiple unrelated changes bundled together.
+- Logic changes without tests, or with tests that assert nothing.
+- Unrelated file churn (formatting sweeps, `.gitignore`, CI, docs
+  restructuring smuggled into a functional PR).
+- Falsely checked checklist items (e.g. claiming tests ran when they
+  did not).
+- Breaking public API changes without prior maintainer sign-off.
diff --git a/CONTRIBUTING-ZH.md b/CONTRIBUTING-ZH.md
index daa3f683f..ca6c89bd3 100644
--- a/CONTRIBUTING-ZH.md
+++ b/CONTRIBUTING-ZH.md
@@ -8,6 +8,8 @@ Language: [English](CONTRIBUTING.md) | 简体中文
 
 请记住，每个为这个项目做出贡献的人都需要遵循我们的行为准则。这有助于确保所有贡献者的积极和包容环境。
 
+如果您在 AI agent 的协助下贡献（或您本身就是一个 agent），还必须遵循 [Agent 贡献规范](AGENTS-ZH.md)。
+
 再次感谢您的贡献，我们期待看到您将为 `dio` 项目带来什么！
 
 ## 创建好的工单
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 241d6e791..5d1e0ac30 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,6 +8,8 @@ This document provides some guidelines to help ensure that your contributions ar
 
 Remember, everyone contributing to this project is expected to follow our code of conduct. This helps ensure a positive and inclusive environment for all contributors.
 
+If you are contributing with the help of AI agents (or as one), you must also follow the [Agent Contribution Guidelines](AGENTS.md).
+
 Thank you again for your contributions, and we look forward to seeing what you will bring to the `dio` project!
 
 ## Creating Good Tickets

From efa4933333d93bb5252db8c37c73e2e6afaea5e5 Mon Sep 17 00:00:00 2001
From: Alex Li <github@alexv525.com>
Date: Fri, 10 Jul 2026 16:34:54 +0800
Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=93=9D=20docs:=20address=20AGENTS.md?=
 =?UTF-8?q?=20review=20=E2=80=94=20fix=20version,=20add=20cross-platform?=
 =?UTF-8?q?=20paths,=20expand=20workflow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix deprecation example version (7.0.0 → 6.0.0) to match repo reality
- Soften §3 wording to acknowledge dio CHANGELOG's minor-version breaking-change note; require maintainer sign-off + migration entry regardless
- Add Windows path and PUB_CACHE env var for pub-cache lookup
- ZH: replace ambiguous 「包」 with `package`; switch Melos URL to GitHub docs
- Add §6 "When to stop and ask" for ambiguous/out-of-scope work
- Expand §8 into subsections: gitmoji + Conventional commit format with reference table, mandatory AI attribution (Co-Authored-By + PR disclosure), CHANGELOG rules, self-review diff before commit, review iteration workflow, truthful PR template
- Collapse §9 (patterns that may lead to closure) into a cross-reference table pointing at §1–§8, removing full duplication of rule text
- Tighten §1: `Closes #NNNN` alone does not equal prior discussion

Co-Authored-By: Claude <noreply@anthropic.com>
---
 AGENTS-ZH.md | 188 ++++++++++++++++++++++++++++++------
 AGENTS.md    | 266 +++++++++++++++++++++++++++++++++++++++++----------
 2 files changed, 376 insertions(+), 78 deletions(-)

diff --git a/AGENTS-ZH.md b/AGENTS-ZH.md
index e3f892182..6c3172db7 100644
--- a/AGENTS-ZH.md
+++ b/AGENTS-ZH.md
@@ -4,7 +4,7 @@ Language: [English](AGENTS.md) | 简体中文
 
 本文档定义了 AI agent（及操作它们的人）在本仓库工作时须遵守的规则——无论您是提交拉取请求，还是在本地协助维护者开发。本文档是对 [贡献指南](CONTRIBUTING-ZH.md) 和 [兼容性政策](COMPATIBILITY_POLICY.md) 的补充，且绝不凌驾于它们之上。
 
-dio 是 Dart/Flutter 生态中被依赖最多的包之一。一次草率的改动就可能破坏数以万计的下游项目。在这里贡献不是儿戏：每一个改动都必须有动机、有测试、保持兼容。
+dio 是 Dart/Flutter 生态中被依赖最多的 package 之一。一次草率的改动就可能破坏数以万计的下游项目。在这里贡献不是儿戏：每一个改动都必须有动机、有测试、保持兼容。
 
 ## 1. 动机优先——禁止臆想式改动
 
@@ -14,24 +14,24 @@ dio 是 Dart/Flutter 生态中被依赖最多的包之一。一次草率的改
 - 落地一个 feature 之前，必须在 issue 或 PR 描述中回答以下问题——答不上来就不要开 PR：
   1. 当前的 dio 有什么做不到（或做得不好）的？
   2. 谁需要它？在什么真实场景中需要？
-  3. 为什么它必须进入 dio 本体，而不是通过 interceptor、adapter、transformer 或独立的包来实现？dio 被有意设计为可扩展的，大多数需求靠扩展点即可满足，无需改动核心。
+  3. 为什么它必须进入 dio 本体，而不是通过 interceptor、adapter、transformer 或独立的 package 来实现？dio 被有意设计为可扩展的，大多数需求靠扩展点即可满足，无需改动核心。
   4. 代价是什么——API 面、维护负担、兼容性风险？
 - 一个 PR 只解决一件事。不要把多个互不相关的功能或修复捆绑进同一个 PR。捆绑式的「改进大礼包」可能不经审阅直接关闭。
-- 任何面向用户的 feature，在动手写代码**之前**必须先开 issue 讨论，除非维护者已经明确提出需求。没有事先讨论、缺乏明确动机的 feature PR 既浪费您的 token 也浪费维护者的时间，可能被直接关闭。
+- 任何面向用户的 feature，在动手写代码**之前**必须先开 issue 讨论，除非维护者已经明确提出需求。仅仅写一句 `Closes #NNNN` 不等于「事先讨论过」——被引用的 issue 必须体现出维护者已经表达兴趣或认可了这个方向。缺乏这一基础的 feature PR 既浪费您的 token 也浪费维护者的时间，可能被直接关闭。
 
 ## 2. 逻辑改动必须有测试
 
 每个行为上的改动都必须由测试证明。
 
 - 任何逻辑改动都需要新增测试或调整现有测试，且测试必须「没有此改动则失败、有此改动则通过」。Bug 修复必须附带能复现原始报告的回归测试。
-- CI 会在每个 PR 上报告覆盖率差异。改动代码的覆盖率不得倒退；新增的代码路径（包括错误路径）必须被覆盖。
+- CI 会在每个 PR 上报告覆盖率差异。仓库配置的最低阈值很低，那是底线，不是目标：您改动的代码覆盖率不得倒退，新增逻辑（包括错误路径）应由真实断言覆盖。
 - 测试必须**有效且不重复**：
   - 断言可观察的行为，而不是实现细节。
   - 不要为了抬高覆盖率数字而添加只是重复执行已覆盖路径的测试。
   - 先搜索现有测试套件——优先扩展已有的测试分组，而不是创建近乎重复的文件。
 - 把测试放在正确的位置：
-  - 包内特有的行为 → `<package>/test/`。
-  - 必须在所有 adapter/平台上一致的行为 → 共享的 `dio_test` 包。
+  - package 内特有的行为 → `<package>/test/`。
+  - 必须在所有 adapter/平台上一致的行为 → 共享的 `dio_test` package。
 - 在声称检查通过之前，先在本地实际运行：
 
   ```bash
@@ -47,15 +47,15 @@ dio 是 Dart/Flutter 生态中被依赖最多的包之一。一次草率的改
 dio 的公开 API 是与庞大下游生态的契约。除非维护者另有决定，请把每个公开符号都视为冻结的。
 
 - **默认不做破坏性改动。** 优先做加法：带安全默认值的新可选命名参数、新的类、新的扩展点。
-- 在非 major 版本中，绝不改变公开方法签名、移除/重命名公开符号、改变默认行为、或改变抛出的异常类型。
+- 未经废弃流程，不得改变公开方法签名、移除/重命名公开符号、改变默认行为、或改变抛出的异常类型。破坏性改动应归入 major 版本。正如 dio 自己的 [CHANGELOG](dio/CHANGELOG.md) 开篇所述，在无法避免时，破坏性改动**偶尔**也会出现在 minor 版本——这类情况仍需**事先**获得维护者的书面确认，并在 [迁移指南](dio/doc/migration_guide.md) 中留下记录。
 - 如果某个 API 确实必须移除，先废弃并保持其可用：
 
   ```dart
-  @Deprecated('Use XXX instead. This will be removed in 7.0.0')
+  @Deprecated('Use XXX instead. This will be removed in 6.0.0')
   ```
 
-  废弃标注必须写明替代方案和移除版本，且只在下一个 major 版本中移除，同时在 `dio/doc/migration_guide.md` 中补充对应条目。
-- 不得抬高任何包的 Dart/Flutter SDK 最低约束，除非 [兼容性政策](COMPATIBILITY_POLICY.md) 或其列出的例外情况要求如此。CI 会针对最低支持的 SDK 运行测试；不要使用超出包下限的语言/库特性。
+  废弃标注必须写明替代方案和移除版本，且只在下一个 major 版本中移除，同时在迁移指南中补充对应条目。目标是**下一个** major（当前为 `6.0.0`），而不是更远的版本。
+- 不得抬高任何 package 的 Dart/Flutter SDK 最低约束，除非 [兼容性政策](COMPATIBILITY_POLICY.md) 或其列出的例外情况要求如此。CI 会针对最低支持的 SDK 运行测试；不要使用超出 package 下限的语言/库特性。
 - 同样警惕**行为性**的 breaking change：改变默认值、header 规范化、重定向/错误语义、interceptor 的时序或顺序，即使签名未变也可能破坏下游。
 - 如果破坏性改动确实不可避免，请停下来开 issue 交由维护者决定。不要单方面提交。
 
@@ -63,8 +63,14 @@ dio 的公开 API 是与庞大下游生态的契约。除非维护者另有决
 
 - 编辑之前先阅读周边代码和既有模式。遵循现有的风格、命名和模块边界。
 - 解决根因，而不是症状。收到症状报告时，先定位真正的缺陷再打补丁。
-- 绝不臆测 API——无论是 dio 的内部实现还是第三方包。不确定时去读真实源码（依赖位于 `~/.pub-cache/hosted/pub.dev/<包名>-<版本>/`）以及该包自带的测试/示例。如果 `dart analyze` 提示某个成员不存在，回到源码确认，而不是反复尝试各种变体。
-- 保持最小 diff。只改本次改动必须涉及的文件。禁止顺手重构、对未涉及代码重新格式化、升级依赖，或夹带与所述目的无关的 `.gitignore`/CI 修改。
+- 绝不臆测 API——无论是 dio 的内部实现还是第三方 package。不确定时去读真实源码以及该 package 自带的测试/示例。如果 `dart analyze` 提示某个成员不存在，回到源码确认，而不是反复尝试各种变体。依赖源码的默认位置：
+
+  | 平台 | 默认位置 |
+  |---|---|
+  | macOS / Linux | `~/.pub-cache/hosted/pub.dev/<package>-<version>/` |
+  | Windows | `%LOCALAPPDATA%\Pub\Cache\hosted\pub.dev\<package>-<version>\` |
+
+  如果设置了 `PUB_CACHE` 环境变量，请以该变量指向的位置为准。
 
 ## 5. 只接受生产级质量
 
@@ -72,13 +78,25 @@ dio 的公开 API 是与庞大下游生态的契约。除非维护者另有决
 - 显式处理边界条件和错误路径；绝不静默吞掉错误。
 - 如果确实无法完整完成某项工作，明确说明并指出边界——不要假装已经完成。
 
-## 6. 仓库结构与工作流
+## 6. 何时停下来问人
+
+Agent 的默认行为是「猜了就做」。请不要。遇到以下情形时，暂停并向操作者确认（或开 issue 讨论）：
+
+- 任务描述模糊，多个合理解读会导致差异明显的实现。
+- 修复所报告的问题需要超出请求范围的设计变更。
+- 正确的修复触及了明显不在预期范围内的区域（例如为了修一个不相关的 bug 而重命名公开 API，或为了实现一个小功能而重构 interceptor pipeline）。
+- 在合理尝试后仍无法复现所报告的问题。
+- 请求本身看起来就有问题（例如「bug」其实是预期行为，或「feature」违反了本文档的规则）。
+
+以下情况**不要**停下来问：例行的机械步骤（运行测试/format/analyze、暂存文件、开 draft PR），以及本文档已经明确规定的事项（commit 格式、CHANGELOG、AI 归属）。
+
+## 7. 仓库结构
 
-本项目是使用 [Melos](https://melos.invertase.dev) 管理的单体仓库：
+本项目是使用 [Melos](https://github.com/invertase/melos/tree/main/docs) 管理的单体仓库：
 
-| 路径 | 包 |
+| 路径 | package |
 |---|---|
-| `dio/` | 核心包 |
+| `dio/` | 核心 package |
 | `plugins/web_adapter/` | `dio_web_adapter` |
 | `plugins/cookie_manager/` | `dio_cookie_manager` |
 | `plugins/http2_adapter/` | `dio_http2_adapter` |
@@ -94,22 +112,132 @@ dart pub global activate melos
 melos bootstrap
 ```
 
-每个包独立管理版本、独立发布。注意各包的 **SDK 下限不同**（见各自的 `pubspec.yaml`）。
+每个 package 独立管理版本、独立发布。注意各 package 的 **SDK 下限不同**（见各自的 `pubspec.yaml`）。
 
-## 7. Changelog、提交与 PR 卫生
+## 8. Commit、changelog 与 PR 卫生
 
-- 更新**每个被改动的包**的 `CHANGELOG.md`，写在 `## Unreleased` 小节下（替换掉 `*None.*`）。每项改动一条简明的 bullet，面向下游用户撰写。不要修改版本号——发版由维护者完成。
-- 提交信息和 PR 使用英文。PR 标题遵循仓库现有风格（参考 `git log`），并引用相关 issue。
-- 如实填写 PR 模板。公开 API 变化时检查文档（`README.md`、`README-ZH.md`、API 文档注释、示例）。
-- 欢迎 agent 辅助的 PR，但提交 PR 的人对它负全责：您必须理解每一行代码、能在 review 中为其答辩，并对 review 意见作出实质性回应。「这是 AI 写的」不是对 review 问题的回答。
+### 8.1 Commit message 格式——gitmoji + Conventional
 
-## 8. 可能被直接关闭的情形
+每条 commit 使用 **[gitmoji](https://gitmoji.dev)** 打头，并加上 **[Conventional Commits](https://www.conventionalcommits.org)** 类型前缀。emoji 从 gitmoji 规范中选取——不要自己发明。
+
+```
+<gitmoji> <type>[(<scope>)]: <简短祈使句主题>
+
+[可选正文，每行约 72 字符]
+
+[可选 footer，例如 Closes #1234]
+```
+
+本仓库常用的 gitmoji（完整列表见 `git log`）：
+
+| Gitmoji | Conventional 类型 | 用途 |
+|---|---|---|
+| ✨ `:sparkles:` | `feat` | 新的用户可见特性 |
+| 🐛 `:bug:` | `fix` | Bug 修复 |
+| ⚡️ `:zap:` | `perf` | 性能优化 |
+| ♻️ `:recycle:` | `refactor` | 无行为变化的重构 |
+| 📝 `:memo:` | `docs` | 文档 |
+| ✅ `:white_check_mark:` | `test` | 只涉及测试 |
+| 🚨 `:rotating_light:` | `fix` / `style` | 修复 linter 或 analyzer 警告 |
+| 🔧 `:wrench:` | `chore` | 配置 / 工具链 |
+| 👷 `:construction_worker:` | `ci` | CI / workflow 变更 |
+| 💚 `:green_heart:` | `ci` | 修复失败的 CI |
+| ⬆️ `:arrow_up:` | `chore` | 升级依赖 |
+| 🔥 `:fire:` | `chore` / `refactor` | 删除代码或文件 |
+| 🎨 `:art:` | `style` | 只涉及格式/结构 |
+| 🔖 `:bookmark:` | `chore(release)` | 发版（**仅维护者**） |
+
+规则：
+
+- 主题使用英文祈使句。不要手动加 PR 号——GitHub 在 squash-merge 时会自动追加 `(#N)`。
+- Scope 用于澄清（`fix(dio_web_adapter): ...`）；如果 scope 只是重复了路径信息，就省略。
+- 位置 0 是 emoji。空格，然后 Conventional 前缀，再是主题。
+
+示例（改编自真实仓库历史）：
+
+```
+🐛 fix(dio): allow `callFollowingErrorInterceptor` when rejecting in `ErrorInterceptorHandler`
+⚡️ perf(dio): reduce `FormData.readAsBytes` memory usage for large payloads
+📝 docs: add agent contribution guidelines
+```
+
+### 8.2 AI 归属——必须声明
+
+对 AI 参与的透明化是**强制要求**。不要隐瞒，也不要为了「保持 commit 干净」而省略。
+
+- 对每一个产出代码、测试或文档的 AI agent，都要加上 `Co-Authored-By:` trailer：
+
+  ```
+  Co-Authored-By: Claude <noreply@anthropic.com>
+  Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
+  ```
 
-为了把维护者的时间留给用心的贡献，出现以下情形的 PR 可能会不经详细审阅直接关闭：
+  身份信息以该 agent 自己公开的形式为准（参考其官方文档或该 agent 在 GitHub 上最近的 commit）。多个 agent → 多条 trailer。
+- 同时在 PR 描述中说明**用了哪些 agent、分别参与了哪个阶段**——设计、实现、测试或 review。一句话即可，例如：
 
-- 没有说明动机、没有事先讨论的功能堆砌。
-- 多个不相关改动捆绑在一起。
-- 逻辑改动没有测试，或测试没有任何有效断言。
-- 无关的文件搅动（把格式化清扫、`.gitignore`、CI、文档重组夹带进功能性 PR）。
-- 虚假勾选 checklist 条目（例如没跑过测试却声称已运行）。
-- 未经维护者事先同意的公开 API 破坏性改动。
+  > *Implementation and tests by Devin; local review pass by GLM-5.2.*
+
+- AI 归属不会转移责任。提交 PR 的人对每一行代码负全责，必须理解每一行，并对 review 意见作出实质性回应。「这是 AI 写的」不是对 review 问题的回答。
+
+### 8.3 CHANGELOG 与文档
+
+- 更新**每个被改动的 package** 的 `CHANGELOG.md`，写在 `## Unreleased` 小节下（替换掉 `*None.*`）。
+- 每项改动一条简明的 bullet，面向下游用户撰写，而不是面向 reviewer。
+- 不要修改版本号——发版由维护者完成。
+- 公开 API 变化时，同步检查 `README.md`、`README-ZH.md`、API 文档注释、以及所有受影响的示例。
+
+### 8.4 每次 commit 前自审 diff
+
+提交前始终检查即将进入 commit 的内容：
+
+```bash
+git diff                            # 未暂存
+git diff --staged                   # 已暂存
+git diff <base-branch>...HEAD       # 开 PR / 更新 PR 前的完整分支 diff
+```
+
+commit 前必须清除：
+
+- 调试输出（`print`、`debugPrint`、`console.log`、临时日志）。
+- 前几次尝试遗留的注释掉的代码。
+- 不属于本次改动的文件里的格式化/import 排序变化。
+- `pubspec.yaml` / `pubspec.lock` 中不相关的依赖升降。
+- 无关文件里的纯空白改动。
+- 编辑器/系统垃圾（`.DS_Store`、`.idea/`、个人临时文件）。
+
+如果一段 diff 你说不清为什么会在那里，它就不该进这次 commit。绝不使用 `git add .` 或 `git add -A`——按路径精确 stage。
+
+### 8.5 Review 迭代工作流
+
+PR 开出后：
+
+- **用追加 commit 的方式回应 review 反馈**，不要 squash 后 force-push。Reviewer 依赖增量历史；squash 是 merge 时才做的事情。
+- **对已经有 review 评论的分支，避免 `git push --force`**——这会让评论从对应代码位置脱钩。如果确实需要 rebase（例如为解决与 `main` 的冲突），先在 PR 里留言告知 reviewer 再推送。
+- **不要通过 close 再 reopen PR** 来重置 review 状态、重跑 CI，或绕过一个阻塞的 review。推一个修复即可。
+- **设计层面的 review 反馈是对话，不是指令**。如果一条 review 建议改变的是 PR 的意图（而不仅是实现方式），先回复讨论、达成共识后再动代码。机械地照做一个大改动比不改还糟。
+- **只有在你已经在代码里回应了这个意见，并留言说明了改动内容后，才把 review thread 标记为 resolved**——或者由 reviewer 明确说 resolve。不要静默 resolve。
+- **CI 失败时**：先读失败任务的日志、定位根因，再推修复。绝不通过反复触发 CI 碰运气。如果测试确实 flaky，请在评论里说明——不要通过禁用测试或加重试掩盖。
+
+### 8.6 如实填写 PR 模板
+
+- 只勾选真正完成的条目。对不适用的条目，保持未勾选并在旁边注明「（不适用——原因）」。不要为了「快点通过 checklist」而勾选。
+- 用 `Closes #NNNN` 引用要关闭的 issue。
+- PR 标题和正文使用英文，风格与 §8.1 的 commit 一致。
+
+## 9. 可能被直接关闭的情形
+
+快速对照表——每一项都是对上文规则的违反。出现下列一种或多种情形的 PR，维护者有权不经详细审阅直接关闭。
+
+| 情形 | 参见 |
+|---|---|
+| 缺乏动机或事先讨论 | §1 |
+| 多个不相关改动捆绑在同一个 PR | §1 |
+| 逻辑改动缺少有效、非重复的测试 | §2 |
+| 未经维护者事先同意的公开 API 破坏性改动 | §3 |
+| 臆造 / hallucinate 的 API 用法 | §4 |
+| 顺手重构、格式化清扫、无关的 `.gitignore` / CI 改动 | §4、§8.4 |
+| Diff 中残留调试输出或注释掉的代码 | §8.4 |
+| 不合规范的 commit message（缺 gitmoji、类型错误、非英文） | §8.1 |
+| 缺失或隐瞒 AI 归属 | §8.2 |
+| 虚假勾选 PR checklist 条目 | §8.6 |
+| Force-push 或 close/reopen 用来重置 review 状态 | §8.5 |
diff --git a/AGENTS.md b/AGENTS.md
index bc6ff32b9..d6711c625 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,8 +32,10 @@ that actually exists.
 - One PR, one concern. Do not bundle several unrelated features or fixes
   into a single PR. Bundled "improvement packs" might be closed unreviewed.
 - For any user-facing feature, open an issue for discussion **before**
-  writing code, unless a maintainer has already asked for it. Feature PRs
-  without prior discussion or clear motivation waste both your tokens and
+  writing code, unless a maintainer has already asked for it. A bare
+  `Closes #NNNN` is not the same as prior discussion: the referenced issue
+  must show that maintainers have expressed interest or accepted the
+  direction. Feature PRs without that grounding waste both your tokens and
   the maintainers' time, and might be closed.
 
 ## 2. Tests are mandatory for logic changes
@@ -43,8 +45,10 @@ Every behavioral change must be proven by tests.
 - Any change to logic requires new tests or adjustments to existing tests
   that fail without the change and pass with it. Bug fixes must include a
   regression test that reproduces the original report.
-- CI reports coverage diffs on every PR. Coverage of changed code must not
-  regress; new code paths (including error paths) must be covered.
+- CI reports coverage diffs on every PR. The published minimum threshold is
+  low, but that is a floor, not a target: coverage of code you changed
+  should not regress, and new logic (including error paths) should be
+  covered by real assertions.
 - Tests must be **effective and non-duplicated**:
   - Assert observable behavior, not implementation details.
   - Do not add tests that merely re-execute existing covered paths to
@@ -74,18 +78,23 @@ public symbol as frozen unless a maintainer decides otherwise.
 
 - **Default to non-breaking.** Prefer additive changes: new optional named
   parameters with safe defaults, new classes, new extension points.
-- Never change public method signatures, remove/rename public symbols,
-  change default behavior, or alter thrown exception types in a
-  non-major release.
+- Do not change public method signatures, remove/rename public symbols,
+  change default behavior, or alter thrown exception types without going
+  through a deprecation cycle. Breaking changes belong in major releases.
+  As dio's own [CHANGELOG](dio/CHANGELOG.md) preamble states, unavoidable
+  breaking changes may occasionally ship in minor releases — those still
+  require maintainer sign-off in advance and an entry in the
+  [Migration Guide](dio/doc/migration_guide.md).
 - If an API must go away, deprecate first and keep it working:
 
   ```dart
-  @Deprecated('Use XXX instead. This will be removed in 7.0.0')
+  @Deprecated('Use XXX instead. This will be removed in 6.0.0')
   ```
 
-  Deprecations state their replacement and the removal version, and are
-  only removed in the next major release, together with an entry in
-  `dio/doc/migration_guide.md`.
+  Deprecations must state their replacement and the removal version, and
+  are only removed in the next major release, together with an entry in
+  the Migration Guide. Target the *next* major (currently `6.0.0`), not a
+  version beyond that.
 - Do not raise the minimum Dart/Flutter SDK constraint of any package
   unless required by the [Compatibility Policy](COMPATIBILITY_POLICY.md)
   or its listed exceptions. CI tests against the minimum supported SDK;
@@ -103,13 +112,17 @@ public symbol as frozen unless a maintainer decides otherwise.
 - Fix root causes, not symptoms. When a symptom is reported, locate the
   actual defect before patching.
 - Never guess an API — neither dio's internals nor third-party packages.
-  Read the actual source (dependencies live in
-  `~/.pub-cache/hosted/pub.dev/<package>-<version>/`) and the package's
-  own tests/examples when unsure. If `dart analyze` says a member does
-  not exist, go back to the source instead of retrying variations.
-- Keep diffs minimal. Touch only files required by the change. No drive-by
-  refactoring, reformatting of untouched code, dependency bumps, or
-  `.gitignore`/CI edits that are unrelated to the stated purpose.
+  Read the actual source and the package's own tests/examples when
+  unsure. If `dart analyze` says a member does not exist, go back to the
+  source instead of retrying variations. Dependency source locations:
+
+  | Platform | Default location |
+  |---|---|
+  | macOS / Linux | `~/.pub-cache/hosted/pub.dev/<package>-<version>/` |
+  | Windows | `%LOCALAPPDATA%\Pub\Cache\hosted\pub.dev\<package>-<version>\` |
+
+  If the `PUB_CACHE` environment variable is set, use that location
+  instead of the platform default.
 
 ## 5. Production quality only
 
@@ -120,9 +133,31 @@ public symbol as frozen unless a maintainer decides otherwise.
 - If you cannot finish something completely, say so explicitly and state
   the boundary — do not pretend it is done.
 
-## 6. Repository layout and workflow
+## 6. When to stop and ask
+
+Agents default to "guess and proceed". Do not. Pause and check with the
+operator (or open a discussion issue) when:
+
+- The task description is ambiguous and multiple reasonable interpretations
+  would produce materially different implementations.
+- Fixing the reported problem would require design changes that go beyond
+  what was asked for.
+- The right fix touches an area not obviously in scope (e.g., renaming a
+  public API to fix an unrelated bug, or restructuring an interceptor
+  pipeline to enable a small feature).
+- You cannot reproduce the reported issue after a reasonable attempt.
+- The request itself seems wrong (e.g., the "bug" is intended behavior, or
+  the "feature" would violate a rule in this document).
 
-This is a [Melos](https://melos.invertase.dev) mono-repo:
+Do **not** stop to ask permission for routine mechanical steps: running
+tests / format / analyze, staging files, opening a draft PR, or choices
+that are already decided by this document (commit format, changelog,
+attribution).
+
+## 7. Repository layout
+
+This is a [Melos](https://github.com/invertase/melos/tree/main/docs)
+mono-repo:
 
 | Path | Package |
 |---|---|
@@ -145,31 +180,166 @@ melos bootstrap
 Each package versions and releases independently. Note that packages have
 **different SDK lower bounds** (see each `pubspec.yaml`).
 
-## 7. Changelog, commits, and PR hygiene
-
-- Update the `CHANGELOG.md` of **every package you changed**, under the
-  `## Unreleased` section (replace `*None.*`). One concise bullet per
-  change, written for downstream users. Do not bump version numbers —
-  releases are done by maintainers.
-- Write commits and PRs in English. Keep the PR title in the repository's
-  existing style (see `git log`), and reference the related issue.
-- Fill in the PR template truthfully. Check the docs when public APIs
-  changed (`README.md`, `README-ZH.md`, API docs comments, examples).
-- Agent-assisted PRs are welcome, but the human submitting the PR owns it:
-  you must understand every line, be able to defend it in review, and
-  respond to review feedback substantively. "The AI wrote it" is not an
-  answer to a review question.
-
-## 8. Patterns that may lead to closure
-
-To keep maintainer time for well-cared contributions, PRs exhibiting these
-patterns might be closed without detailed review:
-
-- Feature dumps with no stated motivation or prior discussion.
-- Multiple unrelated changes bundled together.
-- Logic changes without tests, or with tests that assert nothing.
-- Unrelated file churn (formatting sweeps, `.gitignore`, CI, docs
-  restructuring smuggled into a functional PR).
-- Falsely checked checklist items (e.g. claiming tests ran when they
-  did not).
-- Breaking public API changes without prior maintainer sign-off.
+## 8. Commits, changelog, and PR hygiene
+
+### 8.1 Commit message format — gitmoji + Conventional
+
+Every commit uses **[gitmoji](https://gitmoji.dev)** at the front and a
+**[Conventional Commits](https://www.conventionalcommits.org)** type
+prefix. Emojis are chosen from the gitmoji specification — do not invent
+new ones.
+
+```
+<gitmoji> <type>[(<scope>)]: <short imperative subject>
+
+[optional body — wrap at ~72 chars]
+
+[optional footer, e.g. Closes #1234]
+```
+
+Gitmoji commonly used in this repository (see `git log` for the full set):
+
+| Gitmoji | Conventional type | Use for |
+|---|---|---|
+| ✨ `:sparkles:` | `feat` | New user-facing feature |
+| 🐛 `:bug:` | `fix` | Bug fix |
+| ⚡️ `:zap:` | `perf` | Performance improvement |
+| ♻️ `:recycle:` | `refactor` | Refactor with no behavior change |
+| 📝 `:memo:` | `docs` | Documentation |
+| ✅ `:white_check_mark:` | `test` | Tests only |
+| 🚨 `:rotating_light:` | `fix` / `style` | Fix linter or analyzer warnings |
+| 🔧 `:wrench:` | `chore` | Config / tooling |
+| 👷 `:construction_worker:` | `ci` | CI / workflow changes |
+| 💚 `:green_heart:` | `ci` | Fix a failing CI job |
+| ⬆️ `:arrow_up:` | `chore` | Bump a dependency |
+| 🔥 `:fire:` | `chore` / `refactor` | Remove code or files |
+| 🎨 `:art:` | `style` | Formatting / structure only |
+| 🔖 `:bookmark:` | `chore(release)` | Release (**maintainers only**) |
+
+Rules:
+
+- Subject is an imperative English sentence. Do not append the PR number —
+  GitHub adds `(#N)` automatically on squash-merge.
+- Use scope when it clarifies (`fix(dio_web_adapter): ...`); omit when it
+  would just repeat the file path.
+- Emoji at position 0. Space, then the Conventional prefix, then subject.
+
+Examples (adapted from actual repo history):
+
+```
+🐛 fix(dio): allow `callFollowingErrorInterceptor` when rejecting in `ErrorInterceptorHandler`
+⚡️ perf(dio): reduce `FormData.readAsBytes` memory usage for large payloads
+📝 docs: add agent contribution guidelines
+```
+
+### 8.2 AI attribution — mandatory
+
+Transparency about AI involvement is required. Do not hide it, and do not
+skip it "to keep the commit clean".
+
+- Add a `Co-Authored-By:` trailer for **every AI agent** that produced
+  code, tests, or docs in the commit:
+
+  ```
+  Co-Authored-By: Claude <noreply@anthropic.com>
+  Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
+  ```
+
+  Use the identity the agent itself publishes (see its own docs / recent
+  commits from that agent on GitHub). Multiple agents → multiple trailers.
+- Also disclose in the PR description **which agent(s) were used and for
+  what stage** — design, implementation, tests, or review. One line is
+  enough, e.g.:
+
+  > *Implementation and tests by Devin; local review pass by GLM-5.2.*
+
+- AI attribution never shifts accountability. The human submitting the PR
+  owns every line, must understand it, and must respond to review feedback
+  substantively. "The AI wrote it" is not an answer to a review question.
+
+### 8.3 CHANGELOG and docs
+
+- Update the `CHANGELOG.md` of **every package you changed**, under
+  `## Unreleased` (replace `*None.*`).
+- One concise bullet per change, written for downstream users, not for
+  reviewers.
+- Do not bump version numbers — releases are handled by maintainers.
+- When public APIs change, also update `README.md`, `README-ZH.md`, API
+  doc comments, and any affected examples.
+
+### 8.4 Self-review your diff before every commit
+
+Always inspect what you are about to commit:
+
+```bash
+git diff                          # unstaged
+git diff --staged                 # staged
+git diff <base-branch>...HEAD     # full branch diff before opening/updating a PR
+```
+
+Remove before committing:
+
+- Debug output (`print`, `debugPrint`, `console.log`, temporary logs).
+- Commented-out code left from earlier attempts.
+- Reformatting or import re-ordering of files that are not the subject
+  of this change.
+- Unrelated bumps in `pubspec.yaml` / `pubspec.lock`.
+- Whitespace-only changes in unrelated files.
+- Editor/OS junk (`.DS_Store`, `.idea/`, personal scratch files).
+
+If you cannot explain why a hunk is in the diff, it does not belong in
+the commit. Never use `git add .` or `git add -A` — stage files by path.
+
+### 8.5 Review iteration workflow
+
+After opening the PR:
+
+- **Address feedback with new commits appended to the branch**, not by
+  squash-and-force-push. Maintainers rely on incremental history during
+  review; squashing happens at merge time.
+- **Avoid `git push --force` on a branch that already has review
+  comments** — it detaches those comments from their code position. If a
+  rebase is genuinely required (e.g., conflict resolution against
+  `main`), leave a comment before pushing so reviewers know.
+- **Do not close and reopen the PR** to reset review state, retry CI, or
+  bypass a blocking review. Push a fix instead.
+- **Design-level feedback is a conversation, not an instruction.** If a
+  reviewer's suggestion changes the intent of the PR (not just its
+  implementation), reply first and reach agreement before writing new
+  code. Blindly applying a large suggestion is worse than discussing it.
+- **Mark review threads resolved** only after you have addressed the
+  point in code and left a reply explaining what changed — or after the
+  reviewer explicitly says so. Do not silently resolve.
+- **CI failures**: read the failing job's log, find the root cause, then
+  push a fix. Never re-run CI hoping for a green run. If a test is
+  genuinely flaky, say so in a comment — do not paper over it by
+  disabling the test or adding retries.
+
+### 8.6 Fill in the PR template truthfully
+
+- Only tick a checklist item that is genuinely done. For items that do
+  not apply, keep the box unchecked and add *(not applicable — reason)*
+  next to it. Do not check "done" as a shortcut.
+- Reference the closing issue with `Closes #NNNN` in the description.
+- Write PR titles and bodies in English, in the same commit style as
+  §8.1.
+
+## 9. Patterns that may lead to closure
+
+Quick cross-reference — each pattern is a violation of the rules above.
+PRs matching one or more of these may be closed without detailed review
+at the maintainers' discretion.
+
+| Pattern | See |
+|---|---|
+| No motivation or prior maintainer discussion | §1 |
+| Multiple unrelated changes bundled in one PR | §1 |
+| Logic changes without effective, non-duplicated tests | §2 |
+| Public-API break without maintainer sign-off | §3 |
+| Guessed / hallucinated API usage | §4 |
+| Drive-by refactors, formatting sweeps, unrelated `.gitignore` / CI edits | §4, §8.4 |
+| Debug output or commented-out code left in the diff | §8.4 |
+| Non-standard commit message format (missing gitmoji, wrong type, non-English) | §8.1 |
+| Missing or hidden AI attribution | §8.2 |
+| Falsely checked PR checklist items | §8.6 |
+| Force-pushing or close/reopen to reset review state | §8.5 |

From 1d3185fec662ad02a850f298ac88877c781cb05e Mon Sep 17 00:00:00 2001
From: Alex Li <github@alexv525.com>
Date: Fri, 10 Jul 2026 16:56:18 +0800
Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20sensitive-area?=
 =?UTF-8?q?=20scrutiny,=20dependency=20rules,=20branch=20naming,=20draft-P?=
 =?UTF-8?q?R=20guidance?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- §3: add "Extra scrutiny in security- and network-critical areas" listing SSL/TLS, redirects, cookies, headers, timeout, interceptors, body encoding — sensitive-area changes must call out the touched area and @ a maintainer
- §3: add "Dependency changes" rules — no drive-by bumps, state motivation, verify against all supported SDKs, prefer narrowest constraint, disclose new transitives, use `⬆️ chore`
- §8.1: new "Branch naming" subsection — enforce `category/ticket-id-or-short-description`, category matches Conventional types, one branch per PR
- §8.6: rename to "Opening the PR" and merge in draft-PR guidance (open as draft for large/exploratory changes, convert on ready)
- §8: renumber subsections; move Review iteration to §8.7
- §9: update cross-reference table for new numbering; add rows for sensitive-area, drive-by dep bump, and branch naming violations

Co-Authored-By: Claude <noreply@anthropic.com>
---
 AGENTS-ZH.md |  82 +++++++++++++++++++++++++++------
 AGENTS.md    | 127 ++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 178 insertions(+), 31 deletions(-)

diff --git a/AGENTS-ZH.md b/AGENTS-ZH.md
index 6c3172db7..810cbb7af 100644
--- a/AGENTS-ZH.md
+++ b/AGENTS-ZH.md
@@ -59,6 +59,30 @@ dio 的公开 API 是与庞大下游生态的契约。除非维护者另有决
 - 同样警惕**行为性**的 breaking change：改变默认值、header 规范化、重定向/错误语义、interceptor 的时序或顺序，即使签名未变也可能破坏下游。
 - 如果破坏性改动确实不可避免，请停下来开 issue 交由维护者决定。不要单方面提交。
 
+### 安全与网络关键区域——需要额外谨慎
+
+dio 的部分区域一旦出问题波及面极大。这些区域的改动需要额外小心，PR 描述中必须显式说明改动、并 @ 维护者：
+
+- SSL/TLS 处理与证书 pinning（`badCertificateCallback`、`SecurityContext`、各 adapter 的 `HttpClient` 配置）。
+- 重定向处理与跨源行为（重定向策略、header 转发、跨重定向的 cookie 泄漏）。
+- Cookie 管理（`dio_cookie_manager`、domain/path 匹配）。
+- Header 处理（`Authorization`、`Content-Type`、大小写、重复项）。
+- 超时、cancellation、连接池。
+- Interceptor pipeline（顺序、错误传递、`next` / `resolve` / `reject` 语义）。
+- 请求体编码：`FormData`、multipart 流式、编码探测。
+
+判定标准：如果处理不当会泄漏凭证、让请求永远挂起、或改变发到网络上的数据，就属于敏感区域。
+
+### 依赖变更
+
+不要把顺手的依赖升级夹带进 feature/fix PR。当依赖变更本身就是 PR 的目的时：
+
+- 在描述中说明原因（安全修复、新特性所需、上游弃用等等）。「新的比旧的好」不是原因。
+- 在受影响的 `pubspec.yaml` 声明的所有支持 SDK 版本下验证改动。除非 [兼容性政策](COMPATIBILITY_POLICY.md) 允许，否则不得为了容纳新依赖而抬高 package 的 SDK 下限。
+- 优先选择能解决问题的最窄约束（patch > minor > major）。
+- 显式指出新增的传递依赖——下游用户在意他们的 lockfile。
+- Commit 使用 `⬆️ chore`（或 `chore(deps)`）类型。
+
 ## 4. 先理解，再改动
 
 - 编辑之前先阅读周边代码和既有模式。遵循现有的风格、命名和模块边界。
@@ -116,7 +140,21 @@ melos bootstrap
 
 ## 8. Commit、changelog 与 PR 卫生
 
-### 8.1 Commit message 格式——gitmoji + Conventional
+### 8.1 分支命名
+
+在名为 `category/ticket-id-or-short-description` 的功能分支上工作：
+
+- `category` 与 commit 中使用的 Conventional 类型对应：`feat`、`fix`、`perf`、`refactor`、`docs`、`test`、`chore`、`ci`、`style`。
+- 有对应的 **ticket id**（issue 或 PR 号）时优先使用：`fix/2201`、`feat/2555`。两者结合以增强可读性也可以：`fix/2201-cookie-domain-match`。
+- 否则使用 **short description**——2–5 个 kebab-case 单词描述改动（`docs/agents-guidelines`、`feat/cors-preflight-warning`、`chore/bump-http2-3.0.0`）。
+
+规则：
+
+- 绝不直接在 `main` 上工作。
+- 每个 PR 一个分支；不要把已合并的分支重新用于新的改动。
+- 分支名保持 ASCII、小写、简短。
+
+### 8.2 Commit message 格式——gitmoji + Conventional
 
 每条 commit 使用 **[gitmoji](https://gitmoji.dev)** 打头，并加上 **[Conventional Commits](https://www.conventionalcommits.org)** 类型前缀。emoji 从 gitmoji 规范中选取——不要自己发明。
 
@@ -161,7 +199,7 @@ melos bootstrap
 📝 docs: add agent contribution guidelines
 ```
 
-### 8.2 AI 归属——必须声明
+### 8.3 AI 归属——必须声明
 
 对 AI 参与的透明化是**强制要求**。不要隐瞒，也不要为了「保持 commit 干净」而省略。
 
@@ -179,14 +217,14 @@ melos bootstrap
 
 - AI 归属不会转移责任。提交 PR 的人对每一行代码负全责，必须理解每一行，并对 review 意见作出实质性回应。「这是 AI 写的」不是对 review 问题的回答。
 
-### 8.3 CHANGELOG 与文档
+### 8.4 CHANGELOG 与文档
 
 - 更新**每个被改动的 package** 的 `CHANGELOG.md`，写在 `## Unreleased` 小节下（替换掉 `*None.*`）。
 - 每项改动一条简明的 bullet，面向下游用户撰写，而不是面向 reviewer。
 - 不要修改版本号——发版由维护者完成。
 - 公开 API 变化时，同步检查 `README.md`、`README-ZH.md`、API 文档注释、以及所有受影响的示例。
 
-### 8.4 每次 commit 前自审 diff
+### 8.5 每次 commit 前自审 diff
 
 提交前始终检查即将进入 commit 的内容：
 
@@ -207,7 +245,15 @@ commit 前必须清除：
 
 如果一段 diff 你说不清为什么会在那里，它就不该进这次 commit。绝不使用 `git add .` 或 `git add -A`——按路径精确 stage。
 
-### 8.5 Review 迭代工作流
+### 8.6 提交 PR
+
+- 当改动较大、处于探索阶段、或希望在打磨前先获得维护者方向性反馈时，**以 draft PR 形式开启**（`Create draft pull request`）。在本地检查通过、描述完整之后再切换为 Ready for Review。
+- 在描述中用 `Closes #NNNN` 引用要关闭的 issue。
+- 遵循 §8.3 的 AI 归属规则：说明用了哪些 agent、参与了哪个阶段。
+- PR 标题和正文使用英文，风格与 §8.2 的 commit 一致。
+- 只勾选真正完成的 checklist 条目。对不适用的条目，保持未勾选并在旁边注明「（不适用——原因）」。不要为了「快点通过 checklist」而勾选。
+
+### 8.7 Review 迭代工作流
 
 PR 开出后：
 
@@ -218,11 +264,16 @@ PR 开出后：
 - **只有在你已经在代码里回应了这个意见，并留言说明了改动内容后，才把 review thread 标记为 resolved**——或者由 reviewer 明确说 resolve。不要静默 resolve。
 - **CI 失败时**：先读失败任务的日志、定位根因，再推修复。绝不通过反复触发 CI 碰运气。如果测试确实 flaky，请在评论里说明——不要通过禁用测试或加重试掩盖。
 
-### 8.6 如实填写 PR 模板
+### 8.7 Review 迭代工作流
 
-- 只勾选真正完成的条目。对不适用的条目，保持未勾选并在旁边注明「（不适用——原因）」。不要为了「快点通过 checklist」而勾选。
-- 用 `Closes #NNNN` 引用要关闭的 issue。
-- PR 标题和正文使用英文，风格与 §8.1 的 commit 一致。
+PR 开出后：
+
+- **用追加 commit 的方式回应 review 反馈**，不要 squash 后 force-push。Reviewer 依赖增量历史；squash 是 merge 时才做的事情。
+- **对已经有 review 评论的分支，避免 `git push --force`**——这会让评论从对应代码位置脱钩。如果确实需要 rebase（例如为解决与 `main` 的冲突），先在 PR 里留言告知 reviewer 再推送。
+- **不要通过 close 再 reopen PR** 来重置 review 状态、重跑 CI，或绕过一个阻塞的 review。推一个修复即可。
+- **设计层面的 review 反馈是对话，不是指令**。如果一条 review 建议改变的是 PR 的意图（而不仅是实现方式），先回复讨论、达成共识后再动代码。机械地照做一个大改动比不改还糟。
+- **只有在你已经在代码里回应了这个意见，并留言说明了改动内容后，才把 review thread 标记为 resolved**——或者由 reviewer 明确说 resolve。不要静默 resolve。
+- **CI 失败时**：先读失败任务的日志、定位根因，再推修复。绝不通过反复触发 CI 碰运气。如果测试确实 flaky，请在评论里说明——不要通过禁用测试或加重试掩盖。
 
 ## 9. 可能被直接关闭的情形
 
@@ -234,10 +285,13 @@ PR 开出后：
 | 多个不相关改动捆绑在同一个 PR | §1 |
 | 逻辑改动缺少有效、非重复的测试 | §2 |
 | 未经维护者事先同意的公开 API 破坏性改动 | §3 |
+| 敏感区域改动未通知维护者 | §3 |
+| 在 feature/fix PR 中夹带顺手的依赖升级 | §3 |
 | 臆造 / hallucinate 的 API 用法 | §4 |
-| 顺手重构、格式化清扫、无关的 `.gitignore` / CI 改动 | §4、§8.4 |
-| Diff 中残留调试输出或注释掉的代码 | §8.4 |
-| 不合规范的 commit message（缺 gitmoji、类型错误、非英文） | §8.1 |
-| 缺失或隐瞒 AI 归属 | §8.2 |
+| 顺手重构、格式化清扫、无关的 `.gitignore` / CI 改动 | §4、§8.5 |
+| 分支命名不符合 `category/ticket-id-or-short-description` | §8.1 |
+| 不合规范的 commit message（缺 gitmoji、类型错误、非英文） | §8.2 |
+| 缺失或隐瞒 AI 归属 | §8.3 |
+| Diff 中残留调试输出或注释掉的代码 | §8.5 |
 | 虚假勾选 PR checklist 条目 | §8.6 |
-| Force-push 或 close/reopen 用来重置 review 状态 | §8.5 |
+| Force-push 或 close/reopen 用来重置 review 状态 | §8.7 |
diff --git a/AGENTS.md b/AGENTS.md
index d6711c625..facbef8e8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -105,6 +105,45 @@ public symbol as frozen unless a maintainer decides otherwise.
 - If a breaking change is genuinely unavoidable, stop and raise it in an
   issue for maintainers to decide. Do not merge-request it unilaterally.
 
+### Extra scrutiny in security- and network-critical areas
+
+Some parts of dio have oversized blast radius when broken. Changes here
+require extra care, and the PR description should explicitly call the
+change out and @-mention a maintainer:
+
+- SSL / TLS handling and certificate pinning (`badCertificateCallback`,
+  `SecurityContext`, adapters' `HttpClient` configuration).
+- Redirect handling and cross-origin behavior (redirect policy, header
+  forwarding, cookie leakage across redirects).
+- Cookie management (`dio_cookie_manager`, domain / path matching).
+- Header handling (`Authorization`, `Content-Type`, casing, duplicates).
+- Timeout, cancellation, and connection pooling.
+- The interceptor pipeline (ordering, error propagation, `next` /
+  `resolve` / `reject` semantics).
+- Request-body encoding: `FormData`, multipart streaming, encoding
+  detection.
+
+Rule of thumb: if getting this wrong could leak credentials, hang a
+request forever, or change data on the wire, treat it as sensitive.
+
+### Dependency changes
+
+Do not bundle drive-by dependency bumps into a feature/fix PR. When a
+dependency change is itself the point of the PR:
+
+- State the reason in the description (security fix, required for a new
+  feature, upstream deprecation, etc.). "Latest is greater" is not a
+  reason.
+- Verify the change under every supported SDK version declared in the
+  affected `pubspec.yaml`. Do not raise the package's SDK lower bound
+  just to accommodate the new dependency unless the
+  [Compatibility Policy](COMPATIBILITY_POLICY.md) allows it.
+- Prefer the narrowest constraint that solves the problem (patch >
+  minor > major bump).
+- Call out any new transitive dependencies — downstream users care about
+  their lockfile.
+- Use `⬆️ chore` (or `chore(deps)`) as the commit type.
+
 ## 4. Understand before you change
 
 - Read the surrounding code and existing patterns before editing. Match
@@ -182,7 +221,27 @@ Each package versions and releases independently. Note that packages have
 
 ## 8. Commits, changelog, and PR hygiene
 
-### 8.1 Commit message format — gitmoji + Conventional
+### 8.1 Branch naming
+
+Work on a feature branch named `category/ticket-id-or-short-description`:
+
+- `category` matches the Conventional type used in the commit:
+  `feat`, `fix`, `perf`, `refactor`, `docs`, `test`, `chore`, `ci`,
+  `style`.
+- Use the tracked **ticket id** when one exists — the issue or PR
+  number: `fix/2201`, `feat/2555`. Combining both is fine when it aids
+  discoverability: `fix/2201-cookie-domain-match`.
+- Otherwise use a **short description** — 2–5 kebab-case words that
+  describe the change (`docs/agents-guidelines`,
+  `feat/cors-preflight-warning`, `chore/bump-http2-3.0.0`).
+
+Rules:
+
+- Never work on `main` directly.
+- One branch per PR; do not reuse a merged branch for a new change.
+- Keep branch names ASCII, lowercase, and short.
+
+### 8.2 Commit message format — gitmoji + Conventional
 
 Every commit uses **[gitmoji](https://gitmoji.dev)** at the front and a
 **[Conventional Commits](https://www.conventionalcommits.org)** type
@@ -232,7 +291,7 @@ Examples (adapted from actual repo history):
 📝 docs: add agent contribution guidelines
 ```
 
-### 8.2 AI attribution — mandatory
+### 8.3 AI attribution — mandatory
 
 Transparency about AI involvement is required. Do not hide it, and do not
 skip it "to keep the commit clean".
@@ -257,7 +316,7 @@ skip it "to keep the commit clean".
   owns every line, must understand it, and must respond to review feedback
   substantively. "The AI wrote it" is not an answer to a review question.
 
-### 8.3 CHANGELOG and docs
+### 8.4 CHANGELOG and docs
 
 - Update the `CHANGELOG.md` of **every package you changed**, under
   `## Unreleased` (replace `*None.*`).
@@ -267,7 +326,7 @@ skip it "to keep the commit clean".
 - When public APIs change, also update `README.md`, `README-ZH.md`, API
   doc comments, and any affected examples.
 
-### 8.4 Self-review your diff before every commit
+### 8.5 Self-review your diff before every commit
 
 Always inspect what you are about to commit:
 
@@ -290,7 +349,22 @@ Remove before committing:
 If you cannot explain why a hunk is in the diff, it does not belong in
 the commit. Never use `git add .` or `git add -A` — stage files by path.
 
-### 8.5 Review iteration workflow
+### 8.6 Opening the PR
+
+- **Open as a draft PR** (`Create draft pull request`) when the change
+  is large, exploratory, or when you want maintainer direction before
+  polishing. Convert to Ready for Review once local checks pass and the
+  description is complete.
+- Reference the closing issue with `Closes #NNNN` in the description.
+- Follow the AI attribution rules in §8.3: disclose which agent(s)
+  contributed and at which stage.
+- Write PR titles and bodies in English, in the same commit style as
+  §8.2.
+- Only tick a PR checklist item that is genuinely done. For items that
+  do not apply, keep the box unchecked and add *(not applicable —
+  reason)* next to it. Do not check "done" as a shortcut.
+
+### 8.7 Review iteration workflow
 
 After opening the PR:
 
@@ -315,14 +389,30 @@ After opening the PR:
   genuinely flaky, say so in a comment — do not paper over it by
   disabling the test or adding retries.
 
-### 8.6 Fill in the PR template truthfully
+### 8.7 Review iteration workflow
 
-- Only tick a checklist item that is genuinely done. For items that do
-  not apply, keep the box unchecked and add *(not applicable — reason)*
-  next to it. Do not check "done" as a shortcut.
-- Reference the closing issue with `Closes #NNNN` in the description.
-- Write PR titles and bodies in English, in the same commit style as
-  §8.1.
+After opening the PR:
+
+- **Address feedback with new commits appended to the branch**, not by
+  squash-and-force-push. Maintainers rely on incremental history during
+  review; squashing happens at merge time.
+- **Avoid `git push --force` on a branch that already has review
+  comments** — it detaches those comments from their code position. If a
+  rebase is genuinely required (e.g., conflict resolution against
+  `main`), leave a comment before pushing so reviewers know.
+- **Do not close and reopen the PR** to reset review state, retry CI, or
+  bypass a blocking review. Push a fix instead.
+- **Design-level feedback is a conversation, not an instruction.** If a
+  reviewer's suggestion changes the intent of the PR (not just its
+  implementation), reply first and reach agreement before writing new
+  code. Blindly applying a large suggestion is worse than discussing it.
+- **Mark review threads resolved** only after you have addressed the
+  point in code and left a reply explaining what changed — or after the
+  reviewer explicitly says so. Do not silently resolve.
+- **CI failures**: read the failing job's log, find the root cause, then
+  push a fix. Never re-run CI hoping for a green run. If a test is
+  genuinely flaky, say so in a comment — do not paper over it by
+  disabling the test or adding retries.
 
 ## 9. Patterns that may lead to closure
 
@@ -336,10 +426,13 @@ at the maintainers' discretion.
 | Multiple unrelated changes bundled in one PR | §1 |
 | Logic changes without effective, non-duplicated tests | §2 |
 | Public-API break without maintainer sign-off | §3 |
+| Sensitive-area change without maintainer notice | §3 |
+| Drive-by dependency bump in a feature/fix PR | §3 |
 | Guessed / hallucinated API usage | §4 |
-| Drive-by refactors, formatting sweeps, unrelated `.gitignore` / CI edits | §4, §8.4 |
-| Debug output or commented-out code left in the diff | §8.4 |
-| Non-standard commit message format (missing gitmoji, wrong type, non-English) | §8.1 |
-| Missing or hidden AI attribution | §8.2 |
+| Drive-by refactors, formatting sweeps, unrelated `.gitignore` / CI edits | §4, §8.5 |
+| Branch name not following `category/ticket-id-or-short-description` | §8.1 |
+| Non-standard commit message format (missing gitmoji, wrong type, non-English) | §8.2 |
+| Missing or hidden AI attribution | §8.3 |
+| Debug output or commented-out code left in the diff | §8.5 |
 | Falsely checked PR checklist items | §8.6 |
-| Force-pushing or close/reopen to reset review state | §8.5 |
+| Force-pushing or close/reopen to reset review state | §8.7 |

From ee879a3c074def5ca68eb5b01453313217bf89b6 Mon Sep 17 00:00:00 2001
From: Alex Li <github@alexv525.com>
Date: Fri, 10 Jul 2026 17:13:08 +0800
Subject: [PATCH 4/6] =?UTF-8?q?=F0=9F=93=9D=20docs:=20describe=20verificat?=
 =?UTF-8?q?ion=20honestly=20instead=20of=20boilerplate=20test-plan=20check?=
 =?UTF-8?q?list?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

§8.6 (Opening the PR) now asks contributors to state what they actually
verified in prose, rather than a "Test plan" ticklist that mixes
mechanical prerequisites with behavioral tests. Anything that ought to
be verified but could not be goes under an explicit "Unverified"
paragraph — surfacing known risk instead of hiding it as an
unchecked-with-disclaimer item.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 AGENTS-ZH.md |  7 +++++++
 AGENTS.md    | 16 ++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/AGENTS-ZH.md b/AGENTS-ZH.md
index 810cbb7af..3e823e2a9 100644
--- a/AGENTS-ZH.md
+++ b/AGENTS-ZH.md
@@ -252,6 +252,13 @@ commit 前必须清除：
 - 遵循 §8.3 的 AI 归属规则：说明用了哪些 agent、参与了哪个阶段。
 - PR 标题和正文使用英文，风格与 §8.2 的 commit 一致。
 - 只勾选真正完成的 checklist 条目。对不适用的条目，保持未勾选并在旁边注明「（不适用——原因）」。不要为了「快点通过 checklist」而勾选。
+- **诚实描述已完成的验证——不要写套版式 "Test plan" 勾选清单。** 用一两句话散文式说明你实际验证了什么、怎么验证的：
+
+  > *添加了 15 个单元测试覆盖 method / content-type / custom-header 各种组合；`melos run test:vm` 与 `melos run analyze` 均通过。*
+
+  机械性的前置检查（`dart analyze`、`dart format`）已经由 PR 模板顶部的 checklist 覆盖——不要把它们当作「测试」再列一遍。行为验证指的是「本次改动如果回退，这条检查会失败」的那种检查。
+
+  如果确实有该验证但**无法**在本地验证的部分（需要浏览器 CI、真机、生产负载等等），单独用一小段 **Unverified** 段落说明**为什么**没验。未验证区域等于「已知风险」；这个段落应保持罕见，不能变成默认项。
 
 ### 8.7 Review 迭代工作流
 
diff --git a/AGENTS.md b/AGENTS.md
index facbef8e8..47ee30890 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -363,6 +363,22 @@ the commit. Never use `git add .` or `git add -A` — stage files by path.
 - Only tick a PR checklist item that is genuinely done. For items that
   do not apply, keep the box unchecked and add *(not applicable —
   reason)* next to it. Do not check "done" as a shortcut.
+- **Describe verification honestly — no boilerplate "Test plan"
+  checklist.** In prose, state what you actually confirmed and how, in
+  one or two sentences:
+
+  > *Added 15 unit tests covering method / content-type / custom-header
+  > combinations; `melos run test:vm` and `melos run analyze` clean.*
+
+  Mechanical prerequisites (`dart analyze`, `dart format`) are already
+  covered by the PR template's top-level checklist — do not re-list them
+  as "tests". Behavioral verification means checks that would fail if
+  this change regressed.
+
+  If something that ought to be verified genuinely could not be — needs
+  browser CI, a physical device, production load, and so on — list it
+  under a short **Unverified** paragraph explaining why. Unverified
+  items are known risks; this should stay rare, not become routine.
 
 ### 8.7 Review iteration workflow
 

From ffb035f7242d7bbb6a393e84950888c6d0ad1116 Mon Sep 17 00:00:00 2001
From: Alex Li <github@alexv525.com>
Date: Sat, 11 Jul 2026 10:52:13 +0800
Subject: [PATCH 5/6] =?UTF-8?q?=F0=9F=93=9D=20Fix=20deprecation=20hints?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS-ZH.md | 4 ++--
 AGENTS.md    | 5 ++---
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/AGENTS-ZH.md b/AGENTS-ZH.md
index 3e823e2a9..d4bd9f287 100644
--- a/AGENTS-ZH.md
+++ b/AGENTS-ZH.md
@@ -51,10 +51,10 @@ dio 的公开 API 是与庞大下游生态的契约。除非维护者另有决
 - 如果某个 API 确实必须移除，先废弃并保持其可用：
 
   ```dart
-  @Deprecated('Use XXX instead. This will be removed in 6.0.0')
+  @Deprecated('Use XXX instead. This will be removed in X.0.0')
   ```
 
-  废弃标注必须写明替代方案和移除版本，且只在下一个 major 版本中移除，同时在迁移指南中补充对应条目。目标是**下一个** major（当前为 `6.0.0`），而不是更远的版本。
+  废弃标注必须写明替代方案和移除版本，且只在下一个 major 版本中移除，同时在迁移指南中补充对应条目。目标是**下一个** major，而不是更远的版本。
 - 不得抬高任何 package 的 Dart/Flutter SDK 最低约束，除非 [兼容性政策](COMPATIBILITY_POLICY.md) 或其列出的例外情况要求如此。CI 会针对最低支持的 SDK 运行测试；不要使用超出 package 下限的语言/库特性。
 - 同样警惕**行为性**的 breaking change：改变默认值、header 规范化、重定向/错误语义、interceptor 的时序或顺序，即使签名未变也可能破坏下游。
 - 如果破坏性改动确实不可避免，请停下来开 issue 交由维护者决定。不要单方面提交。
diff --git a/AGENTS.md b/AGENTS.md
index 47ee30890..7e2a2d30e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,13 +88,12 @@ public symbol as frozen unless a maintainer decides otherwise.
 - If an API must go away, deprecate first and keep it working:
 
   ```dart
-  @Deprecated('Use XXX instead. This will be removed in 6.0.0')
+  @Deprecated('Use XXX instead. This will be removed in X.0.0')
   ```
 
   Deprecations must state their replacement and the removal version, and
   are only removed in the next major release, together with an entry in
-  the Migration Guide. Target the *next* major (currently `6.0.0`), not a
-  version beyond that.
+  the Migration Guide. Target the *next* major, not a version beyond that.
 - Do not raise the minimum Dart/Flutter SDK constraint of any package
   unless required by the [Compatibility Policy](COMPATIBILITY_POLICY.md)
   or its listed exceptions. CI tests against the minimum supported SDK;

From 80a670e02132e53dfad88536758289788886f7b6 Mon Sep 17 00:00:00 2001
From: Alex Li <github@alexv525.com>
Date: Sat, 11 Jul 2026 10:52:24 +0800
Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=93=9D=20Fix=20commit=20message=20pre?=
 =?UTF-8?q?fix?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS-ZH.md | 16 +++++++++-------
 AGENTS.md    | 16 +++++++++-------
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/AGENTS-ZH.md b/AGENTS-ZH.md
index d4bd9f287..20ec22b99 100644
--- a/AGENTS-ZH.md
+++ b/AGENTS-ZH.md
@@ -154,12 +154,14 @@ melos bootstrap
 - 每个 PR 一个分支；不要把已合并的分支重新用于新的改动。
 - 分支名保持 ASCII、小写、简短。
 
-### 8.2 Commit message 格式——gitmoji + Conventional
+### 8.2 Commit message 格式 —— Gitmoji 或 Conventional
 
-每条 commit 使用 **[gitmoji](https://gitmoji.dev)** 打头，并加上 **[Conventional Commits](https://www.conventionalcommits.org)** 类型前缀。emoji 从 gitmoji 规范中选取——不要自己发明。
+每条 commit 使用 **[gitmoji](https://gitmoji.dev)** 打头，或使用 **[Conventional Commits](https://www.conventionalcommits.org)** 类型前缀。emoji 从 gitmoji 规范中选取——不要自己发明。
 
 ```
-<gitmoji> <type>[(<scope>)]: <简短祈使句主题>
+<gitmoji> <简短祈使句主题>
+(或者)
+<type>[(<scope>)]: <简短祈使句主题>
 
 [可选正文，每行约 72 字符]
 
@@ -189,14 +191,14 @@ melos bootstrap
 
 - 主题使用英文祈使句。不要手动加 PR 号——GitHub 在 squash-merge 时会自动追加 `(#N)`。
 - Scope 用于澄清（`fix(dio_web_adapter): ...`）；如果 scope 只是重复了路径信息，就省略。
-- 位置 0 是 emoji。空格，然后 Conventional 前缀，再是主题。
+- 位置 0 是 emoji 或者 Conventional 前缀加冒号，然后空格，再是主题。
 
 示例（改编自真实仓库历史）：
 
 ```
-🐛 fix(dio): allow `callFollowingErrorInterceptor` when rejecting in `ErrorInterceptorHandler`
-⚡️ perf(dio): reduce `FormData.readAsBytes` memory usage for large payloads
-📝 docs: add agent contribution guidelines
+🐛 Allow `callFollowingErrorInterceptor` when rejecting in `ErrorInterceptorHandler`
+perf(dio): reduce `FormData.readAsBytes` memory usage for large payloads
+docs: add agent contribution guidelines
 ```
 
 ### 8.3 AI 归属——必须声明
diff --git a/AGENTS.md b/AGENTS.md
index 7e2a2d30e..88305845d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -240,15 +240,17 @@ Rules:
 - One branch per PR; do not reuse a merged branch for a new change.
 - Keep branch names ASCII, lowercase, and short.
 
-### 8.2 Commit message format — gitmoji + Conventional
+### 8.2 Commit message format — Gitmoji or Conventional
 
-Every commit uses **[gitmoji](https://gitmoji.dev)** at the front and a
+Every commit uses **[gitmoji](https://gitmoji.dev)** at the front or a
 **[Conventional Commits](https://www.conventionalcommits.org)** type
 prefix. Emojis are chosen from the gitmoji specification — do not invent
 new ones.
 
 ```
-<gitmoji> <type>[(<scope>)]: <short imperative subject>
+<gitmoji> <Short imperative subject>
+(or)
+<type>[(<scope>)]: <short imperative subject>
 
 [optional body — wrap at ~72 chars]
 
@@ -280,14 +282,14 @@ Rules:
   GitHub adds `(#N)` automatically on squash-merge.
 - Use scope when it clarifies (`fix(dio_web_adapter): ...`); omit when it
   would just repeat the file path.
-- Emoji at position 0. Space, then the Conventional prefix, then subject.
+- Emoji at position 0 or the Conventional prefix plus the colon. Then the space, then the Conventional prefix, then subject.
 
 Examples (adapted from actual repo history):
 
 ```
-🐛 fix(dio): allow `callFollowingErrorInterceptor` when rejecting in `ErrorInterceptorHandler`
-⚡️ perf(dio): reduce `FormData.readAsBytes` memory usage for large payloads
-📝 docs: add agent contribution guidelines
+🐛 Allow `callFollowingErrorInterceptor` when rejecting in `ErrorInterceptorHandler`
+perf(dio): reduce `FormData.readAsBytes` memory usage for large payloads
+docs: add agent contribution guidelines
 ```
 
 ### 8.3 AI attribution — mandatory