df-test-framework 4.10.2__tar.gz → 4.10.3__tar.gz

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/.github/workflows/docs.yml

@@ -30,9 +30,12 @@ jobs:
     timeout-minutes: 10
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
-    - uses: astral-sh/setup-uv@v3
+    - uses: astral-sh/setup-uv@v7
+      with:
+        version: "latest"
+        enable-cache: false
 
     - name: 安装依赖
       run: uv sync

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/.github/workflows/lint.yml

@@ -24,15 +24,18 @@ jobs:
 
     steps:
     - name: 检出代码
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: 设置Python 3.12
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 
     - name: 安装uv
-      uses: astral-sh/setup-uv@v3
+      uses: astral-sh/setup-uv@v7
+      with:
+        version: "latest"
+        enable-cache: false
 
     - name: 同步依赖
       run: |

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/.github/workflows/release.yml

@@ -26,10 +26,10 @@ jobs:
 
     steps:
     - name: 检出代码
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: 设置Python 3.12
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 
@@ -53,10 +53,10 @@ jobs:
 
     steps:
     - name: 检出代码
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: 设置Python 3.12
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 
@@ -66,7 +66,10 @@ jobs:
         pip install build twine
 
     - name: 安装uv
-      uses: astral-sh/setup-uv@v3
+      uses: astral-sh/setup-uv@v7
+      with:
+        version: "latest"
+        enable-cache: false
 
     - name: 安装锁定的检查工具
       run: uv sync --locked
@@ -116,7 +119,7 @@ jobs:
         "$RUNNER_TEMP/release-smoke/bin/python" -I "$GITHUB_WORKSPACE/scripts/smoke_config_release.py" "$EXPECTED"
 
     - name: 上传构建产物
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v6
       with:
         name: dist-packages
         path: dist/
@@ -141,7 +144,7 @@ jobs:
 
     steps:
     - name: 下载构建产物
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v7
       with:
         name: dist-packages
         path: dist/
@@ -171,18 +174,18 @@ jobs:
 
     steps:
     - name: 检出代码
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
       with:
         fetch-depth: 0  # 获取完整历史用于生成changelog
 
     - name: 下载构建产物
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v7
       with:
         name: dist-packages
         path: dist/
 
     - name: 设置Python 3.12
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 
@@ -195,7 +198,7 @@ jobs:
         python scripts/check_release.py "$VERSION" --notes release_notes.md
 
     - name: 创建GitHub Release
-      uses: softprops/action-gh-release@v2
+      uses: softprops/action-gh-release@v3
       with:
         name: v${{ steps.changelog.outputs.version }}
         body_path: release_notes.md

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/.github/workflows/scheduled.yml

@@ -13,15 +13,18 @@ jobs:
 
     steps:
     - name: 检出代码
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: 设置Python 3.12
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 
     - name: 安装uv
-      uses: astral-sh/setup-uv@v3
+      uses: astral-sh/setup-uv@v7
+      with:
+        version: "latest"
+        enable-cache: false
 
     - name: 同步依赖
       run: |
@@ -99,10 +102,10 @@ jobs:
 
     steps:
     - name: 检出代码
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: 设置Python 3.12
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/.github/workflows/security.yml

@@ -20,10 +20,10 @@ jobs:
 
     steps:
       - name: 检出代码
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 设置 Python 环境
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
           cache: 'pip'
@@ -84,7 +84,7 @@ jobs:
           fi
 
       - name: 上传扫描报告
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         if: always()
         with:
           name: security-reports-${{ github.run_number }}
@@ -166,10 +166,10 @@ jobs:
 
     steps:
       - name: 检出代码
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 设置 Python 环境
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
           cache: 'pip'
@@ -205,7 +205,7 @@ jobs:
           fi
 
       - name: 上传质量报告
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         if: always()
         with:
           name: quality-reports-${{ github.run_number }}
@@ -221,7 +221,7 @@ jobs:
 
     steps:
       - name: 检出代码
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0  # 获取完整历史，检查所有提交
 
@@ -231,6 +231,6 @@ jobs:
           extra_args: --only-verified
 
       - name: Gitleaks - 备用密钥扫描
-        uses: gitleaks/gitleaks-action@v2
+        uses: gitleaks/gitleaks-action@v3
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/.github/workflows/test.yml

