df-test-framework 4.7.3__tar.gz → 4.7.5__tar.gz

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/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.7.3
-- **更新时间**: 2026-05-27
+- **版本**: v4.7.4
+- **更新时间**: 2026-06-29
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/CHANGELOG.md

@@ -7,6 +7,37 @@
 
 ## [Unreleased]
 
+## [4.7.5] - 2026-06-29
+
+### ✨ 新增
+
+- **能力层实例级可观测性注入**：`AsyncHttpClient(event_bus=...)` / `HttpEventPublisherMiddleware(event_bus=...)` 支持直接注入 `EventBus`，使能力层脱离 Bootstrap / RuntimeContext / 全局 `EventBus` 单例也可观测（嵌入/库式用法）。显式 `event_bus` 优先于 `runtime.event_bus`；两者皆无时中间件自然 no-op。这是可观测性架构现代化（从"全局单例事件总线"到"实例级注入监听器"）的基石，设计与分阶段方案见 [可观测性架构现代化设计](docs/architecture/observability-modernization.md)。
+- **`event_bus` 注入统一到所有事件型客户端**：同步 `HttpClient` 与 `GrpcClient` 构造参数补齐 `event_bus`（`AsyncHttpClient`、`GraphQLClient` 此前已有），并透传给各自 EventPublisher 中间件，注入模型统一。DB/MQ 不走 EventPublisher 中间件模型，无此参数。
+
+### 💥 移除
+
+- **`OmsReporterPlugin` 已移除**：该插件是 OMS 平台专用的 HTTP 事件上报插件。但 `Bootstrap().run()` 默认不注入 `runtime.event_bus`（恒为 None），`HttpEventPublisherMiddleware` 在 event_bus 为空时跳过发布，因此该插件在嵌入场景下实际从不触发。OMS 已改为零-Bootstrap、直接消费能力层（执行结果由其自身上报），框架不再保留 OMS 专用插件。v4.7.4 为其新增的 `bind_execution` / `unbind_execution` 一并移除。
+- **`df_event_handlers` Hook 移除**：事件订阅改为实例级注入模型——能力客户端 `AsyncHttpClient(event_bus=bus)`、监控/报告插件 `attach_to_event_bus(bus)`，取代"注册到全局事件总线"的旧钩子。`MonitoringPlugin` 的事件注册随之从 `df_event_handlers` 迁为 `attach_to_event_bus(bus)`。`AllurePlugin`（已废弃）中冗余的 `df_event_handlers` 实现一并删除。
+
+### 🔧 改进
+
+- **插件扩展 Hook 接线**：此前 `HookSpecs` 多数 Hook 仅定义未被框架触发（消费项目实现了也不生效）。现起把这些扩展点逐步接到对应调用点，使其成为测试项目/插件可用的真实能力。本版本已接线 `df_pre_bootstrap`（Bootstrap 初始化前回调，与既有 `df_post_bootstrap` 对称）与 **`df_http_middlewares`**（HTTP 客户端构建时收集插件贡献的中间件并 `use()` 应用，供项目注入全局鉴权/签名等中间件）。**`df_test_setup/teardown`**（每条测试前后，由 core pytest 插件的 autouse fixture 触发，携带 `request`+`runtime`）与 **`df_session_start/finish`**（`pytest_sessionstart/finish` 触发）也已接线。**`df_config_loaded`**（配置加载后回调，供插件读取/校验配置）也已接线。`df_db/mq_middlewares`（待 DB/MQ 客户端支持中间件）、`df_config_sources`、`df_telemetry_exporters` 为已恢复扩展点，按需接线（见扩展文档"接线状态"表）。
+
+### 🐛 修复
+
+- **`RuntimeContext.event_bus` 类型与语义不一致**：字段曾声明为必填 `EventBus`，但 `RuntimeBuilder` 默认 `None`、`close()` 按可空处理、纯库式构造也允许不注入——类型与实际矛盾。现统一为 `EventBus | None = None`，`publish_event` 在未注入时静默 no-op，与"实例级注入、不传则 opt-out"模型一致。
+- **`df_test_teardown` 的 `outcome` 恒为 `None`**：autouse fixture 此前固定传 `outcome=None`。现通过 `pytest_runtest_makereport` 捕获 call 阶段 `TestReport` 存入 `item.stash`，teardown 时传入真实结果（含 `.passed`/`.failed`/`.outcome`）。
+- **pytest 路径下 `df_plugins` 与生命周期钩子不生效**：`pytest_configure` 在 `env_plugin` 已加载配置时走 `RuntimeBuilder` 快速路径，绕过 `Bootstrap`，导致 `df_plugins` 未注册、`runtime.extensions` 为空，`df_pre/post_bootstrap`、`df_config_loaded`、`df_providers`、`df_http_middlewares` 等钩子全部不触发——上面"插件扩展 Hook 接线"的能力在常规 pytest 用法下形同虚设。现统一通过 `Bootstrap` 加载（`BootstrapApp.run(settings=...)` 新增参数复用 env_plugin 已加载的配置实例，避免重复加载），两条路径行为一致。
+- **`RuntimeContext.close()` 空指针**：当 runtime 设置了 `scope` 但未注入 `event_bus`（纯库式构造的 runtime）时，`close()` 访问 `event_bus.clear_scope` 会抛 `AttributeError`，已加判空。
+
+## [4.7.4] - 2026-06-29
+
+### ✨ 新增
+
+- **`OmsReporterPlugin` 嵌入式 scope 路由**：新增 `bind_execution(scope, callback, task_id, execution_id)` / `unbind_execution(scope)`，支持单个常驻插件实例按事件 `scope` 路由到对应执行的上报回调。嵌入方（如 OMS 测试平台）可一次 Bootstrap、多次执行复用，无需每次执行重建插件 + Bootstrap，多执行并发互不串扰。旧用法 `OmsReporterPlugin(callback, task_id, execution_id)` 完全向后兼容（构造即绑定一个作用域无关的默认上报目标）。
+
+**详细内容**: 查看完整发布说明 [v4.7.4](docs/releases/v4.7.4.md)
+
 ## [4.7.3] - 2026-05-27
 
 ### 💥 破坏性变更

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/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.7.3
-- **更新时间**: 2026-05-27
+- **版本**: v4.7.4
+- **更新时间**: 2026-06-29
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.7.3
+Version: 4.7.5
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/README.md

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

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/docs/ESSENTIAL_DOCS.md

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

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/docs/README.md