@@ -50,15 +50,18 @@ jobs:
 
     steps:
     - name: 检出代码
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: 设置Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 
     - name: 安装uv
-      uses: astral-sh/setup-uv@v3
+      uses: astral-sh/setup-uv@v7
+      with:
+        version: "latest"
+        enable-cache: false
 
     - name: 同步依赖（使用 uv sync）
       run: |
@@ -140,15 +143,18 @@ jobs:
 
     steps:
     - name: 检出代码
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: 设置Python 3.12
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 
     - name: 安装uv
-      uses: astral-sh/setup-uv@v3
+      uses: astral-sh/setup-uv@v7
+      with:
+        version: "latest"
+        enable-cache: false
 
     - name: 同步依赖
       run: |

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/AGENTS.md

@@ -8,8 +8,8 @@ This file provides guidance to Codex (Codex.ai/code) when working with code in t
 
 **DF Test Framework** - 现代化 Python 测试自动化框架
 
-- **版本**: v4.10.2
-- **更新时间**: 2026-10-10
+- **版本**: v4.10.3
+- **更新时间**: 2026-11-04
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/CHANGELOG.md

@@ -7,6 +7,51 @@
 
 ## [Unreleased]
 
+## [4.10.3] - 2026-11-04
+
+> 含 HTTP 重试参数与请求参数的破坏性变更。维护者指定按 PATCH 发布，依据是消费项目
+> 由内部统一维护并同步迁移；详见 [v4.10.3 发布说明](docs/releases/v4.10.3.md)。
+
+### HTTP 重试参数统一（破坏性变更）
+
+- HTTPConfig、HttpClient/AsyncHttpClient、RetryMiddleware 及其配置统一使用 `retries`，
+  表示首次之外的额外次数；默认值为 0。单请求 `retries=N` 覆盖，`None` 继承。
+- 移除 HTTP `max_retries`，环境变量改为 `HTTP__RETRIES`。YAML 中的旧键 `max_retries`
+  不再读取，升级时须改名；工厂、Provider、CLI、生成模板及当前指南同步迁移。
+- 同一客户端只保留一个重试执行器，手动配置替换默认执行器，避免叠加放大发送次数。
+  重试耗尽以最后一次响应或异常为准，显式空状态码/异常列表不回退默认值。
+- 详细迁移见 [HTTP 客户端指南](docs/guides/http_client_guide.md#从旧名称迁移)。
+
+### HTTP 请求参数显式化（破坏性变更）
+
+- 同步/异步客户端只接受已支持的请求参数，未识别参数（如拼写错误 `jsoon=`、`timout=`）
+  在发送前报 `TypeError`，不再被静默丢弃。
+- 新增单请求 `follow_redirects`；此前该参数被丢弃，始终按客户端默认跟随重定向。
+- 修复多值查询参数被压掉同名值：`params=[("a","1"),("a","2")]` 此前实际只发送 `?a=2`；
+  现统一规范为字典（多值为列表），支持键值对序列、查询字符串与 `httpx.QueryParams`。
+- 修复 `ApiKeyMiddleware` 查询参数模式在请求未传 `params` 时报 `TypeError`。
+- 新增 [HTTP 客户端接口支持面方案](docs/development/http-client-interface-plan.md)（讨论草案）。
+
+### 国密导出修复
+
+- 修复包级 `sm3` 被同名实现子模块遮蔽：先使用 `SM3Hasher` 等后，`crypto.sm3` 变成模块，
+  `sm3()` 与 `digest_sign(algorithm="sm3")` 报 `'module' object is not callable`。
+  实现模块改为私有 `_sm2/_sm3/_sm4/_aes`，公共接口仍从 `infrastructure.crypto` 包导入。
+
+### 运行依赖修复
+
+- 补齐同步 HTTP/GraphQL 在运行中事件循环调用所需的 `nest-asyncio` 核心依赖。
+  原安装包在 API 与 Playwright 混合回归的后续前置中可能报缺模块；
+  修复依赖声明及嵌套循环请求回归，不改客户端公开接口或业务项目配置。
+
+### CI 与脚手架
+
+- 仓库工作流和 GitHub Actions 脚手架模板升级为 Node.js 24 Action：
+  checkout v5、setup-python v6、setup-uv v7、upload-artifact v6、
+  download-artifact v7、action-gh-release v3、gitleaks-action v3。
+- setup-uv 显式保留安装 latest uv 与关闭缓存的策略，避免升级默认值改变执行行为；
+  模板更新随下一版包交付，已发布版本与标签保持不变。
+
 ## [4.10.2] - 2026-10-10
 
 ### 配置按环境隔离（破坏性配置迁移，维护者指定 PATCH）

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/CLAUDE.md

@@ -8,8 +8,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **DF Test Framework** - 现代化 Python 测试自动化框架
 
-- **版本**: v4.10.2
-- **更新时间**: 2026-10-10
+- **版本**: v4.10.3
+- **更新时间**: 2026-11-04
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: df-test-framework
-Version: 4.10.2
+Version: 4.10.3
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Author-email: DF QA Team <qa@example.com>
 License: MIT
@@ -28,6 +28,7 @@ Requires-Dist: jinja2>=3.1.0
 Requires-Dist: jsonpath-ng>=1.7.0
 Requires-Dist: jsonschema-spec>=0.2.4
 Requires-Dist: jsonschema>=4.25.1
+Requires-Dist: nest-asyncio>=1.6.0
 Requires-Dist: openpyxl>=3.1.0
 Requires-Dist: pluggy>=1.5.0
 Requires-Dist: prance[osv]>=23.6.0

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/README.md

@@ -1,7 +1,7 @@
 # DF Test Framework
 
-> **版本**: v4.10.2
-> **更新时间**: 2026-10-10
+> **版本**: v4.10.3
+> **更新时间**: 2026-11-04
 > 简单、强大、可扩展的现代化 Python 测试自动化框架
 
 [![PyPI version](https://img.shields.io/pypi/v/df-test-framework.svg)](https://pypi.org/project/df-test-framework/)

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/docs/ESSENTIAL_DOCS.md

@@ -1,8 +1,8 @@
 # 核心文档导航 - 真正有价值的文档清单
 
 > **目标读者**: 测试开发人员、框架使用者、新团队成员
-> **更新日期**: 2026-10-10
-> **框架版本**: v4.10.2
+> **更新日期**: 2026-11-04
+> **框架版本**: v4.10.3
 
 ---
 

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/docs/README.md

@@ -1,6 +1,6 @@
 # DF Test Framework 文档中心
 
-> 版本：v4.10.2 · 最近更新：2026-09-01
+> 版本：v4.10.3 · 最近更新：2026-09-01
 > 现代化 Python 测试自动化框架的官方知识库。
 
 ---

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/docs/architecture/CODE_STRUCTURE.md

@@ -281,7 +281,7 @@ infrastructure/plugins/
 infrastructure/helpers/
 ├── __init__.py          # 统一导出
 ├── hash.py              # MD5/SHA256/HMAC-SHA256（基于 stdlib）
-├── crypto.py            # AES 文本门面（实现在 infrastructure/crypto/aes.py，需 crypto extra）
+├── crypto.py            # AES 文本门面（实现在 infrastructure/crypto/_aes.py，需 crypto extra）
 ├── national_crypto.py   # 国密便捷层 SM2Cipher/SM2Signer/SM4Cipher（需 gm extra）
 ├── signature.py         # API 参数签名计算
 └── network.py           # 公网 IP 探测
@@ -289,7 +289,7 @@ infrastructure/helpers/
 
 **关键函数**：
 - `md5(text)` / `sha256(text)` / `hmac_sha256(text, secret)` - 哈希函数
-- `aes_encrypt()` / `aes_decrypt()` - AES-CBC/ECB 文本门面（字节核心在 `infrastructure/crypto/aes.py`，需 `crypto` 可选依赖）
+- `aes_encrypt()` / `aes_decrypt()` - AES-CBC/ECB 文本门面（字节核心在 `infrastructure/crypto/_aes.py`，需 `crypto` 可选依赖）
 - `compute_sign(params, secret)` - API 参数签名（支持 MD5/SHA256/HMAC-SHA256）
 - `get_public_ip()` - 公网出口 IP 探测
 

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/docs/architecture/multi-project-reuse.md

@@ -238,7 +238,7 @@ class MicroserviceConfig(BaseModel):
     name: str
     base_url: str
     timeout: int = 30
-    max_retries: int = 3
+    retries: int = 3
     api_version: str = "v1"
 
 class AuthConfig(BaseModel):

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/docs/architecture/national-crypto-design.md

@@ -48,7 +48,7 @@ SM3 一次性和增量摘要；HMAC-SM3；SM4-GCM 与 CBC/ECB 协议互操作。
 它是新 API 的便利门面，不是已删除旧接口的兼容包装。
 
 **结构规则（2026-09-22 评审决定，本批已落实）**：`infrastructure/crypto/` 是所有密码原语的唯一归属，
-helpers 只放文本/编码门面。AES 已同批归位：`crypto/aes.py` 字节核心（pycryptodome，`crypto` extra），
+helpers 只放文本/编码门面。AES 已同批归位：`crypto/_aes.py` 字节核心（pycryptodome，`crypto` extra），
 `helpers/crypto.py` 保留原 `aes_encrypt/aes_decrypt` 签名只做编码转换。`crypto` 包按子模块懒加载，
 导入包不绑定任何 extra，缺哪组依赖只影响对应算法。不得再向 helpers 新增算法实现。
 
@@ -150,13 +150,15 @@ SM4 nonce/IV 每次调用时传入，不保存在配置对象中。不自动生
 ## 6. 实现地图
 
 以下路径均相对仓库根目录；公开入口可以从 `df_test_framework` 按需导入。
+`crypto/` 下带下划线前缀的实现模块是私有的，只通过 `infrastructure.crypto` 包导入公共接口，
+避免子模块与同名导出（如 `sm3`）互相遮蔽。
 
 | 文件 | 实现职责 |
 |---|---|
-| `infrastructure/crypto/sm2.py`（位于 `src/df_test_framework/` 下） | 密钥对象、ASN.1、SM2 消息签名及密文格式 |
-| 同目录 `sm3.py`、`sm4.py`、`_common.py` | 摘要/MAC、模式专用 SM4、字节类型校验 |
+| `infrastructure/crypto/_sm2.py`（位于 `src/df_test_framework/` 下） | 密钥对象、ASN.1、SM2 消息签名及密文格式 |
+| 同目录 `_sm3.py`、`_sm4.py`、`_common.py` | 摘要/MAC、模式专用 SM4、字节类型校验 |
 | `src/df_test_framework/infrastructure/helpers/national_crypto.py` | 文本/编码便捷对象与密钥加载器 |
-| `src/df_test_framework/infrastructure/crypto/aes.py`、`helpers/crypto.py` | AES 字节核心与保留签名的文本门面（`crypto` extra） |
+| `src/df_test_framework/infrastructure/crypto/_aes.py`、`helpers/crypto.py` | AES 字节核心与保留签名的文本门面（`crypto` extra） |
 | `src/df_test_framework/infrastructure/crypto/__init__.py` | 核心导出、缺 extra 的安装提示 |
 | `src/df_test_framework/infrastructure/helpers/__init__.py` | 便捷层懒加载导出 |
 | `src/df_test_framework/__init__.py` | 顶层懒加载及类型检查入口 |

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/docs/architecture/test-type-support.md

@@ -80,7 +80,7 @@ class HttpClient:
     def _execute_with_retry(self, method: str, url: str, **kwargs):
         last_exception = None
 
-        for attempt in range(self._max_retries + 1):
+        for attempt in range(self._retries + 1):
             try:
                 response = self._client.request(method, url, **kwargs)
 
@@ -88,17 +88,17 @@ class HttpClient:
                 if response.status_code < 500:
                     return response
 
-                if attempt < self._max_retries:
+                if attempt < self._retries:
                     self._logger.warning(
                         f"请求失败 ({response.status_code})，"
                         f"将在 {self._retry_delay * (2 ** attempt)}s 后重试..."
                     )
             except (httpx.ConnectError, httpx.TimeoutException) as e:
                 last_exception = e
-                if attempt < self._max_retries:
+                if attempt < self._retries:
                     self._logger.warning(f"连接错误，将重试: {e}")
 
-            if attempt < self._max_retries:
+            if attempt < self._retries:
                 delay = self._retry_delay * (2 ** attempt)  # 指数退避
                 time.sleep(delay)
 
@@ -109,7 +109,7 @@ class HttpClient:
 
 ```python
 class HTTPConfig(BaseModel):
-    max_retries: int = 3        # 最大重试次数
+    retries: int = 3        # 最大重试次数
     retry_delay: float = 1.0    # 初始重试延迟（秒）
     retry_on_status: List[int] = [500, 502, 503, 504]  # 重试的状态码
 ```

{df_test_framework-4.10.2 → df_test_framework-4.10.3}/docs/development/BACKLOG.md

@@ -49,6 +49,8 @@
 | 12 | ✅ 文档大修四篇（2026-08-20 完成：USER_MANUAL 导航型、TEST_EXECUTION_LIFECYCLE 七层模型重写、extension-points 合并 api-reference/extensions、BEST_PRACTICES 吸收 VERIFIED 实战模式并按 v4.9 API 更新；顺带更新 observability-architecture 现状标记） | 完成 | 2026-08-20 整理批次只做了"部分过时"警示头，完整重写待办：USER_MANUAL 瘦身为导航型（停止维护与 guides 重复的示例）、TEST_EXECUTION_LIFECYCLE 按七层模型重写（45KB）、extension-points 与 api-reference/extensions 合并、BEST_PRACTICES 深度合并（吸收 VERIFIED 的实战片段） |
 | ~~14~~ | ~~PageMock 轮换/延迟响应~~（v4.9.23 已完成：route_json_sequence + 全注册方法 delay_ms，双轨镜像+对账） | ~~低~~ | yx-mixue 收敛批（2026-08-21）发现：PageMock 不支持按调用轮换响应与延迟响应，项目留 74 行扩展 tests/ui/page_mock_extensions.py（route_json_sequence/route_delayed_json）——第二个项目需要时下沉框架（双轨镜像 AsyncPageMock） |
 | 13 | 统一推送远端 | **待用户确认** | v4.9.11 起本地累积提交（GitHub Actions 额度约束），一次 push origin master |
+| 15 | [HTTP 接口支持面设计](http-client-interface-plan.md) | 中 | 后续讨论草案，不扩大 v4.10.3 收尾范围。多值查询参数被压成 `?a=2` 的缺陷已于 v4.10.3 修复；后续按 extensions、认证策略与 auth、Cookie 管理、流式接口及其余参数表达能力推进；客户端默认跟随重定向保持不变。详细边界、待定项和验收要求见方案，排期另定 |
+| 16 | 消费项目迁移至 4.10.3 | 高（发布后） | Master/FSC：`max_retries`→`retries`（属性读取、构造参数、`model_copy` 键、测试桩、YAML、`HTTP__MAX_RETRIES` 文档），写接口改按请求声明 `retries=0`；切换前以本地源码跑单元、`--collect-only` 与代表性 API 用例，确认无未知参数 TypeError |
 
 ## 已决策记录
 

df_test_framework-4.10.3/docs/development/http-client-interface-plan.md

@@ -0,0 +1,134 @@
+# HTTP 客户端接口支持面方案
+
+> 状态：讨论草案，供后续实现评审；不代表已实现能力或排期承诺。
+> 整理日期：2026-11-04。
+> 入口：[Backlog 第 15 项](BACKLOG.md)。当前可用接口以
+> [HTTP 客户端指南](../guides/http_client_guide.md) 为准。
+
+## 1. 与 v4.10.3 的边界
+
+v4.10.3 已纳入未知请求参数报错、单请求 `follow_redirects` 生效、多值查询参数修复及 HTTP 重试统一。
+本方案记录后续支持面设计，不扩大该版本的收尾范围，也不要求先完成本方案才能发布。
+版本交付与迁移范围见 [v4.10.3 发布说明](../releases/v4.10.3.md)。
+
+框架默认跟随重定向的行为保持不变。最早的初始化提交 `4f81ff5` 已显式配置
+`follow_redirects=True`，[早期优化报告](../archive/v1/optimization-report.md)
+也将自动跟踪重定向列为已有能力。没有找到当初选择该默认值的详细理由。
+讨论中的“测试客户端默认不跟随更便于观察原始响应”是一个建议，未采纳为本框架的新默认。
+需要检查原始 301/302 响应时，使用单请求 `follow_redirects=False`。
+
+## 2. 问题与设计目标
+
+历史请求链路接收 `**kwargs`，提取部分字段构造框架 Request，中间件处理后再组装
+httpx 参数。没有进入 Request 的参数不会到达传输层，又未检查剩余参数，因而被静默忽略。
+提交 `d4c7a94`（v3.20.0）补入 `files/content`，`253742b`（v4.1.2）补入单请求
+`timeout`，说明支持面曾逐步接通；这些记录不能证明静默忽略是一项有意的扩展设计。
+
+设计目标同时包含两点：
+
+- 不认识或放错层级的顶层参数应明确报错，避免实际请求偏离用例声明。
+- 通用 HTTP 能力应有正式入口，不能仅因“当前项目没用”或“目前没接通”而永久排除。
+
+`**kwargs` 只是传参形式，不是完整支持底层能力的保证。公开接口应有清晰签名、类型与
+文档；便捷方法可透传到统一入口。支持范围与严格校验分别设计，不用放开任意 kwargs
+替代能力建设，也不把当前校验集合当成永久能力上限。
+
+## 3. 建议的能力边界
+
+以下是目标设计，不是 v4.10.3 的支持列表。实施前应先核对当前行为，已有能力不重复建设。
+
+| 能力 | 建议归属 | 必须保留的语义 |
+|---|---|---|
+| `method`、`url`、`params`、`headers` | 请求级 | 多值查询参数、重复请求头能够表达，不强制压成普通字典 |
+| `json`、`data`、`content`、`files` | 请求级 | JSON 对象/数组/标量、表单、原始内容、文件上传；不改变原始字节 |
+| `timeout` | 客户端默认值与单请求覆盖 | 简单秒数、分阶段超时；省略继承与显式禁用应有区别（当前单请求 `None`、`httpx.Timeout` 原样到达传输层，实施时先核对，可能只需补契约测试与文档） |
+| `follow_redirects` | 客户端默认值与单请求覆盖 | 框架默认 True，本次 False 有效；是否增加构造/配置入口另行评审 |
+| `auth` | 客户端策略与单请求选择 | 标准和自定义认证；与框架认证注入使用明确的选择规则 |
+| Cookie | 客户端容器与管理接口 | 域、路径、持久化、重定向语义；不通过临时修改共享容器模拟单请求覆盖 |
+| `extensions` | 请求级高级入口 | 保留 transport 扩展空间，与框架 metadata 分开 |
+| TLS、代理、连接池、HTTP/2、transport | 客户端构造级 | 连接与资源的生命周期属于客户端，不作为任意单请求参数传递 |
+| 流式传输 | 独立 `stream()` 接口 | 上下文管理、分段读取、关闭责任；框架不能预先完整读取响应 |
+| `retries` 等框架策略 | 框架执行层 | 与 HTTP 参数分清职责，仍经过统一中间件和观测链路 |
+
+名称接通不代表完整支持：还要检查参数值经过模型、签名中间件、事件与传输层时是否
+丢失信息。请求体为 JSON 数组、重复参数或原始字节时，不应被框架转换成另一种请求。
+
+## 4. 后续能力的具体建议
+
+### 4.1 `extensions`：建议接通
+
+在明确的 `extensions` 字典中保留传输层扩展，不对白名单之外的内部键一律拒绝。
+框架负责传递，具体扩展是否有效由 transport 契约决定；不能承诺所有 transport
+都理解任意扩展。框架自有上下文仍放在独立 metadata 中，避免两个命名空间混用。
+与 `timeout` 等正式参数涉及同一控制项时，应遵循并说明底层优先级。
+
+### 4.2 `auth`：建议支持，先定认证选择规则
+
+已有 BearerToken 中间件不构成排除 Basic、Digest 或自定义认证的理由。
+建议方向是：省略时继承客户端认证策略，显式 auth 时选择本次策略，不再由框架默认
+认证注入覆盖它；显式禁用认证也应有明确表达。
+
+实施前必须确定 `auth` 与 `token`、`skip_auth`、显式 Authorization 请求头的关系，
+包括冲突时如何报错或选择。具体签名及“未指定”表示法尚未定稿，不以普通 None 同时
+表达继承和禁用两种语义，也不依赖中间件先后执行来偶然决定最终认证。
+
+Digest 等认证可能在 httpx 内部发生多轮网络交互，不能假定每轮都会重新进入框架
+中间件。需要说明框架事件记录的是逻辑调用还是每次网络发送，并核对签名、重试及
+脱敏的边界，不能把逻辑调用次数等同于实际发送次数。
+
+### 4.3 Cookie：维持客户端管理方向
+
+补齐必要的设置、读取、清理接口和语义说明，不新增单请求 `cookies=`。
+精确构造某次 Cookie 请求头可使用 `headers`；这与完整 Cookie 容器管理不同。
+实施时验证客户端容器、显式 Cookie 头与重定向的实际交互，不承诺二者任意叠加。
+
+### 4.4 流式传输：独立设计接口
+
+通过 `stream()` 明确响应生命周期，同步/异步保持对等，正常结束、异常或提前退出都
+应释放资源。复用请求准备、认证与框架观测，不另建一条无观测的裸客户端旁路。
+读取正文的责任交给调用者；事件和报告不能为了记录正文而耗尽流。
+不可重放请求体及响应开始交付后的重试边界需要明确，不能直接套用普通请求自动重试。
+
+### 4.5 参数表达能力：按链路补全（优先）
+
+先检查 JSON 数组/标量、多值查询参数、文件/原始内容等现有语义，再处理重复请求头。
+重复请求头可能影响 Request/Response 模型、中间件、脱敏和事件消费者，不能只改
+客户端签名。对已正确支持的情况补足契约或文档，不为形式统一重新实现。
+
+2026-11-04 用内存传输核对 v4.10.3 当前行为：
+
+| 输入 | 实际发送 | 结论 |
+|---|---|---|
+| `params=[("a", "1"), ("a", "2")]` | `?a=2` | 已确认缺陷，**v4.10.3 已修复**：请求入口规范为字典，同名多值为列表 |
+| `json=[1, 2]` | `[1,2]` | 运行时正确；`Request.json` 类型标注仅为 `dict`，需放宽并核对签名中间件假设 |
+| `files` 内存文件 + `retries=1` | 两次发送请求体均完整 | 当前无问题，流式与生成器请求体另在 4.4 定边界 |
+
+多值查询参数与“参数被静默丢弃”同属请求偏离用例声明且不报错，已并入 v4.10.3 修复：
+请求入口统一规范为字典（同名多值为列表），不改变 `Request.params` 公开类型，
+签名与事件中间件沿用字典取值；未采用 `httpx.QueryParams` 作为内部类型，因其会把值
+转为字符串（如 `True`→`"true"`），改变签名输入。同批修复 `ApiKeyMiddleware`
+查询参数模式在无 `params` 时的 `TypeError`。
+
+## 5. 推进顺序与验收
+
+已确认的多值查询参数失真已在 v4.10.3 修复。后续按 `extensions` → 认证策略与 `auth` → Cookie 接口补齐 → 流式接口 → 其余参数表达能力
+（JSON 类型标注、重复请求头）推进。理由：前者是不报错的请求失真，后几项是能力缺口，
+未接通时调用方会被明确拒绝。各项可独立评审，排期由维护者确定，不提前指定发布版本。
+客户端连接选项按缺口另行核对，不把所有 HTTPX 构造参数一次性复制到配置模型。
+
+每项实现至少确认：
+
+- 同步/异步公开接口和行为一致，未知顶层参数仍在发送前报错。
+- 参数实际到达传输层且改变对应行为，而非只断言内部字典出现某个键。
+- 客户端默认值、单请求覆盖、显式禁用的行为清晰；合并规则按参数分别定义。
+- 中间件、重试、事件、脱敏和资源释放仍成立；涉及认证多轮和流式传输时验证真实协议行为。
+- 指南、类型注解、必要的配置/工厂与迁移说明同步，代表性消费入口可用。
+
+## 6. 参考资料
+
+- [框架设计标准](../architecture/DESIGN_STANDARDS.md)：公开 API、双轨、执行核心与资源约束。
+- [HTTPX API](https://www.python-httpx.org/api/)：客户端构造、请求与流式接口。
+- [HTTPX Clients](https://www.python-httpx.org/advanced/clients/)：客户端与请求配置的合并。
+- [HTTPX Authentication](https://www.python-httpx.org/advanced/authentication/)：标准及自定义认证。
+- [HTTPX Extensions](https://www.python-httpx.org/advanced/extensions/)：传输扩展空间。
+- [HTTPX Compatibility](https://www.python-httpx.org/compatibility/)：重定向、Cookie 与流式行为。