@@ -1,6 +1,6 @@
 # DF Test Framework 文档中心
 
-> 版本：v4.7.3 · 最近更新：2026-05-27
+> 版本：v4.7.4 · 最近更新：2026-06-29
 > 现代化 Python 测试自动化框架的官方知识库。
 
 ---
@@ -94,8 +94,9 @@
 | [Bootstrap 引导系统指南](guides/bootstrap_guide.md) | RuntimeContext，多数据库注册 |
 | [Fixtures 指南](guides/fixtures_guide.md) | pytest fixtures 完整参考 |
 | [装饰器指南](guides/decorators_guide.md) | `@api_class`、`@actions_class`、`@service_client` |
+| [插件 Hook 扩展指南](guides/plugin_hooks_guide.md) ⭐ | 注册插件、注入全局中间件、挂接测试/会话生命周期 |
 | [插件系统指南](guides/plugins_guide.md) | Pluggy Hooks，自定义插件 |
-| [扩展点指南](guides/extensions.md) | Hook 接入自定义能力 |
+| [扩展点指南](guides/extensions.md) | Hook 接入自定义能力（历史参考） |
 | [工具函数指南](guides/helpers_guide.md) | 加解密、哈希、签名、公网 IP |
 
 ---

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/docs/api-reference/extensions.md

@@ -2,6 +2,10 @@
 
 扩展系统的完整API参考，包含Hook机制、ExtensionManager和自定义扩展开发。
 
+> ℹ️ **Hook 体系状态（v4.7.5）**：Hook 是给测试项目/插件用的扩展点，框架在对应阶段触发。
+> `df_event_handlers` 已移除（由实例级注入取代，详见
+> [可观测性架构现代化设计](../architecture/observability-modernization.md)）；其余扩展点正分阶段接线，见下表"接线状态"。
+
 ---
 
 ## 📦 模块导入
@@ -48,22 +52,24 @@ DF Test Framework的扩展系统基于[pluggy](https://pluggy.readthedocs.io/)
 
 ### Hook 点分类
 
-| 分类 | Hook 点 | 说明 |
-|------|---------|------|
-| **配置** | `df_config_sources` | 添加配置源 |
-| | `df_config_loaded` | 配置加载后处理 |
-| **启动** | `df_providers` | 注册 Provider |
-| | `df_pre_bootstrap` | Bootstrap 前 |
-| | `df_post_bootstrap` | Bootstrap 后 |
-| **中间件** | `df_http_middlewares` | HTTP 中间件 |
-| | `df_db_middlewares` | 数据库中间件 |
-| | `df_mq_middlewares` | 消息队列中间件 |
-| **事件和遥测** | `df_event_handlers` | 事件处理器 |
-| | `df_telemetry_exporters` | 遥测导出器 |
-| **测试生命周期** | `df_test_setup` | 测试前置 |
-| | `df_test_teardown` | 测试后置 |
-| | `df_session_start` | 会话开始 |
-| | `df_session_finish` | 会话结束 |
+| 分类 | Hook 点 | 说明 | 接线状态 |
+|------|---------|------|------|
+| **启动** | `df_providers` | 注册自定义 Provider（依赖注入阶段） | ✅ 已接线 |
+| | `df_pre_bootstrap` | Bootstrap 前回调 | ✅ 已接线 |
+| | `df_post_bootstrap` | Bootstrap 后回调 | ✅ 已接线 |
+| **中间件** | `df_http_middlewares` | 注入全局 HTTP 中间件 | ✅ 已接线 |
+| | `df_db_middlewares` | 注入全局数据库中间件 | ⏸ 待 DB 客户端支持中间件 |
+| | `df_mq_middlewares` | 注入全局 MQ 中间件 | ⏸ 待 MQ 客户端支持中间件 |
+| **配置** | `df_config_loaded` | 配置加载后回调（读取/校验已加载配置） | ✅ 已接线 |
+| | `df_config_sources` | 添加配置源 | ⏸ 扩展点已恢复，按需接线 |
+| **测试生命周期** | `df_test_setup` | 测试前置（每条测试，含 runtime 上下文） | ✅ 已接线 |
+| | `df_test_teardown` | 测试后置 | ✅ 已接线 |
+| | `df_session_start` | 会话开始 | ✅ 已接线 |
+| | `df_session_finish` | 会话结束 | ✅ 已接线 |
+| **可观测性** | `df_telemetry_exporters` | 添加遥测导出器 | ⏸ 扩展点已恢复，按需接线 |
+| | ~~`df_event_handlers`~~ | ~~事件处理器~~ | ❌ 已移除（实例级注入取代） |
+
+> 事件订阅不走 Hook：见 [可观测性架构现代化设计](../architecture/observability-modernization.md)。
 
 ---
 
@@ -481,61 +487,6 @@ class MQMiddlewareExtension:
 
 ---
 
-### df_event_handlers
-
-**时机**: 事件总线初始化后
-
-**功能**: 注册事件处理器
-
-**签名**:
-```python
-@hookimpl
-def df_event_handlers(
-    self,
-    event_bus: EventBus
-) -> list:
-    """注册事件处理器"""
-```
-
-**参数**:
-- `event_bus`: 事件总线实例
-
-**返回**: `list` - 事件处理器列表(通常返回空列表,因为已通过 subscribe 注册)
-
-**使用场景**:
-- 监听 HTTP 请求事件
-- 监听数据库查询事件
-- 监听测试执行事件
-
-**示例**:
-```python
-from df_test_framework import hookimpl
-
-class EventLoggingExtension:
-    """事件日志扩展"""
-
-    @hookimpl
-    def df_event_handlers(self, event_bus):
-        """注册事件处理器"""
-        # 监听 HTTP 请求完成事件
-        event_bus.subscribe("http.request.completed", self.on_request_completed)
-
-        # 监听数据库查询事件
-        event_bus.subscribe("database.query.executed", self.on_query_executed)
-
-        return []
-
-    def on_request_completed(self, event):
-        """HTTP 请求完成处理"""
-        print(f"请求完成: {event.method} {event.url} - {event.status_code}")
-
-    def on_query_executed(self, event):
-        """数据库查询执行处理"""
-        print(f"查询执行: {event.sql} - {event.duration}ms")
-```
-
----
-
 ### df_telemetry_exporters
 
 **时机**: 遥测系统初始化时

df_test_framework-4.7.5/docs/architecture/observability-modernization.md

@@ -0,0 +1,146 @@
+# 可观测性架构现代化设计
+
+> **状态**：设计已定，分阶段实施中
+> **作者**：架构评审（OMS 嵌入集成驱动）
+> **适用版本**：v4.7.4+
+> **关联**：[ARCHITECTURE_V4.0.md](ARCHITECTURE_V4.0.md)、[event_bus_guide](../guides/event_bus_guide.md)、[plugins_guide](../guides/plugins_guide.md)
+
+## 1. 背景与问题
+
+OMS 测试平台把 df-test-framework 当**执行引擎嵌入**长期运行的服务时，暴露出框架可观测性/插件体系的一组结构性问题。逐一查实如下：
+
+### 1.1 可观测性被绑死在 pytest 上
+
+事件流的真实接线：
+
+```
+pytest 模式（设计意图）
+  testing/fixtures/core.py: pytest_configure
+    → 建全局 EventBus + set_global_event_bus()
+    → RuntimeBuilder().with_event_bus(global_bus) 建 runtime
+  能力客户端（provider 注入 runtime，runtime.event_bus = global_bus）→ 发事件 ✅
+
+嵌入模式（Bootstrap().run()）
+  无 pytest_configure → 从不调 with_event_bus → runtime.event_bus = None
+  → HttpEventPublisherMiddleware 在 event_bus 为空时直接 return（event_publisher.py L91）
+  → 能力层事件全程不发，可观测性死 ❌
+```
+
+根因：能力层（HTTP/DB/MQ/...）的可观测性依赖**进程级全局 EventBus 单例**，而该单例只在 `pytest_configure` 中创建并注入 runtime。离开 pytest，能力层就失去可观测性。
+
+### 1.2 插件 Hook 体系大面积未接线（此前问题，已由 W1-W4 修复）
+
+> 状态（2026-06-29）：本节描述的是**历史问题**。`infrastructure/plugins/hooks.py` 的 hookspec 当时多数仅定义、
+> 在 `bootstrap.py` 中**无调用方**——只有 `df_providers`、`df_post_bootstrap` 被触发，其余
+> （`df_test_setup/teardown`、`df_session_*`、`df_*_middlewares`、`df_config_*`、`df_telemetry_exporters`、
+> `df_pre_bootstrap`）形同虚设。**现已修复**：这些是给消费项目的扩展点，已恢复并把高价值的接到对应调用点
+> （`df_pre_bootstrap`、`df_http_middlewares`、`df_test_setup/teardown`、`df_session_*`、`df_config_loaded`
+> 已接线；且 pytest env_plugin 路径统一走 Bootstrap，钩子在常规 pytest 用法下也生效）。详见扩展文档"接线状态"表与
+> CHANGELOG。唯 `df_event_handlers` 作为事件模型钩子被实例级注入取代而移除（下文）。
+
+特别地，`df_event_handlers` 这个"插件注册事件处理器"的核心钩子从未被触发：
+
+- `monitoring` 插件**唯一的注册路径**就是 `df_event_handlers`（无其它入口）→ 真实使用中恒休眠，仅在单测里被手动调用。
+- `AllurePlugin` 实际通过 fixture 的 `attach_to_event_bus(get_global_event_bus())` 这条 ad-hoc 路径接事件，`df_event_handlers` 是死的。
+- 已移除的 `OmsReporterPlugin` 同时依赖死钩子 + 永不注入的 event_bus，**双重死**，从未工作。
+
+### 1.3 结论：两个关注点被错误耦合
+
+| 关注点 | 应有定位 | 现状 |
+|---|---|---|
+| **测试编写框架**（fixtures / Bootstrap-session / Allure / 自动发现） | 可以、且应该耦合 pytest | 正常 |
+| **协议客户端能力层**（AsyncHttpClient+中间件 / AsyncDatabase / Playwright / MQ） | 应是干净可嵌入的独立库 | 被全局 EventBus 单例 + Pluggy 死钩子缠住，离开 pytest 即失能 |
+
+能力层本该是一等公民的可嵌入库，却把"可观测性"实现成"发到 pytest 设置的进程级全局总线"。这是病根。
+
+## 2. 现代/标准目标
+
+参照成熟库的通行做法——**httpx `event_hooks`、OpenTelemetry instrumentor、Playwright `page.on()`**——同一原则：
+
+> **可观测性靠"实例级、依赖注入的监听器"，不靠"全局单例事件总线 + 插件管理器"。**
+
+目标分层：
+
+```
+能力层（独立库，零会话依赖）
+  AsyncHttpClient(middlewares=[...], event_bus=<可选>)   # 观测者实例级注入
+  └─ 不传也完全能用；传了就发事件到你给的 bus/listener，无需 Bootstrap/pytest/全局单例
+
+测试框架层（pytest，建在能力层之上）
+  fixtures 把能力实例接到 session 级 bus + Allure
+  插件 = listener 提供者，不再"注册到全局单例"
+
+嵌入方（OMS / 任意服务）
+  直接 new 能力对象；要观测就注入自己的 bus/listener
+  （OMS 用 telemetry + 直发，连这个都不需要——这正是"嵌入方零会话依赖"的体现）
+```
+
+要点：
+1. 能力层可观测性 = **构造时注入 event_bus/listener**（实例级），删除"必须有全局 EventBus 才能发事件"的耦合。
+2. **退役** `df_event_handlers` 这一死钩子；插件改为"提供 listener / 订阅具体能力实例"。
+3. pytest 层照旧好用：fixture 把能力实例桥接到 session bus + Allure，测试编写体验不变。
+4. 全局 EventBus 从"进程级可变单例"降级为"按需的 session 级聚合器"。
+
+## 3. 分阶段实施
+
+整套改动横跨 clients + 多类能力 + fixtures + 插件 + EventBus，须保 2630 测试绿，**禁止大爆炸**，分阶段：
+
+### L2（基石，已落地）— 能力层支持实例级 event_bus 注入
+
+让能力客户端**直接注入 event_bus**，脱离 Bootstrap/全局单例也能观测。已实现于 `AsyncHttpClient` 作为参考：
+
+```python
+from df_test_framework.infrastructure.events import EventBus
+from df_test_framework import AsyncHttpClient
+from df_test_framework.core.events import HttpRequestEndEvent
+
+bus = EventBus()
+
+@bus.on(HttpRequestEndEvent)
+async def on_end(e): ...   # 实例级订阅，无需 Bootstrap / pytest / 全局单例
+
+client = AsyncHttpClient(middlewares=[...], event_bus=bus)
+```
+
+`HttpEventPublisherMiddleware` 同时接受 `event_bus` 或 `runtime`，二者皆无则自然 no-op（天然 opt-in）。**加法式、向后兼容**：pytest 路径（runtime 携全局 bus）不变。
+
+**进展**：走"中间件发布事件"模型的客户端已统一支持构造时 `event_bus` 注入——同步 `HttpClient`、
+异步 `AsyncHttpClient`、`GraphQLClient`、`GrpcClient` 均在构造参数暴露 `event_bus` 并透传给各自的
+EventPublisher 中间件（显式注入优先，不传则回退 runtime/全局，皆无则 no-op）。DB/MQ 不走 EventPublisher
+中间件模型（无此注入参数需统一）。
+
+### L1（清理，需与 monitoring 重接一起做）— 退役死钩子
+
+`df_event_handlers` 死钩子退役（仅此一个，因 L2 实例级注入已取代其"注册到全局事件总线"的语义）。
+**注意纠缠**：`monitoring` 插件唯一注册路径就是它，已改造为 `attach_to_event_bus(bus)` 监听器。
+
+> 更正（2026-06-29）：其余"从未被调用"的 hookspec（`df_*_middlewares`、`df_test_setup/teardown`、
+> `df_session_*`、`df_config_*`、`df_pre_bootstrap`、`df_telemetry_exporters`）**不是事件模型的一部分，
+> 也不该删**——它们是给消费项目/插件的扩展点，问题是框架"没接线"。已全部恢复，并把高价值的接到对应
+> 调用点（`df_pre_bootstrap`、`df_http_middlewares`、`df_test_setup/teardown`、`df_session_*`、
+> `df_config_loaded` 已接线）。详见扩展文档的"接线状态"表与 CHANGELOG。
+
+### L3（评估后**不做**，2026-06-29）— 退役全局 EventBus 单例
+
+原计划把全局 EventBus 单例（`set/get_global_event_bus`）降级为 fixture 持有的 session 级聚合器。
+评估纠缠面与收益后**决定不做**：
+
+- `get/set_global_event_bus` 是**顶层导出的公共 API**，被 `pytest_configure`（core.py）+ allure/debugging
+  fixtures + 3 个测试文件使用，runtime 在 configure 阶段用它构建。退役它是**破坏公共 pytest API 的多文件重构**。
+- 该单例本质是 **pytest-session 作用域的容器**（每 session 创建一次，在 session 内使用），不是有害的
+  跨进程全局可变态。
+- **高价值目标"嵌入方不经全局单例即可观测"已由 L2 达成**：嵌入方走实例级注入，根本不触碰这个全局 bus；
+  它如今只是 pytest 内部的 session 事件容器，可接受。
+- 插件模型也已基本归一：`MonitoringPlugin`、`AllurePlugin` 均为 `attach_to_event_bus(bus)` 监听器（L1）。
+
+结论：现代化收在 **L1 + L2**。全局单例作为 pytest-session 容器保留；如未来确有 session 间隔离/并行需求，
+再以 pytest `config.stash` 方式替换模块级全局，届时单列任务评估。
+
+## 4. 对 OMS 集成的含义
+
+OMS 已经是此模型下的**正确形态**：零-Bootstrap、能力层当库、用自身 telemetry + 直发 `task.step_result` 做可观测性。在现代模型里，OMS 就是"嵌入方既不碰 Bootstrap 也不碰全局 EventBus，要观测就注入 listener，而它连这个都不需要"。**OMS 侧无需再改**；本现代化纯属框架自身质量演进。
+
+## 5. 待观察风险
+
+- L1/L3 触及 allure/monitoring/fixtures 与全局单例的纠缠，回归面大，须逐插件迁移并保测试绿。
+- 全局 EventBus 退役可能影响依赖 `get_global_event_bus()` 的外部使用者，需在 release note 明确迁移路径。

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/docs/guides/extensions.md

@@ -1,10 +1,22 @@
 # 扩展系统使用指南
 
-> **适用版本**: v3.0.0+ (v4.0.0 完全兼容)
-> **最后更新**: 2026-01-20
+> **适用版本**: v3.0.0+
+> **最后更新**: 2026-06-29
 >
 > 本指南介绍如何使用 DF Test Framework 的扩展系统来扩展框架功能。
 
+> ℹ️ **Hook 体系状态（v4.7.5）**：这些 Hook 是给消费框架的测试项目/插件用的扩展点，框架在对应阶段触发。
+> 当前接线状态（以 [Extensions API 参考](../api-reference/extensions.md) 的"接线状态"表为准）：
+> - **已接线可用**：`df_providers`、`df_pre_bootstrap`、`df_post_bootstrap`、`df_http_middlewares`、
+>   `df_test_setup/teardown`、`df_session_start/finish`、`df_config_loaded`。
+> - **扩展点已恢复·按需接线**（已定义可实现，框架尚未接到调用点）：`df_db/mq_middlewares`（待 DB/MQ
+>   客户端支持中间件）、`df_config_sources`、`df_telemetry_exporters`。
+> - **已移除**：`df_event_handlers` —— 由实例级注入取代（`AsyncHttpClient(event_bus=bus)` +
+>   插件 `attach_to_event_bus(bus)`），详见 [可观测性架构现代化设计](../architecture/observability-modernization.md)。
+>
+> 👉 **实战用法**（注册插件、注入全局中间件、挂接生命周期）见
+> [插件 Hook 扩展指南](plugin_hooks_guide.md)。下文章节为历史参考。
+
 ## 📋 目录
 
 - [什么是扩展系统](#什么是扩展系统)
@@ -310,23 +322,11 @@ def df_mq_middlewares(self, settings):
 
 ---
 
-### 4. 事件和遥测 Hook
-
-#### df_event_handlers
-
-**时机**: 事件总线初始化后
-**用途**: 注册事件处理器
+### 4. 遥测 Hook
 
-```python
-@hookimpl
-def df_event_handlers(self, event_bus):
-    """注册自定义事件处理器"""
-    event_bus.subscribe("http.request.completed", self.on_request_completed)
-    return []
-
-def on_request_completed(self, event):
-    print(f"请求完成: {event.method} {event.url}")
-```
+> 事件订阅不再走 Hook：`df_event_handlers` 已移除，改用实例级注入
+> （`AsyncHttpClient(event_bus=bus)` + 插件 `attach_to_event_bus(bus)`）。见
+> [插件 Hook 扩展指南](plugin_hooks_guide.md) 与 [可观测性架构现代化设计](../architecture/observability-modernization.md)。
 
 #### df_telemetry_exporters
 

df_test_framework-4.7.5/docs/guides/plugin_hooks_guide.md

@@ -0,0 +1,176 @@
+# 插件 Hook 扩展指南
+
+> **适用版本**: v4.7.5+
+> **最后更新**: 2026-06-29
+>
+> 本指南面向**消费框架的测试项目**，讲如何用插件 Hook 扩展 df-test-framework：
+> 注入全局中间件、挂接测试/会话生命周期、注册自定义服务、读取配置等。
+> 事件可观测性走的是另一套"实例级注入监听器"模型，见末节。
+
+---
+
+## 1. 两分钟上手
+
+一个插件就是一个**带 `@hookimpl` 方法的类（或带模块级 `@hookimpl` 函数的模块）**。
+
+```python
+# myproject/df_plugin.py
+from df_test_framework.infrastructure.plugins import hookimpl
+
+
+class MyPlugin:
+    @hookimpl
+    def df_http_middlewares(self, settings):
+        """给所有 HTTP 客户端注入一个全局鉴权中间件"""
+        from myproject.middlewares import AuthMiddleware
+        return [AuthMiddleware(token=settings.auth.token)]
+```
+
+**注册插件**有两种方式：
+
+```toml
+# 方式 A（pytest 项目，推荐）：pyproject.toml
+[tool.pytest.ini_options]
+# 由框架 core pytest 插件自动加载；多个用逗号分隔
+df_plugins = "myproject.df_plugin"
+```
+
+```python
+# 方式 B（嵌入/编程式）：直接传插件实例
+from df_test_framework.bootstrap import Bootstrap
+runtime = Bootstrap().with_plugin(MyPlugin()).build().run()
+```
+
+> 方式 A 的 `df_plugins` 值是**模块路径**，框架会 `import` 该模块并注册（pluggy 扫描其中的
+> `@hookimpl`）。也支持环境变量 `DF_PLUGINS=...` 与 CLI `--df-plugin=...`。
+
+---
+
+## 2. 可用 Hook 一览
+
+| 阶段 | Hook | 触发时机 | 典型用途 |
+|---|---|---|---|
+| 启动 | `df_providers(settings, logger)` | 依赖注入阶段 | 注册自定义服务 |
+| 启动 | `df_pre_bootstrap(bootstrap)` | 初始化前 | 介入 Bootstrap |
+| 启动 | `df_post_bootstrap(runtime)` | 初始化后 | 拿到 runtime 做收尾 |
+| 配置 | `df_config_loaded(settings)` | 配置加载后 | 读取/校验配置 |
+| 中间件 | `df_http_middlewares(settings)` | HTTP 客户端构建时 | 注入全局 HTTP 中间件 |
+| 测试 | `df_test_setup(request, runtime)` | 每条测试前 | 逐测试前置（含 runtime 上下文） |
+| 测试 | `df_test_teardown(request, runtime, outcome)` | 每条测试后 | 逐测试收尾 |
+| 会话 | `df_session_start(session)` | 会话开始 | 会话级初始化 |
+| 会话 | `df_session_finish(session, exitstatus)` | 会话结束 | 会话级汇总/上报 |
+
+> Hook 返回值约定：`df_*_middlewares` / `df_providers` 返回内容会被框架收集；其余生命周期 Hook
+> 无返回（副作用即可）。一个 Hook 可被多个插件实现，框架会全部调用。
+
+---
+
+## 3. 实战示例
+
+### 3.1 全局 HTTP 中间件（最常用）
+
+让**所有** HTTP 客户端自动带上项目级鉴权/签名/重试，无需逐处配置：
+
+```python
+class AuthPlugin:
+    @hookimpl
+    def df_http_middlewares(self, settings):
+        return [BearerTokenMiddleware(token_provider=lambda: get_token())]
+```
+
+注册后，框架构建 `HttpClient` / `AsyncHttpClient` 时会把这些中间件 `use()` 进中间件链
+（与 `config.middlewares`、重试、事件发布中间件共存，按 priority 排序）。
+
+### 3.2 测试生命周期
+
+`df_test_setup` / `df_test_teardown` 在**每条测试**前后触发，且携带 `request` 与当前 `runtime`
+（pytest 原生 `pytest_runtest_*` 拿不到框架 runtime，这是 df 版的价值）：
+
+```python
+class TestTaggingPlugin:
+    @hookimpl
+    def df_test_setup(self, request, runtime):
+        # 例：把被测环境写进 Allure 标签 / 准备逐测试数据
+        for marker in request.node.iter_markers():
+            ...
+
+    @hookimpl
+    def df_test_teardown(self, request, runtime, outcome):
+        # outcome 是 call 阶段的 pytest TestReport（含 .passed/.failed/.outcome），无则 None
+        ...
+```
+
+### 3.3 会话生命周期
+
+```python
+class ReportPlugin:
+    @hookimpl
+    def df_session_start(self, session):
+        self._started = True
+
+    @hookimpl
+    def df_session_finish(self, session, exitstatus):
+        # 例：会话结束后汇总并推送报告
+        push_summary(exitstatus)
+```
+
+### 3.4 注册自定义服务 + 读取配置
+
+```python
+class ServicePlugin:
+    @hookimpl
+    def df_providers(self, settings, logger):
+        return {"my_cache": MyCache(url=settings.redis.url)}
+
+    @hookimpl
+    def df_config_loaded(self, settings):
+        assert settings.auth.token, "缺少鉴权配置"
+```
+
+`df_providers` 返回的服务可经 `runtime.get("my_cache")` 取用。
+
+---
+
+## 4. 事件可观测性（不走 Hook）
+
+观测 HTTP/DB 等能力层事件，用**实例级注入监听器**，而非全局 Hook：
+
+```python
+from df_test_framework import AsyncHttpClient
+from df_test_framework.infrastructure.events import EventBus
+from df_test_framework.core.events import HttpRequestEndEvent
+
+bus = EventBus()
+
+@bus.on(HttpRequestEndEvent)
+async def on_end(event):
+    print(event.method, event.url, event.status_code)
+
+client = AsyncHttpClient(event_bus=bus)   # 注入即观测，无需 Bootstrap/pytest
+```
+
+内置监控/报告插件同理，提供 `attach_to_event_bus(bus)`：
+
+```python
+from df_test_framework.plugins.builtin.monitoring.plugin import MonitoringPlugin
+mon = MonitoringPlugin()
+mon.attach_to_event_bus(bus)
+... # 运行后
+mon.get_summary()
+```
+
+> 旧的 `df_event_handlers` Hook 已移除——它依赖全局事件总线单例、在嵌入场景不触发；
+> 实例级注入是更标准、可嵌入的替代。详见
+> [可观测性架构现代化设计](../architecture/observability-modernization.md)。
+
+---
+
+## 5. 尚未接线的扩展点
+
+以下 hookspec 已定义（你可以实现），但框架尚未接到调用点，按需提 issue 推进：
+
+- `df_db_middlewares` / `df_mq_middlewares`：待 DB/MQ 客户端支持中间件注入。
+- `df_config_sources`：待接入配置加载链。
+- `df_telemetry_exporters`：待接入可观测性初始化。
+
+完整接线状态见 [Extensions API 参考](../api-reference/extensions.md) 的"接线状态"表。

{df_test_framework-4.7.3 → df_test_framework-4.7.5}/docs/releases/README.md

@@ -1,6 +1,6 @@
 # Release Notes 发布说明索引
 
-> 当前版本：**v4.7.3** · 最近更新：2026-05-27
+> 当前版本：**v4.7.4** · 最近更新：2026-06-29
 
 完整变更摘要见 [CHANGELOG.md](../../CHANGELOG.md)。
 
@@ -10,7 +10,8 @@
 
 | 版本 | 发布日期 | 核心特性 |
 |------|----------|----------|
-| **[v4.7.3](v4.7.3.md)** ⭐ 当前 | 2026-05-27 | 日志时间戳标准化：RFC 3339 毫秒 + 显式时区，`use_utc` → `timestamp` |
+| **[v4.7.4](v4.7.4.md)** ⭐ 当前 | 2026-06-29 | `OmsReporterPlugin` 嵌入式 scope 路由：一次 Bootstrap 多次执行复用，`bind_execution` / `unbind_execution` |
+| **[v4.7.3](v4.7.3.md)** | 2026-05-27 | 日志时间戳标准化：RFC 3339 毫秒 + 显式时区，`use_utc` → `timestamp` |
 | **[v4.7.2](v4.7.2.md)** | 2026-05-26 | 脚手架 `flows/` 目录 + 文档结构补强 + pytest addopts 收敛 |
 | **[v4.7.1](v4.7.1.md)** | 2026-05-22 | 修复 `_auto_allure_observer` 未取消订阅导致 Allure 重复记录 |
 | **[v4.7.0](v4.7.0.md)** | 2026-05-19 | `RuntimeContext.metadata` + 命名 AsyncDatabase 多数据库注册 |